@adcp/sdk per-tool get-reporting-status type makes OperationalFailure uninhabitable

[bokelley]

Version

• @adcp/sdk@14.0.0-beta.29
• bundled AdCP schemas: 3.2.0-beta.11
• TypeScript 5.9.2, strict: true, skipLibCheck: false
• Node 24.14.1

Minimal reproduction

import type { GetReportingStatusResponse } from '@adcp/sdk/types/get-reporting-status'

const response: GetReportingStatusResponse = {
  status: 'failed',
  view: 'revision',
  failure_kind: 'operational',
  errors: [{ code: 'INTERNAL_ERROR', message: 'Temporarily unavailable.' }],
}

void response

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": false,
    "noEmit": true
  }
}

Running tsc reports:

error-type.ts(7,14): error TS2322: Type 'string' is not assignable to type '"NOT_FOUND"'.
error-type.ts(7,38): error TS2322: Type 'string' is not assignable to type '"Reporting status resource is unavailable."'.

The same operational-failure JSON is valid under the bundled media-buy/get-reporting-status-response.json schema.

Cause

The advertised self-contained per-tool declaration uses Error in the base response and in OperationalFailure (errors: Error[]) but does not declare or import the protocol Error type. TypeScript therefore resolves the JavaScript global Error. Intersecting the base response with FailedLookup makes the operational arm effectively uninhabitable and produces the misleading unavailable-lookup literal errors above.

UnavailableLookup does not exhibit the same problem because it inlines its exact error object.

Expected

The per-tool generator should emit the protocol error declaration (or inline the operational error shape), so a schema-valid OperationalFailure is assignable to GetReportingStatusResponse without a cast.

[bokelley]

Triage

Classification: Bug
Bucket: schema (SDK per-tool codegen)
Status: ready-to-implement

What the experts said:

• code-reviewer: Diagnosis confirmed against schema source. Generator conflates Error[] (JS global class) with the AdCP protocol error type; intersecting with FailedLookup's const-typed errors makes OperationalFailure uninhabitable. Schema in this repo is correct — OperationalFailure refs core/error.json; UnavailableLookup correctly inlines const error shapes. Fix belongs in adcp-client per-tool type generator. Non-breaking patch. P1.

My take: Nothing needs to change in this repo — the schema is right. The fix is in the adcp-client per-tool .d.ts emitter. Audit all OperationalFailure arms, not only get_reporting_status.

Implementation brief:

• Repo: adcontextprotocol/adcp-client — per-tool type generator
• Root cause: emits errors: Error[] (JS global class) instead of AdCP protocol error shape
• Fix: emit a named AdcpError interface derived from core/error.json ({ code: string; message: string }) at the top of each per-tool declaration file; use errors: AdcpError[] in all OperationalFailure arms. Prefer the named type over inlining for reuse across tasks.
• Audit: check every per-tool file with an OperationalFailure arm for the same pattern — UnavailableLookup is safe because it inlines const values, but any task using the open protocol error type via $ref to core/error.json may be affected.
• Non-breaking: the prior type was too broad (JS global Error); correcting it to the protocol shape makes previously-invalid assignments valid, not the reverse.
• Changeset: patch in adcp-client.

Sibling-repo-fix-needed: adcp-client — per-tool generator emits JS global Error class instead of AdCP protocol error shape; fix OperationalFailure arm in get_reporting_status emit and audit all other per-tool types.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01KL6QEfmqpJRSGw8vEpQfsM

---

Generated by Claude Code