@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/core/TaskExecutor.js

@@ -43,6 +43,7 @@ var import_protocols = require('../protocols/index.js');
 var import_mcp_tasks = require('../protocols/mcp-tasks.js');
 var import_prepared_call_context = require('../protocols/prepared-call-context.js');
 var import_auth = require('../auth/index.js');
+var import_signedRequestRejection = require('../protocols/signedRequestRejection.js');
 var import_errors = require('../errors/index.js');
 var import_client_hooks = require('../validation/client-hooks.js');
 var import_schema_validator = require('../validation/schema-validator.js');
@@ -943,16 +944,19 @@ class TaskExecutor {
       (0, import_abort.throwIfAborted)(options.signal);
       if (beforeProtocolDispatch) {
         let decision;
-        dispatchBoundaryOwnsTerminalState = true;
+        const ownsSettlement = beforeProtocolDispatch.terminalSettlement !== "executor";
+        dispatchBoundaryOwnsTerminalState = ownsSettlement;
         try {
-          this.compactClosedExternalTaskSettlementFences();
-          if (this.liveExternalTaskSettlementCount() + this.settlementCapacityReservations.size >= COMPACTED_TASK_STATE_LIMIT) {
-            throw new Error("The durable task-settlement capacity is exhausted; no mutation claim was attempted.");
-          }
-          this.settlementCapacityReservations.add(taskId);
-          if (webhookRegistrationPersisted) {
-            await this.config.onDurableSettlementRequired?.(taskId);
-            (0, import_abort.throwIfAborted)(options.signal);
+          if (ownsSettlement) {
+            this.compactClosedExternalTaskSettlementFences();
+            if (this.liveExternalTaskSettlementCount() + this.settlementCapacityReservations.size >= COMPACTED_TASK_STATE_LIMIT) {
+              throw new Error("The durable task-settlement capacity is exhausted; no mutation claim was attempted.");
+            }
+            this.settlementCapacityReservations.add(taskId);
+            if (webhookRegistrationPersisted) {
+              await this.config.onDurableSettlementRequired?.(taskId);
+              (0, import_abort.throwIfAborted)(options.signal);
+            }
           }
           decision = await beforeProtocolDispatch(preparedCall.args, {
             operationId: taskId,
@@ -961,6 +965,7 @@ class TaskExecutor {
             registerExternalTaskSettlement: (handler) => this.registerExternalTaskSettlement(taskId, handler)
           });
           if (decision.action === "dispatch_committed") {
+            if (!ownsSettlement) throw new Error("An executor-settled dispatch hook cannot claim durable settlement.");
             if (decision.requireDeferredSettlementResumeAuthorization === true && this.config.deferredStorage !== void 0) {
               this.requireDeferredSettlementOperationRouting(this.config.deferredStorage);
             }
@@ -984,8 +989,8 @@ class TaskExecutor {
           }
           return (0, import_match.attachMatch)(earlyResult);
         }
-        dispatchCommitted = true;
-        dispatchSettlement = decision;
+        dispatchCommitted = decision.action === "dispatch_committed";
+        dispatchSettlement = decision.action === "dispatch_committed" ? decision : void 0;
       }
       (0, import_abort.throwIfAborted)(options.signal);
       const postDispatchOptions = dispatchCommitted ? { ...options, signal: void 0 } : options;
@@ -4212,7 +4217,7 @@ class TaskExecutor {
       status: "failed",
       error: error.message || String(error),
       adcpError: adcpErrorInfo,
-      errorInstance: this.buildErrorInstance(taskId, adcpErrorInfo),
+      errorInstance: (0, import_signedRequestRejection.getSignedRequestRejection)(error) ?? this.buildErrorInstance(taskId, adcpErrorInfo),
       correlationId,
       metadata: this.buildMetadata({
         taskId,

package/dist/lib/core/TaskExecutor.mjs

@@ -7,6 +7,7 @@ import {
 import { listMCPTasks } from "../protocols/mcp-tasks.mjs";
 import { withPreparedProtocolToolCall } from "../protocols/prepared-call-context.mjs";
 import { getAuthToken } from "../auth/index.mjs";
+import { getSignedRequestRejection } from "../protocols/signedRequestRejection.mjs";
 import { is401Error, adcpErrorToTypedError, ConfigurationError } from "../errors/index.mjs";
 import {
   validateOutgoingRequest,
@@ -916,16 +917,19 @@ class TaskExecutor {
       throwIfAborted(options.signal);
       if (beforeProtocolDispatch) {
         let decision;
-        dispatchBoundaryOwnsTerminalState = true;
+        const ownsSettlement = beforeProtocolDispatch.terminalSettlement !== "executor";
+        dispatchBoundaryOwnsTerminalState = ownsSettlement;
         try {
-          this.compactClosedExternalTaskSettlementFences();
-          if (this.liveExternalTaskSettlementCount() + this.settlementCapacityReservations.size >= COMPACTED_TASK_STATE_LIMIT) {
-            throw new Error("The durable task-settlement capacity is exhausted; no mutation claim was attempted.");
-          }
-          this.settlementCapacityReservations.add(taskId);
-          if (webhookRegistrationPersisted) {
-            await this.config.onDurableSettlementRequired?.(taskId);
-            throwIfAborted(options.signal);
+          if (ownsSettlement) {
+            this.compactClosedExternalTaskSettlementFences();
+            if (this.liveExternalTaskSettlementCount() + this.settlementCapacityReservations.size >= COMPACTED_TASK_STATE_LIMIT) {
+              throw new Error("The durable task-settlement capacity is exhausted; no mutation claim was attempted.");
+            }
+            this.settlementCapacityReservations.add(taskId);
+            if (webhookRegistrationPersisted) {
+              await this.config.onDurableSettlementRequired?.(taskId);
+              throwIfAborted(options.signal);
+            }
           }
           decision = await beforeProtocolDispatch(preparedCall.args, {
             operationId: taskId,
@@ -934,6 +938,7 @@ class TaskExecutor {
             registerExternalTaskSettlement: (handler) => this.registerExternalTaskSettlement(taskId, handler)
           });
           if (decision.action === "dispatch_committed") {
+            if (!ownsSettlement) throw new Error("An executor-settled dispatch hook cannot claim durable settlement.");
             if (decision.requireDeferredSettlementResumeAuthorization === true && this.config.deferredStorage !== void 0) {
               this.requireDeferredSettlementOperationRouting(this.config.deferredStorage);
             }
@@ -957,8 +962,8 @@ class TaskExecutor {
           }
           return attachMatch(earlyResult);
         }
-        dispatchCommitted = true;
-        dispatchSettlement = decision;
+        dispatchCommitted = decision.action === "dispatch_committed";
+        dispatchSettlement = decision.action === "dispatch_committed" ? decision : void 0;
       }
       throwIfAborted(options.signal);
       const postDispatchOptions = dispatchCommitted ? { ...options, signal: void 0 } : options;
@@ -4185,7 +4190,7 @@ class TaskExecutor {
       status: "failed",
       error: error.message || String(error),
       adcpError: adcpErrorInfo,
-      errorInstance: this.buildErrorInstance(taskId, adcpErrorInfo),
+      errorInstance: getSignedRequestRejection(error) ?? this.buildErrorInstance(taskId, adcpErrorInfo),
       correlationId,
       metadata: this.buildMetadata({
         taskId,

package/dist/lib/core/account-key.d.mts

@@ -0,0 +1,3 @@
+import type { AccountReference } from '../types/index.mjs';
+/** Stable identity; never includes billing details or credentials. */
+export declare function accountReferenceKey(ref: AccountReference): string;

package/dist/lib/core/account-key.d.ts

@@ -0,0 +1,3 @@
+import type { AccountReference } from '../types';
+/** Stable identity; never includes billing details or credentials. */
+export declare function accountReferenceKey(ref: AccountReference): string;

package/dist/lib/core/account-key.js

@@ -0,0 +1,41 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var account_key_exports = {};
+__export(account_key_exports, {
+  accountReferenceKey: () => accountReferenceKey
+});
+module.exports = __toCommonJS(account_key_exports);
+function accountReferenceKey(ref) {
+  if ("account_id" in ref) return JSON.stringify(["id", ref.account_id]);
+  return JSON.stringify([
+    "natural",
+    ref.brand.domain,
+    ref.brand.brand_id ?? null,
+    ref.brand.countries ? [...ref.brand.countries].sort() : null,
+    ref.operator,
+    ref.operator_unit?.id ?? null,
+    ref.currency ?? null,
+    ref.timezone ?? null,
+    ref.sandbox === true
+  ]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  accountReferenceKey
+});

package/dist/lib/core/account-key.mjs

@@ -0,0 +1,17 @@
+function accountReferenceKey(ref) {
+  if ("account_id" in ref) return JSON.stringify(["id", ref.account_id]);
+  return JSON.stringify([
+    "natural",
+    ref.brand.domain,
+    ref.brand.brand_id ?? null,
+    ref.brand.countries ? [...ref.brand.countries].sort() : null,
+    ref.operator,
+    ref.operator_unit?.id ?? null,
+    ref.currency ?? null,
+    ref.timezone ?? null,
+    ref.sandbox === true
+  ]);
+}
+export {
+  accountReferenceKey
+};

package/dist/lib/core/account-resolution.d.mts

@@ -16,6 +16,8 @@ export interface ResolveAccountOptions {
     forTask?: string;
     /** Billing party for buyer-declared accounts when the seller has no default. */
     billing?: 'operator' | 'agent' | 'advertiser';
+    paymentTerms?: import('../types/tools.generated.mjs').PaymentTerms;
+    billingEntity?: import('../types/tools.generated.mjs').BusinessEntity;
     /** An account_id or a callback choosing one of the eligible list_accounts rows. */
     select?: string | ((accounts: readonly ListedAccount[]) => string);
 }

package/dist/lib/core/account-resolution.d.ts

@@ -16,6 +16,8 @@ export interface ResolveAccountOptions {
     forTask?: string;
     /** Billing party for buyer-declared accounts when the seller has no default. */
     billing?: 'operator' | 'agent' | 'advertiser';
+    paymentTerms?: import('../types/tools.generated').PaymentTerms;
+    billingEntity?: import('../types/tools.generated').BusinessEntity;
     /** An account_id or a callback choosing one of the eligible list_accounts rows. */
     select?: string | ((accounts: readonly ListedAccount[]) => string);
 }

package/dist/lib/core/buyer-account-registry.d.mts

@@ -0,0 +1,93 @@
+import type { AccountReference, BusinessEntity, PaymentTerms, SyncAccountsResponse } from '../types/tools.generated.mjs';
+import type { TaskOptions, TaskResult } from './ConversationTypes.mjs';
+export type AccountPolicy = 'auto' | 'strict' | 'off';
+export interface EnsureAccountOptions {
+    billing?: 'operator' | 'agent' | 'advertiser';
+    paymentTerms?: PaymentTerms;
+    billingEntity?: BusinessEntity;
+    /** Caller-owned retry identity. Settle ambiguous dispatches explicitly with this key; the registry never rotates it. */
+    idempotencyKey?: string;
+}
+export interface ProvisionedAccount {
+    account: AccountReference;
+    account_id?: string;
+    status: string;
+    pendingTaskId?: string;
+    /** Hashes of explicitly selected setup options; billing identities themselves are never persisted. */
+    setupTerms?: Partial<Record<keyof EnsureAccountOptions, string>>;
+    /** Stored reference aliases for authoritative repair after restart. */
+    aliases?: AccountReference[];
+    /** Monotonically increasing row revision when compareAndSet is implemented. */
+    revision?: number;
+    /** Durable claim. Reconcile an uncertain dispatch explicitly before provisioning again. */
+    dispatch?: {
+        idempotencyKey: string;
+        startedAt: string;
+    };
+}
+/** Partitioned by seller and caller scope. Implementations must provide read-your-writes. */
+export interface BuyerAccountStorage {
+    get(key: string): Promise<ProvisionedAccount | undefined>;
+    set(key: string, account: ProvisionedAccount): Promise<void>;
+    /** Atomically insert (undefined revision) or replace. Store the supplied new revision. Required for multi-process safety. */
+    compareAndSet?(key: string, expectedRevision: number | undefined, account: ProvisionedAccount): Promise<boolean>;
+}
+export interface BuyerAccountDispatch {
+    storageKey: string;
+    account: AccountReference;
+    idempotencyKey: string;
+}
+export interface BuyerAccountProvisioningDispatch {
+    idempotencyKey: string;
+    /** Invoke immediately before the transport receives the mutation. */
+    beforeDispatch(): Promise<void>;
+}
+export interface BuyerAccountRegistryOptions {
+    /** Awaited before dispatch; rejection prevents the mutation. */
+    onDispatchStart?: (dispatch: BuyerAccountDispatch) => Promise<void>;
+    /** Awaited for each seller result before account writes. Rejection preserves the claim for caller reconciliation. */
+    onResult?: (dispatch: BuyerAccountDispatch & {
+        result: TaskResult<unknown>;
+    }) => Promise<void>;
+    maxEntries?: number;
+    normalizeOptions?: (options: EnsureAccountOptions, taskOptions?: TaskOptions) => Promise<EnsureAccountOptions>;
+}
+export declare class BuyerAccountRegistry {
+    private scope;
+    private provision;
+    private storage?;
+    private repair?;
+    private readonly registryOptions;
+    private entries;
+    private pending;
+    private writes;
+    private repairs;
+    private repairWaiters;
+    private invalidatedHandles;
+    private observationEpoch;
+    private observationFloor;
+    private statusEpochs;
+    private readonly maxEntries;
+    private readonly normalizeOptions?;
+    constructor(scope: () => string, provision: (key: AccountReference, options: EnsureAccountOptions, taskOptions?: TaskOptions, dispatch?: BuyerAccountProvisioningDispatch) => Promise<TaskResult<SyncAccountsResponse>>, storage?: BuyerAccountStorage | undefined, repair?: ((accountId: string, taskOptions?: TaskOptions) => Promise<readonly unknown[]>) | undefined, registryOptions?: BuyerAccountRegistryOptions);
+    private key;
+    /** Capture before a seller request; observations older than a status repair are ignored. */
+    captureObservation(): number;
+    private observationIsCurrent;
+    private remember;
+    get(account: AccountReference): Promise<ProvisionedAccount | undefined>;
+    ensure(account: AccountReference, options?: EnsureAccountOptions, taskOptions?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ProvisionedAccount>;
+    private write;
+    private record;
+    private enqueue;
+    observeSync(refs: readonly AccountReference[], rows: readonly unknown[], dryRun?: boolean, observationEpoch?: number, expectedRevision?: number): Promise<void>;
+    private reconcileId;
+    observeList(rows: readonly unknown[], queriedAccountId?: string, observationEpoch?: number): Promise<void>;
+    private observeListAtScope;
+    /** After verifying account.status_changed, repair aliases by handle from the authoritative seller. */
+    applyStatusChange(notification: {
+        account_id: string;
+    }, options?: TaskOptions): Promise<void>;
+    private repairStatus;
+    private runRepair;
+}

package/dist/lib/core/buyer-account-registry.d.ts

@@ -0,0 +1,93 @@
+import type { AccountReference, BusinessEntity, PaymentTerms, SyncAccountsResponse } from '../types/tools.generated';
+import type { TaskOptions, TaskResult } from './ConversationTypes';
+export type AccountPolicy = 'auto' | 'strict' | 'off';
+export interface EnsureAccountOptions {
+    billing?: 'operator' | 'agent' | 'advertiser';
+    paymentTerms?: PaymentTerms;
+    billingEntity?: BusinessEntity;
+    /** Caller-owned retry identity. Settle ambiguous dispatches explicitly with this key; the registry never rotates it. */
+    idempotencyKey?: string;
+}
+export interface ProvisionedAccount {
+    account: AccountReference;
+    account_id?: string;
+    status: string;
+    pendingTaskId?: string;
+    /** Hashes of explicitly selected setup options; billing identities themselves are never persisted. */
+    setupTerms?: Partial<Record<keyof EnsureAccountOptions, string>>;
+    /** Stored reference aliases for authoritative repair after restart. */
+    aliases?: AccountReference[];
+    /** Monotonically increasing row revision when compareAndSet is implemented. */
+    revision?: number;
+    /** Durable claim. Reconcile an uncertain dispatch explicitly before provisioning again. */
+    dispatch?: {
+        idempotencyKey: string;
+        startedAt: string;
+    };
+}
+/** Partitioned by seller and caller scope. Implementations must provide read-your-writes. */
+export interface BuyerAccountStorage {
+    get(key: string): Promise<ProvisionedAccount | undefined>;
+    set(key: string, account: ProvisionedAccount): Promise<void>;
+    /** Atomically insert (undefined revision) or replace. Store the supplied new revision. Required for multi-process safety. */
+    compareAndSet?(key: string, expectedRevision: number | undefined, account: ProvisionedAccount): Promise<boolean>;
+}
+export interface BuyerAccountDispatch {
+    storageKey: string;
+    account: AccountReference;
+    idempotencyKey: string;
+}
+export interface BuyerAccountProvisioningDispatch {
+    idempotencyKey: string;
+    /** Invoke immediately before the transport receives the mutation. */
+    beforeDispatch(): Promise<void>;
+}
+export interface BuyerAccountRegistryOptions {
+    /** Awaited before dispatch; rejection prevents the mutation. */
+    onDispatchStart?: (dispatch: BuyerAccountDispatch) => Promise<void>;
+    /** Awaited for each seller result before account writes. Rejection preserves the claim for caller reconciliation. */
+    onResult?: (dispatch: BuyerAccountDispatch & {
+        result: TaskResult<unknown>;
+    }) => Promise<void>;
+    maxEntries?: number;
+    normalizeOptions?: (options: EnsureAccountOptions, taskOptions?: TaskOptions) => Promise<EnsureAccountOptions>;
+}
+export declare class BuyerAccountRegistry {
+    private scope;
+    private provision;
+    private storage?;
+    private repair?;
+    private readonly registryOptions;
+    private entries;
+    private pending;
+    private writes;
+    private repairs;
+    private repairWaiters;
+    private invalidatedHandles;
+    private observationEpoch;
+    private observationFloor;
+    private statusEpochs;
+    private readonly maxEntries;
+    private readonly normalizeOptions?;
+    constructor(scope: () => string, provision: (key: AccountReference, options: EnsureAccountOptions, taskOptions?: TaskOptions, dispatch?: BuyerAccountProvisioningDispatch) => Promise<TaskResult<SyncAccountsResponse>>, storage?: BuyerAccountStorage | undefined, repair?: ((accountId: string, taskOptions?: TaskOptions) => Promise<readonly unknown[]>) | undefined, registryOptions?: BuyerAccountRegistryOptions);
+    private key;
+    /** Capture before a seller request; observations older than a status repair are ignored. */
+    captureObservation(): number;
+    private observationIsCurrent;
+    private remember;
+    get(account: AccountReference): Promise<ProvisionedAccount | undefined>;
+    ensure(account: AccountReference, options?: EnsureAccountOptions, taskOptions?: TaskOptions, onTaskResult?: (result: TaskResult<unknown>) => void): Promise<ProvisionedAccount>;
+    private write;
+    private record;
+    private enqueue;
+    observeSync(refs: readonly AccountReference[], rows: readonly unknown[], dryRun?: boolean, observationEpoch?: number, expectedRevision?: number): Promise<void>;
+    private reconcileId;
+    observeList(rows: readonly unknown[], queriedAccountId?: string, observationEpoch?: number): Promise<void>;
+    private observeListAtScope;
+    /** After verifying account.status_changed, repair aliases by handle from the authoritative seller. */
+    applyStatusChange(notification: {
+        account_id: string;
+    }, options?: TaskOptions): Promise<void>;
+    private repairStatus;
+    private runRepair;
+}