feat(sdk): add TypeScript SDK for AP2 mandates and receipts

[wakqasahmed]

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
• Ensure the tests and linter pass
• Appropriate docs were updated (if necessary)

Addresses #67 🦕

What this adds

code/sdk/typescript, a publishable @ap2-protocol/sdk npm package: Zod schemas + TypeScript types for AP2's mandate and receipt models, generated directly from the canonical JSON Schemas in code/sdk/schemas/ap2 (the same source of truth code/sdk/schemas/generate.py generates the Python SDK from).

import { PaymentMandateSchema } from '@ap2-protocol/sdk';

const result = PaymentMandateSchema.safeParse({
  transaction_id: 'tx_1',
  payee: { id: 's-1', name: 'Shop' },
  payment_amount: { amount: 1000, currency: 'USD' },
  payment_instrument: { id: 'pi-1', type: 'credit' },
});

Exports PaymentMandate, CheckoutMandate, OpenPaymentMandate, OpenCheckoutMandate, PaymentReceipt, CheckoutReceipt, plus the shared types (Amount, Merchant, Pisp, PaymentInstrument, Jwk, Item, ReceiptStatus) — each as both a Zod validator and its inferred TS type.

npm run generate (scripts/generate.ts) dereferences every schema under code/sdk/schemas/ap2 and emits the matching Zod code, so this can't drift from the protocol the way hand-maintained TS types would (the exact risk the issue calls out under "alternatives considered").

A correctness bug found and fixed along the way

payment_receipt.json / checkout_receipt.json each put a oneOf alongside properties/required at the schema root (Success branch requires psp_confirmation_id/network_confirmation_id; Error branch requires error/error_description). The underlying json-schema-to-zod generator only reads each branch's discriminator const and silently drops each branch's own required list in this "oneOf as sibling constraint" shape — so a status: "Success" receipt with no confirmation IDs generated as valid. materializeSiblingOneOf in scripts/generate.ts merges outer + branch properties/required before generation (the same shape the generator already handles correctly when branches are fully self-contained, e.g. OpenPaymentMandate.constraints). Covered by a regression test in test/schemas.test.ts.

Scope

This covers the TS types + validation half of #67 ("mirrors the AP2 IntentMandate, CartMandate, PaymentMandate ... models with validation, e.g. zod"). It intentionally does not port ap2.sdk's SD-JWT signing/verification, mandate chain builders, or JWT/JWK helpers — that's cryptography-sensitive code better reviewed on its own. Also unrelated to #144: that PR is a sample application (Genkit + A2A agents) with its own inline, non-reusable schema types, not a publishable library — this package is the standalone SDK #67 is asking for, and the sample could depend on it in a follow-up.

Known limitations (documented in the package README)

• contains isn't enforced. Two schemas use contains to require "at least one array element matching a specific alternative" (e.g. OpenCheckoutMandate.constraints should include a checkout.line_items entry). json-schema-to-zod doesn't support contains; it's silently dropped rather than hand-patched into generated output. Flagged in the README rather than papered over — happy to follow up with a .refine()-emitting fix if that's the preferred direction.
• No compile-time narrowing on the oneOf-branch schemas (PaymentReceipt, CheckoutReceipt, OpenPaymentMandate.constraints entries) — generated as z.object(...).and(z.any().superRefine(...)), and TS collapses T & any to any. Runtime validation is correct and tested; only static narrowing is coarser than the flat schemas.

Testing

cd code/sdk/typescript
npm install
npm run generate   # regenerates src/generated/ from code/sdk/schemas/ap2
npm run lint        # eslint, mirrors code/web-client's config
npm run typecheck   # tsc --noEmit
npm run test         # vitest — 20 tests, incl. the oneOf regression test
npm run build        # tsup esm+cjs+dts

All pass locally. dist/ is gitignored (not committed), matching a standard npm package layout; package-lock.json is committed, matching code/web-client.

CLA

I'll sign the Google CLA via the bot's prompt on this PR.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[wakqasahmed]

Fixed the spellcheck/Prettier/markdownlint findings from the Lint Code Base check in f97b0e7 (root cause: generate.ts hardcoded singleQuote: true instead of reading this repo's own .prettierrc, plus added AP2-specific terms — PISP, IDAS, QWAC, etc. — to the cspell dictionary).

Two remaining Lint Code Base failures (n/no-missing-import on resolvable imports, and BIOME_LINT reporting errors across ~99 files well outside this PR's diff) trace back to CI infrastructure gaps unrelated to this PR's code — filed separately as #306 with repro details so they don't block review here on unrelated ground.