@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/index.js

@@ -0,0 +1,441 @@
+import { env as processEnv, versions } from 'node:process';
+import { createHash } from 'node:crypto';
+import { normalizeBrowserOperation } from './browser-operations.js';
+import { validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+
+const ID = /^mcs_[A-Za-z0-9_-]{43}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const STATUSES = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved',
+  'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const WAIT_STOPS = new Set(['ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const HOSTED_SERVICE = 'https://accelerate-agent-sdk.vercel.app';
+const ERROR_CODES = new Set(['invalid_input', 'unauthorized', 'permission_denied', 'not_found', 'conflict',
+  'rate_limited', 'checkout_expired', 'checkout_unavailable', 'approval_required', 'invalid_state',
+  'operation_in_progress', 'fill_continuation_required', 'review_unavailable', 'capability_disabled', 'checkout_unsupported', 'integration_unavailable', 'outcome_unknown',
+  'authentication_required', 'checkout_closed', 'checkout_frozen', 'upstream_unavailable', 'wallet_required',
+  'revision_conflict', 'address_changed', 'details_required', 'quote_changed', 'submit_unavailable',
+  'approval_unavailable', 'authentication_completed', 'verification_required', 'verification_failed',
+  'verification_consumed', 'handoff_consumed', 'wallet_refreshing', 'consent_required',
+  'idempotency_conflict', 'operation_conflict', 'checkout_not_found', 'tenant_unauthorized',
+  'checkout_busy', 'store_unavailable', 'store_integrity_error', 'selection_rejected', 'upstream_invalid',
+  'upstream_request_invalid', 'upstream_response_invalid', 'configuration_error', 'configuration_invalid',
+  'route_not_found', 'method_not_allowed', 'json_required', 'invalid_json', 'request_too_large', 'checkout_event_unconfirmed']);
+const MESSAGES = {
+  invalid_input: 'Invalid Accelerate client request.',
+  invalid_response: 'Accelerate returned an unrecognized private response.',
+  request_timeout: 'Accelerate request timed out. Check checkout status; do not repeat uncertain payment work.',
+  request_cancelled: 'Accelerate request was cancelled. Check checkout status; do not repeat uncertain payment work.',
+  wait_timeout: 'Checkout status wait timed out. Check status before continuing; no payment action was taken by this wait.',
+  missing_api_key: 'Set ACCELERATE_API_KEY on your application server.',
+  missing_merchant_id: 'Set ACCELERATE_MERCHANT_ID on your application server.',
+  invalid_api_key: 'ACCELERATE_API_KEY is invalid. Check the server key supplied by Accelerate.',
+  invalid_merchant_id: 'ACCELERATE_MERCHANT_ID must be the merchant UUID supplied by Accelerate.',
+  invalid_base_url: 'ACCELERATE_BASE_URL must be an HTTPS origin without a path, query, fragment or credentials.',
+};
+const GUIDANCE = Object.create(null);
+for (const [codes, message, nextAction] of [
+  [['checkout_unsupported'],
+    'This checkout’s payment fields or safe review are not supported. No private verification was started.', 'stop'],
+  [['unauthorized', 'tenant_unauthorized', 'permission_denied', 'configuration_error', 'configuration_invalid', 'capability_disabled', 'integration_unavailable'],
+    'Check the server API key, merchant ID and enabled Accelerate capabilities.', 'check_configuration'],
+  [['invalid_input', 'invalid_json', 'json_required', 'request_too_large', 'method_not_allowed', 'route_not_found', 'upstream_request_invalid'],
+    'Check the checkout request against the SDK contract.', 'check_request'],
+  [['operation_in_progress', 'operation_conflict', 'checkout_busy', 'rate_limited', 'wallet_refreshing', 'conflict'],
+    'Read checkout status before continuing. Do not repeat an uncertain payment action.', 'check_status'],
+  [['wallet_required', 'authentication_required', 'authentication_completed', 'selection_rejected'],
+    'Continue the private wallet authentication and selection flow.', 'complete_wallet'],
+  [['verification_required', 'verification_failed', 'consent_required', 'approval_required', 'approval_unavailable'],
+    'Complete the private purchase approval and verification flow before continuing.', 'complete_verification'],
+  [['quote_changed', 'address_changed', 'details_required'],
+    'Prepare the current checkout details and request approval for the updated quote.', 'refresh_quote'],
+  [['revision_conflict'], 'Read the current checkout revision before continuing.', 'refresh_revision'],
+  [['fill_continuation_required'],
+    'The private backend continues this staged fill after security-code verification. Read the same checkout status; do not request another fill.', 'check_status'],
+  [['review_unavailable'],
+    'This checkout has insufficient time for safe filled review and cleanup. Read its safe status; do not repeat filling.', 'stop'],
+  [['checkout_frozen', 'submit_unavailable', 'invalid_state'],
+    'Read checkout status and use only the actions permitted for its current state.', 'check_status'],
+  [['checkout_closed', 'checkout_expired', 'checkout_not_found', 'not_found', 'verification_consumed', 'handoff_consumed'],
+    'Stop this checkout action. Read its status and reconcile any previous payment attempt.', 'stop'],
+  [['outcome_unknown'],
+    'Reconcile checkout status and the merchant order. Do not repeat the payment action.', 'reconcile_order'],
+  [['checkout_event_unconfirmed'],
+    'Private chat progress delivery could not be confirmed. Check this existing checkout; do not create a replacement.', 'check_status'],
+]) for (const code of codes) GUIDANCE[code] = Object.freeze({ message, nextAction });
+
+/** Safe diagnostics only: no response body, URL, credentials, cause or provider stack. */
+export class AccelerateError extends Error {
+  constructor(code = 'request_failed', status = 0, supportReference) {
+    const known = Object.hasOwn(MESSAGES, code) || ERROR_CODES.has(code);
+    super(known && Object.hasOwn(MESSAGES, code) ? MESSAGES[code] : GUIDANCE[code]?.message ??
+      'Accelerate could not complete the request. Check checkout status before continuing.');
+    this.name = 'AccelerateError';
+    this.code = known ? code : 'request_failed';
+    this.status = Number.isInteger(status) && status >= 100 && status <= 599 ? status : 0;
+    this.retrySafe = false;
+    this.paymentConfirmed = false;
+    this.nextAction = GUIDANCE[this.code]?.nextAction ??
+      (['missing_api_key', 'missing_merchant_id', 'invalid_api_key', 'invalid_merchant_id', 'invalid_base_url'].includes(this.code) ?
+        'check_configuration' : 'check_status');
+    if (typeof supportReference === 'string' && /^(?:acs_|arq_)[a-f0-9]{32}$/.test(supportReference)) this.supportReference = supportReference;
+  }
+}
+const fail = (code = 'invalid_input') => { throw new AccelerateError(code); };
+const check = (value, code) => { if (!value) fail(code); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  [Object.prototype, null].includes(Object.getPrototypeOf(value));
+function keys(value, allowed, required = allowed, code = 'invalid_input') {
+  check(object(value) && Object.keys(value).every(key => allowed.includes(key)) &&
+    required.every(key => Object.hasOwn(value, key)), code);
+  return value;
+}
+function string(value, max = 200, code = 'invalid_input') {
+  check(typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/u.test(value), code);
+  return value;
+}
+function integer(value, min, max, code = 'invalid_input') {
+  check(Number.isSafeInteger(value) && value >= min && value <= max, code); return value;
+}
+function checkoutId(id) { check(typeof id === 'string' && ID.test(id)); return id; }
+function httpsUrl(value, { originOnly = false, loopback = false, code = 'invalid_input' } = {}) {
+  string(value, 2048, code);
+  let url; try { url = new URL(value); } catch { fail(code); }
+  const local = loopback && url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname);
+  check((url.protocol === 'https:' || local) && !url.username && !url.password && !url.hash &&
+    (!originOnly || (url.pathname === '/' && !url.search)), code);
+  return url;
+}
+function revisionInput(input) {
+  keys(input, ['revision']); return { revision: integer(input.revision, 1, 2147483647) };
+}
+function preparationText(value, max = 2000, code = 'invalid_input') {
+  string(value, max, code);
+  check(!/(?:\d[ -]?){13,19}/u.test(value) &&
+    !/\b(?:cvv|cvc|security\s*code|card\s*(?:number|expiry|expiration))\b.{0,30}\d/iu.test(value), code);
+  return value;
+}
+function browserInput(input) {
+  keys(input, ['operation', 'arguments']);
+  try { return { operation: input.operation, arguments: normalizeBrowserOperation(input.operation, input.arguments) }; }
+  catch { fail(); }
+}
+function merchantUrl(value) {
+  try { normalizeBrowserOperation('navigate', { url: value }); }
+  catch { fail(); }
+  return value;
+}
+function timestamp(value) {
+  check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/u.test(value) && Number.isFinite(Date.parse(value)), 'invalid_response');
+  return value;
+}
+function safeText(value, max = 1000, multiline = false) {
+  if (multiline) {
+    check(typeof value === 'string' && value.length <= max && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value) &&
+      !/(?:\d[ -]?){13,19}/u.test(value) &&
+      !/\b(?:cvv|cvc|csc|security\s*code|card\s*(?:number|expiry|expiration))\b.{0,30}\d/iu.test(value), 'invalid_response');
+  } else preparationText(value, max, 'invalid_response');
+  check(!/\b(?:cdp|browser_live_view|session_token|handoff_token|submit_token|id_token|authorizationToken)\b/iu.test(value) &&
+    !/\b(?:cvv|cvc|csc|security\s*code)\b["'\s:=]{0,12}\d{3,4}\b/iu.test(value) &&
+    !/(?:wss?:\/\/|chrome-extension:\/\/|devtools:\/\/|devtools\/browser|aw[12]\.[\w.-]+|\b(?:agw_|atk_)[A-Za-z0-9_-]+|\b(?:Bearer\s+\S+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.|tok_(?:sandbox|live)_|vgs_)|\b(?:api_key|hmac_secret)\b)/iu.test(value) &&
+    !/\b(?:0[1-9]|1[0-2])\s*\/\s*(?:20)?\d{2}\b/u.test(value) &&
+    !/https?:\/\/[^\s/]*(?:onkernel\.com|verygoodproxy\.com|verygoodvault\.com)(?:[/:\s]|$)/iu.test(value), 'invalid_response');
+  return value;
+}
+function statusResponse(value, expectedId, { create, origin, loopback }) {
+  keys(value, ['id', 'status', 'revision', 'expires_at', 'card', 'address', 'quote', 'submit_expires_at', 'purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'diagnostics',
+    'fill_after_verification', 'retry_safe', 'payment_confirmed', ...(create ? ['wallet_url'] : [])],
+  ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], 'invalid_response');
+  check(typeof value.id === 'string' && ID.test(value.id) && (!expectedId || value.id === expectedId) && STATUSES.has(value.status) &&
+    value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
+  integer(value.revision, 0, 2147483647, 'invalid_response'); timestamp(value.expires_at);
+  if (value.purpose !== undefined || value.submit_allowed !== undefined) check(
+    ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(value.purpose) &&
+    value.submit_allowed === (value.purpose === 'purchase'), 'invalid_response');
+  if (value.approval_policy !== undefined || value.purchase_approved !== undefined) check(value.approval_policy === 'after_fill' && typeof value.purchase_approved === 'boolean' && (!value.purchase_approved || value.status === 'ready_for_submit' && value.purpose === 'purchase'), 'invalid_response');
+  if (value.fill_after_verification !== undefined) check(value.fill_after_verification === true && value.approval_policy === 'after_fill' &&
+    ['purchase', 'sandbox_fill_only'].includes(value.purpose), 'invalid_response');
+  if (value.submit_expires_at !== undefined) timestamp(value.submit_expires_at);
+  if (value.diagnostics !== undefined) {
+    try { validateCheckoutDiagnostics(value.diagnostics, value); } catch { fail('invalid_response'); }
+  }
+  if (value.card !== undefined) {
+    keys(value.card, ['last4', 'brand'], ['last4', 'brand'], 'invalid_response');
+    check(value.card.last4 === null || typeof value.card.last4 === 'string' && /^\d{4}$/u.test(value.card.last4), 'invalid_response');
+    if (value.card.brand !== null) safeText(value.card.brand, 40);
+  }
+  if (value.address !== undefined) {
+    keys(value.address, ['label', 'city', 'state', 'postal_code_mask'], ['label'], 'invalid_response');
+    if (value.address.label !== null) safeText(value.address.label, 400);
+    for (const key of ['city', 'state', 'postal_code_mask']) if (value.address[key] != null) safeText(value.address[key], 128);
+    check(value.address.postal_code_mask == null || /[*•]/u.test(value.address.postal_code_mask), 'invalid_response');
+  }
+  if (value.quote !== undefined) {
+    keys(value.quote, ['checkout_origin', 'amount_cents', 'currency'], undefined, 'invalid_response');
+    httpsUrl(value.quote.checkout_origin, { originOnly: true, code: 'invalid_response' });
+    integer(value.quote.amount_cents, 1, 2147483647, 'invalid_response');
+    check(value.quote.currency === 'USD', 'invalid_response');
+  }
+  if (value.wallet_url !== undefined) {
+    string(value.wallet_url, 2048, 'invalid_response');
+    let url; try { url = new URL(value.wallet_url); } catch { fail('invalid_response'); }
+    check(url.origin === origin && url.pathname === `/checkout/${value.id}` && !url.search && !url.username && !url.password &&
+      /^#ticket=[A-Za-z0-9_-]{43}$/u.test(url.hash) && (url.protocol === 'https:' || loopback), 'invalid_response');
+  }
+  return value;
+}
+function browserResponse(value) {
+  keys(value, ['content', 'isError'], ['content'], 'invalid_response');
+  check(value.isError === undefined || value.isError === false, 'invalid_response');
+  check(Array.isArray(value.content) && value.content.length > 0 && value.content.length <= 20, 'invalid_response');
+  let total = 0;
+  for (const part of value.content) {
+    keys(part, ['type', 'text'], undefined, 'invalid_response');
+    check(part.type === 'text', 'invalid_response'); safeText(part.text, 24000, true);
+    total += Buffer.byteLength(part.text, 'utf8');
+  }
+  check(total <= 24000, 'invalid_response');
+  return { content: value.content };
+}
+function verifiedQuoteResponse(value, id, input) {
+  keys(value, ['checkout_id', 'revision', 'verified', 'quote'], undefined, 'invalid_response');
+  check(value.checkout_id === id && value.revision === input.revision && value.verified === true, 'invalid_response');
+  keys(value.quote, ['checkout_origin', 'amount_cents', 'currency'], undefined, 'invalid_response');
+  check(value.quote.checkout_origin === new URL(input.checkout_url).origin &&
+    value.quote.amount_cents === input.expected_amount_cents && value.quote.currency === input.expected_currency, 'invalid_response');
+  return value;
+}
+function creationInspectionInput(input) {
+  keys(input, ['customer_id', 'workspace_id', 'conversation_id', 'idempotency_key', 'browser']);
+  for (const name of ['customer_id', 'workspace_id', 'conversation_id'])
+    check(typeof input[name] === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input[name]));
+  string(input.idempotency_key, 200);
+  keys(input.browser, ['provider', 'browser_id', 'custody_mode']);
+  check(input.browser.provider === 'browser_use' && typeof input.browser.browser_id === 'string' &&
+    UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase() &&
+    input.browser.custody_mode === 'customer_backend_trusted');
+  return { ...input, browser: { ...input.browser } };
+}
+function creationInspectionResponse(value, input) {
+  if (value?.confirmed === false) { keys(value, ['confirmed'], undefined, 'invalid_response'); return value; }
+  keys(value, ['confirmed', 'checkout_id', 'revision', 'purpose', 'creation_key_sha256', 'retirement'], undefined, 'invalid_response');
+  check(value.confirmed === true && typeof value.checkout_id === 'string' && ID.test(value.checkout_id) && value.revision === 0 &&
+    ['purchase', 'sandbox_fill_only'].includes(value.purpose) &&
+    value.creation_key_sha256 === createHash('sha256').update(input.idempotency_key).digest('hex'), 'invalid_response');
+  keys(value.retirement, ['browser_provider', 'browser_id', 'retired', 'provider_stopped', 'private_lease_closed', 'recording_disabled'], undefined, 'invalid_response');
+  check(value.retirement.browser_provider === input.browser.provider && value.retirement.browser_id === input.browser.browser_id &&
+    value.retirement.retired === true && value.retirement.provider_stopped === true && value.retirement.private_lease_closed === true &&
+    value.retirement.recording_disabled === true, 'invalid_response');
+  return value;
+}
+function retirementInspectionInput(input) {
+  keys(input, ['customer_id', 'workspace_id', 'conversation_id', 'idempotency_key', 'revision', 'browser']);
+  const { revision, ...scope } = input;
+  return { ...creationInspectionInput(scope), revision: integer(revision, 1, 2147483647) };
+}
+function retirementInspectionResponse(value, id, input) {
+  if (value?.confirmed === false) { keys(value, ['confirmed'], undefined, 'invalid_response'); return value; }
+  keys(value, ['confirmed', 'checkout_id', 'revision', 'status', 'purpose', 'approval_policy', 'submit_allowed',
+    'purchase_approved', 'creation_key_sha256', 'retirement'], undefined, 'invalid_response');
+  check(value.confirmed === true && value.checkout_id === id && value.revision === input.revision && value.status === 'outcome_unknown' &&
+    value.purpose === 'sandbox_fill_only' && value.approval_policy === 'after_fill' && value.submit_allowed === false &&
+    value.purchase_approved === false && value.creation_key_sha256 === createHash('sha256').update(input.idempotency_key).digest('hex'), 'invalid_response');
+  keys(value.retirement, ['browser_provider', 'browser_id', 'retired', 'provider_stopped', 'private_lease_closed', 'recording_disabled'], undefined, 'invalid_response');
+  check(value.retirement.browser_provider === input.browser.provider && value.retirement.browser_id === input.browser.browser_id &&
+    value.retirement.retired === true && value.retirement.provider_stopped === true && value.retirement.private_lease_closed === true &&
+    value.retirement.recording_disabled === true, 'invalid_response');
+  return value;
+}
+function connectionResponse(value, merchantId) {
+  keys(value, ['status', 'api_version', 'merchant_id', 'interaction_modes', 'currencies'], undefined, 'invalid_response');
+  check(value.status === 'connected' && value.api_version === 'v1' && value.merchant_id === merchantId &&
+    Array.isArray(value.interaction_modes) && value.interaction_modes.length === 2 &&
+    value.interaction_modes[0] === 'chat' && value.interaction_modes[1] === 'hosted' &&
+    Array.isArray(value.currencies) && value.currencies.length === 1 && value.currencies[0] === 'USD', 'invalid_response');
+  return value;
+}
+async function readJson(response, signal) {
+  check(response.body && /^application\/json(?:\s*;|$)/iu.test(response.headers.get('content-type') ?? ''), 'invalid_response');
+  const reader = response.body.getReader();
+  const abort = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', abort, { once: true });
+  let size = 0; const chunks = [];
+  try {
+    while (true) {
+      const next = await reader.read(); if (next.done) break;
+      signal.throwIfAborted();
+      size += next.value.byteLength; check(size <= 65536, 'invalid_response'); chunks.push(next.value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } finally { signal.removeEventListener('abort', abort); await reader.cancel().catch(() => {}); reader.releaseLock(); }
+}
+function bounded(operation, signal) {
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(new AccelerateError('request_cancelled'));
+    signal.addEventListener('abort', aborted, { once: true });
+    if (signal.aborted) aborted();
+    Promise.resolve(operation).then(value => {
+      signal.removeEventListener('abort', aborted);
+      if (signal.aborted) { Promise.resolve(value?.body?.cancel()).catch(() => {}); reject(new AccelerateError('request_cancelled')); }
+      else resolve(value);
+    }, error => { signal.removeEventListener('abort', aborted);
+      reject(error instanceof AccelerateError ? error : new AccelerateError('request_failed')); });
+  });
+}
+
+/** Instantiate only on your authenticated application server. Never bundle an API key in a browser. */
+export class AccelerateClient {
+  #origin; #apiKey; #merchantId; #fetch; #loopback;
+  /** Server environment only. Never pass model input or expose the returned client to a browser. */
+  static fromEnv(env = processEnv) {
+    check(Number(versions.node?.split('.')[0]) >= 22 && typeof globalThis.window === 'undefined' &&
+      typeof globalThis.document === 'undefined' && typeof globalThis.self === 'undefined');
+    check(env === processEnv || object(env));
+    const apiKey = env.ACCELERATE_API_KEY, merchantId = env.ACCELERATE_MERCHANT_ID;
+    check(apiKey !== undefined && !(typeof apiKey === 'string' && apiKey.trim().length === 0), 'missing_api_key');
+    check(typeof apiKey === 'string' && /^[A-Za-z0-9_-]{32,256}$/u.test(apiKey), 'invalid_api_key');
+    check(merchantId !== undefined && !(typeof merchantId === 'string' && merchantId.trim().length === 0), 'missing_merchant_id');
+    check(typeof merchantId === 'string' && UUID.test(merchantId), 'invalid_merchant_id');
+    const baseUrl = env.ACCELERATE_BASE_URL === undefined ? HOSTED_SERVICE : env.ACCELERATE_BASE_URL;
+    try { httpsUrl(baseUrl, { originOnly: true }); } catch { fail('invalid_base_url'); }
+    return new this({ baseUrl, apiKey, merchantId });
+  }
+  constructor({ baseUrl, apiKey, merchantId, fetchImpl = globalThis.fetch, allowLoopbackForTests = false } = {}) {
+    check(Number(versions.node?.split('.')[0]) >= 22 && typeof globalThis.window === 'undefined' &&
+      typeof globalThis.document === 'undefined' && typeof globalThis.self === 'undefined');
+    const url = httpsUrl(baseUrl, { originOnly: true, loopback: allowLoopbackForTests === true });
+    check(typeof apiKey === 'string' && /^[A-Za-z0-9_-]{32,256}$/u.test(apiKey));
+    check(typeof merchantId === 'string' && UUID.test(merchantId) && typeof fetchImpl === 'function');
+    this.#origin = url.origin; this.#apiKey = apiKey; this.#merchantId = merchantId.toLowerCase();
+    this.#fetch = fetchImpl; this.#loopback = allowLoopbackForTests === true;
+    this.connection = Object.freeze({
+      check: async options => this.#request('GET', undefined, '', undefined, options, true),
+    });
+    this.checkouts = Object.freeze({
+      inspectCreation: async (input, options) => this.#request('POST', null, '/inspect-creation', creationInspectionInput(input), options),
+      inspectRetirement: async (id, input, options) => this.#request('POST', checkoutId(id), '/inspect-retirement', retirementInspectionInput(input), options),
+      create: async (input, options) => this.#create(input, options),
+      get: async (id, options) => this.#request('GET', checkoutId(id), '', undefined, options),
+      waitFor: async (id, input, options) => this.#waitFor(checkoutId(id), input, options),
+      browser: async (id, input, options) => this.#request('POST', checkoutId(id), '/browser', browserInput(input), options),
+      applyDetails: async (id, input, options) => {
+        keys(input, ['checkout_url']); merchantUrl(input.checkout_url);
+        return this.#request('POST', checkoutId(id), '/details', { checkout_url: input.checkout_url }, options);
+      },
+      verifyQuote: async (id, input, options) => {
+        keys(input, ['revision', 'checkout_url', 'expected_amount_cents', 'expected_currency', 'checkout_total_selector']);
+        integer(input.revision, 1, 2147483647); merchantUrl(input.checkout_url);
+        integer(input.expected_amount_cents, 1, 2147483647); check(input.expected_currency === 'USD');
+        string(input.checkout_total_selector, 500);
+        return this.#request('POST', checkoutId(id), '/verify-quote', { ...input }, options);
+      },
+      requestApproval: async (id, input, options) => {
+        keys(input, ['checkout_url', 'amount_cents', 'currency', 'checkout_total_selector', 'submit_selector', 'fill_after_verification'],
+          ['checkout_url', 'amount_cents', 'currency', 'checkout_total_selector', 'submit_selector']);
+        check(input.fill_after_verification === undefined || input.fill_after_verification === true);
+        merchantUrl(input.checkout_url); integer(input.amount_cents, 1, 2147483647); check(input.currency === 'USD');
+        string(input.checkout_total_selector, 500); string(input.submit_selector, 200);
+        const result = await this.#request('POST', checkoutId(id), '/approval', { ...input }, options);
+        check(input.fill_after_verification !== true || result.fill_after_verification === true, 'invalid_response');
+        return result;
+      },
+      fill: async (id, input, options) => this.#request('POST', checkoutId(id), '/fill', revisionInput(input), options),
+      submit: async (id, input, options) => this.#request('POST', checkoutId(id), '/submit', revisionInput(input), options),
+      cancel: async (id, options) => this.#request('POST', checkoutId(id), '/cancel', {}, options),
+    });
+  }
+  async #waitFor(id, input, options = {}) {
+    keys(input, ['statuses', 'timeoutMs', 'intervalMs'], ['statuses']);
+    check(Array.isArray(input.statuses) && input.statuses.length > 0 && input.statuses.length <= STATUSES.size &&
+      [...input.statuses].every(status => STATUSES.has(status)));
+    const statuses = new Set(input.statuses);
+    const timeoutMs = integer(input.timeoutMs ?? 60000, 1, 300000);
+    const intervalMs = integer(input.intervalMs ?? 1000, 250, 5000);
+    keys(options, ['signal'], []);
+    check(options.signal === undefined || options.signal instanceof AbortSignal);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs); timer.unref?.();
+    const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+    try {
+      while (true) {
+        signal.throwIfAborted();
+        const checkout = await this.#request('GET', id, '', undefined, { signal });
+        signal.throwIfAborted();
+        // Readiness is an urgent decision boundary: never poll away its ten-second submit claim.
+        if (statuses.has(checkout.status) || WAIT_STOPS.has(checkout.status)) return checkout;
+        let pause;
+        try { await bounded(new Promise(resolve => { pause = setTimeout(resolve, intervalMs); }), signal); }
+        finally { clearTimeout(pause); }
+      }
+    } catch (error) {
+      if (signal.aborted) throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'wait_timeout');
+      throw error;
+    } finally { clearTimeout(timer); }
+  }
+  #create(input, options) {
+    keys(input, ['customer_id', 'workspace_id', 'phone_number', 'start_url', 'idempotency_key', 'interaction_mode', 'conversation_id', 'purpose', 'approval_policy', 'browser', 'browser_resource', 'fill_after_verification'],
+      ['customer_id', 'workspace_id', 'phone_number', 'start_url', 'idempotency_key']);
+    check(typeof input.customer_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.customer_id));
+    check(typeof input.workspace_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.workspace_id));
+    string(input.idempotency_key, 200);
+    check(typeof input.phone_number === 'string' && /^\+[1-9]\d{6,14}$/u.test(input.phone_number));
+    merchantUrl(input.start_url);
+    check(input.interaction_mode === undefined || ['hosted', 'chat'].includes(input.interaction_mode));
+    check(input.purpose === undefined || ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(input.purpose));
+    check(input.approval_policy === undefined || ['before_fill', 'after_fill'].includes(input.approval_policy));
+    check(input.approval_policy !== 'after_fill' || input.interaction_mode === 'chat' && input.purpose !== 'sandbox_source_comparison');
+    check(input.fill_after_verification === undefined || input.fill_after_verification === true && input.interaction_mode === 'chat' && input.approval_policy === 'after_fill' && ['purchase', 'sandbox_fill_only'].includes(input.purpose ?? 'purchase'));
+    check(input.purpose !== 'sandbox_fill_only' || input.interaction_mode === 'chat');
+    check(input.interaction_mode === 'chat' ? typeof input.conversation_id === 'string' && /^[A-Za-z0-9_.:-]{1,500}$/u.test(input.conversation_id) : input.conversation_id === undefined);
+    if (input.browser !== undefined) {
+      keys(input.browser, ['provider', 'browser_id', 'custody_mode', ...(input.browser?.provider === 'connector' ? ['connector_id'] : [])]);
+      const supportedBinding = input.browser.provider === 'browser_use'
+        ? typeof input.browser.browser_id === 'string' && UUID.test(input.browser.browser_id) && input.browser.browser_id === input.browser.browser_id.toLowerCase()
+        : input.browser.provider === 'connector' && typeof input.browser.connector_id === 'string' && /^[a-z][a-z0-9_-]{0,63}$/u.test(input.browser.connector_id) &&
+          typeof input.browser.browser_id === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/u.test(input.browser.browser_id);
+      check(supportedBinding && input.browser.custody_mode === 'customer_backend_trusted' &&
+        input.interaction_mode === 'chat' && input.approval_policy === 'after_fill' && input.purpose !== 'sandbox_source_comparison');
+    }
+    check(input.browser_resource === undefined || input.browser?.provider === 'browser_use' && input.browser_resource?.id === input.browser.browser_id);
+    return this.#request('POST', null, '', { ...input }, options).then(result => {
+      check(input.purpose !== 'sandbox_fill_only' || result.purpose === 'sandbox_fill_only' && result.submit_allowed === false, 'invalid_response');
+      check(input.approval_policy !== 'after_fill' || result.approval_policy === 'after_fill' && result.purchase_approved === false, 'invalid_response');
+      check(input.interaction_mode !== 'chat' || result.wallet_url === undefined, 'invalid_response');
+      check(input.fill_after_verification !== true || result.fill_after_verification === true, 'invalid_response'); return result;
+    });
+  }
+  async #request(method, id, suffix, body, options = {}, connection = false) {
+    keys(options, ['signal'], []);
+    check(options.signal === undefined || options.signal instanceof AbortSignal);
+    const controller = new AbortController();
+    const milliseconds = connection ? 45000 : ['/inspect-creation', '/inspect-retirement'].includes(suffix) ? 60000 : id === null ? 245000 : ({ '/fill': 235000, '/details': 125000, '/verify-quote': 125000, '/approval': 125000,
+      '/submit': 125000, '/browser': 85000, '/cancel': 45000, '': 45000 })[suffix];
+    const timer = setTimeout(() => controller.abort(), milliseconds); timer.unref?.();
+    const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+    const url = connection ? `${this.#origin}/v1/connection` :
+      `${this.#origin}/v1/checkouts${id === null ? '' : `/${id}`}${suffix}`;
+    let response;
+    try {
+      signal.throwIfAborted();
+      response = await bounded(this.#fetch(url, { method, redirect: 'error', cache: 'no-store', signal,
+        headers: { Authorization: `Bearer ${this.#apiKey}`, 'X-Accelerate-Merchant-Id': this.#merchantId,
+          ...(!connection ? { 'X-Accelerate-Diagnostics': 'v1' } : {}),
+          Accept: 'application/json', ...(method === 'POST' ? { 'Content-Type': 'application/json' } : {}) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }) }), signal);
+      check(!response.redirected && response.status < 300 && (!response.url || response.url === url) ||
+        (!response.redirected && response.status >= 400 && (!response.url || response.url === url)), 'invalid_response');
+      const value = await bounded(readJson(response, signal), signal);
+      signal.throwIfAborted();
+      if (!response.ok) throw new AccelerateError(ERROR_CODES.has(value?.error?.code) ? value.error.code : 'request_failed', response.status,
+        response.headers.get('x-accelerate-support-reference'));
+      return connection ? connectionResponse(value, this.#merchantId) : suffix === '/browser' ? browserResponse(value) :
+        suffix === '/verify-quote' ? verifiedQuoteResponse(value, id, body) : suffix === '/inspect-creation' ? creationInspectionResponse(value, body) : suffix === '/inspect-retirement' ? retirementInspectionResponse(value, id, body) : statusResponse(value, id, {
+        create: id === null, origin: this.#origin, loopback: this.#loopback });
+    } catch (error) {
+      Promise.resolve(response?.body?.cancel()).catch(() => {});
+      if (signal.aborted) throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'request_timeout');
+      if (error instanceof AccelerateError) throw error;
+      throw new AccelerateError('request_failed');
+    } finally { clearTimeout(timer); }
+  }
+}

package/linq-messaging.d.ts

@@ -0,0 +1,45 @@
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { AuthenticatedPrivateMessage, PrivateMessagingAdapter } from './private-ingress.js';
+
+interface LinqRequestOptions { signal?: AbortSignal; maxRetries?: number; timeout?: number }
+export interface LinqMessage {
+  id: string;
+  chat_id?: string;
+  is_from_me?: boolean;
+  delivery_status: string;
+  sent_at?: string | null;
+}
+export interface LinqPrivateChat {
+  id: string;
+  is_group: boolean;
+  handles: Array<{ handle: string; is_me: boolean; left_at?: string | null; status?: string | null }>;
+}
+/** Structural surface compatible with the installed @linqapp/sdk. No provider
+ * credential is returned by this adapter or required in model-visible config. */
+export interface LinqMessagingClient {
+  chats: {
+    retrieve(id: string, options?: LinqRequestOptions): Promise<LinqPrivateChat>;
+    messages: { send(id: string, body: { message: { idempotency_key: string; parts: Array<
+      { type: 'text'; value: string } | { type: 'media'; attachment_id: string }> } },
+      options?: LinqRequestOptions): Promise<{ chat_id: string; message: LinqMessage }> };
+  };
+  messages: { retrieve(id: string, options?: LinqRequestOptions): Promise<LinqMessage> };
+  attachments: { create(input: { filename: string; content_type: 'image/png'; size_bytes: number },
+    options?: LinqRequestOptions): Promise<{ attachment_id: string; upload_url: string; http_method: string; required_headers: Record<string, string> }> };
+}
+export function createLinqMessagingAdapter(options: {
+  client: LinqMessagingClient;
+  sendingPhone: string;
+  /** Resolve an EXISTING established private chat from backend records. Do not
+   * accept a recipient chosen by a model; never create a new chat here. */
+  resolveDestination(context: Readonly<ManagedCheckoutContext>): Promise<string> | string;
+  fetchImpl?: typeof fetch;
+}): Readonly<PrivateMessagingAdapter>;
+export function createLinqWebhookAuthenticator<Request = unknown>(options: {
+  /** Strict true only after real signature/OIDC verification over raw bytes. */
+  verifyWebhook(request: Request, rawBody: Uint8Array): Promise<boolean> | boolean;
+  /** Map verified provider sender to an authenticated, phone-verified account,
+   * workspace and exact established conversation in backend records. */
+  resolveIdentity(identity: { phone_number: string; chat_id: string }): Promise<ManagedCheckoutContext> | ManagedCheckoutContext;
+  retrieveChat(chatId: string): Promise<Pick<LinqPrivateChat, 'id' | 'is_group'>>;
+}): (request: Request, rawBody: Uint8Array) => Promise<AuthenticatedPrivateMessage | { kind: 'ignore' }>;

package/linq-messaging.js

@@ -0,0 +1,123 @@
+import { AccelerateError } from './index.js';
+import { authenticatedCheckoutContext } from './host-adapter.js';
+
+const HANDLE = /^[A-Za-z0-9_-]{1,500}$/;
+const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const maximumReviewImageBytes = 8 * 1024 * 1024;
+const check = condition => { if (!condition) throw new AccelerateError('request_failed'); };
+const phone = value => typeof value === 'string' && /^\+[1-9][\d ()-]+$/.test(value) ? value.replace(/[ ()-]/g, '') : undefined;
+function receipt(value, chatId, expectedId) {
+  check(value && value.chat_id === chatId && value.is_from_me === true && MESSAGE.test(value.id) && (!expectedId || value.id === expectedId));
+  if (!['sent', 'delivered', 'read'].includes(value.delivery_status)) return undefined;
+  check(typeof value.sent_at === 'string' && Number.isFinite(Date.parse(value.sent_at)) && Date.parse(value.sent_at) <= Date.now());
+  return { message_id: value.id, sent_at: new Date(value.sent_at).toISOString() };
+}
+async function wait(ms, signal) {
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    function done() { signal?.removeEventListener('abort', abort); resolve(); }
+    function abort() { clearTimeout(timer); signal?.removeEventListener('abort', abort); reject(new AccelerateError('request_cancelled')); }
+    signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  });
+}
+function boundedSignal(signal, expiresAt) {
+  const remaining = expiresAt === undefined ? 45000 : Date.parse(expiresAt) - Date.now(); check(Number.isFinite(remaining) && remaining > 0);
+  const timeout = AbortSignal.timeout(Math.min(45000, remaining));
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function prompt(message) {
+  check(message && typeof message.text === 'string' && message.text.length > 0 && message.text.length <= 10000 && typeof message.idempotency_key === 'string' && /^[A-Za-z0-9_.:-]{1,200}$/.test(message.idempotency_key));
+}
+
+/** Native Linq transport. Inject the installed @linqapp/sdk client configured
+ * with its server-only credential; the SDK does not install or own that key. */
+export function createLinqMessagingAdapter({ client, sendingPhone, resolveDestination, fetchImpl = globalThis.fetch } = {}) {
+  check(typeof client?.chats?.retrieve === 'function' && typeof client?.chats?.messages?.send === 'function' && typeof client?.messages?.retrieve === 'function' && typeof client?.attachments?.create === 'function' && /^\+[1-9]\d{6,14}$/.test(sendingPhone) && typeof resolveDestination === 'function' && typeof fetchImpl === 'function');
+  const destination = async (input, signal) => {
+    const context = authenticatedCheckoutContext(input), chatId = await resolveDestination(context);
+    check(typeof chatId === 'string' && HANDLE.test(chatId) && chatId !== 'pending' && context.phone_number !== sendingPhone);
+    signal.throwIfAborted();
+    const chat = await client.chats.retrieve(chatId, { signal, maxRetries: 0, timeout: 5000 });
+    check(chat?.id === chatId && chat.is_group === false && Array.isArray(chat.handles) && chat.handles.length === 2);
+    const own = chat.handles.filter(handle => handle.is_me === true), recipient = chat.handles.filter(handle => handle.is_me === false);
+    check(own.length === 1 && recipient.length === 1 && phone(own[0].handle) === sendingPhone && phone(recipient[0].handle) === context.phone_number && chat.handles.every(handle => handle.left_at == null && !['left', 'removed'].includes(handle.status)));
+    return chatId;
+  };
+  const send = async (chatId, message, signal, expiresAt) => {
+    signal.throwIfAborted();
+    const sent = await client.chats.messages.send(chatId, { message }, { signal, maxRetries: 0, timeout: 15000 });
+    check(sent?.chat_id === chatId && MESSAGE.test(sent?.message?.id));
+    const expectedId = sent.message.id;
+    // The send envelope proves this is our send; retrieval independently checks
+    // direction. Neither API's queue timestamp can arm purchase approval.
+    let current = { ...sent.message, chat_id: chatId, is_from_me: true };
+    for (let attempt = 0; attempt < 12; attempt++) {
+      signal.throwIfAborted(); check(expiresAt === undefined || Date.parse(expiresAt) > Date.now());
+      const confirmed = receipt(current, chatId, expectedId);
+      if (confirmed) return confirmed;
+      check(current.delivery_status !== 'failed');
+      await wait(1000, signal);
+      current = await client.messages.retrieve(expectedId, { signal, maxRetries: 0, timeout: 5000 });
+    }
+    throw new AccelerateError('request_failed');
+  };
+  return Object.freeze({
+    async sendText(context, message, options = {}) {
+      try {
+        prompt(message); const signal = boundedSignal(options.signal), chatId = await destination(context, signal);
+        return await send(chatId, { parts: [{ type: 'text', value: message.text }], idempotency_key: message.idempotency_key }, signal);
+      } catch { throw new AccelerateError('request_failed'); }
+    },
+    async sendReview(context, message) {
+      let uploadCopy;
+      try {
+        prompt(message);
+        check(Buffer.isBuffer(message.bytes) && message.bytes.length > 8 && message.bytes.length <= maximumReviewImageBytes && message.bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && message.contentType === 'image/png' && message.signal instanceof AbortSignal);
+        const signal = boundedSignal(message.signal, message.delivery_expires_at), chatId = await destination(context, signal);
+        const attachment = await client.attachments.create({ filename: 'accelerate-payment-review.png', content_type: 'image/png', size_bytes: message.bytes.length }, { signal, maxRetries: 0, timeout: 10000 });
+        let url; try { url = new URL(attachment.upload_url); } catch { check(false); }
+        check(url.protocol === 'https:' && !url.username && !url.password && attachment.http_method === 'PUT' && HANDLE.test(attachment.attachment_id) && attachment.required_headers && typeof attachment.required_headers === 'object' && Object.entries(attachment.required_headers).every(([key, value]) => typeof key === 'string' && typeof value === 'string'));
+        signal.throwIfAborted(); uploadCopy = Buffer.from(message.bytes);
+        const uploaded = await fetchImpl(url, { method: 'PUT', redirect: 'error', cache: 'no-store', credentials: 'omit', referrerPolicy: 'no-referrer', signal, headers: attachment.required_headers, body: uploadCopy });
+        try { await uploaded.body?.cancel(); } catch {}
+        check(uploaded.ok && !uploaded.redirected); signal.throwIfAborted();
+        return await send(chatId, { parts: [{ type: 'media', attachment_id: attachment.attachment_id }, { type: 'text', value: message.text }], idempotency_key: message.idempotency_key }, signal, message.delivery_expires_at);
+      } catch { throw new AccelerateError('request_failed'); }
+      finally { uploadCopy?.fill(0); }
+    },
+  });
+}
+
+/** Signature/OIDC verification and identity resolution are host dependencies.
+ * Never treat provider sender text, chat ID or a successful JSON parse as auth. */
+export function createLinqWebhookAuthenticator({ verifyWebhook, resolveIdentity, retrieveChat } = {}) {
+  check(typeof verifyWebhook === 'function' && typeof resolveIdentity === 'function' && typeof retrieveChat === 'function');
+  return async (request, rawBody) => {
+    let decoded;
+    try {
+      check(rawBody instanceof Uint8Array && rawBody.byteLength <= 262144 && await verifyWebhook(request, rawBody) === true);
+      decoded = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(rawBody));
+      if (decoded?.event_type !== 'message.received') return { kind: 'ignore' };
+      const data = decoded.data;
+      check(data && MESSAGE.test(data.id) && ['inbound', 'outbound'].includes(data.direction) && HANDLE.test(data.chat?.id) && data.sender_handle && typeof data.sender_handle.handle === 'string' && Array.isArray(data.parts) && data.parts.length <= 100);
+      if (data.direction !== 'inbound' || data.sender_handle.is_me === true) return { kind: 'ignore' };
+      const senderPhone = phone(data.sender_handle.handle); check(senderPhone && /^\+[1-9]\d{6,14}$/.test(senderPhone));
+      let isGroup = data.chat.is_group;
+      if (typeof isGroup !== 'boolean') { const chat = await retrieveChat(data.chat.id); check(chat?.id === data.chat.id && typeof chat.is_group === 'boolean'); isGroup = chat.is_group; }
+      check(isGroup === false);
+      const context = authenticatedCheckoutContext(await resolveIdentity({ phone_number: senderPhone, chat_id: data.chat.id }));
+      check(context.phone_number === senderPhone);
+      const parts = data.parts.map(part => { check(part && typeof part.type === 'string' && (part.value === undefined || typeof part.value === 'string')); return part; });
+      const text = parts.filter(part => ['text', 'link'].includes(part.type)).map(part => part.value ?? '').join('\n').trim(); check(text.length <= 2000);
+      const result = { authenticated: true, direct: true, context, message_id: data.id, text };
+      // Historical/reconciled deliveries cannot approve a current payment.
+      if (!data.reconciled_at && data.sent_at != null) { check(typeof data.sent_at === 'string' && Number.isFinite(Date.parse(data.sent_at))); result.sent_at = new Date(data.sent_at).toISOString(); }
+      if (data.reply_to?.message_id !== undefined) { check(MESSAGE.test(data.reply_to.message_id)); result.reply_to_message_id = data.reply_to.message_id; }
+      return result;
+    } catch { throw new AccelerateError('permission_denied'); }
+    finally {
+      if (Array.isArray(decoded?.data?.parts)) for (const part of decoded.data.parts) { if (part && typeof part === 'object' && Object.hasOwn(part, 'value')) part.value = ''; }
+      decoded = undefined;
+    }
+  };
+}