@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/adapters/oauth-passthrough-resolver.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * OAuth pass-through `accounts.resolve` factory. Standardizes the canonical
+ * "Shape B" account-resolution pattern: an adapter wraps a vendor OAuth +
+ * ad-account API (Snap, Meta, TikTok, LinkedIn, Reddit, Pinterest, etc.) and
+ * resolves the buyer's `AccountReference` by hitting the upstream's
+ * "list-my-accounts" endpoint with the buyer's bearer.
+ *
+ * Without this factory, every Shape B adapter rolls the same ~30 LOC:
+ * extract bearer from `ctx.authInfo`, GET `/me/adaccounts`, match by id,
+ * return tenant with `ctx_metadata` populated. This factory handles the
+ * boilerplate; the adapter supplies the upstream specifics
+ * (`listEndpoint`, `toAccount` mapper) and the auth shape via
+ * {@link createUpstreamHttpClient}'s `dynamic_bearer.getToken`.
+ *
+ * Closes adcp-client#1363.
+ *
+ * **Picking an AccountStore?** Three reference shapes by *who creates the
+ * account*:
+ * - **Buyer self-onboards via `sync_accounts`** → `InMemoryImplicitAccountStore`
+ *   (Shape A).
+ * - **Upstream OAuth API owns the roster** → `createOAuthPassthroughResolver`
+ *   (this file, Shape B, returns just `resolve`).
+ * - **Publisher ops curates the roster** → `createRosterAccountStore`
+ *   (Shape C, complete AccountStore).
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOAuthPassthroughResolver = createOAuthPassthroughResolver;
+const node_crypto_1 = require("node:crypto");
+const account_1 = require("../server/decisioning/account");
+/**
+ * Create an `accounts.resolve` implementation that resolves buyer-supplied
+ * `AccountReference` against an upstream OAuth-protected listing endpoint.
+ * Returns just the resolve function — adapters compose it into their own
+ * `AccountStore` (typically alongside a no-op `upsert` since Shape B
+ * adapters don't manage account lifecycle).
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createUpstreamHttpClient,
+ *   createOAuthPassthroughResolver,
+ *   defineSalesPlatform,
+ * } from '@adcp/sdk/server';
+ *
+ * const snap = createUpstreamHttpClient({
+ *   baseUrl: 'https://adsapi.snapchat.com',
+ *   auth: {
+ *     kind: 'dynamic_bearer',
+ *     getToken: async (ctx) => (ctx as any)?.authInfo?.credential?.token,
+ *   },
+ * });
+ *
+ * const resolve = createOAuthPassthroughResolver({
+ *   httpClient: snap,
+ *   listEndpoint: '/v1/me/adaccounts',
+ *   idField: 'id',
+ *   rowsPath: 'adaccounts',
+ *   toAccount: (row, ctx) => ({
+ *     id: row.id,
+ *     name: row.name,
+ *     status: 'active',
+ *     advertiser: row.advertiser_url,
+ *     ctx_metadata: {
+ *       upstreamId: row.id,
+ *       // Treat as secret — see `toAccount` JSDoc above.
+ *       accessToken: (ctx as any)?.authInfo?.credential?.token,
+ *     },
+ *   }),
+ *   cache: { ttlMs: 60_000 },
+ * });
+ *
+ * defineSalesPlatform({
+ *   accounts: { resolve },
+ *   ...
+ * });
+ * ```
+ *
+ * Behavior:
+ * - The factory only handles the `{ account_id }` discriminated-union arm.
+ *   Other arms (`{ brand, operator }`) and `undefined` ref return `null`
+ *   without calling upstream.
+ * - Upstream throws (4xx/5xx other than 404) propagate verbatim — adopters
+ *   compose `composeMethod` over the result if they want to catch and map
+ *   to a typed envelope (e.g. throw `AdcpError('AUTH_REQUIRED')` on 401).
+ * - Cache is opt-in and listing-keyed: one upstream hit per buyer per TTL
+ *   window regardless of how many `account_id`s that buyer queries.
+ *
+ * @public
+ */
+function createOAuthPassthroughResolver(options) {
+    const idField = (options.idField ?? 'id');
+    const rowsPath = options.rowsPath === undefined ? 'data' : options.rowsPath;
+    const getAuthContext = options.getAuthContext ??
+        ((ctx) => ctx?.authInfo);
+    const cacheTtlMs = options.cache?.ttlMs;
+    const getCacheKey = options.cache?.getCacheKey ?? defaultGetCacheKey;
+    const maxEntries = options.cache?.maxEntries ?? 1024;
+    const cache = cacheTtlMs !== undefined ? new Map() : undefined;
+    return async (ref, ctx) => {
+        const accountId = (0, account_1.refAccountId)(ref);
+        if (accountId === undefined)
+            return null;
+        const authContext = getAuthContext(ctx);
+        let cacheKey;
+        let rows = null;
+        if (cache !== undefined) {
+            cacheKey = getCacheKey(authContext);
+            const hit = cache.get(cacheKey);
+            if (hit !== undefined && hit.expiresAt > Date.now()) {
+                // Refresh LRU position on hit.
+                cache.delete(cacheKey);
+                cache.set(cacheKey, hit);
+                rows = hit.rows;
+            }
+            else if (hit !== undefined) {
+                cache.delete(cacheKey);
+            }
+        }
+        if (rows === null) {
+            const result = await options.httpClient.get(options.listEndpoint, undefined, undefined, authContext !== undefined ? { authContext } : undefined);
+            if (result.body == null)
+                return null;
+            rows = extractRows(result.body, rowsPath);
+            if (rows === null)
+                return null;
+            if (cache !== undefined && cacheKey !== undefined) {
+                // Evict oldest entry first when at capacity. Map iteration order is
+                // insertion order, so the first key is the LRU-coldest after the
+                // hit-side refresh above.
+                if (cache.size >= maxEntries) {
+                    const oldest = cache.keys().next().value;
+                    if (oldest !== undefined)
+                        cache.delete(oldest);
+                }
+                cache.set(cacheKey, { rows, expiresAt: Date.now() + cacheTtlMs });
+            }
+        }
+        const match = rows.find(row => row[idField] === accountId);
+        if (match === undefined)
+            return null;
+        return options.toAccount(match, ctx);
+    };
+}
+/**
+ * Default cache-key derivation: SHA-256 of the JSON-serialized auth context.
+ * Hashing keeps the bearer token out of Map keys (no plaintext credential
+ * surfaces in heap dumps or `util.inspect(cache)` output).
+ *
+ * Falls back to a literal `<none>` key when the auth context is undefined,
+ * and to the truncated stringified value when JSON serialization throws
+ * (circular refs, BigInt, etc.) — adopters with non-serializable auth
+ * contexts should provide their own `getCacheKey`.
+ */
+function defaultGetCacheKey(authContext) {
+    if (authContext === undefined)
+        return '<none>';
+    let serialized;
+    try {
+        serialized = JSON.stringify(authContext);
+    }
+    catch {
+        return `<unserializable:${String(authContext).slice(0, 64)}>`;
+    }
+    return (0, node_crypto_1.createHash)('sha256').update(serialized).digest('hex');
+}
+function extractRows(body, rowsPath) {
+    if (rowsPath === null) {
+        return Array.isArray(body) ? body : null;
+    }
+    if (body === null || typeof body !== 'object')
+        return null;
+    const rows = body[rowsPath];
+    return Array.isArray(rows) ? rows : null;
+}
+//# sourceMappingURL=oauth-passthrough-resolver.js.map

package/dist/lib/adapters/oauth-passthrough-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-passthrough-resolver.js","sourceRoot":"","sources":["../../../src/lib/adapters/oauth-passthrough-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AAmLH,wEAgEC;AAjPD,6CAAyC;AAEzC,2DAA6D;AAmH7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,SAAgB,8BAA8B,CAI5C,OAAgE;IAEhE,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAgC,CAAC;IACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC5E,MAAM,cAAc,GAClB,OAAO,CAAC,cAAc;QACtB,CAAC,CAAC,GAA+B,EAAE,EAAE,CAAC,GAAG,EAAE,QAA8C,CAAC,CAAC;IAE7F,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;IACxC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,WAAW,IAAI,kBAAkB,CAAC;IACrE,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,EAAE,UAAU,IAAI,IAAI,CAAC;IACrD,MAAM,KAAK,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,EAA2C,CAAC,CAAC,CAAC,SAAS,CAAC;IAExG,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,SAAS,GAAG,IAAA,sBAAY,EAAC,GAAG,CAAC,CAAC;QACpC,IAAI,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAEzC,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,QAA4B,CAAC;QACjC,IAAI,IAAI,GAA0B,IAAI,CAAC;QAEvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,QAAQ,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBACpD,+BAA+B;gBAC/B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACvB,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBACzB,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YAClB,CAAC;iBAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBAC7B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,CACzC,OAAO,CAAC,YAAY,EACpB,SAAS,EACT,SAAS,EACT,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CACxD,CAAC;YACF,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;YACrC,IAAI,GAAG,WAAW,CAAe,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACxD,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAClD,oEAAoE;gBACpE,iEAAiE;gBACjE,0BAA0B;gBAC1B,IAAI,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC;oBAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;oBACzC,IAAI,MAAM,KAAK,SAAS;wBAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACjD,CAAC;gBACD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAW,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC;QAC3D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CAAC,WAAoC;IAC9D,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC/C,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,mBAAmB,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;IAChE,CAAC;IACD,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,WAAW,CAAe,IAAa,EAAE,QAAuB;IACvE,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAuB,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,IAAI,GAAI,IAAgC,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAuB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC"}

package/dist/lib/adapters/roster-account-store.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Roster-backed `AccountStore` factory for `resolution: 'explicit'` platforms
+ * where the publisher curates accounts out-of-band (admin UI, config file,
+ * publisher-managed DB row) and buyers pass `account_id` on every request.
+ *
+ * Pairs with the existing reference adapters. Pick by asking *who creates the
+ * account?*:
+ * - **Buyer self-onboards via `sync_accounts`** → {@link InMemoryImplicitAccountStore}
+ *   (Shape A, `resolution: 'implicit'`). Framework owns persistence; the
+ *   buyer's first request to a tenant-scoped tool resolves from a prior
+ *   sync. LinkedIn, some retail-media operators.
+ * - **Upstream OAuth API owns the roster** → {@link createOAuthPassthroughResolver}
+ *   (Shape B, `resolution: 'explicit'`). Returns just the `resolve` function;
+ *   adopter composes into an AccountStore. Snap, Meta, TikTok — anywhere
+ *   the buyer's bearer is the lookup key for an upstream `/me/adaccounts`.
+ * - **Publisher ops curates the roster out-of-band** → `createRosterAccountStore`
+ *   (this file, Shape C, `resolution: 'explicit'`). Adopter keeps the
+ *   persistence layer (storefront table, admin-UI-managed JSON column,
+ *   in-memory map); the SDK provides the AccountStore plumbing. Most
+ *   SSPs, broadcasters, and retail-media networks where AE/CSM provisions
+ *   the account in an internal admin tool before the buyer ever calls.
+ *
+ * Design notes:
+ * - Lookup is a point function, not a roster getter. An adopter with
+ *   thousands of accounts per tenant in Postgres can issue a SELECT WHERE
+ *   id = $1 instead of materializing the full array on every request.
+ * - `list` is opt-in. Omit it and the framework emits UNSUPPORTED_FEATURE
+ *   for `list_accounts` calls (matches `AccountStore.list?` semantics).
+ *   Provide it and the adopter pushes filter+page down to whatever index
+ *   they have.
+ * - No `upsert`, `reportUsage`, `getAccountFinancials`, or `refreshToken`.
+ *   Adopters who need those compose the helper output:
+ *   `{ ...createRosterAccountStore(...), refreshToken: async (a) => { ... } }`.
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+import type { Account, AccountFilter, AccountStore, ResolveContext } from '../server/decisioning/account';
+import type { CursorPage, CursorRequest } from '../server/decisioning/pagination';
+/**
+ * Options for {@link createRosterAccountStore}.
+ *
+ * @public
+ */
+export interface RosterAccountStoreOptions<TRosterEntry, TCtxMeta = Record<string, unknown>> {
+    /**
+     * Point-lookup against the adopter's roster source. Return the entry for
+     * a given `account_id`, or `undefined` when no row matches.
+     *
+     * Called once per `resolve()` with an `account_id`-shaped reference. Wire
+     * shape `{ brand, operator }` and missing refs do NOT call `lookup`; see
+     * the resolve behavior below.
+     *
+     * Throw to signal a transient upstream failure (DB outage, network blip).
+     * The framework projects to `SERVICE_UNAVAILABLE`. Returning `undefined`
+     * is the canonical not-found path and projects to `ACCOUNT_NOT_FOUND`.
+     */
+    lookup: (accountId: string, ctx: ResolveContext | undefined) => TRosterEntry | undefined | Promise<TRosterEntry | undefined>;
+    /**
+     * Convert a roster entry to the framework's `Account<TCtxMeta>` shape.
+     *
+     * The adopter's roster row typically lacks `ctx_metadata` (which is a
+     * framework-internal field). This mapper is where the adopter populates
+     * it — upstream IDs, per-account caches, anything specialism methods will
+     * read off `ctx.account.ctx_metadata` later.
+     *
+     * **DO NOT put credentials in `ctx_metadata`.** See
+     * `docs/guides/CTX-METADATA-SAFETY.md` for the rationale and the
+     * recommended re-derive-per-request pattern (read tokens off
+     * `ctx.authInfo` instead).
+     *
+     * Adopters MAY omit `authInfo` from the returned `Account` — the
+     * framework auto-attaches the principal from `ctx.authInfo` when absent.
+     */
+    toAccount: (entry: TRosterEntry, ctx: ResolveContext | undefined) => Account<TCtxMeta>;
+    /**
+     * Optional `list_accounts` implementation. The adopter receives the wire
+     * filter + cursor request and returns a page of roster entries; the
+     * helper threads each entry through `toAccount` before returning.
+     *
+     * Omit to leave `list_accounts` unimplemented (framework returns
+     * `UNSUPPORTED_FEATURE`).
+     *
+     * **Push filter + pagination down.** The naive shape — fetch the full
+     * roster, filter+slice in memory — works for tens of accounts per tenant
+     * but does not scale. Adopters with a Postgres-backed roster should map
+     * `filter.brand_domain` / `filter.operator` / `filter.status[]` /
+     * `cursor` / `limit` to a SQL query. The helper does NOT post-filter;
+     * the adopter is the source of truth.
+     *
+     * **No default status filter.** `filter.status` is `undefined` unless the
+     * buyer passed it. If you want production callers to see only `active` +
+     * `pending_approval` by default, apply that fallback inside your query —
+     * the helper passes `filter` through verbatim.
+     */
+    list?: (filter: AccountFilter & CursorRequest, ctx: ResolveContext | undefined) => CursorPage<TRosterEntry> | Promise<CursorPage<TRosterEntry>>;
+}
+/**
+ * Build an `AccountStore<TCtxMeta>` from an adopter-supplied roster source.
+ *
+ * The adopter brings persistence (DB row, admin-UI-managed JSON column,
+ * in-memory Map, file). The helper provides:
+ * - `resolution: 'explicit'` declaration
+ * - `account_id`-arm dispatch from the wire reference
+ * - Mapping from roster entry → `Account<TCtxMeta>` via `toAccount`
+ * - Optional `list_accounts` plumbing with cursor envelope passthrough
+ * - `null` return for `{ brand, operator }`-shaped refs and ref-less
+ *   calls (publisher-curated platforms expect explicit ids)
+ *
+ * Adopters who need to handle ref-less calls (`provide_performance_feedback`,
+ * `list_creative_formats`, `preview_creative`), special account shapes,
+ * `upsert` (buyer-driven write paths via `sync_accounts`), `refreshToken`,
+ * `reportUsage`, or `getAccountFinancials` compose on top of the returned
+ * store with a spread:
+ *
+ * ```ts
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createRosterAccountStore({ lookup, toAccount }),
+ *   refreshToken: async (account) => myUpstream.refresh(account),
+ * };
+ * ```
+ *
+ * **Ref-less calls (singleton fallback).** `list_creative_formats`,
+ * `preview_creative`, and `provide_performance_feedback` call
+ * `accounts.resolve(undefined, ctx)`. The helper returns `null` for these
+ * by default — handlers narrow on `ctx.account === undefined`. If your
+ * platform needs a synth "publisher tenant" instead, wrap `resolve`:
+ *
+ * ```ts
+ * const base = createRosterAccountStore({ lookup, toAccount });
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...base,
+ *   resolve: async (ref, ctx) => {
+ *     if (ref === undefined) {
+ *       return { id: '__publisher__', name: 'Publisher', status: 'active', ctx_metadata: {} };
+ *     }
+ *     return base.resolve(ref, ctx);
+ *   },
+ * };
+ * ```
+ *
+ * **Ref-less calls (auth-principal lookup).** Same wrap pattern when the
+ * synth tenant should be derived from the caller's principal — useful for
+ * `provide_performance_feedback` where the buyer giving feedback identifies
+ * the tenant:
+ *
+ * ```ts
+ * resolve: async (ref, ctx) => {
+ *   if (ref === undefined) {
+ *     const id = deriveAccountIdFromAuth(ctx?.authInfo);
+ *     return id ? base.resolve({ account_id: id }, ctx) : null;
+ *   }
+ *   return base.resolve(ref, ctx);
+ * },
+ * ```
+ *
+ * **Hybrid roster + buyer-updatable fields.** Some publisher-curated
+ * platforms (GAM, FreeWheel, several retail-media networks) let the buyer
+ * PATCH a narrow set of fields — billing contact, AP email, agency-of-record
+ * cert — on a publisher-provisioned account, while keeping creation and
+ * commercial terms (credit limit, rate card) read-only to the buyer. Compose
+ * a partial `upsert` over the roster store and gate it on a field allowlist:
+ *
+ * ```ts
+ * const BUYER_WRITABLE = new Set(['billing_entity', 'setup']);
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createRosterAccountStore({ lookup, toAccount }),
+ *   upsert: async (refs, ctx) => refs.map(r => applyBuyerPatch(r, BUYER_WRITABLE, ctx)),
+ * };
+ * ```
+ *
+ * **Brand-arm refs return `null`.** Buyers who pass `{ brand, operator }`
+ * (no `account_id`) hit the framework's `ACCOUNT_NOT_FOUND` envelope. The
+ * helper cannot synthesize `INVALID_REQUEST` from inside `resolve` — if your
+ * platform needs to reject brand-arm refs as a wire-shape error rather than
+ * a not-found, wrap `resolve` and throw `AdcpError('INVALID_REQUEST', { field:
+ * 'account.brand' })` before delegating to the helper.
+ *
+ * @example In-memory roster (tests, small fixed configs):
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup: (id) => roster.get(id),
+ *   toAccount: (row) => ({
+ *     id: row.id,
+ *     name: row.name,
+ *     status: 'active',
+ *     ctx_metadata: { upstreamId: row.upstream_id },
+ *   }),
+ * });
+ * ```
+ *
+ * @example Postgres-backed roster (publisher with admin UI):
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup: async (id, ctx) => {
+ *     const tenantId = deriveTenant(ctx?.authInfo);
+ *     return await db.oneOrNone(
+ *       'SELECT * FROM storefront_accounts WHERE id = $1 AND tenant = $2',
+ *       [id, tenantId],
+ *     );
+ *   },
+ *   toAccount: (row) => ({
+ *     id: row.id,
+ *     name: row.name,
+ *     status: row.status,
+ *     brand: row.brand,
+ *     operator: row.operator,
+ *     ctx_metadata: { tenant: row.tenant, upstreamRef: row.upstream_ref },
+ *   }),
+ *   list: async (filter, ctx) => {
+ *     const tenantId = deriveTenant(ctx?.authInfo);
+ *     const rows = await db.any(buildListQuery(filter, tenantId));
+ *     return { items: rows, nextCursor: nextCursorFor(rows, filter) };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createRosterAccountStore<TRosterEntry, TCtxMeta = Record<string, unknown>>(options: RosterAccountStoreOptions<TRosterEntry, TCtxMeta>): AccountStore<TCtxMeta>;
+//# sourceMappingURL=roster-account-store.d.ts.map

package/dist/lib/adapters/roster-account-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster-account-store.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/roster-account-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE1G,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,yBAAyB,CAAC,YAAY,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzF;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CACN,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,cAAc,GAAG,SAAS,KAC5B,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAElE;;;;;;;;;;;;;;;OAeG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,GAAG,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,EAAE,CACL,MAAM,EAAE,aAAa,GAAG,aAAa,EACrC,GAAG,EAAE,cAAc,GAAG,SAAS,KAC5B,UAAU,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvF,OAAO,EAAE,yBAAyB,CAAC,YAAY,EAAE,QAAQ,CAAC,GACzD,YAAY,CAAC,QAAQ,CAAC,CAiCxB"}

package/dist/lib/adapters/roster-account-store.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Roster-backed `AccountStore` factory for `resolution: 'explicit'` platforms
+ * where the publisher curates accounts out-of-band (admin UI, config file,
+ * publisher-managed DB row) and buyers pass `account_id` on every request.
+ *
+ * Pairs with the existing reference adapters. Pick by asking *who creates the
+ * account?*:
+ * - **Buyer self-onboards via `sync_accounts`** → {@link InMemoryImplicitAccountStore}
+ *   (Shape A, `resolution: 'implicit'`). Framework owns persistence; the
+ *   buyer's first request to a tenant-scoped tool resolves from a prior
+ *   sync. LinkedIn, some retail-media operators.
+ * - **Upstream OAuth API owns the roster** → {@link createOAuthPassthroughResolver}
+ *   (Shape B, `resolution: 'explicit'`). Returns just the `resolve` function;
+ *   adopter composes into an AccountStore. Snap, Meta, TikTok — anywhere
+ *   the buyer's bearer is the lookup key for an upstream `/me/adaccounts`.
+ * - **Publisher ops curates the roster out-of-band** → `createRosterAccountStore`
+ *   (this file, Shape C, `resolution: 'explicit'`). Adopter keeps the
+ *   persistence layer (storefront table, admin-UI-managed JSON column,
+ *   in-memory map); the SDK provides the AccountStore plumbing. Most
+ *   SSPs, broadcasters, and retail-media networks where AE/CSM provisions
+ *   the account in an internal admin tool before the buyer ever calls.
+ *
+ * Design notes:
+ * - Lookup is a point function, not a roster getter. An adopter with
+ *   thousands of accounts per tenant in Postgres can issue a SELECT WHERE
+ *   id = $1 instead of materializing the full array on every request.
+ * - `list` is opt-in. Omit it and the framework emits UNSUPPORTED_FEATURE
+ *   for `list_accounts` calls (matches `AccountStore.list?` semantics).
+ *   Provide it and the adopter pushes filter+page down to whatever index
+ *   they have.
+ * - No `upsert`, `reportUsage`, `getAccountFinancials`, or `refreshToken`.
+ *   Adopters who need those compose the helper output:
+ *   `{ ...createRosterAccountStore(...), refreshToken: async (a) => { ... } }`.
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRosterAccountStore = createRosterAccountStore;
+const account_1 = require("../server/decisioning/account");
+/**
+ * Build an `AccountStore<TCtxMeta>` from an adopter-supplied roster source.
+ *
+ * The adopter brings persistence (DB row, admin-UI-managed JSON column,
+ * in-memory Map, file). The helper provides:
+ * - `resolution: 'explicit'` declaration
+ * - `account_id`-arm dispatch from the wire reference
+ * - Mapping from roster entry → `Account<TCtxMeta>` via `toAccount`
+ * - Optional `list_accounts` plumbing with cursor envelope passthrough
+ * - `null` return for `{ brand, operator }`-shaped refs and ref-less
+ *   calls (publisher-curated platforms expect explicit ids)
+ *
+ * Adopters who need to handle ref-less calls (`provide_performance_feedback`,
+ * `list_creative_formats`, `preview_creative`), special account shapes,
+ * `upsert` (buyer-driven write paths via `sync_accounts`), `refreshToken`,
+ * `reportUsage`, or `getAccountFinancials` compose on top of the returned
+ * store with a spread:
+ *
+ * ```ts
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createRosterAccountStore({ lookup, toAccount }),
+ *   refreshToken: async (account) => myUpstream.refresh(account),
+ * };
+ * ```
+ *
+ * **Ref-less calls (singleton fallback).** `list_creative_formats`,
+ * `preview_creative`, and `provide_performance_feedback` call
+ * `accounts.resolve(undefined, ctx)`. The helper returns `null` for these
+ * by default — handlers narrow on `ctx.account === undefined`. If your
+ * platform needs a synth "publisher tenant" instead, wrap `resolve`:
+ *
+ * ```ts
+ * const base = createRosterAccountStore({ lookup, toAccount });
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...base,
+ *   resolve: async (ref, ctx) => {
+ *     if (ref === undefined) {
+ *       return { id: '__publisher__', name: 'Publisher', status: 'active', ctx_metadata: {} };
+ *     }
+ *     return base.resolve(ref, ctx);
+ *   },
+ * };
+ * ```
+ *
+ * **Ref-less calls (auth-principal lookup).** Same wrap pattern when the
+ * synth tenant should be derived from the caller's principal — useful for
+ * `provide_performance_feedback` where the buyer giving feedback identifies
+ * the tenant:
+ *
+ * ```ts
+ * resolve: async (ref, ctx) => {
+ *   if (ref === undefined) {
+ *     const id = deriveAccountIdFromAuth(ctx?.authInfo);
+ *     return id ? base.resolve({ account_id: id }, ctx) : null;
+ *   }
+ *   return base.resolve(ref, ctx);
+ * },
+ * ```
+ *
+ * **Hybrid roster + buyer-updatable fields.** Some publisher-curated
+ * platforms (GAM, FreeWheel, several retail-media networks) let the buyer
+ * PATCH a narrow set of fields — billing contact, AP email, agency-of-record
+ * cert — on a publisher-provisioned account, while keeping creation and
+ * commercial terms (credit limit, rate card) read-only to the buyer. Compose
+ * a partial `upsert` over the roster store and gate it on a field allowlist:
+ *
+ * ```ts
+ * const BUYER_WRITABLE = new Set(['billing_entity', 'setup']);
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createRosterAccountStore({ lookup, toAccount }),
+ *   upsert: async (refs, ctx) => refs.map(r => applyBuyerPatch(r, BUYER_WRITABLE, ctx)),
+ * };
+ * ```
+ *
+ * **Brand-arm refs return `null`.** Buyers who pass `{ brand, operator }`
+ * (no `account_id`) hit the framework's `ACCOUNT_NOT_FOUND` envelope. The
+ * helper cannot synthesize `INVALID_REQUEST` from inside `resolve` — if your
+ * platform needs to reject brand-arm refs as a wire-shape error rather than
+ * a not-found, wrap `resolve` and throw `AdcpError('INVALID_REQUEST', { field:
+ * 'account.brand' })` before delegating to the helper.
+ *
+ * @example In-memory roster (tests, small fixed configs):
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup: (id) => roster.get(id),
+ *   toAccount: (row) => ({
+ *     id: row.id,
+ *     name: row.name,
+ *     status: 'active',
+ *     ctx_metadata: { upstreamId: row.upstream_id },
+ *   }),
+ * });
+ * ```
+ *
+ * @example Postgres-backed roster (publisher with admin UI):
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup: async (id, ctx) => {
+ *     const tenantId = deriveTenant(ctx?.authInfo);
+ *     return await db.oneOrNone(
+ *       'SELECT * FROM storefront_accounts WHERE id = $1 AND tenant = $2',
+ *       [id, tenantId],
+ *     );
+ *   },
+ *   toAccount: (row) => ({
+ *     id: row.id,
+ *     name: row.name,
+ *     status: row.status,
+ *     brand: row.brand,
+ *     operator: row.operator,
+ *     ctx_metadata: { tenant: row.tenant, upstreamRef: row.upstream_ref },
+ *   }),
+ *   list: async (filter, ctx) => {
+ *     const tenantId = deriveTenant(ctx?.authInfo);
+ *     const rows = await db.any(buildListQuery(filter, tenantId));
+ *     return { items: rows, nextCursor: nextCursorFor(rows, filter) };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+function createRosterAccountStore(options) {
+    const store = {
+        resolution: 'explicit',
+        async resolve(ref, ctx) {
+            const accountId = (0, account_1.refAccountId)(ref);
+            if (accountId !== undefined) {
+                const entry = await options.lookup(accountId, ctx);
+                return entry === undefined ? null : options.toAccount(entry, ctx);
+            }
+            // Brand+operator-shaped refs (no account_id) and ref-less calls fall
+            // through to null. Publisher-curated platforms expect explicit ids;
+            // adopters who want a synth tenant for `list_creative_formats` /
+            // `provide_performance_feedback` / `preview_creative`, or brand-arm
+            // resolution, wrap `resolve` — see the JSDoc on
+            // `createRosterAccountStore` for both patterns.
+            return null;
+        },
+    };
+    if (options.list !== undefined) {
+        const adopterList = options.list;
+        store.list = async (filter, ctx) => {
+            const page = await adopterList(filter, ctx);
+            return {
+                items: page.items.map(entry => options.toAccount(entry, ctx)),
+                ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+            };
+        };
+    }
+    return store;
+}
+//# sourceMappingURL=roster-account-store.js.map

package/dist/lib/adapters/roster-account-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster-account-store.js","sourceRoot":"","sources":["../../../src/lib/adapters/roster-account-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;;AAoMH,4DAmCC;AAnOD,2DAA6D;AAsE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyHG;AACH,SAAgB,wBAAwB,CACtC,OAA0D;IAE1D,MAAM,KAAK,GAA2B;QACpC,UAAU,EAAE,UAAU;QAEtB,KAAK,CAAC,OAAO,CAAC,GAAiC,EAAE,GAAoB;YACnE,MAAM,SAAS,GAAG,IAAA,sBAAY,EAAC,GAAG,CAAC,CAAC;YACpC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;gBACnD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACpE,CAAC;YAED,qEAAqE;YACrE,oEAAoE;YACpE,iEAAiE;YACjE,oEAAoE;YACpE,gDAAgD;YAChD,gDAAgD;YAChD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;IAEF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;QACjC,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;YACjC,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO;gBACL,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAC7D,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;aACtE,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/auth/oauth/ClientCredentialsFlow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClientCredentialsFlow.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/ClientCredentialsFlow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAmC,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAOlD;;;;;;;;;;;;;GAaG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;aAIrC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS;aACvC,UAAU,CAAC,EAAE,MAAM;aACnB,qBAAqB,CAAC,EAAE,MAAM;aAC9B,UAAU,CAAC,EAAE,MAAM;IANrC,QAAQ,CAAC,IAAI,wCAAwC;gBAEnD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,EACvC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,qBAAqB,CAAC,EAAE,MAAM,YAAA,EAC9B,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA0FD;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,2BAA2B,EACxC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,gBAAgB,CAAC,CAuG3B;AAED;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CA6C3B"}
+{"version":3,"file":"ClientCredentialsFlow.d.ts","sourceRoot":"","sources":["../../../../src/lib/auth/oauth/ClientCredentialsFlow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAmC,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAQlD;;;;;;;;;;;;;GAaG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;aAIrC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS;aACvC,UAAU,CAAC,EAAE,MAAM;aACnB,qBAAqB,CAAC,EAAE,MAAM;aAC9B,UAAU,CAAC,EAAE,MAAM;IANrC,QAAQ,CAAC,IAAI,wCAAwC;gBAEnD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,EACvC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,qBAAqB,CAAC,EAAE,MAAM,YAAA,EAC9B,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA0FD;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,2BAA2B,EACxC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,gBAAgB,CAAC,CA0G3B;AAED;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CA6C3B"}

package/dist/lib/auth/oauth/ClientCredentialsFlow.js

@@ -35,6 +35,7 @@ exports.ensureClientCredentialsTokens = ensureClientCredentialsTokens;
 const types_1 = require("./types");
 const secret_resolver_1 = require("./secret-resolver");
 const net_1 = require("../../net");
+const responseSizeLimit_1 = require("../../protocols/responseSizeLimit");
 /** Max length we'll echo from an AS-supplied error description into errors. */
 const MAX_AS_ERROR_LENGTH = 200;
 /**
@@ -152,7 +153,10 @@ function validateTokenEndpoint(tokenEndpoint, options = {}) {
  * @throws {MissingEnvSecretError} if a `$ENV:VAR` ref points at an unset var
  */
 async function exchangeClientCredentials(credentials, options = {}) {
-    const fetchImpl = options.fetch ?? fetch;
+    // Wrap with the response-size-limit guard so a hostile token endpoint
+    // can't buffer-bomb on every refresh. Pass-through when no
+    // `withResponseSizeLimit` slot is active. (#1175)
+    const fetchImpl = (0, responseSizeLimit_1.wrapFetchWithSizeLimit)(options.fetch ?? fetch);
     const timeoutMs = options.timeoutMs ?? 30_000;
     validateTokenEndpoint(credentials.token_endpoint, { allowPrivateIp: options.allowPrivateIp });
     const clientId = (0, secret_resolver_1.resolveSecret)(credentials.client_id);