SDK API reference

const catalog = await listTokens();
const forThisSite = await listTokens({ url: "https://shop.example.com/checkout" });

const { cards, logins, relatedLogins } = await tokensForUrl("https://www.example.com/checkout");

// One full catalog, reused for several sites without another round trip.
const full = await listTokens();
const siteA = await tokensForUrl("https://shop-a.example.com/checkout", { catalog: full });
const siteB = await tokensForUrl("https://shop-b.example.com/checkout", { catalog: full });

const browser = await chromium.launch({ tunnel: true });

const browser = await chromium.launch();
if (!browser.verificationOnly()) {
  await browser.close();
  throw new Error("Refusing to run: this key would fill a real card.");
}

interface HandoffRecord {
  handoffs: {
    kind: "cvv_entry" | "purchase_approval" | "destination_approval";
    ms: number;
    host?: string;
  }[];
  unanswered: number;
}

import type { HandoffRecord } from "@agentvault/playwright";

const record: HandoffRecord = { handoffs: [], unanswered: 0 };
try {
  await browser.recordingHandoffs(record, () =>
    page.fill("#card-number", card.number, { amount: 42, currency: "USD" })
  );
} finally {
  if (record.handoffs.length > 0) {
    console.log("The owner took part in this fill.");
  } else if (record.unanswered > 0 || !browser.reportsHandoffs()) {
    console.log("Unknown whether the owner was involved.");
  } else {
    console.log("Nobody was asked.");
  }
}

import { observingOwnerWaits } from "@agentvault/playwright";

await observingOwnerWaits(
  (wait) => {
    if (wait?.reason === "new_destination") {
      console.log(`Approve ${wait.site} in the email titled 'Authorize new site: ${wait.site}'.`);
    }
  },
  () => page.fill("#email", identity.email)
);

interface FillReport {
  verification?: true;
  card_fields_verified?: true;
}

const report = await page.fill("#card-number", card.number);
if (report.card_fields_verified) {
  // A test card went in. Do not submit this as a real order.
}

const card = page.frameLocator('iframe[title="Secure payment input frame"]');
await card.locator('input[name="number"]').pressSequentially(catalog.cards[0].number, {
  amount: orderTotal,
  currency: "USD",
});
await card.locator('input[name="cvc"]').pressSequentially(catalog.cards[0].cvv);

const shot = await page.screenshot();
if (shot.redaction === "blackout") {
  // Not a dark page, not a failed render, and not proof a click did nothing.
}
if (shot.redaction === "unknown") {
  // An older proxy did not say. Handle it like a capture that may be redacted.
}
writeFileSync("/tmp/checkout.png", shot);

await page.hint("order.total", { selector: ".summary__grand-total" });
await page.hint("order.total", { selector: "#total", frame: "#paddle-checkout iframe" });
await page.hint("order.total", { selector: "#order-total", read: "attribute", attribute: "aria-label" });

const { requestId } = await createLogin({ website: "shop.example.com", email: "agent-inbox@example.com" });
const { login } = await awaitSignupApproval({ requestId });

const { merchant, platform, signup, signupPlatform } = await recipesForUrl(productUrl);
const candidates = await buyableMerchants();
const { id } = await submitRecipe(recipe, { note: "Reached a filled card form." });
const verdict = await recipeSubmission(id);