@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/index.js

@@ -0,0 +1,504 @@
+import { env as processEnv, versions } from 'node:process';
+import { createHash } from 'node:crypto';
+import { normalizeBrowserOperation } from './browser-operations.js';
+import { validateCheckoutDiagnostics, validateCheckoutReconciliation } 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', 'final_click_armed', '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_pending',
+  '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',
+  'reconciliation_unavailable', 'reconciliation_mismatch', 'reconciliation_conflict', 'customer_click_required', 'final_click_in_progress']);
+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'],
+  [['verification_pending'],
+    'A private verification for this shopper, card, total and site is still open. Wait for it to expire, up to five minutes, then start a new checkout.', 'stop'],
+  [['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'],
+  [['final_click_in_progress'],
+    'A customer-owned final click is armed and not yet observed. Read the checkout status; do not cancel, re-arm or click again.', 'check_status'],
+  [['customer_click_required'],
+    'Accelerate never performs the final payment click. Use the customer-owned browser host: arm, click once in the customer browser, then complete.', 'check_request'],
+  [['reconciliation_unavailable'],
+    'This checkout has no submit outcome to reconcile. Nothing was recorded. Read its status.', 'check_status'],
+  [['reconciliation_mismatch'],
+    'The order does not match the approved quote. Nothing was recorded. Check the merchant order.', 'reconcile_order'],
+  [['reconciliation_conflict'],
+    'A different result is already recorded for this checkout. It cannot be replaced.', '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 reconciliationInput(input) {
+  keys(input, ['state', 'order_reference', 'amount_cents', 'currency', 'source'], ['state', 'source']);
+  check(['confirmed', 'declined', 'not_found'].includes(input.state) && typeof input.source === 'string' &&
+    /^[a-z][a-z0-9_.-]{0,39}$/u.test(input.source) && !/(?:\d[ -]?){13,19}/u.test(input.source));
+  if (input.order_reference !== undefined) string(input.order_reference, 200);
+  if (input.amount_cents !== undefined) integer(input.amount_cents, 1, 2147483647);
+  check(input.currency === undefined || input.currency === 'USD');
+  check(input.state !== 'confirmed' || [input.order_reference, input.amount_cents, input.currency].every(value => value !== undefined));
+  return { ...input };
+}
+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', 'reconciliation', 'final_click_actor', 'submit_actor', '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 || ['ready_for_submit', 'final_click_armed'].includes(value.status) && 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);
+  // Only the customer's own backend/browser may ever perform the final click.
+  if (value.final_click_actor !== undefined) check(value.final_click_actor === 'customer' && value.purpose === 'purchase', 'invalid_response');
+  if (value.submit_actor !== undefined) check(value.submit_actor === 'customer' && value.final_click_actor === 'customer' &&
+    ['submit_attempted', 'outcome_unknown'].includes(value.status), 'invalid_response');
+  // An attested attempt names the customer; an unknown outcome cannot assert that a click happened.
+  if (value.status === 'submit_attempted' && value.purpose === 'purchase') check(value.submit_actor === 'customer', 'invalid_response');
+  if (value.reconciliation !== undefined) {
+    try { validateCheckoutReconciliation(value.reconciliation, value.status); } catch { fail('invalid_response'); }
+  }
+  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;
+}
+const ARM_ID = /^[\x21-\x7e]{20,16000}$/u;
+function armId(value, code = 'invalid_input') { check(typeof value === 'string' && ARM_ID.test(value), code); return value; }
+function finalClickArmResponse(value, input) {
+  keys(value, ['arm_id', 'armed_expires_at', 'target', 'retry_safe', 'payment_confirmed'], undefined, 'invalid_response');
+  armId(value.arm_id, 'invalid_response'); timestamp(value.armed_expires_at);
+  check(value.retry_safe === false && value.payment_confirmed === false, 'invalid_response');
+  keys(value.target, ['checkout_url', 'submit_selector'], undefined, 'invalid_response');
+  try { merchantUrl(value.target.checkout_url); string(value.target.submit_selector, 200); } catch { fail('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),
+      // The old executor-click endpoint is permanently closed: Accelerate never sends the final click.
+      submit: async () => fail('customer_click_required'),
+      /** Backend only. The returned target is never model/MCP output. */
+      armFinalClick: async (id, input, options) => this.#request('POST', checkoutId(id), '/final-click/arm', revisionInput(input), options),
+      completeFinalClick: async (id, input, options) => {
+        keys(input, ['revision', 'arm_id']); integer(input.revision, 1, 2147483647); armId(input.arm_id);
+        const result = await this.#request('POST', checkoutId(id), '/final-click/complete', { revision: input.revision, arm_id: input.arm_id }, options);
+        check(['submit_attempted', 'outcome_unknown'].includes(result.status) && result.purpose === 'purchase' &&
+          result.final_click_actor === 'customer' && (result.status === 'outcome_unknown' || result.submit_actor === 'customer'), 'invalid_response');
+        return result;
+      },
+      cancel: async (id, options) => this.#request('POST', checkoutId(id), '/cancel', {}, options),
+      reconcile: async (id, input, options) => {
+        const body = reconciliationInput(input);
+        const result = await this.#request('POST', checkoutId(id), '/reconcile', body, options);
+        check(result.reconciliation?.state === body.state && result.reconciliation.source === body.source, 'invalid_response');
+        return result;
+      },
+    });
+  }
+  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', 'final_click_actor'],
+      ['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');
+    // Purchases are never clicked by Accelerate. They require the customer's own trusted browser and final-click actor.
+    check(input.final_click_actor === undefined || input.final_click_actor === 'customer' && (input.purpose ?? 'purchase') === 'purchase');
+    if ((input.purpose ?? 'purchase') === 'purchase') check(input.final_click_actor === 'customer' && input.interaction_mode === 'chat' &&
+      input.approval_policy === 'after_fill' && input.browser?.custody_mode === 'customer_backend_trusted');
+    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');
+      check(input.final_click_actor !== 'customer' || result.final_click_actor === 'customer' && result.purpose === 'purchase', '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,
+      '/final-click/arm': 20000, '/final-click/complete': 125000, '/browser': 85000, '/cancel': 45000, '/reconcile': 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 === '/final-click/arm' ? finalClickArmResponse(value, 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' }>;