aps_issues_get

Instructions

Implementation Reference

• src/index.ts:531-557 (registration)

  Tool registration for aps_issues_get: defines the tool name 'aps_issues_get', description, and inputSchema requiring project_id and issue_id (with optional region).

  // 13 ── aps_issues_get
  {
    name: "aps_issues_get",
    description:
      "Get detailed information about a single issue. " +
      "Returns a compact summary with: id, title, description, status, assignee, dates, location, " +
      "custom attributes, linked document count, permitted statuses, and more.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID – accepts with or without 'b.' prefix.",
        },
        issue_id: {
          type: "string",
          description: "Issue UUID. Get this from aps_issues_list.",
        },
        region: {
          type: "string",
          enum: ["US", "EMEA", "AUS", "CAN", "DEU", "IND", "JPN", "GBR"],
          description: "Data centre region. Defaults to US.",
        },
      },
      required: ["project_id", "issue_id"],
    },
  },

• src/index.ts:1273-1293 (handler)

  Handler for aps_issues_get: validates project ID and issue ID, converts project ID (strips 'b.' prefix), makes GET request to construction/issues/v1/projects/{pid}/issues/{issueId}, and returns the summarized issue detail.

  // ── aps_issues_get ──────────────────────────────────────────
  if (name === "aps_issues_get") {
    const projectId = args.project_id as string;
    const issueId = args.issue_id as string;
    const e1 = validateIssuesProjectId(projectId);
    if (e1) return fail(e1);
    const e2 = validateIssueId(issueId);
    if (e2) return fail(e2);
  
    const pid = toIssuesProjectId(projectId);
    const region = args.region as string | undefined;
    const t = await token();
  
    const raw = await apsDmRequest(
      "GET",
      `construction/issues/v1/projects/${pid}/issues/${issueId}`,
      t,
      { headers: issuesHeaders(region) },
    );
    return json(summarizeIssueDetail(raw));
  }

• src/aps-issues-helpers.ts:120-167 (helper)

  summarizeIssueDetail helper: transforms raw API response into a compact IssueDetailSummary with fields like id, title, description, status, assignee, dates, custom attributes, linked document count, watchers, and permitted statuses.

  export function summarizeIssueDetail(raw: unknown): IssueDetailSummary {
    const issue = raw as Record<string, unknown>;
  
    const customAttrs = Array.isArray(issue.customAttributes)
      ? (issue.customAttributes as Record<string, unknown>[]).map((ca) => ({
          id: (ca.attributeDefinitionId as string) ?? "",
          value: ca.value,
          type: (ca.type as string) ?? undefined,
          title: (ca.title as string) ?? undefined,
        }))
      : undefined;
  
    const linkedDocs = Array.isArray(issue.linkedDocuments)
      ? issue.linkedDocuments.length
      : 0;
  
    return {
      id: issue.id as string,
      displayId: (issue.displayId as number) ?? 0,
      title: (issue.title as string) ?? "",
      description: (issue.description as string) ?? undefined,
      status: (issue.status as string) ?? "",
      issueTypeId: (issue.issueTypeId as string) ?? undefined,
      issueSubtypeId: (issue.issueSubtypeId as string) ?? undefined,
      assignedTo: (issue.assignedTo as string) ?? undefined,
      assignedToType: (issue.assignedToType as string) ?? undefined,
      dueDate: (issue.dueDate as string) ?? undefined,
      startDate: (issue.startDate as string) ?? undefined,
      locationId: (issue.locationId as string) ?? undefined,
      locationDetails: (issue.locationDetails as string) ?? undefined,
      rootCauseId: (issue.rootCauseId as string) ?? undefined,
      published: (issue.published as boolean) ?? false,
      commentCount: (issue.commentCount as number) ?? 0,
      createdBy: (issue.createdBy as string) ?? "",
      createdAt: (issue.createdAt as string) ?? "",
      updatedAt: (issue.updatedAt as string) ?? "",
      closedBy: (issue.closedBy as string) ?? undefined,
      closedAt: (issue.closedAt as string) ?? undefined,
      customAttributes: customAttrs,
      linkedDocumentCount: linkedDocs,
      watchers: Array.isArray(issue.watchers)
        ? (issue.watchers as string[])
        : undefined,
      permittedStatuses: Array.isArray(issue.permittedStatuses)
        ? (issue.permittedStatuses as string[])
        : undefined,
    };
  }

• src/aps-issues-helpers.ts:69-71 (helper)

  toIssuesProjectId helper: strips the 'b.' prefix from a Data Management project ID for use with the Issues API.

  export function toIssuesProjectId(projectId: string): string {
    return projectId.replace(/^b\./, "");
  }

• src/aps-issues-helpers.ts:260-263 (helper)

  validateIssueId helper: validates that the issue_id parameter is non-empty.

  export function validateIssueId(id: string): string | null {
    if (!id) return "issue_id is required.";
    return null;
  }