@weaccelerateinc/agent-sdk 0.0.0-stage → 0.10.3

package/index.d.ts

@@ -0,0 +1,209 @@
+import type { BrowserOperation, BrowserResult } from './browser-operations.js';
+import type { CheckoutDiagnostics } from './checkout-diagnostics.js';
+export { checkoutDiagnosticsJsonSchema, validateCheckoutDiagnostics } from './checkout-diagnostics.js';
+export type { CheckoutDiagnostics, CheckoutDiagnosticStage, CheckoutDiagnosticAction, CheckoutCleanupStatus } from './checkout-diagnostics.js';
+export type { BrowserOperation, BrowserResult, BrowserStep, BrowserCondition } from './browser-operations.js';
+
+export type CheckoutId = `mcs_${string}`;
+export type CheckoutPurpose = 'purchase' | 'sandbox_source_comparison' | 'sandbox_fill_only';
+export type CheckoutStatus = 'wallet_required' | 'selection_ready' | 'details_ready' | 'approval_required' |
+  'approved' | 'ready_for_submit' | 'cancelled' | 'expired' | 'failed' | 'submit_attempted' | 'outcome_unknown';
+export interface RequestOptions { signal?: AbortSignal }
+export interface WaitForCheckout {
+  /** Return on these states, or immediately on ready_for_submit or any terminal state. GET requests only. */
+  statuses: readonly CheckoutStatus[];
+  /** Overall wait, including requests. Default 60 seconds; range 1–300000 milliseconds. */
+  timeoutMs?: number;
+  /** Delay between successful status reads. Default 1000; range 250–5000 milliseconds. Errors are never retried. */
+  intervalMs?: number;
+}
+export type AccelerateNextAction = 'check_configuration' | 'check_request' | 'check_status' | 'complete_wallet' |
+  'complete_verification' | 'refresh_quote' | 'refresh_revision' | 'reconcile_order' | 'stop';
+export interface AccelerateEnvironment {
+  /** Optional HTTPS origin; defaults to Accelerate's hosted managed service. */
+  ACCELERATE_BASE_URL?: string;
+  ACCELERATE_API_KEY?: string;
+  ACCELERATE_MERCHANT_ID?: string;
+}
+export interface AccelerateConnection {
+  status: 'connected';
+  api_version: 'v1';
+  merchant_id: string;
+  interaction_modes: ['chat', 'hosted'];
+  currencies: ['USD'];
+}
+export interface Checkout {
+  id: CheckoutId;
+  status: CheckoutStatus;
+  revision: number;
+  expires_at: string;
+  /** Immutable policy metadata. Omitted only by service versions predating this field. */
+  purpose?: CheckoutPurpose;
+  /** Submission is enabled only for purchase purpose; never for sandbox_fill_only. */
+  submit_allowed?: boolean;
+  /** after_fill: final customer approval follows a privately delivered masked review. */
+  approval_policy?: 'after_fill';
+  purchase_approved?: boolean;
+  /** Explicit v2 policy acknowledged at creation; a later explicit quote arm lets private CVV continue
+   * one fill under the backend lock. Does not authorize final submission. */
+  fill_after_verification?: true;
+  card?: { last4: string | null; brand: string | null };
+  address?: { label: string | null; city?: string | null; state?: string | null; postal_code_mask?: string | null };
+  quote?: { checkout_origin: string; amount_cents: number; currency: 'USD' };
+  submit_expires_at?: string;
+  retry_safe: false;
+  payment_confirmed: false;
+  /** Negotiated safe metadata; absent when connecting to an older service. */
+  diagnostics?: CheckoutDiagnostics;
+}
+export interface CreatedCheckout extends Checkout { wallet_url?: string }
+/** Server-owned existing browser, resolved from the authenticated application's
+ * durable browser record. Never accept this binding from model arguments.
+ * The customer backend retains provider access; this is not private-from-creation custody. */
+export interface BrowserUseBrowserBinding {
+  provider: 'browser_use';
+  browser_id: string;
+  custody_mode: 'customer_backend_trusted';
+}
+/** Registered server-side executor connector; IDs are resolved from owned backend records. */
+export interface RegisteredBrowserBinding {
+  provider: 'connector';
+  connector_id: string;
+  browser_id: string;
+  custody_mode: 'customer_backend_trusted';
+}
+export type CustomerBrowserBinding = BrowserUseBrowserBinding | RegisteredBrowserBinding;
+/** Derive every field from authenticated server ownership and its immutable browser reservation. Never expose as model input. */
+export interface CreationInspectionRequest {
+  customer_id: string;
+  workspace_id: string;
+  conversation_id: string;
+  idempotency_key: string;
+  browser: BrowserUseBrowserBinding;
+}
+export type CreationInspection = { confirmed: false } | {
+  confirmed: true;
+  checkout_id: CheckoutId;
+  revision: 0;
+  purpose: 'purchase' | 'sandbox_fill_only';
+  creation_key_sha256: string;
+  retirement: { browser_provider: 'browser_use'; browser_id: string; retired: true; provider_stopped: true; private_lease_closed: true; recording_disabled: true };
+};
+/** Read-only proof for an already terminal, retired fill-only attempt. Never permits replay or purchase. */
+export interface RetirementInspectionRequest extends CreationInspectionRequest { revision: number; }
+export type RetirementInspection = { confirmed: false } | {
+  confirmed: true;
+  checkout_id: CheckoutId;
+  revision: number;
+  status: 'outcome_unknown';
+  purpose: 'sandbox_fill_only';
+  approval_policy: 'after_fill';
+  submit_allowed: false;
+  purchase_approved: false;
+  creation_key_sha256: string;
+  retirement: Extract<CreationInspection, { confirmed: true }>['retirement'];
+};
+export interface CreateCheckout {
+  /** Derive from your server's authenticated user, never model input. */
+  customer_id: string;
+  /** Derive from the authenticated workspace. */
+  workspace_id: string;
+  phone_number: string;
+  start_url: string;
+  /** Reuse only for this exact creation attempt. */
+  idempotency_key: string;
+  /** Default hosted. Chat creates no hosted wallet link or browser session capability. */
+  interaction_mode?: 'hosted' | 'chat';
+  /** Required in chat mode; derive from the authenticated messaging webhook. */
+  conversation_id?: string;
+  /** Immutable. Source comparison cannot approve/fill/submit. Fill-only uses chat and can never submit. */
+  purpose?: CheckoutPurpose;
+  /** Defaults before_fill for compatibility. after_fill requires chat and private review delivery acknowledgement. */
+  approval_policy?: 'before_fill' | 'after_fill';
+  /** Declare v2 before OTP and require its true acknowledgement. Does not arm filling until requestApproval explicitly repeats true. */
+  fill_after_verification?: true;
+  /** Explicit chat/after_fill attachment. Omit to retain Accelerate-created
+   * private Kernel custody. Attachment never navigates or replaces the document. */
+  browser?: CustomerBrowserBinding;
+  /** Your own provider read of `browser`, so Accelerate never needs your provider API key.
+   * Send it on every create. It is held in memory for this checkout and never stored. */
+  browser_resource?: ClientBrowserResource;
+}
+/** The fields of Browser Use `GET /api/v4/browsers/{id}` that Accelerate needs. */
+export interface ClientBrowserResource {
+  id: string;
+  status: 'active';
+  cdpUrl: string;
+  startedAt: string;
+  timeoutAt: string;
+  recordingAvailable: false;
+  metadata: Record<string, string>;
+  extensions: [{ id: string; version: string; runtimeId: string }];
+}
+/** Hypothesis to inspect against the actual checkout; never a caller assertion of currency evidence. */
+export interface QuoteVerificationRequest {
+  revision: number;
+  checkout_url: string;
+  expected_amount_cents: number;
+  expected_currency: 'USD';
+  checkout_total_selector: string;
+}
+/** Read-only verification of this revision. Does not authorize approval, CVV, filling or submission. */
+export interface VerifiedCheckoutQuote {
+  checkout_id: CheckoutId;
+  revision: number;
+  verified: true;
+  quote: { checkout_origin: string; amount_cents: number; currency: 'USD' };
+}
+export interface ApprovalRequest {
+  checkout_url: string;
+  amount_cents: number;
+  currency: 'USD';
+  checkout_total_selector: string;
+  submit_selector: string;
+  /** Opt in explicitly; only chat/after_fill purchase or sandbox_fill_only.
+   * Successful private verification fills this exact revision without AI. */
+  fill_after_verification?: true;
+}
+export interface AccelerateClientOptions {
+  baseUrl: string;
+  apiKey: string;
+  merchantId: string;
+  fetchImpl?: typeof fetch;
+  /** Test servers only. Production origins must use HTTPS. */
+  allowLoopbackForTests?: boolean;
+}
+export class AccelerateError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly retrySafe: false;
+  readonly paymentConfirmed: false;
+  /** Fixed local guidance only; it never authorizes or performs a payment action. */
+  readonly nextAction: AccelerateNextAction;
+  /** Opaque support correlation only, never an authorization capability. */
+  readonly supportReference?: string;
+  constructor(code?: string, status?: number, supportReference?: string);
+}
+export class AccelerateClient {
+  /** Reads process.env by default. Requires API key and merchant ID; server only. */
+  static fromEnv(env?: AccelerateEnvironment): AccelerateClient;
+  constructor(options: AccelerateClientOptions);
+  /** Authenticated API/configuration check only; does not qualify downstream payment readiness. */
+  readonly connection: { check(options?: RequestOptions): Promise<AccelerateConnection> };
+  readonly checkouts: {
+    /** Pure inspection of an exact failed creation and authoritative provider/lease retirement; never creates, cancels, verifies or fills. */
+    inspectCreation(input: CreationInspectionRequest, options?: RequestOptions): Promise<CreationInspection>;
+    inspectRetirement(id: CheckoutId, input: RetirementInspectionRequest, options?: RequestOptions): Promise<RetirementInspection>;
+    create(input: CreateCheckout, options?: RequestOptions): Promise<CreatedCheckout>;
+    get(id: CheckoutId, options?: RequestOptions): Promise<Checkout>;
+    /** Stops on readiness/terminal states even if not requested; inspect returned status before continuing. */
+    waitFor(id: CheckoutId, input: WaitForCheckout, options?: RequestOptions): Promise<Checkout>;
+    browser(id: CheckoutId, input: BrowserOperation, options?: RequestOptions): Promise<BrowserResult>;
+    applyDetails(id: CheckoutId, input: { checkout_url: string }, options?: RequestOptions): Promise<Checkout>;
+    verifyQuote(id: CheckoutId, input: QuoteVerificationRequest, options?: RequestOptions): Promise<VerifiedCheckoutQuote>;
+    requestApproval(id: CheckoutId, input: ApprovalRequest, options?: RequestOptions): Promise<Checkout>;
+    fill(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<Checkout>;
+    submit(id: CheckoutId, input: { revision: number }, options?: RequestOptions): Promise<Checkout>;
+    cancel(id: CheckoutId, options?: RequestOptions): Promise<Checkout>;
+  };
+}