@vrs-pay/js 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @vrs-pay/js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Lightweight, framework-agnostic browser SDK for VRS Pay.**
+
+[![npm version](https://img.shields.io/npm/v/@vrs-pay/js.svg)](https://www.npmjs.com/package/@vrs-pay/js)
+[![license](https://img.shields.io/npm/l/@vrs-pay/js.svg)](https://github.com/vrs-pay/multivrs)
+
+`@vrs-pay/js` is the core JavaScript client for VRS Pay in the browser. It works seamlessly with **any frontend framework** (Vanilla JS, React, Vue, Svelte, Angular, Solid) or static websites to load pricing plans, trigger Stripe checkout sessions, query customer billing records, and verify feature entitlements.
+
+---
+
+## Features
+
+- 🌐 **Framework-agnostic**: Zero framework dependencies. Use in Vanilla JS, Vue, Svelte, Angular, React, or Astro.
+- 🔒 **Safe client-side access**: Operates strictly using your publishable key (`pk_test_...` or `pk_live_...`). Rejects secret keys to prevent accidental leaks.
+- 💳 **Direct Checkout**: Redirect users straight to Stripe-powered checkout sessions with custom return URLs.
+- 👤 **Customer Self-Service**: Fetch active subscriptions, view past invoices, cancel or resume subscriptions.
+- ⚡ **Feature Entitlements**: Query client-side feature flags and limits based on the user's active tier.
+- 💱 **Price Formatting**: Built-in currency formatting utility (`formatPrice`) with localized currencies and recurring intervals.
+
+---
+
+## Installation
+
+```bash
+npm install @vrs-pay/js
+# or
+bun add @vrs-pay/js
+# or
+pnpm add @vrs-pay/js
+```
+
+---
+
+## Quickstart
+
+```ts
+import { createVrsPayClient, formatPrice } from "@vrs-pay/js";
+
+// Initialize the client
+const vrs = createVrsPayClient({
+  publishableKey: "pk_test_your_key",
+  apiUrl: "https://your-vrs-pay-api.com",
+  // Return your server-generated customer session token
+  customerSession: async () => {
+    const res = await fetch("/api/vrs-session");
+    return res.text();
+  },
+});
+
+// 1. Fetch products & pricing tiers (public, no customer required)
+const products = await vrs.pricing();
+const priceString = formatPrice(products[0].prices[0]); // e.g. "$29.00 / month"
+
+// 2. Redirect to Stripe Checkout
+await vrs.redirectToCheckout({
+  price: products[0].prices[0].id,
+  successUrl: "https://example.com/billing?status=success",
+  cancelUrl: "https://example.com/pricing",
+});
+
+// 3. Manage customer subscriptions and invoices
+const { subscriptions, invoices } = await vrs.customer();
+if (subscriptions[0]) {
+  // Cancel subscription at period end
+  await vrs.cancelSubscription(subscriptions[0].id);
+
+  // Or resume subscription
+  await vrs.resumeSubscription(subscriptions[0].id);
+}
+
+// 4. Client-side entitlement checks
+if (await vrs.hasFeature("csv_export")) {
+  showExportButton();
+}
+```
+
+---
+
+## The VRS Pay Ecosystem
+
+- **`@vrs-pay/js`** *(This package)*: Universal browser SDK for any frontend.
+- **`@vrs-pay/react`**: Turnkey React 18 & 19 components (`<PricingTable />`, `<PricingComparisonTable />`, `<CustomerPortal />`, `<Gate />`) and hooks.
+- **`@vrs-pay/sdk`**: Server SDK for Node.js, Bun, Cloudflare Workers, and backend API routes.
+
+---
+
+## License
+
+MIT © [VRS Pay](https://github.com/vrs-pay)

package/dist/client.d.ts

@@ -0,0 +1,38 @@
+import type { CheckoutParams, CustomerOverview, CustomerSubscription, Entitlements, PricingProduct } from "./types";
+export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+export interface VrsPayClientOptions {
+    /** pk_test_… or pk_live_…; safe to ship to browsers. */
+    publishableKey: string;
+    /** Your VRS Pay API address. */
+    apiUrl: string;
+    /**
+     * Who the customer is: the `client_secret` your server got from
+     * `customerSessions.create`, or a function that fetches a fresh one
+     * (sessions last 30 minutes; a function is called again when one expires).
+     * Leave it out for pages that only show pricing.
+     */
+    customerSession?: string | (() => Promise<string>);
+    fetch?: Fetch;
+}
+/** VRS Pay in the browser, with a publishable key. */
+export declare function createVrsPayClient(options: VrsPayClientOptions): {
+    /** Active products and prices, for a pricing table. Needs no customer. */
+    pricing: () => Promise<PricingProduct[]>;
+    /** The customer, their subscriptions, invoices and entitlements, for a portal. */
+    customer: () => Promise<CustomerOverview>;
+    entitlements: () => Promise<Entitlements>;
+    /** Whether the customer has `feature`: true, or a limit above zero. */
+    hasFeature: (feature: string) => Promise<boolean>;
+    checkout: (params: CheckoutParams) => Promise<{
+        id: string;
+        url: string;
+    }>;
+    /** Starts checkout and sends the browser to it. */
+    redirectToCheckout: (params: CheckoutParams) => Promise<void>;
+    changePlan: (subscriptionId: string, price: string) => Promise<CustomerSubscription>;
+    /** Cancels at the end of the period; access continues until then. */
+    cancelSubscription: (subscriptionId: string) => Promise<CustomerSubscription>;
+    resumeSubscription: (subscriptionId: string) => Promise<CustomerSubscription>;
+};
+export type VrsPayClient = ReturnType<typeof createVrsPayClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAID,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB;IAqD3D,0EAA0E;;IAE1E,kFAAkF;;;IAGlF,uEAAuE;0BAC3C,MAAM;uBApBJ,cAAc,KAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAwBnF,mDAAmD;iCAChB,cAAc;iCAGpB,MAAM,SAAS,MAAM;IAElD,qEAAqE;yCAChC,MAAM;yCAEN,MAAM;EAG9C;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/** An error the VRS Pay API returned, with its stable `code`. */
+export declare class VrsPayError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly status: number;
+    constructor(type: string, code: string, message: string, status: number);
+}
+export declare function errorFromResponse(status: number, body: unknown): VrsPayError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOxE;AAUD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CAQ5E"}

package/dist/format.d.ts

@@ -0,0 +1,6 @@
+import type { PricingPrice } from "./types";
+/** Minor units → "£9.00", "₦15,000.00". */
+export declare function formatAmount(amount: number, currency: string, locale?: string): string;
+/** "£9.00", "£9.00 / month", "£27.00 every 3 months", "£0.10 per unit / month". */
+export declare function formatPrice(price: PricingPrice, currency?: string, locale?: string): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C,2CAA2C;AAC3C,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAMtF;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,SAAiB,EAAE,MAAM,CAAC,EAAE,MAAM,UAW1F"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createVrsPayClient, type Fetch, type VrsPayClient, type VrsPayClientOptions, } from "./client";
+export { VrsPayError } from "./errors";
+export { formatAmount, formatPrice } from "./format";
+export type * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACrD,mBAAmB,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,108 @@
+// src/errors.ts
+class VrsPayError extends Error {
+  type;
+  code;
+  status;
+  constructor(type, code, message, status) {
+    super(message);
+    this.name = "VrsPayError";
+    this.type = type;
+    this.code = code;
+    this.status = status;
+  }
+}
+function isErrorBody(value) {
+  return typeof value === "object" && value !== null && "error" in value;
+}
+function errorFromResponse(status, body) {
+  const error = isErrorBody(body) ? body.error : undefined;
+  return new VrsPayError(error?.type ?? "api_error", error?.code ?? "unexpected_response", error?.message ?? `VRS Pay answered ${status}.`, status);
+}
+
+// src/client.ts
+var SESSION_HEADER = "VRS-Customer-Session";
+function createVrsPayClient(options) {
+  if (options.publishableKey.startsWith("sk_")) {
+    throw new Error("VRS Pay: never put a secret key in a browser. Use your publishable key.");
+  }
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/client/v1`;
+  const send = options.fetch ?? ((input, init) => fetch(input, init));
+  let session = typeof options.customerSession === "string" ? options.customerSession : null;
+  async function sessionSecret(refresh) {
+    if (typeof options.customerSession !== "function")
+      return session;
+    if (!session || refresh)
+      session = await options.customerSession();
+    return session;
+  }
+  async function request(method, path, body) {
+    for (const refresh of [false, true]) {
+      const secret = await sessionSecret(refresh);
+      const response = await send(`${base}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${options.publishableKey}`,
+          "Content-Type": "application/json",
+          ...secret ? { [SESSION_HEADER]: secret } : {}
+        },
+        body: body === undefined ? undefined : JSON.stringify(body)
+      });
+      const json = await response.json().catch(() => null);
+      if (response.ok)
+        return json;
+      const canRefresh = response.status === 401 && typeof options.customerSession === "function";
+      if (!refresh && canRefresh)
+        continue;
+      throw errorFromResponse(response.status, json);
+    }
+    throw new Error("unreachable");
+  }
+  const here = () => typeof window === "undefined" ? undefined : window.location.href;
+  async function checkout(params) {
+    const successUrl = params.successUrl ?? here();
+    const cancelUrl = params.cancelUrl ?? here();
+    if (!successUrl || !cancelUrl)
+      throw new Error("VRS Pay: pass successUrl and cancelUrl.");
+    return request("POST", "/checkout", {
+      price: params.price,
+      currency: params.currency,
+      quantity: params.quantity,
+      success_url: successUrl,
+      cancel_url: cancelUrl
+    });
+  }
+  return {
+    pricing: async () => (await request("GET", "/pricing")).data,
+    customer: () => request("GET", "/customer"),
+    entitlements: () => request("GET", "/entitlements"),
+    hasFeature: async (feature) => (await request("GET", `/entitlements?feature=${encodeURIComponent(feature)}`)).granted === true,
+    checkout,
+    redirectToCheckout: async (params) => {
+      window.location.assign((await checkout(params)).url);
+    },
+    changePlan: (subscriptionId, price) => request("POST", `/subscriptions/${subscriptionId}`, { price }),
+    cancelSubscription: (subscriptionId) => request("POST", `/subscriptions/${subscriptionId}/cancel`, {}),
+    resumeSubscription: (subscriptionId) => request("POST", `/subscriptions/${subscriptionId}/resume`, {})
+  };
+}
+// src/format.ts
+var ZERO_DECIMAL = new Set(["jpy"]);
+function formatAmount(amount, currency, locale) {
+  const code = currency.toLowerCase();
+  const value = ZERO_DECIMAL.has(code) ? amount : amount / 100;
+  return new Intl.NumberFormat(locale, { style: "currency", currency: code.toUpperCase() }).format(value);
+}
+function formatPrice(price, currency = price.currency, locale) {
+  const option = price.currency_options[currency.toLowerCase()];
+  const money = option ? formatAmount(option.amount, currency, locale) : formatAmount(price.amount, price.currency, locale);
+  const each = price.usage_type === "metered" ? `${money} per unit` : money;
+  if (price.interval === "one_time")
+    return each;
+  return price.interval_count === 1 ? `${each} / ${price.interval}` : `${each} every ${price.interval_count} ${price.interval}s`;
+}
+export {
+  formatPrice,
+  formatAmount,
+  createVrsPayClient,
+  VrsPayError
+};

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/** What the browser API returns. Amounts are in minor units (pence, cents, kobo). */
+export type PriceInterval = "one_time" | "day" | "week" | "month" | "year";
+export interface PricingPrice {
+    id: string;
+    amount: number;
+    currency: string;
+    currency_options: Record<string, {
+        amount: number;
+    }>;
+    interval: PriceInterval;
+    interval_count: number;
+    usage_type: "licensed" | "metered";
+    lookup_key: string | null;
+}
+export interface PricingProduct {
+    id: string;
+    object: "product";
+    name: string;
+    description: string | null;
+    images: string[];
+    marketing_features: Array<{
+        name: string;
+    }>;
+    trial_days: number;
+    features: Record<string, boolean | number>;
+    prices: PricingPrice[];
+}
+export interface Entitlements {
+    object: "entitlements";
+    customer: string;
+    plans: string[];
+    features: Record<string, boolean | number>;
+    feature?: string;
+    granted?: boolean;
+}
+export interface CustomerSubscription {
+    id: string;
+    status: "incomplete" | "trialing" | "active" | "past_due" | "canceled";
+    plan: string;
+    price: string;
+    product_name: string | null;
+    price_details: PricingPrice | null;
+    quantity: number;
+    currency: string;
+    current_period_end: number | null;
+    trial_end: number | null;
+    cancel_at_period_end: boolean;
+    pending_price: string | null;
+}
+export interface CustomerInvoice {
+    id: string;
+    status: "draft" | "open" | "paid" | "void" | "uncollectible";
+    currency: string;
+    total: number;
+    period_start: number;
+    period_end: number;
+    paid_at: number | null;
+    created: number;
+}
+export interface CustomerOverview {
+    object: "customer_overview";
+    customer: {
+        id: string;
+        email: string | null;
+        name: string | null;
+    };
+    subscriptions: CustomerSubscription[];
+    invoices: CustomerInvoice[];
+    entitlements: Entitlements;
+}
+export interface CheckoutParams {
+    price: string;
+    /** One of the price's currencies; its own by default. */
+    currency?: string;
+    quantity?: number;
+    /** Where to land after paying or giving up; the current page by default. */
+    successUrl?: string;
+    cancelUrl?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@vrs-pay/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "VRS Pay in the browser: pricing, checkout, customer portal and access checks with a publishable key.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist && tsc --emitDeclarationOnly --declaration --outDir ./dist",
+    "prepublishOnly": "bun run build",
+    "lint": "biome check .",
+    "format": "biome check --fix .",
+    "check-types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@repo/biome-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/bun": "^1.3.5",
+    "typescript": "5.9.2"
+  }
+}

package/src/client.ts

@@ -0,0 +1,107 @@
+import { errorFromResponse } from "./errors";
+import type {
+  CheckoutParams,
+  CustomerOverview,
+  CustomerSubscription,
+  Entitlements,
+  PricingProduct,
+} from "./types";
+
+export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface VrsPayClientOptions {
+  /** pk_test_… or pk_live_…; safe to ship to browsers. */
+  publishableKey: string;
+  /** Your VRS Pay API address. */
+  apiUrl: string;
+  /**
+   * Who the customer is: the `client_secret` your server got from
+   * `customerSessions.create`, or a function that fetches a fresh one
+   * (sessions last 30 minutes; a function is called again when one expires).
+   * Leave it out for pages that only show pricing.
+   */
+  customerSession?: string | (() => Promise<string>);
+  fetch?: Fetch;
+}
+
+const SESSION_HEADER = "VRS-Customer-Session";
+
+/** VRS Pay in the browser, with a publishable key. */
+export function createVrsPayClient(options: VrsPayClientOptions) {
+  if (options.publishableKey.startsWith("sk_")) {
+    throw new Error("VRS Pay: never put a secret key in a browser. Use your publishable key.");
+  }
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/client/v1`;
+  const send = options.fetch ?? ((input: string, init: RequestInit) => fetch(input, init));
+  let session: string | null =
+    typeof options.customerSession === "string" ? options.customerSession : null;
+
+  async function sessionSecret(refresh: boolean): Promise<string | null> {
+    if (typeof options.customerSession !== "function") return session;
+    if (!session || refresh) session = await options.customerSession();
+    return session;
+  }
+
+  async function request<T>(method: "GET" | "POST", path: string, body?: unknown): Promise<T> {
+    for (const refresh of [false, true]) {
+      const secret = await sessionSecret(refresh);
+      const response = await send(`${base}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${options.publishableKey}`,
+          "Content-Type": "application/json",
+          ...(secret ? { [SESSION_HEADER]: secret } : {}),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+      const json: unknown = await response.json().catch(() => null);
+      if (response.ok) return json as T;
+      // An expired session: fetch a fresh one once, then try again.
+      const canRefresh = response.status === 401 && typeof options.customerSession === "function";
+      if (!refresh && canRefresh) continue;
+      throw errorFromResponse(response.status, json);
+    }
+    throw new Error("unreachable");
+  }
+
+  const here = () => (typeof window === "undefined" ? undefined : window.location.href);
+
+  async function checkout(params: CheckoutParams): Promise<{ id: string; url: string }> {
+    const successUrl = params.successUrl ?? here();
+    const cancelUrl = params.cancelUrl ?? here();
+    if (!successUrl || !cancelUrl) throw new Error("VRS Pay: pass successUrl and cancelUrl.");
+    return request("POST", "/checkout", {
+      price: params.price,
+      currency: params.currency,
+      quantity: params.quantity,
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+    });
+  }
+
+  return {
+    /** Active products and prices, for a pricing table. Needs no customer. */
+    pricing: async () => (await request<{ data: PricingProduct[] }>("GET", "/pricing")).data,
+    /** The customer, their subscriptions, invoices and entitlements, for a portal. */
+    customer: () => request<CustomerOverview>("GET", "/customer"),
+    entitlements: () => request<Entitlements>("GET", "/entitlements"),
+    /** Whether the customer has `feature`: true, or a limit above zero. */
+    hasFeature: async (feature: string) =>
+      (await request<Entitlements>("GET", `/entitlements?feature=${encodeURIComponent(feature)}`))
+        .granted === true,
+    checkout,
+    /** Starts checkout and sends the browser to it. */
+    redirectToCheckout: async (params: CheckoutParams) => {
+      window.location.assign((await checkout(params)).url);
+    },
+    changePlan: (subscriptionId: string, price: string) =>
+      request<CustomerSubscription>("POST", `/subscriptions/${subscriptionId}`, { price }),
+    /** Cancels at the end of the period; access continues until then. */
+    cancelSubscription: (subscriptionId: string) =>
+      request<CustomerSubscription>("POST", `/subscriptions/${subscriptionId}/cancel`, {}),
+    resumeSubscription: (subscriptionId: string) =>
+      request<CustomerSubscription>("POST", `/subscriptions/${subscriptionId}/resume`, {}),
+  };
+}
+
+export type VrsPayClient = ReturnType<typeof createVrsPayClient>;

package/src/errors.ts

@@ -0,0 +1,32 @@
+/** An error the VRS Pay API returned, with its stable `code`. */
+export class VrsPayError extends Error {
+  readonly type: string;
+  readonly code: string;
+  readonly status: number;
+
+  constructor(type: string, code: string, message: string, status: number) {
+    super(message);
+    this.name = "VrsPayError";
+    this.type = type;
+    this.code = code;
+    this.status = status;
+  }
+}
+
+interface ErrorBody {
+  error?: { type?: string; code?: string; message?: string };
+}
+
+function isErrorBody(value: unknown): value is ErrorBody {
+  return typeof value === "object" && value !== null && "error" in value;
+}
+
+export function errorFromResponse(status: number, body: unknown): VrsPayError {
+  const error = isErrorBody(body) ? body.error : undefined;
+  return new VrsPayError(
+    error?.type ?? "api_error",
+    error?.code ?? "unexpected_response",
+    error?.message ?? `VRS Pay answered ${status}.`,
+    status,
+  );
+}

package/src/format.ts

@@ -0,0 +1,27 @@
+import type { PricingPrice } from "./types";
+
+/** Currencies without minor units. */
+const ZERO_DECIMAL = new Set(["jpy"]);
+
+/** Minor units → "£9.00", "₦15,000.00". */
+export function formatAmount(amount: number, currency: string, locale?: string): string {
+  const code = currency.toLowerCase();
+  const value = ZERO_DECIMAL.has(code) ? amount : amount / 100;
+  return new Intl.NumberFormat(locale, { style: "currency", currency: code.toUpperCase() }).format(
+    value,
+  );
+}
+
+/** "£9.00", "£9.00 / month", "£27.00 every 3 months", "£0.10 per unit / month". */
+export function formatPrice(price: PricingPrice, currency = price.currency, locale?: string) {
+  const option = price.currency_options[currency.toLowerCase()];
+  // A currency the price isn't sold in falls back to the price's own.
+  const money = option
+    ? formatAmount(option.amount, currency, locale)
+    : formatAmount(price.amount, price.currency, locale);
+  const each = price.usage_type === "metered" ? `${money} per unit` : money;
+  if (price.interval === "one_time") return each;
+  return price.interval_count === 1
+    ? `${each} / ${price.interval}`
+    : `${each} every ${price.interval_count} ${price.interval}s`;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  createVrsPayClient,
+  type Fetch,
+  type VrsPayClient,
+  type VrsPayClientOptions,
+} from "./client";
+export { VrsPayError } from "./errors";
+export { formatAmount, formatPrice } from "./format";
+export type * from "./types";

package/src/types.ts

@@ -0,0 +1,79 @@
+/** What the browser API returns. Amounts are in minor units (pence, cents, kobo). */
+
+export type PriceInterval = "one_time" | "day" | "week" | "month" | "year";
+
+export interface PricingPrice {
+  id: string;
+  amount: number;
+  currency: string;
+  currency_options: Record<string, { amount: number }>;
+  interval: PriceInterval;
+  interval_count: number;
+  usage_type: "licensed" | "metered";
+  lookup_key: string | null;
+}
+
+export interface PricingProduct {
+  id: string;
+  object: "product";
+  name: string;
+  description: string | null;
+  images: string[];
+  marketing_features: Array<{ name: string }>;
+  trial_days: number;
+  features: Record<string, boolean | number>;
+  prices: PricingPrice[];
+}
+
+export interface Entitlements {
+  object: "entitlements";
+  customer: string;
+  plans: string[];
+  features: Record<string, boolean | number>;
+  feature?: string;
+  granted?: boolean;
+}
+
+export interface CustomerSubscription {
+  id: string;
+  status: "incomplete" | "trialing" | "active" | "past_due" | "canceled";
+  plan: string;
+  price: string;
+  product_name: string | null;
+  price_details: PricingPrice | null;
+  quantity: number;
+  currency: string;
+  current_period_end: number | null;
+  trial_end: number | null;
+  cancel_at_period_end: boolean;
+  pending_price: string | null;
+}
+
+export interface CustomerInvoice {
+  id: string;
+  status: "draft" | "open" | "paid" | "void" | "uncollectible";
+  currency: string;
+  total: number;
+  period_start: number;
+  period_end: number;
+  paid_at: number | null;
+  created: number;
+}
+
+export interface CustomerOverview {
+  object: "customer_overview";
+  customer: { id: string; email: string | null; name: string | null };
+  subscriptions: CustomerSubscription[];
+  invoices: CustomerInvoice[];
+  entitlements: Entitlements;
+}
+
+export interface CheckoutParams {
+  price: string;
+  /** One of the price's currencies; its own by default. */
+  currency?: string;
+  quantity?: number;
+  /** Where to land after paying or giving up; the current page by default. */
+  successUrl?: string;
+  cancelUrl?: string;
+}