@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/private-chat.js

@@ -0,0 +1,309 @@
+import { AccelerateClient, AccelerateError } from './index.js';
+import { createHash } from 'node:crypto';
+
+const idPattern = /^mcs_[A-Za-z0-9_-]{43}$/;
+const identityPattern = /^[A-Za-z0-9_.:-]{1,500}$/;
+// Native checkout reviews retain full lossless PNGs, including product photos.
+// This limit applies only to the private review image, not JSON responses.
+const maximumReviewImageBytes = 8 * 1024 * 1024;
+const stages = new Set(['not_started', 'identity_required', 'otp_required', 'selection_required', 'preparing_checkout', 'approval_required', 'cvv_required', 'verified', 'review_delivery_required', 'review_delivered', 'approved_for_submit', 'closed']);
+const statuses = new Set(['wallet_required', 'selection_ready', 'details_ready', 'approval_required', 'approved', 'ready_for_submit', 'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const check = (value, code = 'invalid_input') => { if (!value) throw new AccelerateError(code); };
+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);
+}
+function safe(value, max) {
+  check(typeof value === 'string' && value.length <= max && !/[\x00-\x1f\x7f]|(?:\d[ -]?){13,19}|\b(?:0[1-9]|1[0-2])\s*\/\s*(?:20)?\d{2}\b|aw[12]\.|(?:tok_|vgs_|Bearer\s|(?:wss?|devtools|chrome-extension):\/\/)|\b(?:session_token|handoff_token|submit_token|api_key|cvv|cvc|otp)\b/i.test(value), 'invalid_response');
+}
+function integer(value, min = 1) { check(Number.isSafeInteger(value) && value >= min && value <= 2147483647, 'invalid_response'); }
+function date(value) { check(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value)), 'invalid_response'); }
+function card(value) {
+  keys(value, ['last4', 'brand'], undefined, 'invalid_response');
+  check(value.last4 === null || typeof value.last4 === 'string' && /^\d{4}$/.test(value.last4), 'invalid_response');
+  if (value.brand !== null) safe(value.brand, 40);
+}
+function address(value) {
+  keys(value, ['label', 'city', 'state', 'postal_code_mask'], ['label'], 'invalid_response');
+  for (const [key, max] of [['label', 400], ['city', 128], ['state', 64]]) if (value[key] != null) safe(value[key], max);
+  check(value.postal_code_mask == null || typeof value.postal_code_mask === 'string' && /^\*{3}[A-Za-z0-9 -]{1,2}$/.test(value.postal_code_mask), 'invalid_response');
+}
+function quote(value, revision = false, afterFill = false) {
+  keys(value, ['checkout_origin', 'amount_cents', 'currency', ...(revision ? ['revision', ...(!afterFill ? ['approval_code'] : [])] : [])], undefined, 'invalid_response');
+  let parsed; try { parsed = new URL(value.checkout_origin); } catch { check(false, 'invalid_response'); }
+  check(parsed.protocol === 'https:' && parsed.origin === value.checkout_origin && !parsed.username && !parsed.password && !parsed.port, 'invalid_response');
+  integer(value.amount_cents); check(value.currency === 'USD', 'invalid_response');
+  if (revision) { integer(value.revision); if (!afterFill) check(typeof value.approval_code === 'string' && /^[a-f0-9]{12}$/.test(value.approval_code), 'invalid_response'); }
+}
+function state(value, expectedId) {
+  keys(value, ['checkout', 'stage', 'handled', 'duplicate', 'cards', 'addresses', 'identity_field', 'approval', 'selection_error', 'review'], ['checkout', 'stage', 'handled', 'duplicate', 'cards', 'addresses'], 'invalid_response');
+  keys(value.checkout, ['id', 'status', 'revision', 'expires_at', 'card', 'address', 'quote', 'submit_expires_at', 'purpose', 'submit_allowed', 'approval_policy', 'purchase_approved', 'fill_after_verification', 'retry_safe', 'payment_confirmed'],
+    ['id', 'status', 'revision', 'expires_at', 'retry_safe', 'payment_confirmed'], 'invalid_response');
+  const checkout = value.checkout;
+  if (checkout.purpose !== undefined || checkout.submit_allowed !== undefined) check(
+    ['purchase', 'sandbox_source_comparison', 'sandbox_fill_only'].includes(checkout.purpose) &&
+    checkout.submit_allowed === (checkout.purpose === 'purchase'), 'invalid_response');
+  check(checkout.id === expectedId && statuses.has(checkout.status) && checkout.retry_safe === false && checkout.payment_confirmed === false, 'invalid_response');
+  if (checkout.approval_policy !== undefined || checkout.purchase_approved !== undefined) check(checkout.approval_policy === 'after_fill' && typeof checkout.purchase_approved === 'boolean' && (!checkout.purchase_approved || checkout.status === 'ready_for_submit' && checkout.purpose === 'purchase'), 'invalid_response');
+  if (checkout.fill_after_verification !== undefined) check(checkout.fill_after_verification === true && checkout.approval_policy === 'after_fill' &&
+    ['purchase', 'sandbox_fill_only'].includes(checkout.purpose), 'invalid_response');
+  integer(checkout.revision, 0); date(checkout.expires_at); if (checkout.submit_expires_at !== undefined) date(checkout.submit_expires_at);
+  if (checkout.card !== undefined) card(checkout.card); if (checkout.address !== undefined) address(checkout.address); if (checkout.quote !== undefined) quote(checkout.quote);
+  check(stages.has(value.stage) && typeof value.handled === 'boolean' && typeof value.duplicate === 'boolean' &&
+    Array.isArray(value.cards) && value.cards.length <= 100 && Array.isArray(value.addresses) && value.addresses.length <= 100, 'invalid_response');
+  for (const [index, choice] of value.cards.entries()) { keys(choice, ['choice', 'last4', 'brand'], undefined, 'invalid_response');
+    check(choice.choice === index + 1, 'invalid_response'); card({ last4: choice.last4, brand: choice.brand }); }
+  for (const [index, choice] of value.addresses.entries()) { keys(choice, ['choice', 'label', 'city', 'state', 'postal_code_mask'], ['choice', 'label'], 'invalid_response');
+    check(choice.choice === index + 1, 'invalid_response'); const { choice: _, ...mask } = choice; address(mask); }
+  check(value.stage === 'selection_required' || value.cards.length === 0 && value.addresses.length === 0, 'invalid_response');
+  check(value.selection_error === undefined || value.stage === 'selection_required' &&
+    ['invalid_choice', 'address_required'].includes(value.selection_error), 'invalid_response');
+  check(value.stage === 'identity_required' ? ['first_name', 'last_name', 'email'].includes(value.identity_field) : value.identity_field === undefined, 'invalid_response');
+  if (value.approval !== undefined) { quote(value.approval, true, checkout.approval_policy === 'after_fill'); check(value.approval.revision === checkout.revision &&
+    ['approval_required', 'cvv_required', 'review_delivery_required', 'review_delivered', 'approved_for_submit'].includes(value.stage) &&
+    checkout.quote?.checkout_origin === value.approval.checkout_origin && checkout.quote.amount_cents === value.approval.amount_cents &&
+    checkout.quote.currency === value.approval.currency, 'invalid_response'); }
+  check(!['approval_required', 'cvv_required', 'review_delivery_required', 'review_delivered', 'approved_for_submit'].includes(value.stage) || value.approval !== undefined, 'invalid_response');
+  if (value.review !== undefined) { keys(value.review, ['id', 'expires_at', 'delivered', 'approval_window_ms', 'delivery_expires_at'], ['id', 'expires_at', 'delivered'], 'invalid_response');
+    check(checkout.approval_policy === 'after_fill' && checkout.status === 'ready_for_submit' && /^rvr_[A-Za-z0-9_-]{43}$/.test(value.review.id) && typeof value.review.delivered === 'boolean', 'invalid_response'); date(value.review.expires_at);
+    check(value.review.expires_at === checkout.submit_expires_at && (value.stage === 'review_delivery_required' ? !value.review.delivered : value.review.delivered), 'invalid_response'); }
+  if (value.review?.approval_window_ms !== undefined || value.review?.delivery_expires_at !== undefined) {
+    check(value.review.approval_window_ms === 300000, 'invalid_response'); date(value.review.delivery_expires_at);
+    check(Date.parse(value.review.delivery_expires_at) < Date.parse(value.review.expires_at) &&
+      (value.review.delivered || Date.parse(value.review.expires_at) - Date.parse(value.review.delivery_expires_at) >= 300000), 'invalid_response');
+  }
+  if (['review_delivery_required', 'review_delivered', 'approved_for_submit'].includes(value.stage)) check(value.review !== undefined, 'invalid_response');
+  if (checkout.approval_policy === 'after_fill') {
+    if (value.stage === 'review_delivery_required') check(checkout.purchase_approved === false, 'invalid_response');
+    if (value.stage === 'cvv_required') check(checkout.status === 'approval_required' && value.review === undefined, 'invalid_response');
+    if (value.stage === 'verified') check(checkout.status === 'approved', 'invalid_response');
+    if (value.stage === 'approval_required') check(checkout.status === 'ready_for_submit' && checkout.purpose === 'purchase' && value.review?.delivered === true && checkout.purchase_approved === false, 'invalid_response');
+    if (value.stage === 'approved_for_submit') check(checkout.purchase_approved === true && checkout.purpose === 'purchase', 'invalid_response');
+    if (value.stage === 'review_delivered') check(checkout.purpose === 'sandbox_fill_only' && checkout.purchase_approved === false, 'invalid_response');
+  }
+  return value;
+}
+function binding(input, reply = false, delivered = false) {
+  keys(input, ['customer_id', 'workspace_id', 'conversation_id', ...(reply ? ['message_id', 'text', 'sent_at', 'reply_to_message_id'] : delivered ? ['review_id', 'message_id', 'sent_at'] : [])], ['customer_id', 'workspace_id', 'conversation_id', ...(reply ? ['message_id', 'text'] : delivered ? ['review_id', 'message_id', 'sent_at'] : [])]);
+  for (const key of ['customer_id', 'workspace_id', 'conversation_id']) check(typeof input[key] === 'string' && identityPattern.test(input[key]));
+  if (reply) check(typeof input.message_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(input.message_id) &&
+    typeof input.text === 'string' && input.text.length > 0 && input.text.length <= 2000 && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(input.text));
+  if (input.sent_at !== undefined) check(typeof input.sent_at === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(input.sent_at) && Number.isFinite(Date.parse(input.sent_at)));
+  if (input.reply_to_message_id !== undefined) check(typeof input.reply_to_message_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(input.reply_to_message_id));
+  if (delivered) check(typeof input.review_id === 'string' && /^rvr_[A-Za-z0-9_-]{43}$/.test(input.review_id) && typeof input.message_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(input.message_id));
+}
+
+function presentation(value, options) {
+  keys(options, ['messageId']);
+  check(typeof options.messageId === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(options.messageId));
+  check(object(value) && object(value.checkout) && typeof value.checkout.id === 'string' && idPattern.test(value.checkout.id), 'invalid_response');
+  return state(value, value.checkout.id);
+}
+function deliveryKey(kind, value, messageId, text) {
+  return `accelerate-${kind}:` + createHash('sha256').update(JSON.stringify([
+    value.checkout.id, value.stage, value.checkout.revision, value.identity_field ?? null,
+    value.selection_error ?? null, messageId, text,
+  ])).digest('hex');
+}
+
+/** Render only validated masked state. This does not authenticate a webhook or authorize a checkout. */
+export function renderPrivateChatState(value, options) {
+  const response = presentation(value, options);
+  if (!response.handled) return undefined;
+  const fillOnly = response.checkout.purpose === 'sandbox_fill_only', afterFill = response.checkout.approval_policy === 'after_fill';
+  let text;
+  switch (response.stage) {
+    case 'not_started':
+      text = 'Ask the assistant to resume your existing Accelerate checkout.'; break;
+    case 'identity_required':
+      text = `Accelerate needs your ${response.identity_field === 'first_name' ? 'first name' : response.identity_field === 'last_name' ? 'last name' : 'email address'} to connect your wallet. Reply here privately, or reply cancel to stop.`; break;
+    case 'otp_required':
+      text = 'Accelerate sent a wallet verification code to your phone. Reply here with that code. Accelerate handles this reply privately and keeps it out of assistant prompts, history and memory. Reply cancel to stop.'; break;
+    case 'selection_required': {
+      const card = response.cards[0], address = response.addresses[0], multiple = response.addresses.length > 1;
+      if (!card) { text = 'No selectable saved card is available in your Accelerate wallet. Reply cancel to stop.'; break; }
+      const addressChoices = response.addresses.map(choice => `${multiple ? `Address ${choice.choice}` : 'Saved address'}: ${choice.label ?? 'Saved address'}${choice.city ? `, ${choice.city}` : ''}${choice.state ? `, ${choice.state}` : ''}${choice.postal_code_mask ? ` ${choice.postal_code_mask}` : ''}`);
+      const instructions = multiple && address
+        ? `Reply wallet CARD_NUMBER ADDRESS_NUMBER, for example wallet ${card.choice} ${address.choice}. Both numbers are required because you have multiple saved addresses.`
+        : `Reply Card ${card.choice} or Wallet ${card.choice}, using the number of your chosen card.${address ? ' Your saved address will be used automatically.' : ' No saved address is available.'}`;
+      const addressRequired = response.selection_error === 'address_required' && multiple;
+      text = [
+        response.selection_error
+          ? addressRequired ? 'Choose which saved address to use with your card. Include both choice numbers.' : 'That card or address choice is unavailable. Choose from the previous list.'
+          : multiple ? 'Choose your Accelerate wallet details:' : 'Choose your Accelerate wallet card:',
+        ...(!response.selection_error ? response.cards.map(choice => `Card ${choice.choice}: ${choice.brand ?? 'Card'} •••• ${choice.last4 ?? 'unavailable'}`) : []),
+        ...(!response.selection_error || addressRequired ? addressChoices : []), instructions,
+        'Reply cancel to stop. Do not send card numbers or expiration dates.',
+      ].join('\n'); break;
+    }
+    case 'preparing_checkout':
+      if (afterFill) { text = 'Accelerate wallet details selected. The selected card will be filled privately after security-code verification. No purchase will be made until you review the filled checkout and approve the final amount.' + (fillOnly ? ' This card-fill test cannot submit an order.' : ''); break; }
+      text = fillOnly
+        ? 'Accelerate wallet details selected. You will approve the exact merchant and total here before private card filling. This card-fill test cannot submit an order.'
+        : 'Accelerate wallet details selected. The assistant will continue this same checkout. You will approve its exact merchant and total here before payment.'; break;
+    case 'review_delivery_required':
+    case 'approval_required': {
+      const quote = response.approval;
+      if (afterFill) { text = `Your checkout is filled. Review the attached masked payment form.\nMerchant: ${new URL(quote.checkout_origin).hostname}\nFinal total: ${(quote.amount_cents / 100).toFixed(2)} ${quote.currency}\nCard: ${response.checkout.card?.brand ?? 'Card'} •••• ${response.checkout.card?.last4 ?? 'selected'}\n` + (fillOnly ? 'This card-fill test cannot submit an order. No purchase approval is needed; the checkout will be closed after this review.' : 'Do you approve this purchase? Reply approve or yes to approve, or decline or no to cancel. ' +
+        (response.review.approval_window_ms === 300000 && !response.review.delivered ? 'You have 5 minutes from this message to decide; ' : 'Approval expires at ' + new Date(response.review.expires_at).toISOString().slice(0, 19).replace('T', ' ') + ' UTC; ') + 'no payment has been submitted.'); break; }
+      text = `${fillOnly ? 'Approve this Accelerate card-fill test?' : 'Approve this Accelerate purchase?'}\nMerchant: ${new URL(quote.checkout_origin).hostname}\nTotal: ${(quote.amount_cents / 100).toFixed(2)} ${quote.currency}\nCard: ${response.checkout.card?.brand ?? 'Card'} •••• ${response.checkout.card?.last4 ?? 'selected'}\nAddress: ${response.checkout.address?.label ?? 'Selected address'}\nReply approve ${quote.revision} ${quote.approval_code} to authorize ${fillOnly ? 'private filling only. Order submission is disabled' : 'this exact checkout'}, or cancel to stop.`; break;
+    }
+    case 'cvv_required':
+      text = (afterFill ? 'We will fill your selected card privately so you can review the checkout before any purchase approval. ' : '') + `Reply here with the 3–4 digit security code for ${response.checkout.card?.brand ?? 'your selected card'} •••• ${response.checkout.card?.last4 ?? ''}. Accelerate handles this reply privately and keeps it out of assistant prompts, history and memory. Reply cancel to stop.`; break;
+    case 'review_delivered':
+      text = 'Your card-fill test is complete. The attached form shows masked card details and the final amount. Order submission is disabled; this checkout will be closed.'; break;
+    case 'approved_for_submit':
+      text = 'You approved this exact filled checkout and final total. The assistant can now request the final purchase click. No payment has been submitted yet.'; break;
+    case 'verified':
+      if (afterFill) { text = 'Your card was verified privately. Accelerate will fill it, then send a masked checkout image and final amount for your review. No purchase has been approved.'; break; }
+      text = fillOnly
+        ? 'Accelerate verified this card-fill test privately. The assistant will stop after filling; order submission is disabled. Your security code was withheld from assistant prompts, history and memory.'
+        : 'Accelerate verified your approved checkout privately. The assistant will continue this same checkout. Your security code was withheld from assistant prompts, history and memory.'; break;
+    case 'closed':
+      text = fillOnly ? `Your Accelerate card-fill test is ${response.checkout.status}. Order submission is disabled. Ask the assistant for its safe status; do not resend a security code.` : `Your Accelerate checkout is ${response.checkout.status}. A submit attempt does not confirm a purchase. Ask the assistant for the safe status; do not resend a security code.`; break;
+  }
+  return Object.freeze({ text, idempotency_key: deliveryKey('chat', response, options.messageId, text) });
+}
+
+/** Safe progress only. The caller must persist stage transitions and deduplicate dispatch before resuming its agent. */
+export function privateChatProgress(value, options) {
+  const response = presentation(value, options);
+  if (!response.handled) return undefined;
+  const messages = {
+    preparing_checkout: '[Accelerate private progress] Wallet selection is complete. Check the existing Accelerate checkout status and continue preparing that same checkout.',
+    approved_for_submit: '[Accelerate private progress] The customer approved the current filled checkout and final amount. Read its safe status; submit only that checkout once if submission is enabled. Do not repeat private card filling.',
+    verified: '[Accelerate private progress] Checkout approval and private verification are complete. Check the existing Accelerate checkout status and continue only that approved checkout. Do not request or repeat security codes.',
+    closed: '[Accelerate private progress] The checkout closed. Check its safe status, respect cancellation and reconcile any uncertain payment. Do not repeat a purchase.',
+  };
+  if (!Object.hasOwn(messages, response.stage)) return undefined;
+  const text = (response.stage === 'verified' && response.checkout.approval_policy === 'after_fill' ? response.checkout.fill_after_verification === true ? '[Accelerate private progress] Private card verification is complete. Accelerate continues the staged fill automatically and delivers the masked review privately. Read only this checkout’s safe status; do not call fill, request another security code or submit.' : '[Accelerate private progress] Private card verification is complete. Fill the existing checkout once, then send the safe filled review privately and wait for final customer approval. Do not submit yet.' : messages[response.stage]) + (response.checkout.purpose === 'sandbox_fill_only' ? ' This is a card-fill test; order submission is disabled.' : '');
+  return Object.freeze({ stage: response.stage, text, idempotency_key: deliveryKey('progress', response, options.messageId, text) });
+}
+
+/** Provider-neutral private delivery. The host authenticates the destination and
+ * the send receipt; this helper never receives provider credentials or a public
+ * media URL. Only send the supplied image and prompt together in one message. */
+export async function deliverPrivateCheckoutReview(options) {
+  keys(options, ['client', 'state', 'binding', 'messageId', 'send', 'signal'], ['client', 'state', 'binding', 'messageId', 'send']);
+  check(options.client instanceof AcceleratePrivateChatClient && typeof options.send === 'function' &&
+    (options.signal === undefined || options.signal instanceof AbortSignal));
+  binding(options.binding);
+  const response = presentation(options.state, { messageId: options.messageId });
+  check(response.checkout.approval_policy === 'after_fill' && response.stage === 'review_delivery_required' && response.handled &&
+    response.review?.approval_window_ms === 300000 && response.review.delivery_expires_at && response.approval, 'invalid_response');
+  const deadline = Date.parse(response.review.delivery_expires_at);
+  check(deadline > Date.now(), 'checkout_expired');
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), Math.max(1, Math.min(2147483647, deadline - Date.now()))); timer.unref?.();
+  const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+  let image;
+  const bounded = pending => new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener('abort', abort); reject(new AccelerateError('request_cancelled')); };
+    signal.addEventListener('abort', abort, { once: true }); if (signal.aborted) abort();
+    Promise.resolve(pending).then(value => { signal.removeEventListener('abort', abort);
+      if (signal.aborted) reject(new AccelerateError('request_cancelled')); else resolve(value); },
+    () => { signal.removeEventListener('abort', abort); reject(new AccelerateError('request_failed')); });
+  });
+  try {
+    signal.throwIfAborted();
+    image = await options.client.chat.review(response.checkout.id, options.binding, { signal });
+    check(image.review_id === response.review.id && image.expires_at === response.review.expires_at &&
+      image.approval_window_ms === response.review.approval_window_ms && image.delivery_expires_at === response.review.delivery_expires_at &&
+      image.amount_cents === response.approval.amount_cents && image.currency === response.approval.currency, 'invalid_response');
+    const prompt = renderPrivateChatState(response, { messageId: options.messageId });
+    signal.throwIfAborted(); check(Date.now() < deadline, 'checkout_expired');
+    const receipt = await bounded(options.send({ bytes: image.bytes, contentType: 'image/png', text: prompt.text,
+      idempotency_key: prompt.idempotency_key, delivery_expires_at: new Date(deadline).toISOString(), signal }));
+    keys(receipt, ['message_id', 'sent_at'], undefined, 'invalid_response');
+    check(typeof receipt.message_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(receipt.message_id), 'invalid_response'); date(receipt.sent_at);
+    const sentAt = Date.parse(receipt.sent_at), approvalExpiresAt = sentAt + 300000;
+    check(sentAt <= Date.now() && sentAt < deadline && approvalExpiresAt <= Date.parse(image.expires_at), 'invalid_response');
+    const delivered = await options.client.chat.reviewDelivered(response.checkout.id, { ...options.binding, review_id: image.review_id,
+      message_id: receipt.message_id, sent_at: receipt.sent_at }, { signal });
+    check(delivered.checkout.id === response.checkout.id && delivered.checkout.approval_policy === 'after_fill' && delivered.checkout.revision === response.checkout.revision &&
+      delivered.checkout.purpose === response.checkout.purpose && delivered.checkout.purchase_approved === false &&
+      delivered.stage === (response.checkout.purpose === 'sandbox_fill_only' ? 'review_delivered' : 'approval_required') &&
+      delivered.review?.id === response.review.id && delivered.review.delivered === true &&
+      delivered.review.approval_window_ms === 300000 && delivered.review.delivery_expires_at === response.review.delivery_expires_at &&
+      Date.parse(delivered.review.expires_at) === approvalExpiresAt && approvalExpiresAt > Date.now() &&
+      delivered.approval?.revision === response.approval.revision &&
+      delivered.approval.checkout_origin === response.approval.checkout_origin &&
+      delivered.approval.amount_cents === response.approval.amount_cents && delivered.approval.currency === response.approval.currency,
+    'invalid_response');
+    return delivered;
+  } catch (error) {
+    if (signal.aborted) throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'request_timeout');
+    throw error instanceof AccelerateError ? error : new AccelerateError('request_failed');
+  } finally { if (Buffer.isBuffer(image?.bytes)) image.bytes.fill(0); clearTimeout(timer); controller.abort(); }
+}
+
+/** Private webhook-ingress client. Never expose these methods as agent tools or log their inputs. */
+export class AcceleratePrivateChatClient {
+  #origin; #apiKey; #merchantId; #fetch;
+  static fromEnv(env = process.env) { return AccelerateClient.fromEnv.call(this, env); }
+  constructor(options = {}) {
+    // Keep exactly the normal SDK's server-only runtime and credential checks.
+    new AccelerateClient(options);
+    this.#origin = new URL(options.baseUrl).origin; this.#apiKey = options.apiKey;
+    this.#merchantId = options.merchantId.toLowerCase(); this.#fetch = options.fetchImpl ?? globalThis.fetch;
+    this.chat = Object.freeze({
+      start: async (id, input, options) => this.#request(id, 'start', input, options),
+      get: async (id, input, options) => this.#request(id, 'state', input, options),
+      reply: async (id, input, options) => { try { return await this.#request(id, 'reply', input, options); }
+        finally { if (object(input) && Object.hasOwn(input, 'text')) input.text = ''; } },
+      cancel: async (id, input, options) => this.#request(id, 'cancel', input, options),
+      review: async (id, input, options) => this.#request(id, 'review', input, options),
+      reviewDelivered: async (id, input, options) => this.#request(id, 'review-delivered', input, options),
+    });
+  }
+  async #request(id, action, input, options = {}) {
+    check(typeof id === 'string' && idPattern.test(id)); binding(input, action === 'reply', action === 'review-delivered');
+    keys(options, ['signal'], []); check(options.signal === undefined || options.signal instanceof AbortSignal);
+    const controller = new AbortController(), timer = setTimeout(() => controller.abort(), action === 'reply' ? 215000 : action === 'start' ? 125000 : 45000); timer.unref?.();
+    const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+    const url = `${this.#origin}/v1/checkouts/${id}/private-chat/${action}`;
+    let response, reader, body = JSON.stringify(input), finished = false;
+    const bounded = pending => new Promise((resolve, reject) => {
+      const abort = () => { signal.removeEventListener('abort', abort); reject(new AccelerateError('request_cancelled')); };
+      signal.addEventListener('abort', abort, { once: true }); if (signal.aborted) abort();
+      Promise.resolve(pending).then(value => { signal.removeEventListener('abort', abort);
+        if (signal.aborted) { Promise.resolve(value?.body?.cancel()).catch(() => {}); reject(new AccelerateError('request_cancelled')); } else resolve(value); },
+      () => { signal.removeEventListener('abort', abort); reject(new AccelerateError('request_failed')); });
+    });
+    try {
+      signal.throwIfAborted();
+      response = await bounded(this.#fetch(url, { method: 'POST', redirect: 'error', cache: 'no-store', credentials: 'omit', referrerPolicy: 'no-referrer', signal,
+        headers: { Authorization: `Bearer ${this.#apiKey}`, 'X-Accelerate-Merchant-Id': this.#merchantId, Accept: 'application/json', 'Content-Type': 'application/json' }, body }));
+      body = '';
+      if (action === 'review' && response.ok) {
+        check(!response.redirected && response.status === 200 && (!response.url || response.url === url) && /^image\/png(?:\s*;|$)/i.test(response.headers.get('content-type') ?? ''), 'invalid_response');
+        const review_id = response.headers.get('x-accelerate-review-id'), expires_at = response.headers.get('x-accelerate-review-expires-at'), amount = response.headers.get('x-accelerate-review-amount-cents'), currency = response.headers.get('x-accelerate-review-currency');
+        check(/^rvr_[A-Za-z0-9_-]{43}$/.test(review_id ?? '') && /^[1-9]\d{0,9}$/.test(amount ?? '') && currency === 'USD', 'invalid_response'); date(expires_at); integer(Number(amount));
+        const approvalWindow = response.headers.get('x-accelerate-review-approval-window-ms'), deliveryExpiry = response.headers.get('x-accelerate-review-delivery-expires-at');
+        if (approvalWindow !== null || deliveryExpiry !== null) { check(approvalWindow === '300000', 'invalid_response'); date(deliveryExpiry);
+          check(Date.parse(deliveryExpiry) < Date.parse(expires_at), 'invalid_response'); }
+        const length = response.headers.get('content-length'); check(length === null || /^\d+$/.test(length) && Number(length) <= maximumReviewImageBytes, 'invalid_response');
+        reader = response.body?.getReader(); check(reader, 'invalid_response'); let size = 0, bytes; const chunks = [];
+        try { while (true) { const next = await bounded(reader.read()); signal.throwIfAborted(); if (next.done) { finished = true; break; } size += next.value.byteLength; check(size <= maximumReviewImageBytes, 'invalid_response'); chunks.push(Buffer.from(next.value)); }
+          bytes = Buffer.concat(chunks); check(bytes.length > 8 && bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])), 'invalid_response');
+          const image = { bytes, review_id, expires_at, ...(approvalWindow === '300000' ? { approval_window_ms: 300000, delivery_expires_at: deliveryExpiry } : {}),
+            amount_cents: Number(amount), currency }; bytes = undefined; return image;
+        } finally { bytes?.fill(0); for (const chunk of chunks) chunk.fill(0); }
+      }
+      check(!response.redirected && (response.status === 200 || response.status >= 400) && (!response.url || response.url === url) && /^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') ?? ''), 'invalid_response');
+      const limit = response.ok ? 65536 : 4096, length = response.headers.get('content-length');
+      check(length === null || /^\d+$/.test(length) && Number(length) <= limit, 'invalid_response');
+      reader = response.body?.getReader(); check(reader, 'invalid_response');
+      let size = 0, raw = ''; const decoder = new TextDecoder('utf-8', { fatal: true });
+      while (true) { const next = await bounded(reader.read()); signal.throwIfAborted();
+        if (next.done) { finished = true; break; } size += next.value.byteLength; check(size <= limit, 'invalid_response'); raw += decoder.decode(next.value, { stream: true }); }
+      const value = JSON.parse(raw + decoder.decode()); raw = '';
+      if (!response.ok) throw new AccelerateError(value?.error?.code, response.status);
+      return state(value, id);
+    } catch (error) {
+      if (signal.aborted) throw new AccelerateError(options.signal?.aborted ? 'request_cancelled' : 'request_timeout');
+      throw error instanceof AccelerateError ? error : new AccelerateError('request_failed');
+    } finally { body = ''; clearTimeout(timer); controller.abort();
+      if (!finished) try { Promise.resolve(reader?.cancel() ?? response?.body?.cancel()).catch(() => {}); } catch {}
+      try { reader?.releaseLock(); } catch {} }
+  }
+}

package/private-ingress.d.ts

@@ -0,0 +1,46 @@
+import type { BrowserConnector } from './browser-connector.js';
+import type { AccelerateClient } from './index.js';
+import type { ManagedCheckoutContext } from './managed-mcp.js';
+import type { DurableCheckoutHost, HostOwner } from './host-adapter.js';
+import type { AcceleratePrivateChatClient, PrivateChatPrompt, PrivateChatProgress, PrivateReviewSend } from './private-chat.js';
+
+export interface PrivateMessageReceipt { message_id: string; sent_at: string }
+export interface PrivateMessagingAdapter {
+  /** Verify the established direct recipient against authenticated context on
+   * every send. Provider retries must deduplicate this exact idempotency key. */
+  sendText(context: Readonly<ManagedCheckoutContext>, message: PrivateChatPrompt,
+    options?: { signal?: AbortSignal }): Promise<PrivateMessageReceipt>;
+  /** Exact SDK-rendered PNG and total text in ONE private native message. Return
+   * only a provider-confirmed sent/delivered/read timestamp, never queue time. */
+  sendReview(context: Readonly<ManagedCheckoutContext>, message: PrivateReviewSend): Promise<PrivateMessageReceipt>;
+}
+export type AuthenticatedPrivateMessage = { kind?: 'message'; authenticated: true; direct: true;
+  context: ManagedCheckoutContext; message_id: string; text: string;
+  /** Omit for reconciled/historical events. Never fabricate from receipt time. */
+  sent_at?: string; reply_to_message_id?: string };
+export interface PrivateCheckoutIngress<Request = unknown> {
+  /** Call BEFORE framework parsing/caching/tracing/queues. Always erases rawBody
+   * and transient parsed text. Ordinary traffic is admitted only through the
+   * callback as a new minimal event, never by passing the original envelope. */
+  handle(request: Request, rawBody: Uint8Array): Promise<Readonly<{ handled: boolean; retry?: true }>>;
+  /** Safely recover pending lifecycle/prompt/progress deliveries only. Never
+   * repeats fill or submit. Requires authenticated context from the host. */
+  drain(context: ManagedCheckoutContext): Promise<number>;
+}
+export function isCredentialLikePrivateReply(text: unknown): boolean;
+export function createPrivateCheckoutIngress<Request = unknown>(options: {
+  authenticate(request: Request, rawBody: Uint8Array): Promise<AuthenticatedPrivateMessage | { kind: 'ignore' }>;
+  host: DurableCheckoutHost;
+  privateChat: AcceleratePrivateChatClient;
+  messaging: PrivateMessagingAdapter;
+  /** Ordinary text only, rebuilt from an allowlist after private interception. */
+  admitOrdinaryMessage(event: { binding: HostOwner; message_id: string; text: string }): Promise<void>;
+  /** Durably deduplicate the fixed safe event before resuming the model. Never
+   * append the original provider envelope, reply context or attachments. */
+  dispatchSafeProgress(progress: PrivateChatProgress & { binding: HostOwner; checkout_id: string }): Promise<void>;
+  /** Enables cleanup after durable fill-only review ACK; failure never retries
+   * filling. Purchase checkouts retain separate explicit agent submission. */
+  client?: AccelerateClient;
+  /** Rechecks readiness before OTP/CVV lifecycle delivery and independently confirms cleanup. */
+  browserConnector?: BrowserConnector;
+}): Readonly<PrivateCheckoutIngress<Request>>;

package/private-ingress.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { AccelerateError } from './index.js';
+import { authenticatedCheckoutContext } from './host-adapter.js';
+import { deliverPrivateCheckoutReview } from './private-chat.js';
+
+const MESSAGE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const PENDING = new Set(['identity_required', 'otp_required', 'selection_required', 'cvv_required', 'approval_required', 'review_delivery_required']);
+const TERMINAL = new Set(['cancelled', 'expired', 'failed', 'outcome_unknown', 'submit_attempted']);
+const check = condition => { if (!condition) throw new AccelerateError('invalid_input'); };
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+/** Defense in depth for unsolicited secrets; active private challenges consume
+ * EVERY reply, including prose that this heuristic cannot recognize. */
+export function isCredentialLikePrivateReply(text) {
+  return typeof text === 'string' && (/^\s*\d{3,8}\s*$/.test(text) || /(?:\d[ -]?){13,19}|\b(?:0[1-9]|1[0-2])\s*\/\s*(?:20)?\d{2}\b|\b(?:cvv|cvc|otp|(?:verification|security)\s*code|expiry|expiration)\b.{0,40}\d|\b(?:card|wallet)\s+\d+(?:\s+\d+)?\b|#ticket=[A-Za-z0-9_-]{43}/i.test(text));
+}
+function clearBody(body) { if (body instanceof Uint8Array) body.fill(0); }
+function clearReply(reply) { if (reply && Object.hasOwn(reply, 'text')) { try { reply.text = ''; } catch {} } }
+function replyMetadata(verified) {
+  const metadata = {};
+  if (verified.sent_at !== undefined) {
+    check(typeof verified.sent_at === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(verified.sent_at) && Number.isFinite(Date.parse(verified.sent_at)));
+    metadata.sent_at = new Date(verified.sent_at).toISOString();
+  }
+  if (verified.reply_to_message_id !== undefined) { check(MESSAGE.test(verified.reply_to_message_id)); metadata.reply_to_message_id = verified.reply_to_message_id; }
+  return metadata;
+}
+
+/** Provider-neutral, pre-framework private ingress and SAFE outbox processor.
+ * No callbacks may log/cache raw request bodies. authenticate must verify the
+ * real request signature/forwarder and resolve an established direct recipient. */
+export function createPrivateCheckoutIngress({ authenticate, host, privateChat, messaging, admitOrdinaryMessage,
+  dispatchSafeProgress, client, browserConnector } = {}) {
+  check([authenticate, host?.withPrivateCheckout, host?.drainOutbox, privateChat?.chat?.reply, privateChat?.chat?.get,
+    privateChat?.chat?.start, privateChat?.chat?.cancel, messaging?.sendText, messaging?.sendReview, admitOrdinaryMessage, dispatchSafeProgress].every(value => typeof value === 'function'));
+  if (browserConnector !== undefined) check(typeof browserConnector.assertPaymentReady === 'function' && typeof browserConnector.confirmCleanup === 'function');
+  if (client !== undefined) check(typeof client.checkouts?.get === 'function' && typeof client.checkouts?.cancel === 'function');
+  const completeFillOnly = async (context, state) => {
+    if (state.stage !== 'review_delivered' || state.checkout.purpose !== 'sandbox_fill_only' || !client) return;
+    // Review ACK has already committed. Cancellation is a distinct recovery-safe
+    // action. No failure may turn this into a new fill or a replacement checkout.
+    const result = await host.withOwnedCheckout(context, state.checkout.id, async () => ({ checkout: await client.checkouts.cancel(state.checkout.id) }), { operation: 'accelerate_checkout_cancel' });
+    check(result.checkout.diagnostics?.cleanup_status === 'confirmed');
+    if (browserConnector) {
+      await browserConnector.confirmCleanup(context, { checkout_id: state.checkout.id });
+      await host.confirmBrowserCleanup(context, state.checkout.id);
+    }
+  };
+  const saveAndDeliver = async (context, owned, response, messageId) => {
+    if (response.stage === 'review_delivery_required') {
+      await owned.savePrivateState(response, { messageId, suppressPrompt: true });
+      const delivered = await deliverPrivateCheckoutReview({ client: privateChat, state: response,
+        binding: { customer_id: context.customer_id, workspace_id: context.workspace_id, conversation_id: context.conversation_id },
+        messageId, send: message => host.withPrivateDelivery(context, message.idempotency_key, () => messaging.sendReview(context, message)) });
+      await owned.savePrivateState(delivered, { messageId, suppressPrompt: true });
+      await completeFillOnly(context, delivered);
+      return delivered;
+    }
+    await owned.savePrivateState(response, { messageId });
+    await completeFillOnly(context, response);
+    return response;
+  };
+  const drain = context => host.drainOutbox(context, async (item, trusted) => {
+    if (item.kind === 'private_prompt') {
+      await messaging.sendText(trusted, { text: item.payload.text, idempotency_key: item.id }); return;
+    }
+    if (item.kind === 'safe_progress') { await dispatchSafeProgress({ binding: {
+      customer_id: trusted.customer_id, workspace_id: trusted.workspace_id, conversation_id: trusted.conversation_id,
+    }, ...item.payload }); return; }
+    const event = item.payload;
+    if (browserConnector && ['created', 'payment_requested', 'approval_requested'].includes(event.kind)) await browserConnector.assertPaymentReady(trusted, { checkout_id: event.checkout.id });
+    await host.withPrivateCheckout(trusted, { operation: event.kind === 'payment_requested' || event.kind === 'created' ? 'private_start' : 'private_state' }, async owned => {
+      check(owned.checkout_id === event.checkout.id);
+      const binding = { customer_id: trusted.customer_id, workspace_id: trusted.workspace_id, conversation_id: trusted.conversation_id };
+      const response = await (['created', 'payment_requested'].includes(event.kind) ? privateChat.chat.start(owned.checkout_id, binding) : privateChat.chat.get(owned.checkout_id, binding));
+      await saveAndDeliver(trusted, owned, response, `event-${digest(item.id)}`);
+    });
+  });
+  return Object.freeze({ drain,
+    async handle(request, rawBody) {
+      let verified, context, messageId;
+      try {
+        check(rawBody instanceof Uint8Array);
+        verified = await authenticate(request, rawBody);
+        // Withhold the original envelope even for admitted ordinary messages.
+        // Only a new minimal event can cross the AI/history boundary below.
+        clearBody(rawBody);
+        if (verified?.kind === 'ignore') return Object.freeze({ handled: true });
+        check(verified?.authenticated === true && verified.direct === true);
+        context = authenticatedCheckoutContext(verified.context); messageId = verified.message_id;
+        check(typeof messageId === 'string' && MESSAGE.test(messageId) && typeof verified.text === 'string' && verified.text.length <= 2000 && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(verified.text));
+        const metadata = replyMetadata(verified), text = verified.text.trim(), credentialLike = isCredentialLikePrivateReply(text);
+        const current = await host.withPrivateCheckout(context, { operation: 'private_state' }, async owned => ({ id: owned.checkout_id, stage: owned.previous_stage, status: owned.checkout?.status }));
+        if (!current || !PENDING.has(current.stage) && (TERMINAL.has(current.status) || current.stage === 'not_started' || current.stage === undefined)) {
+          if (!credentialLike) {
+            await admitOrdinaryMessage({ binding: { customer_id: context.customer_id, workspace_id: context.workspace_id, conversation_id: context.conversation_id }, message_id: messageId, text: verified.text });
+            return Object.freeze({ handled: false });
+          }
+          return Object.freeze({ handled: true });
+        }
+        const isStatus = /^status$/i.test(text), isCancel = /^cancel$/i.test(text);
+        let serviceHandled = true;
+        await host.withPrivateCheckout(context, { operation: isStatus ? 'private_state' : isCancel ? 'private_cancel' : 'private_reply',
+          ...(!isStatus && !isCancel ? { message_id: messageId } : {}) }, async owned => {
+          const binding = { customer_id: context.customer_id, workspace_id: context.workspace_id, conversation_id: context.conversation_id };
+          let response;
+          if (isStatus) response = await privateChat.chat.get(owned.checkout_id, binding);
+          else if (isCancel) response = await privateChat.chat.cancel(owned.checkout_id, binding);
+          else {
+            const input = { ...binding, message_id: messageId, text: text || '[non-text reply]', ...metadata };
+            try { response = await privateChat.chat.reply(owned.checkout_id, input); } finally { input.text = ''; }
+          }
+          const consume = response.handled || credentialLike || PENDING.has(current.stage);
+          serviceHandled = consume;
+          await saveAndDeliver(context, owned, consume ? { ...response, handled: true } : response, messageId);
+        });
+        await drain(context);
+        if (!serviceHandled) await admitOrdinaryMessage({ binding: { customer_id: context.customer_id, workspace_id: context.workspace_id, conversation_id: context.conversation_id }, message_id: messageId, text: verified.text });
+        return Object.freeze({ handled: serviceHandled });
+      } catch {
+        // Neither raw provider errors nor sensitive input escape to framework
+        // logs, model tool results, tracing, history, memory or durable jobs.
+        if (context && messageId && MESSAGE.test(messageId)) {
+          try { await messaging.sendText(context, {
+            text: 'The private Accelerate step could not be confirmed. Your reply was withheld from the assistant. Reply status to check this existing checkout; do not restart or repeat a potentially completed purchase.',
+            idempotency_key: `accelerate-private-error:${digest(messageId)}`,
+          }); } catch {}
+        }
+        return Object.freeze({ handled: true, retry: true });
+      } finally { clearBody(rawBody); clearReply(verified); }
+    },
+  });
+}

package/starter/.env.example

@@ -0,0 +1,19 @@
+# Default: no credentials, network, wallet, browser or purchase.
+ACCELERATE_STARTER_MODE=synthetic
+# Supported managed_review_v1: verify at payment, fill, then private review.
+# The default test never asks for purchase approval and cannot submit an order.
+ACCELERATE_STARTER_PURPOSE=sandbox_fill_only
+ACCELERATE_ENABLE_PURCHASE_SUBMIT=false
+
+# Real sandbox mode requires your existing authenticated backend context module.
+# ACCELERATE_STARTER_MODE=live
+# ACCELERATE_CONTEXT_MODULE=/absolute/server/path/trusted-context.mjs
+# ACCELERATE_API_KEY=
+# ACCELERATE_MERCHANT_ID=
+# ACCELERATE_BASE_URL=https://accelerate-agent-sdk.vercel.app
+
+# Only after qualifying the merchant and testing your private provider ingress:
+# ACCELERATE_STARTER_PURPOSE=purchase
+# ACCELERATE_ENABLE_PURCHASE_SUBMIT=true
+# This exposes a separate agent submit tool; private customer approval never
+# invokes it automatically. A five-minute review starts at confirmed delivery.