aps_get_submittal_item_attachments

Instructions

Implementation Reference

• src/index.ts:962-983 (registration)

  Tool registration (schema/definition) for aps_get_submittal_item_attachments in the TOOLS array, defining name, description, and inputSchema (project_id, item_id).

  // 24 ── aps_get_submittal_item_attachments
  {
    name: "aps_get_submittal_item_attachments",
    description:
      "Get attachments for a specific submittal item. " +
      "Returns file names, URNs, revision numbers, and categories. " +
      "Use the URN to download the attachment via the Data Management API.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID (UUID or 'b.' prefixed – auto‑converted).",
        },
        item_id: {
          type: "string",
          description: "Submittal item UUID.",
        },
      },
      required: ["project_id", "item_id"],
    },
  },

• src/index.ts:1552-1570 (handler)

  Handler function for aps_get_submittal_item_attachments in the handleTool() function. Validates project_id and item_id, then calls the APS API endpoint 'items/{itemId}/attachments' via submittalPath() and summarizes the response with summarizeSubmittalAttachments().

  // ── aps_get_submittal_item_attachments ──────────────────────
  if (name === "aps_get_submittal_item_attachments") {
    const projectId = args.project_id as string;
    const rawItemId = args.item_id as string;
    const e1 = validateSubmittalProjectId(projectId);
    if (e1) return fail(e1);
    const e2 = validateSubmittalItemId(rawItemId);
    if (e2) return fail(e2);
    const itemId = encodeURIComponent(rawItemId);
  
    const t = await token();
    const raw = await apsDmRequest(
      "GET",
      submittalPath(projectId, `items/${itemId}/attachments`),
      t,
      { headers: { "Content-Type": "application/json" } },
    );
    return json(summarizeSubmittalAttachments(raw));
  }

• src/aps-submittals-helpers.ts:193-217 (helper)

  Helper function summarizeSubmittalAttachments() that parses the raw API response (items/{itemId}/attachments) into a structured summary with attachment id, name, urn, upload_urn, revision, category, created_at, created_by.

  /** Summarise the response from GET /items/:itemId/attachments. */
  export function summarizeSubmittalAttachments(raw: unknown): {
    attachments: SubmittalAttachmentSummary[];
  } {
    // The response may be { results: [...] } or just an array
    const r = raw as Record<string, unknown> | undefined;
    const results = Array.isArray(r?.results)
      ? (r!.results as Record<string, unknown>[])
      : Array.isArray(raw)
        ? (raw as Record<string, unknown>[])
        : [];
  
    const attachments: SubmittalAttachmentSummary[] = results.map((att) => ({
      id: att.id as string,
      name: (att.name as string) ?? "(unknown)",
      urn: (att.urn as string) ?? undefined,
      upload_urn: (att.uploadUrn as string) ?? undefined,
      revision: (att.revision as number) ?? undefined,
      category: (att.categoryValue as string) ?? (att.category as string) ?? undefined,
      created_at: (att.createdAt as string) ?? undefined,
      created_by: (att.createdBy as string) ?? undefined,
    }));
  
    return { attachments };
  }

• src/aps-submittals-helpers.ts:59-79 (helper)

  Helper function toAccProjectId() strips 'b.' prefix from project IDs, and submittalPath() builds the full API path for submittals endpoints.

  // ── ACC project‑ID helper ────────────────────────────────────────
  
  /**
   * Convert a project ID from DM format ('b.uuid') to ACC format ('uuid').
   * If the ID already lacks the 'b.' prefix, it is returned as‑is.
   */
  export function toAccProjectId(projectId: string): string {
    return projectId.replace(/^b\./, "");
  }
  
  // ── Submittal base path builder ──────────────────────────────────
  
  const SUBMITTALS_BASE = "construction/submittals/v2";
  
  /** Build the Submittals API path for a given project. */
  export function submittalPath(projectId: string, subPath: string): string {
    const pid = toAccProjectId(projectId);
    const sub = subPath.replace(/^\//, "");
    return `${SUBMITTALS_BASE}/projects/${pid}/${sub}`;
  }

• src/aps-submittals-helpers.ts:49-58 (helper)

  Type definition SubmittalAttachmentSummary interface describing the shape of each attachment object returned by the tool.

  export interface SubmittalAttachmentSummary {
    id: string;
    name: string;
    urn?: string;
    upload_urn?: string;
    revision?: number;
    category?: string;
    created_at?: string;
    created_by?: string;
  }