Agent Vault SDK

import { chromium } from 'playwright';
import { ClinkVault, type CheckoutState } from '@clink-ai/agent-vault';
import {
  clickPayButton,
  fillCard,
  readOrderResult,
  waitForOrderResult,
} from './card-form.js';
import {
  loadVaultCard,
  notifyUser,
  saveVaultCard,
  showQrCode,
} from './app.js';

const vault = new ClinkVault({
  clientId: process.env.CLINK_CLIENT_ID!,
  clientSecret: process.env.CLINK_CLIENT_SECRET!,
  environment: 'sandbox',
});

export async function payOnCheckout(
  user: { id: string; email: string },
  checkoutUrl: string,
): Promise<CheckoutState> {
  // A visible browser lets the user complete 3DS if the PSP asks for it
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  const saved = await loadVaultCard(user.id);

  const checkout = await vault.attach(page, {
    customerId: saved?.customerId,
    cardToken: saved?.cardToken,
    email: user.email,
    // Deliver links and QR codes yourself, not through the model
    onUserAction: async (action) => {
      if (action.url) await notifyUser(user.id, action.type, action.url);
      if (action.qr_image_base64) {
        await showQrCode(user.id, action.qr_image_base64);
      }
    },
    onCardBound: (card) => saveVaultCard(user.id, card),
    resolveMerchantResult: () => readOrderResult(page),
  });

  try {
    await page.goto(checkoutUrl);
    // Your Agent fills contact and shipping details here

    const setupDeadline = Date.now() + 15 * 60_000;
    let step = await checkout.pay();
    while (step.status === 'requires_action') {
      const action = step.next_action!;
      if (action.type === 'fill_card') {
        await fillCard(page, action.card);
      } else if (action.type === 'submit') {
        await clickPayButton(page);
      } else if (action.type === 'wait_user') {
        // QR, 3DS, or a redirect: the user completes it, then reconcile
        if (action.reason !== 'bind_card') break;
        // Card setup: poll until the user finishes the link
        if (Date.now() > setupDeadline) {
          await checkout.cancel();
          return checkout.getState();
        }
        await page.waitForTimeout(2_000);
      }
      step = await checkout.pay();
    }

    // No charge occurred
    if (['declined', 'failed', 'unsupported'].includes(step.status)) {
      return checkout.getState();
    }

    // succeeded, outcome_unknown, or the user is verifying
    await waitForOrderResult(page, 10 * 60_000);
    return await checkout.reconcile();
  } finally {
    await checkout.detach();
    await browser.close();
  }
}

import type { Page } from 'playwright';
import type { FillCard, MerchantResult } from '@clink-ai/agent-vault';

// Example selectors. Match them to the merchant's checkout page.
const FIELDS = {
  number: ['input[autocomplete="cc-number"]', 'input[name="cardnumber"]'],
  expiry: ['input[autocomplete="cc-exp"]', 'input[name="exp-date"]'],
  cvc: ['input[autocomplete="cc-csc"]', 'input[name="cvc"]'],
};

// Card fields usually sit inside PSP iframes, so search every frame
export async function fillCard(page: Page, card: FillCard): Promise<void> {
  await typeInto(page, FIELDS.number, card.number);
  const expiry = `${card.exp_month}/${card.exp_year.slice(-2)}`;
  await typeInto(page, FIELDS.expiry, expiry);
  await typeInto(page, FIELDS.cvc, card.cvc);
}

async function typeInto(
  page: Page,
  selectors: string[],
  value: string,
): Promise<void> {
  for (const frame of page.frames()) {
    for (const selector of selectors) {
      const input = frame.locator(selector).first();
      if (await input.isVisible().catch(() => false)) {
        await input.fill('');
        // Type key by key; PSP fields often ignore a direct fill()
        await input.pressSequentially(value, { delay: 30 });
        return;
      }
    }
  }
  throw new Error(`Card field not found: ${selectors[0]}`);
}

export async function clickPayButton(page: Page): Promise<void> {
  const name = /pay now|place order|complete order/i;
  await page.getByRole('button', { name }).first().click();
}

// Called by reconcile(). Report only what the merchant page shows.
export async function readOrderResult(page: Page): Promise<MerchantResult> {
  const confirmed = page.getByText(/thank you for your order/i);
  if (await confirmed.first().isVisible()) {
    const orderId = await page.locator('.order-number').first()
      .textContent({ timeout: 1_000 })
      .catch(() => null);
    return orderId
      ? { status: 'completed', order_id: orderId.trim() }
      : { status: 'completed' };
  }
  const declined = page.getByText(/payment (declined|failed)/i);
  if (await declined.first().isVisible()) {
    return { status: 'failed' };
  }
  return { status: 'unknown' };
}

export async function waitForOrderResult(
  page: Page,
  timeoutMs: number,
): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if ((await readOrderResult(page)).status !== 'unknown') return;
    await page.waitForTimeout(2_000);
  }
}

import { chromium } from 'playwright';

// The cloud browser's CDP endpoint, such as a Browserbase connectUrl
const browser = await chromium.connectOverCDP(connectUrl);
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = context.pages()[0] ?? (await context.newPage());

const checkout = await vault.attach(page, { customerId, cardToken, email });
await page.goto(checkoutUrl);

// cdp: a flatten-mode CDP connection that implements send() and on/off
const { targetId } = (await cdp.send('Target.createTarget', {
  url: checkoutUrl,
})) as { targetId: string };
const { sessionId } = (await cdp.send('Target.attachToTarget', {
  targetId,
  flatten: true,
})) as { sessionId: string };

const checkout = await vault.attachToCdp(cdp, sessionId, {
  customerId,
  cardToken,
  email,
});