@adcp/sdk 6.6.0 → 6.7.0

package/dist/lib/adapters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,YAAY,EACZ,uBAAuB,GACxB,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,YAAY,EACZ,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAMlC,OAAO,EAAE,8BAA8B,EAAE,KAAK,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAOpH,OAAO,EAAE,wBAAwB,EAAE,KAAK,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/lib/adapters/index.js

@@ -11,9 +11,10 @@
  * - PropertyListAdapter: Manage buyer-defined property lists
  * - ProposalManager: Generate and refine media plan proposals
  * - SISessionManager: Handle Sponsored Intelligence conversational sessions
+ * - InMemoryImplicitAccountStore: AccountStore for resolution: 'implicit' platforms
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultSISessionManager = exports.SIErrorCodes = exports.AISISessionManager = exports.SISessionManager = exports.isGovernanceAdapterError = exports.GovernanceAdapterErrorCodes = exports.defaultGovernanceAdapter = exports.GovernanceAdapter = exports.defaultProposalManager = exports.ProposalErrorCodes = exports.AIProposalManager = exports.ProposalManager = exports.defaultPropertyListAdapter = exports.isPropertyListError = exports.PropertyListErrorCodes = exports.PropertyListAdapter = exports.defaultContentStandardsAdapter = exports.isContentStandardsError = exports.ContentStandardsErrorCodes = exports.ContentStandardsAdapter = void 0;
+exports.createRosterAccountStore = exports.createOAuthPassthroughResolver = exports.defaultImplicitKeyFn = exports.InMemoryImplicitAccountStore = exports.defaultSISessionManager = exports.SIErrorCodes = exports.AISISessionManager = exports.SISessionManager = exports.isGovernanceAdapterError = exports.GovernanceAdapterErrorCodes = exports.defaultGovernanceAdapter = exports.GovernanceAdapter = exports.defaultProposalManager = exports.ProposalErrorCodes = exports.AIProposalManager = exports.ProposalManager = exports.defaultPropertyListAdapter = exports.isPropertyListError = exports.PropertyListErrorCodes = exports.PropertyListAdapter = exports.defaultContentStandardsAdapter = exports.isContentStandardsError = exports.ContentStandardsErrorCodes = exports.ContentStandardsAdapter = void 0;
 // Content Standards
 var content_standards_adapter_1 = require("./content-standards-adapter");
 Object.defineProperty(exports, "ContentStandardsAdapter", { enumerable: true, get: function () { return content_standards_adapter_1.ContentStandardsAdapter; } });
@@ -44,4 +45,21 @@ Object.defineProperty(exports, "SISessionManager", { enumerable: true, get: func
 Object.defineProperty(exports, "AISISessionManager", { enumerable: true, get: function () { return si_session_manager_1.AISISessionManager; } });
 Object.defineProperty(exports, "SIErrorCodes", { enumerable: true, get: function () { return si_session_manager_1.SIErrorCodes; } });
 Object.defineProperty(exports, "defaultSISessionManager", { enumerable: true, get: function () { return si_session_manager_1.defaultSISessionManager; } });
+// Implicit Account Store (resolution: 'implicit') — Shape A reference adapter.
+var implicit_account_store_1 = require("./implicit-account-store");
+Object.defineProperty(exports, "InMemoryImplicitAccountStore", { enumerable: true, get: function () { return implicit_account_store_1.InMemoryImplicitAccountStore; } });
+Object.defineProperty(exports, "defaultImplicitKeyFn", { enumerable: true, get: function () { return implicit_account_store_1.defaultImplicitKeyFn; } });
+// OAuth pass-through resolver — closes adcp-client#1363. Shape B factory
+// for adapters wrapping a vendor OAuth + ad-account API; replaces the ~30
+// LOC of bearer-extract + listing-fetch + match-by-id boilerplate every
+// such adapter re-derives by hand.
+var oauth_passthrough_resolver_1 = require("./oauth-passthrough-resolver");
+Object.defineProperty(exports, "createOAuthPassthroughResolver", { enumerable: true, get: function () { return oauth_passthrough_resolver_1.createOAuthPassthroughResolver; } });
+// Roster-backed AccountStore — Shape C factory for `resolution: 'explicit'`
+// publisher-curated platforms. Adopters bring their own roster source (admin-UI
+// managed DB row, in-memory map, file); the helper provides AccountStore
+// plumbing (resolve dispatch, optional list, ctx threading) with no opinion on
+// where the roster lives.
+var roster_account_store_1 = require("./roster-account-store");
+Object.defineProperty(exports, "createRosterAccountStore", { enumerable: true, get: function () { return roster_account_store_1.createRosterAccountStore; } });
 //# sourceMappingURL=index.js.map

package/dist/lib/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/adapters/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,oBAAoB;AACpB,yEAOqC;AANnC,oIAAA,uBAAuB,OAAA;AAGvB,uIAAA,0BAA0B,OAAA;AAC1B,oIAAA,uBAAuB,OAAA;AACvB,2IAAA,8BAA8B,OAAA;AAGhC,iBAAiB;AACjB,iEAOiC;AAN/B,4HAAA,mBAAmB,OAAA;AAGnB,+HAAA,sBAAsB,OAAA;AACtB,4HAAA,mBAAmB,OAAA;AACnB,mIAAA,0BAA0B,OAAA;AAG5B,sBAAsB;AACtB,uDAO4B;AAN1B,mHAAA,eAAe,OAAA;AACf,qHAAA,iBAAiB,OAAA;AAGjB,sHAAA,kBAAkB,OAAA;AAClB,0HAAA,sBAAsB,OAAA;AAGxB,4CAA4C;AAC5C,2DAS8B;AAR5B,uHAAA,iBAAiB,OAAA;AACjB,8HAAA,wBAAwB,OAAA;AAKxB,iIAAA,2BAA2B,OAAA;AAC3B,8HAAA,wBAAwB,OAAA;AAG1B,kCAAkC;AAClC,2DAO8B;AAN5B,sHAAA,gBAAgB,OAAA;AAChB,wHAAA,kBAAkB,OAAA;AAGlB,kHAAA,YAAY,OAAA;AACZ,6HAAA,uBAAuB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/adapters/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,oBAAoB;AACpB,yEAOqC;AANnC,oIAAA,uBAAuB,OAAA;AAGvB,uIAAA,0BAA0B,OAAA;AAC1B,oIAAA,uBAAuB,OAAA;AACvB,2IAAA,8BAA8B,OAAA;AAGhC,iBAAiB;AACjB,iEAOiC;AAN/B,4HAAA,mBAAmB,OAAA;AAGnB,+HAAA,sBAAsB,OAAA;AACtB,4HAAA,mBAAmB,OAAA;AACnB,mIAAA,0BAA0B,OAAA;AAG5B,sBAAsB;AACtB,uDAO4B;AAN1B,mHAAA,eAAe,OAAA;AACf,qHAAA,iBAAiB,OAAA;AAGjB,sHAAA,kBAAkB,OAAA;AAClB,0HAAA,sBAAsB,OAAA;AAGxB,4CAA4C;AAC5C,2DAS8B;AAR5B,uHAAA,iBAAiB,OAAA;AACjB,8HAAA,wBAAwB,OAAA;AAKxB,iIAAA,2BAA2B,OAAA;AAC3B,8HAAA,wBAAwB,OAAA;AAG1B,kCAAkC;AAClC,2DAO8B;AAN5B,sHAAA,gBAAgB,OAAA;AAChB,wHAAA,kBAAkB,OAAA;AAGlB,kHAAA,YAAY,OAAA;AACZ,6HAAA,uBAAuB,OAAA;AAGzB,+EAA+E;AAC/E,mEAIkC;AAHhC,sIAAA,4BAA4B,OAAA;AAC5B,8HAAA,oBAAoB,OAAA;AAItB,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,mCAAmC;AACnC,2EAAoH;AAA3G,4IAAA,8BAA8B,OAAA;AAEvC,4EAA4E;AAC5E,gFAAgF;AAChF,yEAAyE;AACzE,+EAA+E;AAC/E,0BAA0B;AAC1B,+DAAkG;AAAzF,gIAAA,wBAAwB,OAAA"}

package/dist/lib/adapters/oauth-passthrough-resolver.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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
+ */
+import type { Account, ResolveContext } from '../server/decisioning/account';
+import type { AccountReference } from '../types/tools.generated';
+import type { AuthContext, UpstreamHttpClient } from '../server/upstream-helpers';
+/**
+ * Options for {@link createOAuthPassthroughResolver}.
+ *
+ * @public
+ */
+export interface OAuthPassthroughResolverOptions<TUpstreamRow, TCtxMeta = Record<string, unknown>> {
+    /**
+     * Pre-configured upstream HTTP client (typically from
+     * {@link createUpstreamHttpClient}). Should be configured with
+     * `auth: { kind: 'dynamic_bearer', getToken: (ctx) => ... }` so the
+     * factory's `getAuthContext` output flows through to bearer selection.
+     */
+    httpClient: UpstreamHttpClient;
+    /**
+     * Path on the upstream API that returns the buyer's accounts. Common
+     * shapes: `/v1/adaccounts`, `/me/adaccounts`, `/customers`.
+     */
+    listEndpoint: string;
+    /**
+     * Property on each upstream row matching the wire `AccountReference.account_id`.
+     * Defaults to `'id'`.
+     *
+     * **Footgun:** when the generic `TUpstreamRow` is inferred (no explicit
+     * type argument), `keyof TUpstreamRow & string` collapses to `string` and
+     * a typo in `idField` compiles fine but silently always returns `null`.
+     * Pass an explicit `TUpstreamRow` (or a dummy interface with the upstream's
+     * field names) to get compile-time field validation.
+     */
+    idField?: keyof TUpstreamRow & string;
+    /**
+     * Property on the upstream response body that contains the array of rows.
+     * Defaults to `'data'` (Snap, Meta envelope shape). Set to `null` when the
+     * response body itself is the array (some flat-list APIs).
+     *
+     * Single-segment only. APIs with deeper nesting (TikTok's `data.list`,
+     * for example) need a custom response transform — wrap the upstream client
+     * with a fetch override that flattens, or use this factory only for the
+     * 70%-fit upstream shape and write a hand-rolled resolver for the rest.
+     * Google Ads' `customers:listAccessibleCustomers` returns string resource
+     * names (not row objects) and is not a fit for this factory.
+     */
+    rowsPath?: string | null;
+    /**
+     * Extract the auth context to forward to the upstream's
+     * `dynamic_bearer.getToken(ctx)` resolver. The return value flows through
+     * as the `authContext` per-call option on `httpClient.get`.
+     *
+     * Defaults to forwarding `ctx?.authInfo` verbatim — works when the http
+     * client's `getToken` resolver reads `ctx.authInfo.token` /
+     * `ctx.authInfo.credential.token`.
+     */
+    getAuthContext?: (ctx: ResolveContext | undefined) => AuthContext | undefined;
+    /**
+     * Map an upstream row to a framework `Account<TCtxMeta>`. Adapters
+     * typically embed the raw row (or distilled fields) in `ctx_metadata` so
+     * downstream specialism methods can read upstream IDs, tokens, etc.
+     * without re-resolving.
+     *
+     * **Treat `ctx_metadata.accessToken` (or any embedded credential) as a
+     * secret.** The framework strips `ctx_metadata` from the wire response,
+     * but adopter code that throws an error containing `JSON.stringify(account)`
+     * or logs `ctx.account` at info level WILL leak the token. Either don't
+     * embed the bearer (re-derive from `ctx.authInfo` on each downstream
+     * method), or audit your error projections.
+     */
+    toAccount: (row: TUpstreamRow, ctx: ResolveContext | undefined) => Account<TCtxMeta>;
+    /**
+     * Optional in-memory listing cache. Caches the full row array per buyer
+     * (keyed on the auth context); resolves `account_id` matches in-memory
+     * within the TTL window. One upstream hit per buyer per TTL period
+     * regardless of how many account_ids that buyer queries.
+     *
+     * Set `ttlMs` to enable (default: no cache, every resolve hits upstream).
+     *
+     * **TTL guidance:**
+     * - **Read tools** (`get_products`, `list_creative_formats`): 60–300s.
+     *   Buyer-side latency dominates; longer TTL absorbs bursts.
+     * - **Mutating tools** (`create_media_buy`, `update_media_buy`,
+     *   `sync_creatives`): 0–30s, or compose `composeMethod` to skip cache
+     *   on these paths. A revoked-but-not-yet-expired bearer would otherwise
+     *   continue authorizing mutations for the full TTL window.
+     *
+     * `getCacheKey` defaults to a SHA-256 hash of the JSON-serialized auth
+     * context. Hashing (vs raw stringification) keeps the bearer token out
+     * of Map keys — heap dumps and `util.inspect(cache)` no longer surface
+     * plaintext credentials. Provide a custom key when the auth context
+     * contains noise (timestamps, request ids) that would defeat caching.
+     *
+     * Cache size is naturally bounded by the number of distinct buyers
+     * times one entry each. Adopters with token-rotation churn can cap with
+     * `maxEntries` (LRU eviction).
+     */
+    cache?: {
+        ttlMs: number;
+        getCacheKey?: (authContext: AuthContext | undefined) => string;
+        /** LRU eviction cap. Defaults to 1024 — enough for most multi-tenant deployments. */
+        maxEntries?: number;
+    };
+}
+/**
+ * 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
+ */
+export declare function createOAuthPassthroughResolver<TUpstreamRow extends Record<string, unknown>, TCtxMeta = Record<string, unknown>>(options: OAuthPassthroughResolverOptions<TUpstreamRow, TCtxMeta>): (ref: AccountReference | undefined, ctx?: ResolveContext) => Promise<Account<TCtxMeta> | null>;
+//# sourceMappingURL=oauth-passthrough-resolver.d.ts.map

package/dist/lib/adapters/oauth-passthrough-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-passthrough-resolver.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/oauth-passthrough-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,+BAA+B,CAAC,YAAY,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/F;;;;;OAKG;IACH,UAAU,EAAE,kBAAkB,CAAC;IAE/B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,YAAY,GAAG,MAAM,CAAC;IAEtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,KAAK,WAAW,GAAG,SAAS,CAAC;IAE9E;;;;;;;;;;;;OAYG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,GAAG,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,KAAK,MAAM,CAAC;QAC/D,qFAAqF;QACrF,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,8BAA8B,CAC5C,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAElC,OAAO,EAAE,+BAA+B,CAAC,YAAY,EAAE,QAAQ,CAAC,GAC/D,CAAC,GAAG,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CA2DhG"}

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":"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"}

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"}