aps_list_submittal_specs

Instructions

Implementation Reference

• src/index.ts:935-960 (registration)

  Registration of the aps_list_submittal_specs tool in the TOOLS array with its name, description, and input schema (project_id, limit, offset).

  // 23 ── aps_list_submittal_specs
  {
    name: "aps_list_submittal_specs",
    description:
      "List spec sections for submittals in an ACC project. " +
      "Returns a compact summary: identifier (e.g. '033100'), title, dates. " +
      "Spec sections are the specification divisions that submittal items are organised under.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID (UUID or 'b.' prefixed – auto‑converted).",
        },
        limit: {
          type: "number",
          description: "Max items per page (1–200). Default 20.",
        },
        offset: {
          type: "number",
          description: "Pagination offset. Default 0.",
        },
      },
      required: ["project_id"],
    },
  },

• src/index.ts:1533-1550 (handler)

  Handler function that validates the project ID, builds query parameters (limit/offset), calls the Submittals API 'specs' endpoint via apsDmRequest, and formats the result via summarizeSubmittalSpecs.

  // ── aps_list_submittal_specs ────────────────────────────────
  if (name === "aps_list_submittal_specs") {
    const projectId = args.project_id as string;
    const e1 = validateSubmittalProjectId(projectId);
    if (e1) return fail(e1);
  
    const query: Record<string, string> = {};
    const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 200);
    query.limit = String(limit);
    if (args.offset != null) query.offset = String(args.offset);
  
    const t = await token();
    const raw = await apsDmRequest("GET", submittalPath(projectId, "specs"), t, {
      query,
      headers: { "Content-Type": "application/json" },
    });
    return json(summarizeSubmittalSpecs(raw));
  }

• src/aps-submittals-helpers.ts:41-47 (schema)

  Type definition for a spec section summary returned by the tool, with fields: id, identifier, title, created_at, updated_at.

  export interface SubmittalSpecSummary {
    id: string;
    identifier: string;
    title: string;
    created_at?: string;
    updated_at?: string;
  }

• src/aps-submittals-helpers.ts:164-191 (helper)

  Helper function that parses the raw API response from GET /specs, extracts pagination info, and maps each result to a SubmittalSpecSummary object.

  /** Summarise the paginated response from GET /specs. */
  export function summarizeSubmittalSpecs(raw: unknown): {
    pagination: { total: number; limit: number; offset: number };
    specs: SubmittalSpecSummary[];
  } {
    const r = raw as Record<string, unknown> | undefined;
    const pagination = r?.pagination as Record<string, unknown> | undefined;
    const results = Array.isArray(r?.results)
      ? (r!.results as Record<string, unknown>[])
      : [];
  
    const specs: SubmittalSpecSummary[] = results.map((spec) => ({
      id: spec.id as string,
      identifier: (spec.identifier as string) ?? "",
      title: (spec.title as string) ?? "(untitled)",
      created_at: (spec.createdAt as string) ?? undefined,
      updated_at: (spec.updatedAt as string) ?? undefined,
    }));
  
    return {
      pagination: {
        total: (pagination?.totalResults as number) ?? specs.length,
        limit: (pagination?.limit as number) ?? 0,
        offset: (pagination?.offset as number) ?? 0,
      },
      specs,
    };
  }