@weaccelerateinc/agent-sdk 0.0.0-stage → 0.11.0

package/checkout-diagnostics.d.ts

@@ -0,0 +1,34 @@
+export type CheckoutDiagnosticStage = 'not_started' | 'identity_required' | 'otp_required' | 'selection_required' |
+  'preparing_checkout' | 'approval_required' | 'cvv_required' | 'approved' | 'ready_for_submit' | 'review_delivery_required' | 'review_delivered' | 'approved_for_submit' | 'final_click_armed' |
+  'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
+export type CheckoutDiagnosticAction = 'get_status' | 'continue_private_chat' | 'prepare_checkout' | 'apply_details' |
+  'request_approval' | 'fill' | 'submit' | 'cancel' | 'reconcile_order';
+export type CheckoutCleanupStatus = 'not_required' | 'not_started' | 'pending' | 'confirmed';
+export type CheckoutReconciliationState = 'confirmed' | 'declined' | 'not_found';
+/** The client backend's statement of the merchant's result. Not Accelerate's proof: payment_confirmed stays false. */
+export interface CheckoutReconciliation {
+  state: CheckoutReconciliationState;
+  /** Short label for where the client read the result, such as merchant_order_api. */
+  source: string;
+  amount_cents: number | null;
+  currency: 'USD' | null;
+  reconciled_at: string;
+}
+export interface CheckoutDiagnostics {
+  version: 'v1';
+  stage: CheckoutDiagnosticStage;
+  /** Guidance only. Server authorization, revision, private consent and one-use checks remain mandatory. */
+  next_actions: CheckoutDiagnosticAction[];
+  support_reference: `acs_${string}`;
+  /** not_required means no retained browser reference. confirmed means worker closure acknowledgement; neither is independent provider proof. */
+  cleanup_status: CheckoutCleanupStatus;
+  submit_deadline?: string;
+}
+export const checkoutDiagnosticStages: readonly CheckoutDiagnosticStage[];
+export const checkoutDiagnosticActions: readonly CheckoutDiagnosticAction[];
+export const checkoutCleanupStatuses: readonly CheckoutCleanupStatus[];
+export const checkoutDiagnosticsJsonSchema: Readonly<Record<string, unknown>>;
+export function validateCheckoutDiagnostics(value: unknown, checkout?: {
+  status: string; purpose?: string; submit_allowed?: boolean; submit_expires_at?: string; approval_policy?: string; purchase_approved?: boolean; reconciliation?: unknown; final_click_actor?: string;
+}): CheckoutDiagnostics;
+export function validateCheckoutReconciliation(value: unknown, status?: string): CheckoutReconciliation;

package/checkout-diagnostics.js

@@ -0,0 +1,81 @@
+// Safe lifecycle metadata only. No transport, credentials, provider text or automatic actions.
+export const checkoutDiagnosticStages = Object.freeze(['not_started', 'identity_required', 'otp_required', 'selection_required',
+    'preparing_checkout', 'approval_required', 'cvv_required', 'approved', 'ready_for_submit', 'review_delivery_required', 'review_delivered', 'approved_for_submit', 'final_click_armed',
+    'cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+export const checkoutDiagnosticActions = Object.freeze(['get_status', 'continue_private_chat', 'prepare_checkout', 'apply_details',
+    'request_approval', 'fill', 'submit', 'cancel', 'reconcile_order']);
+export const checkoutCleanupStatuses = Object.freeze(['not_required', 'not_started', 'pending', 'confirmed']);
+const freeze = (value) => { if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const item of Object.values(value))
+        freeze(item);
+    Object.freeze(value);
+} return value; };
+export const checkoutDiagnosticsJsonSchema = freeze({ type: 'object', additionalProperties: false,
+    required: ['version', 'stage', 'next_actions', 'support_reference', 'cleanup_status'], properties: {
+        version: { const: 'v1' }, stage: { type: 'string', enum: checkoutDiagnosticStages },
+        next_actions: { type: 'array', minItems: 1, maxItems: checkoutDiagnosticActions.length, uniqueItems: true,
+            items: { type: 'string', enum: checkoutDiagnosticActions } },
+        support_reference: { type: 'string', pattern: '^acs_[a-f0-9]{32}$' },
+        cleanup_status: { type: 'string', enum: checkoutCleanupStatuses }, submit_deadline: { type: 'string', format: 'date-time' },
+    } });
+const terminal = new Set(['cancelled', 'expired', 'failed', 'submit_attempted', 'outcome_unknown']);
+const timestamp = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/.test(value) && Number.isFinite(Date.parse(value));
+const check = (value) => { if (!value) {
+    const error = Object.assign(Error('Invalid Accelerate checkout diagnostics.'), { code: 'invalid_response' });
+    throw error;
+} };
+/** Validate fixed metadata; optional checkout binding prevents contradictory action guidance. Never authorizes an action. */
+export function validateCheckoutDiagnostics(input, checkout) {
+    // Validation below checks every property before returning this value.
+    const value = input;
+    check(value !== null && typeof value === 'object' && !Array.isArray(value) &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(value)) &&
+        Object.keys(value).every(key => Object.hasOwn(checkoutDiagnosticsJsonSchema.properties, key)) &&
+        checkoutDiagnosticsJsonSchema.required.every(key => Object.hasOwn(value, key)) && value.version === 'v1' &&
+        checkoutDiagnosticStages.includes(value.stage) && Array.isArray(value.next_actions) && value.next_actions.length >= 1 &&
+        value.next_actions.length <= checkoutDiagnosticActions.length && new Set(value.next_actions).size === value.next_actions.length &&
+        value.next_actions.every(action => checkoutDiagnosticActions.includes(action)) &&
+        typeof value.support_reference === 'string' && /^acs_[a-f0-9]{32}$/.test(value.support_reference) &&
+        checkoutCleanupStatuses.includes(value.cleanup_status) && (value.submit_deadline === undefined || timestamp(value.submit_deadline)));
+    if (checkout !== undefined) {
+        const { status, purpose = 'purchase', submit_allowed, approval_policy, purchase_approved, reconciliation, final_click_actor } = checkout;
+        check(terminal.has(status) ? value.stage === status : status === 'wallet_required'
+            ? ['not_started', 'identity_required', 'otp_required', 'selection_required'].includes(value.stage)
+            : ['selection_ready', 'details_ready'].includes(status) ? value.stage === 'preparing_checkout'
+                : status === 'approval_required' ? ['approval_required', 'cvv_required'].includes(value.stage) : approval_policy === 'after_fill' && status === 'ready_for_submit' ? ['review_delivery_required', 'review_delivered', 'approval_required', 'approved_for_submit'].includes(value.stage) : value.stage === status);
+        check(status === 'ready_for_submit' ? timestamp(value.submit_deadline) && value.submit_deadline === checkout.submit_expires_at : value.submit_deadline === undefined);
+        for (const action of value.next_actions) {
+            if (action === 'submit')
+                check(status === 'ready_for_submit' && purpose === 'purchase' && submit_allowed !== false && final_click_actor === 'customer' && (approval_policy !== 'after_fill' || purchase_approved === true));
+            if (action === 'fill')
+                check(status === 'approved' && purpose !== 'sandbox_source_comparison');
+            if (['prepare_checkout', 'apply_details'].includes(action))
+                check(['selection_ready', 'details_ready'].includes(status));
+            if (action === 'request_approval')
+                check(status === 'details_ready');
+            if (action === 'continue_private_chat')
+                check(['wallet_required', 'approval_required'].includes(status) || approval_policy === 'after_fill' && status === 'ready_for_submit' && !purchase_approved);
+            if (action === 'reconcile_order')
+                check(['submit_attempted', 'outcome_unknown'].includes(status) && reconciliation === undefined);
+        }
+        // While a customer click is armed only a safe read or cancel is advertised: no browser work, no re-arm.
+        if (status === 'final_click_armed')
+            check(value.next_actions.every(action => ['get_status', 'cancel'].includes(action)));
+        if (!terminal.has(status))
+            check(value.cleanup_status !== 'pending' && value.cleanup_status !== 'confirmed');
+        if (terminal.has(status))
+            check(value.cleanup_status !== 'not_started');
+    }
+    return value;
+}
+/** Validate the client backend's stored statement of the merchant's result. Never proof of payment. */
+export function validateCheckoutReconciliation(input, status) {
+    const value = input;
+    check(value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value)) &&
+        Object.keys(value).length === 5 && ['confirmed', 'declined', 'not_found'].includes(value.state) &&
+        typeof value.source === 'string' && /^[a-z][a-z0-9_.-]{0,39}$/.test(value.source) && !/(?:\d[ -]?){13,19}/.test(value.source) &&
+        (value.amount_cents === null || Number.isSafeInteger(value.amount_cents) && value.amount_cents > 0 && value.amount_cents <= 2147483647) &&
+        (value.currency === null || value.currency === 'USD') && (value.state !== 'confirmed' || value.amount_cents !== null && value.currency === 'USD') &&
+        timestamp(value.reconciled_at) && (status === undefined || ['submit_attempted', 'outcome_unknown'].includes(status)));
+    return value;
+}

package/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { AccelerateClient, AccelerateError } from './index.js';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const help = `Usage: accelerate-agent doctor
+       accelerate-agent init <empty-directory> [--browser existing]
+       accelerate-agent --version
+
+Set ACCELERATE_API_KEY and ACCELERATE_MERCHANT_ID on your server.
+ACCELERATE_BASE_URL is optional for Accelerate's hosted service.
+
+Doctor checks API connectivity and the credential pair. It does not create a
+checkout, send a code, release credentials, fill a form or submit an order.
+It does not qualify the downstream payment source or browser configuration.
+
+Init copies the packaged synthetic MCP starter without credentials, network
+requests or overwrites. --browser existing selects the new provider-independent
+existing-browser starter with purchase purpose and a submit tool; omission
+preserves the managed Kernel starter, which is fill-only. Both start in
+synthetic mode. Purchase requires private approval, an explicit submit and your
+own browser host performing the one final click: Accelerate never clicks.
+Existing symlink paths and nonempty targets are rejected.
+`;
+const starterFiles = ['package.json', '.env.example', '.gitignore', 'README.md', 'server.mjs', 'runtime.mjs',
+  'synthetic.mjs', 'smoke.mjs', 'trusted-context.example.mjs', 'tests/starter.test.mjs'];
+const initFailure = code => { const error = Error('Starter initialization unavailable.'); error.code = code; throw error; };
+async function initializeStarter(directory, existingBrowser = false) {
+  if (typeof directory !== 'string' || !directory || directory.length > 2048 || /[\u0000-\u001f\u007f]/u.test(directory)) initFailure('init_target_invalid');
+  const target = resolve(directory), parent = dirname(target);
+  if (await realpath(parent) !== parent || !(await lstat(parent)).isDirectory()) initFailure('init_target_invalid');
+  try {
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(target) !== target) initFailure('init_target_invalid');
+    if ((await readdir(target)).length !== 0) initFailure('init_target_not_empty');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    await mkdir(target, { mode: 0o700 });
+  }
+  const sourceRoot = resolve(fileURLToPath(new URL(existingBrowser ? './partner-starter/' : './starter/', import.meta.url)));
+  if (await realpath(sourceRoot) !== sourceRoot) initFailure('init_failed');
+  const original = await lstat(target); let total = 0;
+  for (const name of starterFiles) {
+    const current = await lstat(target);
+    if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== original.dev || current.ino !== original.ino ||
+      await realpath(target) !== target) initFailure('init_target_invalid');
+    // npm strips .gitignore from archives; emit it from this explicit template.
+    const sourcePath = join(sourceRoot, name === '.gitignore' ? 'gitignore.template' : name);
+    if (await realpath(sourcePath) !== sourcePath) initFailure('init_failed');
+    const source = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let data;
+    try {
+      const stat = await source.stat();
+      if (!stat.isFile() || stat.size < 1 || stat.size > 65536 || (total += stat.size) > 262144) initFailure('init_failed');
+      data = await source.readFile();
+    } finally { await source.close(); }
+    const destination = join(target, name), folder = dirname(destination);
+    if (folder !== target) {
+      try { await mkdir(folder, { mode: 0o700 }); } catch (error) { if (error?.code !== 'EEXIST') throw error; }
+      if (!(await lstat(folder)).isDirectory() || await realpath(folder) !== folder) initFailure('init_target_invalid');
+    }
+    const output = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try { await output.writeFile(data); } finally { await output.close(); }
+  }
+}
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+  const { version } = JSON.parse(await readFile(new URL('./package.json', import.meta.url), 'utf8'));
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw Error('Invalid SDK package version.');
+  process.stdout.write(version + '\n');
+} else if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+  process.stdout.write(help);
+} else if (args[0] === 'init' && (args.length === 2 || args.length === 4 && args[2] === '--browser' && args[3] === 'existing')) {
+  try {
+    await initializeStarter(args[1], args.length === 4);
+    process.stdout.write(JSON.stringify({ ok: true, status: 'initialized', mode: 'synthetic', next_action: 'install_dependencies' }) + '\n');
+  } catch (error) {
+    const code = ['init_target_invalid', 'init_target_not_empty'].includes(error?.code) ? error.code : 'init_failed';
+    process.stdout.write(JSON.stringify({ ok: false, code }) + '\n'); process.exitCode = 1;
+  }
+} else if (args.length !== 1 || args[0] !== 'doctor') {
+  process.stderr.write(help);
+  process.exitCode = 2;
+} else {
+  try {
+    const result = await AccelerateClient.fromEnv().connection.check();
+    // Do not print environment values, merchant identifiers or upstream bodies.
+    process.stdout.write(JSON.stringify({ ok: true, status: result.status, api_version: result.api_version,
+      interaction_modes: result.interaction_modes, currencies: result.currencies,
+      downstream_payment_readiness: 'not_checked' }) + '\n');
+  } catch (error) {
+    const codes = new Set(['missing_api_key', 'missing_merchant_id', 'invalid_api_key', 'invalid_merchant_id',
+      'invalid_base_url', 'invalid_input', 'tenant_unauthorized', 'unauthorized', 'permission_denied',
+      'configuration_error', 'configuration_invalid', 'route_not_found', 'invalid_response',
+      'request_timeout', 'request_cancelled', 'request_failed', 'upstream_unavailable']);
+    const actions = new Set(['check_configuration', 'check_request', 'check_status', 'stop']);
+    const code = error instanceof AccelerateError && codes.has(error.code) ? error.code : 'request_failed';
+    const nextAction = error instanceof AccelerateError && actions.has(error.nextAction)
+      ? error.nextAction : 'check_configuration';
+    process.stdout.write(JSON.stringify({ ok: false, code, next_action: nextAction }) + '\n');
+    process.exitCode = 1;
+  }
+}

package/customer.env.example

@@ -0,0 +1,6 @@
+# Required: provide these through your backend's secret configuration.
+ACCELERATE_API_KEY=
+ACCELERATE_MERCHANT_ID=
+
+# Optional: omit when using Accelerate's hosted managed service.
+# ACCELERATE_BASE_URL=https://accelerate-agent-sdk.vercel.app

package/host-adapter.d.ts

@@ -0,0 +1,90 @@
+import type { Checkout, CheckoutId, AccelerateClient } from './index.js';
+import type { ManagedCheckoutContext, ManagedCheckoutEvent, ManagedCheckoutToolsOptions } from './managed-mcp.js';
+import type { PrivateChatState, PrivateChatPrompt, PrivateChatProgress } from './private-chat.js';
+
+export type HostOwner = Pick<ManagedCheckoutContext, 'customer_id' | 'workspace_id' | 'conversation_id'>;
+export interface HostCheckoutAttempt {
+  idempotency_key: string;
+  checkout_id?: CheckoutId;
+  phase: 'creating' | 'active' | 'uncertain' | 'closed';
+  /** Sticky across successful status/cancel; requires separate operator reconciliation. */
+  uncertain: boolean;
+  /** Durable one-use fill/submit admissions survive a lost final commit ACK. */
+  /** Independent provider cleanup proof, separate from service ACK. */
+  cleanup_confirmed?: boolean;
+  effects?: Array<'accelerate_checkout_fill' | 'accelerate_checkout_submit'>;
+  pending?: { operation: string; message_id?: string; revision?: number };
+  private_stage?: PrivateChatState['stage'];
+  checkout?: Checkout;
+}
+export type HostOutboxItem = {
+  id: string;
+  delivered: boolean;
+} & ({ kind: 'checkout_event'; payload: ManagedCheckoutEvent } |
+  { kind: 'private_prompt'; payload: PrivateChatPrompt & { checkout_id: CheckoutId } } |
+  { kind: 'safe_progress'; payload: PrivateChatProgress & { checkout_id: CheckoutId } });
+/** No OTP, CVV, PAN, image bytes, browser connection credentials or private reply
+ * text may enter this record. Encrypt at rest according to host policy. */
+export interface HostCheckoutRecord {
+  version: 'v1';
+  owner: HostOwner;
+  /** Authenticated original phone binding hash; never the raw phone number. */
+  phone_binding?: string;
+  attempt?: HostCheckoutAttempt;
+  history: Array<{ idempotency_key: string; checkout_id: CheckoutId; status: 'cancelled' | 'expired' | 'failed'; uncertain: false }>;
+  outbox: HostOutboxItem[];
+  /** Native-send receipts only, never image bytes/URLs or reply text. A pending
+   * send without receipt requires provider reconciliation, not another upload. */
+  deliveries?: Array<{ idempotency_key: string; receipt?: { message_id: string; sent_at: string } }>;
+}
+export interface HostPersistenceAccess {
+  load(): Promise<HostCheckoutRecord | undefined>;
+  /** Resolve only after a DURABLE independent commit. This write MUST survive a
+   * later callback failure; an enclosing rollback transaction is incompatible. */
+  commit(record: HostCheckoutRecord): Promise<void>;
+}
+export interface HostPersistence {
+  /** Hold a cross-process owner lock and call work exactly once. No automatic
+   * transaction/callback retries. Lost locks/commit acknowledgements must reject.
+   * A local Map/mutex does not implement this production durability contract. */
+  withLock<T>(ownerKey: string, work: (access: HostPersistenceAccess) => Promise<T>): Promise<T>;
+}
+export interface PrivateHostOperation {
+  operation: 'private_start' | 'private_reply' | 'private_state' | 'private_cancel' | 'review_delivery';
+  /** Original authenticated provider ID; required for recoverable reply replay. */
+  message_id?: string;
+}
+export interface OwnedPrivateCheckout extends ManagedCheckoutContext {
+  checkout_id: CheckoutId;
+  previous_stage?: PrivateChatState['stage'];
+  checkout?: Readonly<Checkout>;
+  /** Validates and commits only the safe state/progress/outgoing prompt. */
+  savePrivateState(state: PrivateChatState, options: { messageId: string; suppressPrompt?: boolean }): Promise<void>;
+}
+export interface DurableCheckoutHost<Extra = unknown> {
+  resolveContext: ManagedCheckoutToolsOptions<Extra>['resolveContext'];
+  withCheckoutCreation: ManagedCheckoutToolsOptions<Extra>['withCheckoutCreation'];
+  withOwnedCheckout: ManagedCheckoutToolsOptions<Extra>['withOwnedCheckout'];
+  dispatchCheckoutEvent: ManagedCheckoutToolsOptions<Extra>['dispatchCheckoutEvent'];
+  /** Durable actual native-send receipt cache; lost SDK ACK can reuse receipt
+   * without uploading/sending the same review again. */
+  withPrivateDelivery(context: ManagedCheckoutContext, idempotencyKey: string,
+    deliver: () => Promise<{ message_id: string; sent_at: string }>): Promise<Readonly<{ message_id: string; sent_at: string }>>;
+  /** Call ONLY after connector independently verifies stopped/cleared and retained fence. */
+  confirmBrowserCleanup(context: ManagedCheckoutContext, checkoutId: CheckoutId): Promise<void>;
+  withPrivateCheckout<T>(context: ManagedCheckoutContext, metadata: PrivateHostOperation,
+    work: (checkout: Readonly<OwnedPrivateCheckout>) => Promise<T>): Promise<T | undefined>;
+  /** Safe deliveries only. Recipient/queue must durably deduplicate item.id.
+   * Failure leaves the same pending delivery; never repeat fill or submit here. */
+  drainOutbox(context: ManagedCheckoutContext,
+    deliver: (item: Readonly<HostOutboxItem>, context: Readonly<ManagedCheckoutContext>) => Promise<void>): Promise<number>;
+}
+/** Strict runtime validation only; caller must actually authenticate upstream. */
+export function authenticatedCheckoutContext(value: unknown): Readonly<ManagedCheckoutContext>;
+/** Hash-only key scopes one active payment fence to customer+workspace. Exact
+ * authenticated conversation is additionally checked under the owner lock. */
+export function checkoutHostOwnerKey(context: ManagedCheckoutContext): string;
+export function createDurableCheckoutHost<Extra = unknown>(options: {
+  persistence: HostPersistence;
+  resolveContext: ManagedCheckoutToolsOptions<Extra>['resolveContext'];
+}): Readonly<DurableCheckoutHost<Extra>>;