@agent-cards/checkout 0.2.0 → 0.3.0

package/examples/existing-browser.mjs

@@ -0,0 +1,63 @@
+// Existing Kernel / Browserbase / custom Chromium session; does not create or close the provider's browser.
+// Run: CHECKOUT_DRIVER=/absolute/path/to/instinct-driver.mjs node examples/existing-browser.mjs
+// The driver owns the existing agent, its approved purchase and merchant-specific order verification.
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright-core';
+import { VaultClient, attachToPlaywright } from '../dist/index.js';
+
+const driverPath = process.env.CHECKOUT_DRIVER;
+if (!driverPath?.startsWith('/')) throw new Error('CHECKOUT_DRIVER must name an absolute path to your integration module.');
+const driver = await import(pathToFileURL(driverPath).href);
+for (const method of ['prepareCheckout', 'submitCheckout', 'resolveMerchantResult', 'onUserAction', 'finishAfterPayment']) {
+  if (typeof driver[method] !== 'function') throw new Error(`Your driver must implement ${method}.`);
+}
+if (!process.env.CHECKOUT_CDP_URL) throw new Error('Set CHECKOUT_CDP_URL to your existing session connection URL. Never log it.');
+for (const name of ['AGENTCARD_CLIENT_ID', 'AGENTCARD_CLIENT_SECRET']) {
+  if (!process.env[name]) throw new Error(`Set ${name} for your Agentcard organization.`);
+}
+const browser = await chromium.connectOverCDP(process.env.CHECKOUT_CDP_URL);
+try {
+const context = browser.contexts()[0];
+if (!context) throw new Error('The provider returned no default browser context.');
+const pages = context.pages();
+const index = Number(process.env.CHECKOUT_PAGE_INDEX ?? 0);
+const page = pages[index];
+if (!page) throw new Error('CHECKOUT_PAGE_INDEX must select the existing agent checkout tab.');
+
+const vault = new VaultClient({ clientId: process.env.AGENTCARD_CLIENT_ID, clientSecret: process.env.AGENTCARD_CLIENT_SECRET });
+await vault.syncRegistry();
+const checkout = await driver.prepareCheckout(page); // user, merchant, amountCents+currency, exact paymentEndpoints
+const controller = await attachToPlaywright(page, {
+  ...checkout,
+  vault,
+  requireMerchantResult: true,
+  onUserAction: action => driver.onUserAction(action, { page }),
+  resolveMerchantResult: state => driver.resolveMerchantResult({ page, state }),
+  // State has no PAN, replay body, approval capability, or provider connection URL.
+  onStateChange: state => console.log(JSON.stringify(state)),
+});
+
+// Must return after dispatching the click; do not block on a navigation that awaits user approval.
+await driver.submitCheckout(page);
+const deadline = Date.now() + 15 * 60_000;
+while (Date.now() < deadline) {
+  let state = controller.getState();
+  if (['awaiting_merchant', 'requires_user_action', 'outcome_unknown'].includes(state.status)) {
+    state = await controller.reconcile();
+  }
+  if (state.status === 'completed' && state.orderId) {
+    await driver.finishAfterPayment({ page, orderId: state.orderId });
+    break;
+  }
+  if (['declined', 'timed_out', 'cancelled', 'unsupported', 'failed'].includes(state.status)) break;
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+if (controller.getState().status !== 'completed') {
+  controller.cancel(); // local stop only; reconcile any still-valid approval before creating a new one
+  process.exitCode = 2;
+}
+} finally {
+  // Disconnect this CDP client. The existing agent retains ownership of its provider session.
+  // Do not call page.close(), context.close(), or a provider session-delete API here.
+  await browser.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "examples"
   ],
   "publishConfig": {
     "access": "public"
@@ -21,7 +23,8 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs"
+    "test": "node test.mjs && node --test lifecycle.test.mjs",
+    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs"
   },
   "keywords": [
     "payments",