@adcp/sdk 6.6.0 → 6.8.0

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

@@ -0,0 +1,180 @@
+"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?** Four 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).
+ * - **No account concept — auth principal IS the tenant** → `createDerivedAccountStore`
+ *   (Shape D, `resolution: 'derived'`).
+ *
+ * @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,282 @@
+/**
+ * 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.
+ * - **No account concept — auth principal IS the tenant** → `createDerivedAccountStore`
+ *   (Shape D, `resolution: 'derived'`). Single-tenant agents
+ *   (audiostack, flashtalking, single-namespace retail-media) where there
+ *   is no `account_id` on the wire and every call authenticates with the
+ *   per-request bearer.
+ *
+ * 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>>;
+    /**
+     * Handle ref-less `accounts.resolve(undefined, ctx)` calls — invoked by
+     * `list_creative_formats`, `provide_performance_feedback`, `preview_creative`,
+     * and any discovery-phase tool that does not require a buyer-selected account.
+     *
+     * Return a synthetic publisher-wide roster entry; `toAccount` is applied to
+     * it before the result is returned to the framework. Return `undefined` to
+     * fall back to `null` (same as omitting this option — `ctx.account` is
+     * `undefined` in the handler).
+     *
+     * The `ref` parameter is always `undefined` here — it is present for
+     * signature parity with the framework's `resolve(ref, ctx)` shape so
+     * code-generation tools produce consistent two-arg handler signatures.
+     * Ignore it (use `(_ref, ctx) => ...`).
+     *
+     * 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 returns `null` to the framework.
+     *
+     * **Brand+operator refs are not routed here.** A `{ brand, operator }` ref
+     * without an `account_id` still falls through to `null`. Adopters who need
+     * to handle brand-arm refs must override `resolve` on the returned store via
+     * a spread.
+     *
+     * **`toAccount` is called on your return value** with the same `ctx`,
+     * identical to the `lookup` path. Ensure your synthesized entry satisfies
+     * all required fields of `TRosterEntry`.
+     *
+     * **Auth-derived lookup.** If your singleton should be derived from
+     * `ctx.authInfo` (e.g. a per-tenant publisher account keyed on the OAuth
+     * client), and that derivation needs to re-invoke `lookup`, use the
+     * spread-override pattern on the returned store instead — a `resolveWithoutRef`
+     * that calls back into `lookup` is more naturally expressed as a `resolve`
+     * override so the call graph stays flat.
+     *
+     * **If you also override `resolve` on the spread**, `resolveWithoutRef` is
+     * not called — the spread override takes precedence.
+     *
+     * Omit when `ctx.account === undefined` is acceptable for ref-less tools
+     * (handlers can narrow on it and fall back to platform-level config from
+     * their closure).
+     */
+    resolveWithoutRef?: (ref: undefined, ctx: ResolveContext | undefined) => TRosterEntry | undefined | Promise<TRosterEntry | undefined>;
+}
+/**
+ * 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 `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)`. Use `resolveWithoutRef` when your
+ * platform needs a synthetic publisher-wide account for these tools:
+ *
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup,
+ *   toAccount,
+ *   resolveWithoutRef: () => ({ id: '__publisher__', label: 'Publisher', tenantId: myPlatformId }),
+ * });
+ * ```
+ *
+ * The returned entry flows through `toAccount` just like a `lookup` hit.
+ * When omitted the helper returns `null` for ref-less calls — handlers can
+ * narrow on `ctx.account === undefined` and fall back to platform-level
+ * config from their closure.
+ *
+ * **Ref-less calls (singleton from options):**
+ * ```ts
+ * const accounts = createRosterAccountStore({
+ *   lookup,
+ *   toAccount,
+ *   resolveWithoutRef: (_ref, ctx) => ({
+ *     id: '__publisher__',
+ *     name: 'Publisher',
+ *     tenant_id: deriveTenant(ctx?.authInfo),
+ *   }),
+ * });
+ * ```
+ *
+ * **Ref-less calls (auth-derived lookup).** When the singleton should be
+ * derived from the caller's principal and needs to call back into `lookup`,
+ * use the spread-override pattern instead:
+ *
+ * ```ts
+ * const base = createRosterAccountStore({ lookup, toAccount });
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...base,
+ *   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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;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;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,iBAAiB,CAAC,EAAE,CAClB,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,cAAc,GAAG,SAAS,KAC5B,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsIG;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,CAsCxB"}