@proxy-checkout/client-js

Framework-agnostic browser SDK for mounting Proxy Elements into merchant pages.

Current surface

import { loadProxyCheckout } from "@proxy-checkout/client-js";

const proxyCheckout = await loadProxyCheckout("pk_test_123", {
  apiHost: "https://api.proxycheckout.com",
  jsHost: "https://js.proxycheckout.com",
});

const session = await proxyCheckout.sessions.retrieve("psess_123");

const proxyElements = proxyCheckout.elements({
  appearance: {
    theme: "proxy",
    variables: {
      colorPrimary: "#094fbd",
      fontFamily: "Merchant Sans",
    },
    rules: {
      ".Button:hover": {
        backgroundColor: "var(--colorPrimary)",
      },
    },
  },
  fonts: [
    {
      cssSrc: "https://merchant.example.com/fonts.css",
    },
  ],
});

const askPayerToPay = proxyElements.create("ask-payer-to-pay", {
  handoffUrl: "https://pay.proxycheckout.com/s/psess_123?pk=pk_test_123",
  label: "Ask a parent to unlock",
});

askPayerToPay.on("click", ({ url }) => {
  openShareSheet(url);
});

askPayerToPay.mount("#proxy-ask-payer-to-pay");

Create buyer ask/share URLs on your backend with proxy.sessions.createHandoff(...) from @proxy-checkout/server-js, return its handoffUrl to the browser, and pass that URL to the element. The browser SDK intentionally does not build hosted handoff URLs from raw session ids. sessions.retrieve() returns payer-safe state only.

Supported appearance contract

• appearance.theme: "proxy"
• appearance.variables: fontFamily, fontSizeBase, colorPrimary, colorText, colorBackground, spacingUnit, borderRadius, focusRing, buttonPaddingBlock, buttonPaddingInline
• appearance.rules selectors: .Button, .Button:hover, .Button:focus, .Button:disabled
• fonts source shapes: { cssSrc: "https://..." } and { family, src, weight?, style?, display?, unicodeRange? }

The SDK rejects unsupported selectors, invalid mount targets, insecure remote font URLs, invalid handoff URLs, template-based options missing {{sessionId}} segments, duplicate mount attempts, and duplicate destroy() calls.

First Publish Decisions

The first public package versions are intentionally 0.0.x because the SDK API is early and expected to change. The npm package is MIT-licensed under the package-scoped LICENSE file.