From 2bc087c11e94c05991b489c9cc494ec6834c7571 Mon Sep 17 00:00:00 2001 From: "aao-ipr-bot[bot]" <279263549+aao-ipr-bot[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 04:12:23 +0000 Subject: [PATCH] chore: release package (beta) --- .../{ => pre}/account-requests-seller.md | 0 .changeset/{ => pre}/accounts-change.md | 0 .changeset/{ => pre}/legacy-creative-fit.md | 0 .changeset/{ => pre}/package-size-headroom.md | 0 .../reporting-coverage-harness-fixes.md | 0 .../{ => pre}/reporting-managed-local-days.md | 0 .../{ => pre}/reporting-reconcile-issues.md | 0 ...porting-storage-principal-notifications.md | 0 .../reporting-storage-principal-runtime.md | 0 .../reporting-subscriptions-events.md | 0 ...eporting-subscriptions-explain-coverage.md | 0 ...eporting-subscriptions-managed-defaults.md | 0 .../reporting-subscriptions-receipts.md | 0 ...porting-subscriptions-reconcile-explain.md | 0 ...eporting-subscriptions-storyboard-probe.md | 0 .../reporting-subscriptions-test-kit.md | 0 CHANGELOG.md | 88 +++++++++++++++++++ docs/TYPE-SUMMARY.md | 4 +- docs/llms.txt | 4 +- docs/migration-14.x-rc-worksheet.md | 8 +- package-lock.json | 10 +-- package.json | 2 +- packages/client-shim/package.json | 2 +- packages/reporting-storage/CHANGELOG.md | 33 +++++++ packages/reporting-storage/package.json | 4 +- src/lib/version.ts | 6 +- 26 files changed, 141 insertions(+), 20 deletions(-) rename .changeset/{ => pre}/account-requests-seller.md (100%) rename .changeset/{ => pre}/accounts-change.md (100%) rename .changeset/{ => pre}/legacy-creative-fit.md (100%) rename .changeset/{ => pre}/package-size-headroom.md (100%) rename .changeset/{ => pre}/reporting-coverage-harness-fixes.md (100%) rename .changeset/{ => pre}/reporting-managed-local-days.md (100%) rename .changeset/{ => pre}/reporting-reconcile-issues.md (100%) rename .changeset/{ => pre}/reporting-storage-principal-notifications.md (100%) rename .changeset/{ => pre}/reporting-storage-principal-runtime.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-events.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-explain-coverage.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-managed-defaults.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-receipts.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-reconcile-explain.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-storyboard-probe.md (100%) rename .changeset/{ => pre}/reporting-subscriptions-test-kit.md (100%) diff --git a/.changeset/account-requests-seller.md b/.changeset/pre/account-requests-seller.md similarity index 100% rename from .changeset/account-requests-seller.md rename to .changeset/pre/account-requests-seller.md diff --git a/.changeset/accounts-change.md b/.changeset/pre/accounts-change.md similarity index 100% rename from .changeset/accounts-change.md rename to .changeset/pre/accounts-change.md diff --git a/.changeset/legacy-creative-fit.md b/.changeset/pre/legacy-creative-fit.md similarity index 100% rename from .changeset/legacy-creative-fit.md rename to .changeset/pre/legacy-creative-fit.md diff --git a/.changeset/package-size-headroom.md b/.changeset/pre/package-size-headroom.md similarity index 100% rename from .changeset/package-size-headroom.md rename to .changeset/pre/package-size-headroom.md diff --git a/.changeset/reporting-coverage-harness-fixes.md b/.changeset/pre/reporting-coverage-harness-fixes.md similarity index 100% rename from .changeset/reporting-coverage-harness-fixes.md rename to .changeset/pre/reporting-coverage-harness-fixes.md diff --git a/.changeset/reporting-managed-local-days.md b/.changeset/pre/reporting-managed-local-days.md similarity index 100% rename from .changeset/reporting-managed-local-days.md rename to .changeset/pre/reporting-managed-local-days.md diff --git a/.changeset/reporting-reconcile-issues.md b/.changeset/pre/reporting-reconcile-issues.md similarity index 100% rename from .changeset/reporting-reconcile-issues.md rename to .changeset/pre/reporting-reconcile-issues.md diff --git a/.changeset/reporting-storage-principal-notifications.md b/.changeset/pre/reporting-storage-principal-notifications.md similarity index 100% rename from .changeset/reporting-storage-principal-notifications.md rename to .changeset/pre/reporting-storage-principal-notifications.md diff --git a/.changeset/reporting-storage-principal-runtime.md b/.changeset/pre/reporting-storage-principal-runtime.md similarity index 100% rename from .changeset/reporting-storage-principal-runtime.md rename to .changeset/pre/reporting-storage-principal-runtime.md diff --git a/.changeset/reporting-subscriptions-events.md b/.changeset/pre/reporting-subscriptions-events.md similarity index 100% rename from .changeset/reporting-subscriptions-events.md rename to .changeset/pre/reporting-subscriptions-events.md diff --git a/.changeset/reporting-subscriptions-explain-coverage.md b/.changeset/pre/reporting-subscriptions-explain-coverage.md similarity index 100% rename from .changeset/reporting-subscriptions-explain-coverage.md rename to .changeset/pre/reporting-subscriptions-explain-coverage.md diff --git a/.changeset/reporting-subscriptions-managed-defaults.md b/.changeset/pre/reporting-subscriptions-managed-defaults.md similarity index 100% rename from .changeset/reporting-subscriptions-managed-defaults.md rename to .changeset/pre/reporting-subscriptions-managed-defaults.md diff --git a/.changeset/reporting-subscriptions-receipts.md b/.changeset/pre/reporting-subscriptions-receipts.md similarity index 100% rename from .changeset/reporting-subscriptions-receipts.md rename to .changeset/pre/reporting-subscriptions-receipts.md diff --git a/.changeset/reporting-subscriptions-reconcile-explain.md b/.changeset/pre/reporting-subscriptions-reconcile-explain.md similarity index 100% rename from .changeset/reporting-subscriptions-reconcile-explain.md rename to .changeset/pre/reporting-subscriptions-reconcile-explain.md diff --git a/.changeset/reporting-subscriptions-storyboard-probe.md b/.changeset/pre/reporting-subscriptions-storyboard-probe.md similarity index 100% rename from .changeset/reporting-subscriptions-storyboard-probe.md rename to .changeset/pre/reporting-subscriptions-storyboard-probe.md diff --git a/.changeset/reporting-subscriptions-test-kit.md b/.changeset/pre/reporting-subscriptions-test-kit.md similarity index 100% rename from .changeset/reporting-subscriptions-test-kit.md rename to .changeset/pre/reporting-subscriptions-test-kit.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 846747779..c2fa90abe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,93 @@ # Changelog +## 17.0.0-beta.12 + +### Minor Changes + +- a831111: Sellers registering `request_account` (`accounts.requestAccount`) now advertise AdCP 3.3 `account.requests` on `get_adcp_capabilities`, with `request_task`, `read_task: 'list_accounts'` and the `account.requests` experimental feature id, so `client.accounts.ensure` routes to them. `capabilities.accountRequests` supplies `changeableAttributes`, `pendingActionKinds` and `eventType`. On the platform path, the new `accounts.listRequests(request, ctx)` hook serves the caller's requests as `account_requests[]` and `account_requests_pagination` on `list_accounts` when the buyer sends `include_requests`, `request_ids` or `requests_pagination`. `Account.revision` is now served on `list_accounts`, so buyers can read the revision a change is based on. Fixes #3575. + + **Behavior change for 3.3 beta adopters:** a seller that registers `request_account` must declare who bills, because `account.requests` lives in the account capability block, whose schema requires `supported_billing`. A server that registers it without one is now refused at construction. Fix: add `capabilities: { account: { supportedBilling: ['agent'] } }` to `createAdcpServer`, or `capabilities.supportedBillings` on the platform path, with your actual billing model. The SDK never fills in this claim for you. + +- b296a8a: Add `client.accounts.change(accountId, changes, { revision, allowSeparateAccount })`, which changes an account through AdCP 3.3 `request_account` with `account_id`. It resolves to an `AccountChangeOutcome`: `updated` (with `revision` and `effective_at`), `separate_account` (with `not_carried_over` and `subscriptionsNotCovering`), `matched_existing`, `pending`, or `rejected` (with `requiresNewAccount`). A money change (`billing`, `billing_entity`, `payment_terms`) without `revision` is refused before dispatch with `AccountRequestError` code `ACCOUNT_REVISION_REQUIRED`. Other changes read the revision from `list_accounts` and retry once on `CONFLICT`, but only when the changed fields did not move. Unknown attributes (`ACCOUNT_CHANGE_INVALID`) and sellers without `account.requests` (`ACCOUNT_REQUESTS_UNSUPPORTED`) are also refused locally, and the error carries `dispatched: false`. A separate or matched account never re-points the registry: `client.accounts.use(key, accountId)` is the explicit step. `client.accounts.changeStatus(accountId, requestId)` reads a pending change back. `nextStep` accepts change outcomes. The behavior matches the Python SDK's `accounts.change`. +- d134d82: Reporting subscriptions (experimental, AdCP 3.3): reconcile reports name what kept them from being definitive in the Python SDK's shape. + - `ReconcileReport.issues` is a list of `ReconcileIssue` entries (`{ code, message, account_id?, subscription_id? }`). The codes match Python's: `SUBSCRIPTION_ROSTER_UNAVAILABLE`, `SUBSCRIPTION_OFFERINGS_UNAVAILABLE`, `SUBSCRIPTION_ACCOUNT_UNREADABLE`, `SUBSCRIPTION_LEDGER_UNAVAILABLE`, `SUBSCRIPTION_ACCOUNT_NOT_COVERED`, or a coverage input code. As in Python, any issue makes the report `definitive: false`. + - Explicitly requested `accounts` that no subscription covers are now reported (`SUBSCRIPTION_ACCOUNT_NOT_COVERED`) instead of being dropped silently. + - The fleet report (`multiClient.reporting.reconcile()`) renames `failures` to `issues`: an array of `ReconcileIssue & { agent_id }`, with `SUBSCRIPTION_PRINCIPAL_UNAVAILABLE` for a seller that could not be reconciled at all. + +- 8374d8d: Reporting subscriptions (experimental, AdCP 3.3): buyer events. + - `client.reporting.poll()` returns the events since the last acknowledgement, derived by comparing what the seller reports now (`reconcile`, the subscription readback, each account's `subscription_coverage[]`) with the snapshot saved by the last `batch.ack()`. Delivery is at least once with deterministic ids (`rse_` + `sha256(agent, type, natural key, version)`, the same ids as the Python SDK). A partial read never fabricates a change, and `poll({ baseline: true })` records the present without emitting it. + - `client.reporting.events({ pollEvery, signal })` is the loop: each batch is acknowledged after the loop body has run for all its events. + - `client.reporting.handleWebhook(verified)` treats a seller webhook as a doorbell: it wakes a running `events()` loop or polls inline. It takes only a `VerifiedWebhook`, built by `VerifiedWebhook.fromOutcome` from a successful signature verification. + - Event types: `revision.available`, `revision.adjusted`, `period.late`, `period.missing_obligation`, `period.withheld`, `coverage.exception_opened`, `coverage.exception_closed`, `account.covered`, `account.unauthorized`, `account.regranted`, `subscription.state_changed`, `timezone.cutover`. + - Snapshots live in a `ReportingEventStore` with compare-and-set (`ReportingEventConflictError` when another worker acknowledged first). `memoryStorage().events` and `postgresStorage({ pool }).events` provide one, `createReportingEventStore({ store })` builds one over any `AdcpStateStore` with `putIfMatch`, and the client takes it as `reportingEventStore`. + - `@adcp/sdk/reporting/advanced` adds `deriveEvents`, `EVENT_TYPES` and `SNAPSHOT_VERSION`. + +- e4b43a3: Reporting subscriptions (experimental, AdCP 3.3): sellers can explain coverage, and the CLI compares traces. + - `service.explainCoverage({ principal, accountId, period, subscriptionId?, mediaBuyId?, offeringId? })` on the managed `subscriptions` path returns `CoverageTrace`s (`side: 'seller'`) from the engine's own state: the stored version history, the grant journal, the served `subscription_coverage` and the buys read under the principal. `seller_only` carries `buy_visible` and the planned obligation's `reporting_obligation_id`. Its trace of a period equals the buyer's `client.reporting.explain` trace, `inputs_digest` included. + - `@adcp/sdk/reporting/service` re-exports `coverageTraceForBuyer` and `diffCoverageTraces`. + - New CLI: `adcp reporting explain` (buyer with `--agent`, seller with `--app module#export --tenant --principal`), `adcp reporting diff left.json right.json` (names the first differing rule; exits 1 on a difference) and `adcp reporting reconcile --agent`. + +- 7cfccfd: Reporting subscriptions (experimental, AdCP 3.3): the managed seller path derives more and reconciles less. + - The framework `Account` has a `timezone` field (`UTC` or IANA), served on `list_accounts`. The derived roster reads it, so `account_timezone` offerings no longer need an untyped `timezone` on the `accounts.list` items. + - `subscriptions.configure` is optional. Without it each subscription generation is derived from its source offering by `defaultSubscriptionConfiguration` (exported from `@adcp/sdk/reporting/service`): every exactly supported metric and dimension, the first attribution model and window, and a contractual cutoff at the offering's `delivery_sla` for `official` feeds. Billing feeds still need `configure`. + - `isPeriodDelivered` defaults to the service's own ledger, so `withheld_period_count` counts only periods whose obligation has no revision. It used to count every withheld period. + - The `runCycle` boundary sweep reconciles a principal only when it is due: a period of one of its schedules ended since its last reconcile, its last reconcile failed, a grant change was pushed, or `subscriptions.maxSweepIntervalMilliseconds` (one hour by default) elapsed. It used to reconcile every subscribed principal on every cycle. + +- 1da37d9: Reporting subscriptions (experimental, AdCP 3.3): the buyer receipts policy. + - `client.reporting.reconcile({ receipts: { mode: 'verified', commit, resourceReader | inspect } })` receipts `consumer_receipt` (billing) revisions only after the SDK verified the materialization itself and your `commit` returned `{ commitRef }`. `'defer'` sends nothing, and `{ reject: codes }` sends a rejected receipt. A mismatch the SDK finds is rejected without calling `commit`, and a revision it can't verify is listed in `report.receipts.failed`. Receipt ids are stable per (obligation, revision, materialization), so a materialization is never receipted twice. + - The policy is off by default. Delivered billing periods then read `receipt: { status: 'owed_by_buyer' }` with `responsible_party: 'buyer'`, and the client warns once. + - Adjustments are offered to `adjustments(adjustment)` and always deferred: billing never auto-accepts. + - `client.reporting.submitReceipts(accountId, { receipts, adjustmentReceipts })` is the typed manual wrapper over `sync_reporting_receipts`. + - `scripts/package-size-budget.json`: the SDK file ceiling rises from 8,450 to 8,500 for the stacked reporting-subscription slices. + +- dc8cad8: Reporting subscriptions (experimental, AdCP 3.3): buyers can see what a seller owes them and why. + - `client.reporting.reconcile(options)` reads the principal, capabilities, `list_accounts`, `get_media_buys` and `get_reporting_status` and returns a `ReconcileReport`: one `PeriodLine` per owed obligation with `status` (`delivered`, `pending`, `late`, `missing_obligation`, `withheld`), the spec's coverage `reason`, `responsible_party` and a `message`. The roster is `list_accounts` intersected with the subscription scopes on every run. `grace` (default `PT1H`) keeps fresh periods from reading as missing; `includeNotOwed` adds `not_owed` lines with their reasons; `previous` carries a revoked account's undelivered periods as `withheld`. A failed read makes the report `definitive: false`, never smaller, and each read is bounded by `readTimeoutMilliseconds` (30 seconds by default). + - `multiClient.reporting.reconcile()` runs every configured seller with bounded concurrency and returns `{ bySeller, issues, definitive, summary }`. + - `client.reporting.explain({ accountId, period, ... })` returns `CoverageTrace`s (`side: 'buyer'`). + - `@adcp/sdk/reporting/advanced` adds `explainSubscriptionCoverageV1`, `classifySubscriptionPeriodsV1`, `diffCoverageTraces`, `coverageTraceForBuyer`, `EXPLAIN_TEMPLATES` and the spec's frozen reason-code vocabulary (`COVERAGE_REASONS`, `COVERAGE_RULE_ORDER`). Traces carry the same steps, sentences and `inputs_digest` as the Python SDK's `explain_subscription_coverage`. + - New guides: coverage, error reference, and migrating from account-level `reporting_delivery_configs`. + - The managed seller path asks `getMediaBuys` for every wire buy status (`pending_creatives`, `pending_start`) as well. + +- b7b9ec8: Reporting subscriptions (experimental, AdCP 3.3): conformance tooling. + - **Storyboard runner: `check: owed_periods_match`** (runner contract `storyboard-schema.yaml`, "Owed periods"). + - On a `get_reporting_status` periods-view step, it computes the periods a subscription owes the account from wire state alone (`get_principal` with `prior_versions` paging, `list_accounts`, `get_media_buys`, `get_adcp_capabilities`, and the response's `subscription_coverage` entry) with the SDK coverage function at `ledger_as_of`. + - It passes when the seller's obligations are exactly that set from `ledger_retained_from`, within the request's `period`: no missing and no extra periods, the same `media_buy_ids` and `stub` flag. `pagination.has_more` fails as unverifiable. + - **Storyboard runner: brand-subject tasks.** Test-kit brand injection no longer overwrites `request_account`'s `brand`, which dropped `brand.countries` (`BRAND_SUBJECT_TASKS`). + - **`comply_test_controller` scenario `reporting_subscription_probe`.** + - Operations: `revoke_grant`, `regrant`, `reduce_grant`, `set_account_timezone` (returns `timezone_cutovers: [{ offering_id, effective_at }]`) and `advance_time`. + - Types: `ReportingSubscriptionProbeParams` and `ReportingSubscriptionProbeSimulated`. + - Wiring: schema-checked params (`reportingSubscriptionProbeParamsError`), `TestControllerStore.reportingSubscriptionProbe`, `complyTest.reportingSubscriptionProbe`, and `list_scenarios` / `compliance_testing.scenarios` advertisement. + - **Test kit.** + - Its seller implements the probe. + - Its virtual clock may now run past the real clock: under `NODE_ENV=test` or `development`, the Reliable Reporting service hands each cycle's `now` to the inline source executor (`createInlineReportingSourceExecutor({ now })`, refused in other environments). + - **`npx adcp reporting doctor --agent `** and `runReportingDoctor(client)` check a seller's subscription wiring from the wire, and name a fix for each failure. + +- 8856bbd: Reporting subscriptions (experimental, AdCP 3.3): a test kit, a managed reference seller, and fewer host inputs. + - New subpath `@adcp/sdk/testing/reporting`: `createReportingTestKit({ start, offerings, accounts, buys })` runs a managed reference seller over `memoryStorage()` on a virtual clock. It gives buyers bound to it (`kit.buyer(id).reporting`), `clock.advance`/`advanceTo` (running the seller's cycle at every boundary crossed), `grants.revoke`/`regrant`/`windDown`/`reduce`, `accounts.setTimezone`, `buys.add`/`cancel`/`complete`, and `assertAgreement(buyer)`, which checks the seller's frozen owed set against the buyer's `reconcile()` and names the first differing rule. Also `createReferenceReportingSeller`, `offerings.dailyAnalytics()`, `withReportingTestKit` and `reportingTestStart`. + - The reference seller (`examples/reporting-subscriptions-seller/seller.mjs`) is rewritten on the managed path: one `subscriptions` block, `accounts.list` and `getMediaBuys`, with a seeded buy that produces real obligations. `npx adcp reference-seller reporting [--port]` serves it. + - With `subscriptions.principal`, the service now pairs `notification_configs` with `sync_principal` and advertises `capability_changes` unless the platform does, and `principal.notifications` is optional with process-local storage (nothing is sent). Durable storage still requires it. + +### Patch Changes + +- 9cf1b55: Evaluate each package's legacy format references against measured creative dimensions and duration. Recognize resolved legacy shape matches without asserting canonical technical completeness, retain unknown verdicts for unstated constraints, and preserve native canonical contracts and shared wire refusals. Deduplicate fit diagnostics by code and path. +- 6141030: Trim the published package from 26.86 MB to 24.99 MB packed (8,529 to 8,176 files). Runtime behavior is unchanged. + - The compliance bundles no longer ship their `domains/` directories. Each was a byte-identical copy of `protocols/`, which is what the storyboard loader reads. If you read storyboards from `node_modules/@adcp/sdk/compliance/cache//domains//`, read `protocols//` instead. `index.json` keeps listing both arrays because it is the upstream bundle file. + - The ESM declarations for the generated protocol and registry types (`types/core.generated.d.mts`, `types/tools.generated.d.mts`, `registry/types.generated.d.mts`) now re-export the CommonJS declarations, as `types/schemas.generated.d.mts` already did, instead of shipping a second copy. ESM and CommonJS consumers get the same types. + - The MCP `tools/list` request projections under `dist/lib/schemas-data//mcp/` are stored as compact JSON. `tools/list` serves the parsed schemas, so the wire output is the same. + +- ed8f98d: Reporting subscriptions (experimental, AdCP 3.3): fixes found by the cross-SDK differential harness. + - `owedSubscriptionPeriodsV1` owes the billing cutover stub when the incoming schedule's first boundary at or after `authorized_at` falls after the cutover's E (#3572). The authorization start bound now compares the period start with `authorized_at`, which is the same test for calendar periods and also admits a stub that starts at E. + - An `account.timezone` that no schedule reads is no longer refused as `invalid_timezone` (#3573). It is validated where an `account_timezone` schedule reads it. + - The managed engine's `unauthorized` `gaps[]` entries always name their `offering_id` (#3577). An entry without one applies to every offering on the account, so a later version resolving offerings with other boundaries made buyers drop periods the seller owed. + - A `timezone_cutovers` entry without `previous_timezone` is refused (`COVERAGE_INPUT_INCOMPLETE`, `missing_previous_timezone`) whenever an `account_timezone` offering resolves, as `error-codes.json` words it (adcp#8681), not only when a period under the old zone is computed. + +- b5f7461: Reliable Reporting (experimental, AdCP 3.3): the managed service now serves local-day offerings that it used to refuse (#3574). + - `account_timezone` offerings are served on the subscription path. Each account owes the periods of its own `accounts.list` `timezone`, the same periods the buyer's `reconcile` computes. The source offering must not pin `sourceTimezone.ianaTimezone`, and `resolveSource` must return the account's timezone. Without a `subscriptions` block, creating the service still refuses the offering, and an account-level `installConfiguration` refuses it. Both errors now name the subscription path. The managed path does not yet follow an account timezone change on an `account_timezone` subscription. + - `source_timezone` `P1D` offerings are served in zones whose DST change skips local midnight (America/Santiago, America/Havana, Africa/Cairo). Such a day starts at the instant its skipped midnight advances to, per `core/reporting-schedule.json` `period_generation`, and the source is asked for that one local date. The inline executor and source request conformance accept these 23- and 25-hour local days. + - `offerings.dailyAnalytics({ alignment: 'account_timezone' })` in `@adcp/sdk/testing/reporting`. The kit's reference seller reports that offering in each account's timezone and routes each offering to its own adapter. + +- f31e94f: Reporting subscriptions (experimental, AdCP 3.3): a PostgreSQL production seller configured with `subscriptions.principal` now serves the same principal surface as the `memoryStorage()` seller. `createPostgresReliableReportingProductionService` builds the principal runtime with the `notification_configs` task (`syncAgentNotificationConfigs`) and marks it as service-built, so the service advertises `capability_changes` for it. Before, it served neither. + ## 17.0.0-beta.11 ### Major Changes diff --git a/docs/TYPE-SUMMARY.md b/docs/TYPE-SUMMARY.md index 3c3c986aa..62ecc9868 100644 --- a/docs/TYPE-SUMMARY.md +++ b/docs/TYPE-SUMMARY.md @@ -1,7 +1,7 @@ # AdCP Type Summary -> Generated at: 2026-10-31 -> @adcp/sdk v17.0.0-beta.11 +> Generated at: 2026-11-02 +> @adcp/sdk v17.0.0-beta.12 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`. diff --git a/docs/llms.txt b/docs/llms.txt index ee9407694..10dfcc6bb 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -1,7 +1,7 @@ # Ad Context Protocol (AdCP) -> Generated at: 2026-10-31 -> Library: @adcp/sdk v17.0.0-beta.11 +> Generated at: 2026-11-02 +> Library: @adcp/sdk v17.0.0-beta.12 > AdCP major version: 3 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt > Note: the `Library` stamp reflects the package.json version at doc-generation time. The narrative below describes the surface that lands on the next-published minor — including any 6.7 helpers documented here ahead of the release tag. diff --git a/docs/migration-14.x-rc-worksheet.md b/docs/migration-14.x-rc-worksheet.md index 5f803d0fb..9f676ea7d 100644 --- a/docs/migration-14.x-rc-worksheet.md +++ b/docs/migration-14.x-rc-worksheet.md @@ -16,8 +16,8 @@ pin using `ADCP_VERSION` inside that tarball. | Fact | Value | | --- | --- | -| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.11` | -| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.11 dist.integrity` | +| Checkout `package.json` version | `@adcp/sdk@17.0.0-beta.12` | +| npm integrity | registry-derived after publication; run `npm view @adcp/sdk@17.0.0-beta.12 dist.integrity` | | Node.js runtime | `^20.19.0 || >=22.12.0` | | Default AdCP wire release | `3.3.0-beta.3` | | Maintained wire releases | `v3`, `3.0.0`, `3.0`, `3.0.1`, `3.0.2`, `3.0.3`, `3.0.4`, `3.0.5`, `3.0.6`, `3.0.7`, `3.0.8`, `3.0.9`, `3.0.10`, `3.0.11`, `3.0.12`, `3.0.13`, `3.0.14`, `3.0.15`, `3.0.16`, `3.0.17`, `3.0.18`, `3.0.19`, `3.0.20`, `3.0.21`, `3.0.22`, `3.0.23`, `3.0.24`, `3.0.25`, `3.1.0`, `3.1`, `3.1.1`, `3.1.2`, `3.1.3`, `3.1.4`, `3.1.5`, `3.1.6`, `3.1.7`, `3.1.8`, `3.1.9`, `3.1.10`, `3.1.11`, `3.1.12`, `3.1.13`, `3.1.14`, `3.1.15`, `3.1.16`, `3.1.17`, `3.1.18`, `3.1.19`, `3.1.20`, `3.1.21`, `3.1.22`, `3.1.23`, `3.1.24`, `3.1.25`, `3.1.26`, `3.1.27`, `3.1.28`, `3.1.29`, `3.1.30`, `3.1.31`, `3.2.1`, `3.2`, `3.2.2`, `3.2.3`, `3.2.4`, `3.2.5`, `3.2.6`, `3.2.7`, `3.3.0-beta.3`, `3.3-beta.3` | @@ -26,8 +26,8 @@ pin using `ADCP_VERSION` inside that tarball. For a checkout at the published release commit, install the exact package version: ```bash -npm install --save-exact '@adcp/sdk@17.0.0-beta.11' -npm view '@adcp/sdk@17.0.0-beta.11' dist.integrity +npm install --save-exact '@adcp/sdk@17.0.0-beta.12' +npm view '@adcp/sdk@17.0.0-beta.12' dist.integrity ``` ### Required and optional peers diff --git a/package-lock.json b/package-lock.json index a7ddc6cf5..39e6f788c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@adcp/sdk", - "version": "17.0.0-beta.11", + "version": "17.0.0-beta.12", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@adcp/sdk", - "version": "17.0.0-beta.11", + "version": "17.0.0-beta.12", "license": "Apache-2.0", "workspaces": [ ".", @@ -9688,7 +9688,7 @@ "version": "6.0.0", "license": "Apache-2.0", "dependencies": { - "@adcp/sdk": "^17.0.0-beta.11" + "@adcp/sdk": "^17.0.0-beta.12" }, "bin": { "adcp": "bin/adcp.js" @@ -9716,7 +9716,7 @@ }, "packages/reporting-storage": { "name": "@adcp/reporting-storage", - "version": "0.3.0-beta.2", + "version": "0.3.0-beta.3", "license": "Apache-2.0", "bin": { "adcp-reporting-storage": "bin/adcp-reporting-storage.js" @@ -9732,7 +9732,7 @@ "node": "^20.19.0 || >=22.12.0" }, "peerDependencies": { - "@adcp/sdk": "^17.0.0-beta.11", + "@adcp/sdk": "^17.0.0-beta.12", "@aws-sdk/client-s3": "^3.700.0", "@azure/storage-blob": "^12.23.0", "@google-cloud/storage": "^7.22.0 || ^8.2.0" diff --git a/package.json b/package.json index 13f62ad21..8d8709247 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@adcp/sdk", - "version": "17.0.0-beta.11", + "version": "17.0.0-beta.12", "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)", "workspaces": [ ".", diff --git a/packages/client-shim/package.json b/packages/client-shim/package.json index a6129a841..c5ed201d0 100644 --- a/packages/client-shim/package.json +++ b/packages/client-shim/package.json @@ -106,7 +106,7 @@ "LICENSE" ], "dependencies": { - "@adcp/sdk": "^17.0.0-beta.11" + "@adcp/sdk": "^17.0.0-beta.12" }, "keywords": [ "adcp", diff --git a/packages/reporting-storage/CHANGELOG.md b/packages/reporting-storage/CHANGELOG.md index 861904db0..9c99add42 100644 --- a/packages/reporting-storage/CHANGELOG.md +++ b/packages/reporting-storage/CHANGELOG.md @@ -1,5 +1,38 @@ # @adcp/reporting-storage +## 0.3.0-beta.3 + +### Minor Changes + +- 8374d8d: Reporting subscriptions (experimental, AdCP 3.3): buyer events. + - `client.reporting.poll()` returns the events since the last acknowledgement, derived by comparing what the seller reports now (`reconcile`, the subscription readback, each account's `subscription_coverage[]`) with the snapshot saved by the last `batch.ack()`. Delivery is at least once with deterministic ids (`rse_` + `sha256(agent, type, natural key, version)`, the same ids as the Python SDK). A partial read never fabricates a change, and `poll({ baseline: true })` records the present without emitting it. + - `client.reporting.events({ pollEvery, signal })` is the loop: each batch is acknowledged after the loop body has run for all its events. + - `client.reporting.handleWebhook(verified)` treats a seller webhook as a doorbell: it wakes a running `events()` loop or polls inline. It takes only a `VerifiedWebhook`, built by `VerifiedWebhook.fromOutcome` from a successful signature verification. + - Event types: `revision.available`, `revision.adjusted`, `period.late`, `period.missing_obligation`, `period.withheld`, `coverage.exception_opened`, `coverage.exception_closed`, `account.covered`, `account.unauthorized`, `account.regranted`, `subscription.state_changed`, `timezone.cutover`. + - Snapshots live in a `ReportingEventStore` with compare-and-set (`ReportingEventConflictError` when another worker acknowledged first). `memoryStorage().events` and `postgresStorage({ pool }).events` provide one, `createReportingEventStore({ store })` builds one over any `AdcpStateStore` with `putIfMatch`, and the client takes it as `reportingEventStore`. + - `@adcp/sdk/reporting/advanced` adds `deriveEvents`, `EVENT_TYPES` and `SNAPSHOT_VERSION`. + +### Patch Changes + +- 8856bbd: The production service refuses `subscriptions.principal` without `notifications` with a message naming the fix. `@adcp/sdk` now lets development storage omit it; PostgreSQL storage still needs a delivering runtime. +- f31e94f: Reporting subscriptions (experimental, AdCP 3.3): a PostgreSQL production seller configured with `subscriptions.principal` now serves the same principal surface as the `memoryStorage()` seller. `createPostgresReliableReportingProductionService` builds the principal runtime with the `notification_configs` task (`syncAgentNotificationConfigs`) and marks it as service-built, so the service advertises `capability_changes` for it. Before, it served neither. +- Updated dependencies [a831111] +- Updated dependencies [b296a8a] +- Updated dependencies [9cf1b55] +- Updated dependencies [6141030] +- Updated dependencies [ed8f98d] +- Updated dependencies [b5f7461] +- Updated dependencies [d134d82] +- Updated dependencies [f31e94f] +- Updated dependencies [8374d8d] +- Updated dependencies [e4b43a3] +- Updated dependencies [7cfccfd] +- Updated dependencies [1da37d9] +- Updated dependencies [dc8cad8] +- Updated dependencies [b7b9ec8] +- Updated dependencies [8856bbd] + - @adcp/sdk@17.0.0-beta.12 + ## 0.3.0-beta.2 ### Minor Changes diff --git a/packages/reporting-storage/package.json b/packages/reporting-storage/package.json index b07cd5d76..3a09a0570 100644 --- a/packages/reporting-storage/package.json +++ b/packages/reporting-storage/package.json @@ -1,6 +1,6 @@ { "name": "@adcp/reporting-storage", - "version": "0.3.0-beta.2", + "version": "0.3.0-beta.3", "description": "Storage for AdCP Reliable Reporting: the PostgreSQL ledger store, row storage with GCS, S3 and Azure providers, managed delivery, notification activity and the BigQuery warehouse sink. Depends on @adcp/sdk for the protocol layer.", "main": "dist/index.js", "module": "./dist/index.mjs", @@ -168,7 +168,7 @@ "node": "^20.19.0 || >=22.12.0" }, "peerDependencies": { - "@adcp/sdk": "^17.0.0-beta.11", + "@adcp/sdk": "^17.0.0-beta.12", "@aws-sdk/client-s3": "^3.700.0", "@azure/storage-blob": "^12.23.0", "@google-cloud/storage": "^7.22.0 || ^8.2.0" diff --git a/src/lib/version.ts b/src/lib/version.ts index 87b708c2c..5c2fea4bd 100644 --- a/src/lib/version.ts +++ b/src/lib/version.ts @@ -4,7 +4,7 @@ /** * AdCP SDK library version */ -export const LIBRARY_VERSION = '17.0.0-beta.11'; +export const LIBRARY_VERSION = '17.0.0-beta.12'; /** * AdCP specification version this library is built for @@ -113,10 +113,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number]; * Full version information */ export const VERSION_INFO = { - library: '17.0.0-beta.11', + library: '17.0.0-beta.12', adcp: '3.3.0-beta.3', compatibleVersions: COMPATIBLE_ADCP_VERSIONS, - generatedAt: '2026-10-31T21:29:26.679Z', + generatedAt: '2026-11-02T04:12:19.065Z', } as const; /**