@tuppence/node 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @tuppence/node
 
-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.
+The Tuppence API for Node.js (18+). Payments for developers and AI agents.
+
+```sh
+npm install @tuppence/node
+```
+
+```ts
+import { Tuppence } from "@tuppence/node";
+
+const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY!);
+
+// A payment link: share its URL, get paid.
+const link = await tuppence.paymentLinks.create({ name: "Pro plan", amount: 2000 });
+console.log(link.url);
+
+// Every page of a list, fetched as you go.
+for await (const payment of tuppence.payments.listAll({ limit: 100 })) {
+  console.log(payment.id, payment.status, payment.fee);
+}
+```
+
+## Retries are safe
+
+Every POST carries an `Idempotency-Key` — yours (`{ idempotencyKey }`) or a fresh one that is
+**reused across that call's retries**. So when a request times out and is retried, the API does
+it once: a refund is never made twice, a payment never charged twice.
+
+The SDK retries network errors, timeouts, `429` (honouring `Retry-After`), `5xx` and `409
+idempotency_in_progress` — twice by default, with jittered backoff — and never a `4xx` that the
+same request would get again.
+
+```ts
+new Tuppence(key, { maxRetries: 2, timeoutMs: 30_000, apiVersion: "2026-09-20" });
+```
+
+## Another API address
+
+The SDK calls `https://api.tuppence.ai`. To use another Tuppence environment you have been given,
+set `TUPPENCE_API_URL`, or pass `baseUrl`:
+
+```ts
+new Tuppence(key, { baseUrl: "https://…" });
+```
+
+## Errors
+
+```ts
+import { CardError, InvalidRequestError } from "@tuppence/node";
+
+try {
+  await tuppence.payments.create({ amount: 5, currency: "gbp" });
+} catch (error) {
+  if (error instanceof InvalidRequestError) {
+    console.log(error.code, error.param, error.requestId); // "amount_too_small", "amount", "req_…"
+  }
+}
+```
+
+`TuppenceError` → `InvalidRequestError`, `AuthenticationError`, `PermissionError`,
+`RateLimitError`, `IdempotencyError`, `CardError` (`declineCode`), `ApiError`, `ConnectionError`.
+`error.raw` has the whole error object (e.g. `topup_url` on `insufficient_credits`).
+
+## Webhooks
+
+Pass the **raw** body — not re-serialised JSON:
+
+```ts
+app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
+  const event = tuppence.webhooks.constructEvent(
+    req.body,
+    req.headers["tuppence-signature"],
+    process.env.TUPPENCE_WEBHOOK_SECRET!,
+  );
+  if (event.type === "payment.succeeded") { /* … */ }
+  res.sendStatus(200);
+});
+```
+
+A bad signature, the wrong secret or a timestamp older than five minutes throws
+`SignatureVerificationError`. `tuppence.webhooks.generateTestHeader(body, secret)` signs a
+payload the same way, for testing your handler.
+
+## Tuppence Connect: acting as your connected accounts
+
+A platform's connected accounts are full Tuppence accounts. Make one, send its owner onboarding,
+then act as it with your own key — per request, or through a client bound to it:
+
+```ts
+const bella = await tuppence.accounts.create({ email: "bella@example.com", business_type: "individual" });
+const link = await tuppence.accountLinks.create({
+  account: bella.id,
+  type: "account_onboarding",
+  refresh_url: "https://groomly.example/onboarding/refresh",
+  return_url: "https://groomly.example/onboarding/done",
+});
+
+// One request as Bella: the `Tuppence-Account` header, never part of the path.
+await tuppence.payments.create(
+  { amount: 4500, currency: "gbp", application_fee_amount: 100 },
+  { tuppenceAccount: bella.id },
+);
+
+// Or a client bound to her — a new one: `tuppence` itself is unchanged.
+const asBella = tuppence.as(bella.id);
+await asBella.bookings.list();
+```
+
+`tuppence.accounts.persons`, `.externalAccounts` and `.capabilities`, and `tuppence.files.create`
+(a `Blob`, a buffer or a stream) are the rest of onboarding through your own forms.
+`tuppence.applicationFees` (and `.refunds`) and `tuppence.transfers` (and `.reversals`) are the
+money: your fees on your accounts' payments, and what you send them from your Connect balance —
+`tuppence.balance.listTransactions({ balance: "connect" })` lists its every movement. A Connect
+webhook's event carries `event.account`: the connected account it happened on.
+
+## Payouts and prices
+
+`tuppence.payouts.settings()` says when money is paid out and what could change it;
+`.instantQuote()` and `.create({ method: "instant" })` move pending money now, and
+`.setNextDay({ enabled })` switches next-day payouts (UK) on or off once `next_day.available`
+says so. `tuppence.account.retrievePricing()` is every price the account pays — the list's, or
+one agreed with Tuppence, with its dates.
+
+## Types
+
+Types are generated from the API's OpenAPI document, so they match the API exactly — a
+misspelt field is a compile error, not a silently ignored parameter.
+
+## Anything else
+
+`tuppence.request("GET", "/v1/…")` calls any endpoint with the same auth, retries and idempotency.

package/dist/agent-proof.d.ts

@@ -0,0 +1,36 @@
+import { type KeyObject } from "node:crypto";
+/**
+ * Agent identity (plan 20-06), the signing half. An agent holds a private key Tuppence never
+ * sees, and signs a short-lived PROOF for each request: this method, this URL, this body, now.
+ * Whoever receives it checks it against the public key Tuppence publishes for that agent
+ * (`verifyAgentProof` in `@tuppence/http402`).
+ *
+ * A proof is not a credential to keep: it is worth one request, for seconds. Sign a fresh one
+ * per call — that is the point of it.
+ */
+/** A private key: a JWK (what `credentials.create` hands back once), PEM, or a KeyObject. */
+export type AgentPrivateKey = KeyObject | string | {
+    kty: string;
+    crv: string;
+    d: string;
+    x: string;
+};
+export type SignAgentProofInput = {
+    /** The agent this proves: `agt_…`. */
+    agent: string;
+    /** The key's id, as Tuppence publishes it. */
+    kid: string;
+    privateKey: AgentPrivateKey;
+    method: string;
+    url: string;
+    /** The exact bytes you will send, if any: the proof is bound to them. */
+    body?: string | Uint8Array;
+    /** Bind the proof to whoever it is for: a host, a merchant id, anything you both agree. */
+    audience?: string;
+    /** Default 60. A proof should be worth seconds, not minutes. */
+    lifetimeSeconds?: number;
+    nowSeconds?: number;
+};
+export declare function signAgentProof(input: SignAgentProofInput): string;
+/** The header agents put a proof in. */
+export declare const AGENT_PROOF_HEADER = "Tuppence-Agent-Proof";

package/dist/agent-proof.js

@@ -0,0 +1,35 @@
+import { createHash, createPrivateKey, randomUUID, sign } from "node:crypto";
+const b64url = (value) => (Buffer.isBuffer(value) ? value : Buffer.from(JSON.stringify(value))).toString("base64url");
+function keyOf(key) {
+    if (typeof key === "string")
+        return createPrivateKey(key);
+    if (typeof key === "object" && "d" in key)
+        return createPrivateKey({ key, format: "jwk" });
+    return key;
+}
+/** The URL the proof is bound to: no fragment, and no trailing "?" for an empty query. */
+function canonical(url) {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.search === "?" ? parsed.toString().replace(/\?$/, "") : parsed.toString();
+}
+export function signAgentProof(input) {
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const header = { alg: "EdDSA", typ: "agent-proof+jwt", kid: input.kid };
+    const claims = {
+        iss: input.agent,
+        htm: input.method.toUpperCase(),
+        htu: canonical(input.url),
+        iat: now,
+        exp: now + (input.lifetimeSeconds ?? 60),
+        jti: randomUUID(),
+        ...(input.body === undefined
+            ? {}
+            : { bh: createHash("sha256").update(input.body).digest("base64url") }),
+        ...(input.audience === undefined ? {} : { aud: input.audience }),
+    };
+    const signed = `${b64url(header)}.${b64url(claims)}`;
+    return `${signed}.${b64url(sign(null, Buffer.from(signed), keyOf(input.privateKey)))}`;
+}
+/** The header agents put a proof in. */
+export const AGENT_PROOF_HEADER = "Tuppence-Agent-Proof";

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Every failure the API reports, as something you can `catch` and branch on. `code` is stable
+ * (the API only ever adds codes); `message` is for people. Quote `requestId` to support.
+ */
+export type ErrorBody = {
+    type?: string;
+    code?: string;
+    message?: string;
+    param?: string;
+    decline_code?: string;
+    request_id?: string;
+    [key: string]: unknown;
+};
+export declare class TuppenceError extends Error {
+    readonly type: string;
+    readonly code: string;
+    readonly status: number | undefined;
+    readonly param: string | undefined;
+    readonly declineCode: string | undefined;
+    readonly requestId: string | undefined;
+    /**
+     * The whole error object — e.g. `balance` and `topup_url` on `insufficient_credits`; `limit`,
+     * `used`, `max`, `resets_at` and `increase_url` on `issuing_card_limit`; `missing_evidence` on
+     * `dispute_evidence_incomplete`; `country`, `country_label`, `coming_soon` and `waitlist_url` on
+     * `country_not_supported` and `region_unavailable`.
+     */
+    readonly raw: ErrorBody;
+    constructor(body: ErrorBody, status?: number);
+    /** The right subclass for an error envelope. */
+    static from(body: ErrorBody, status?: number): TuppenceError;
+}
+export declare class InvalidRequestError extends TuppenceError {
+}
+export declare class AuthenticationError extends TuppenceError {
+}
+export declare class PermissionError extends TuppenceError {
+}
+export declare class RateLimitError extends TuppenceError {
+}
+export declare class IdempotencyError extends TuppenceError {
+}
+/** The card was declined, needs authenticating, or the payment could not go ahead. */
+export declare class CardError extends TuppenceError {
+}
+export declare class ApiError extends TuppenceError {
+}
+/** The request never got an answer: a network failure or a timeout, after every retry. */
+export declare class ConnectionError extends TuppenceError {
+    constructor(message: string, cause?: unknown);
+}
+/** A webhook whose signature does not check out. Never act on its payload. */
+export declare class SignatureVerificationError extends TuppenceError {
+    constructor(code: string, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,67 @@
+export class TuppenceError extends Error {
+    type;
+    code;
+    status;
+    param;
+    declineCode;
+    requestId;
+    /**
+     * The whole error object — e.g. `balance` and `topup_url` on `insufficient_credits`; `limit`,
+     * `used`, `max`, `resets_at` and `increase_url` on `issuing_card_limit`; `missing_evidence` on
+     * `dispute_evidence_incomplete`; `country`, `country_label`, `coming_soon` and `waitlist_url` on
+     * `country_not_supported` and `region_unavailable`.
+     */
+    raw;
+    constructor(body, status) {
+        super(body.message ?? "The Tuppence API returned an error.");
+        this.name = new.target.name;
+        this.type = body.type ?? "api_error";
+        this.code = body.code ?? "unknown_error";
+        this.status = status;
+        this.param = body.param;
+        this.declineCode = body.decline_code;
+        this.requestId = body.request_id;
+        this.raw = body;
+    }
+    /** The right subclass for an error envelope. */
+    static from(body, status) {
+        const Kind = {
+            invalid_request_error: InvalidRequestError,
+            authentication_error: AuthenticationError,
+            permission_error: PermissionError,
+            rate_limit_error: RateLimitError,
+            idempotency_error: IdempotencyError,
+            card_error: CardError,
+        }[body.type ?? ""] ?? ApiError;
+        return new Kind(body, status);
+    }
+}
+export class InvalidRequestError extends TuppenceError {
+}
+export class AuthenticationError extends TuppenceError {
+}
+export class PermissionError extends TuppenceError {
+}
+export class RateLimitError extends TuppenceError {
+}
+export class IdempotencyError extends TuppenceError {
+}
+/** The card was declined, needs authenticating, or the payment could not go ahead. */
+export class CardError extends TuppenceError {
+}
+export class ApiError extends TuppenceError {
+}
+/** The request never got an answer: a network failure or a timeout, after every retry. */
+export class ConnectionError extends TuppenceError {
+    constructor(message, cause) {
+        super({ type: "connection_error", code: "connection_failed", message });
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/** A webhook whose signature does not check out. Never act on its payload. */
+export class SignatureVerificationError extends TuppenceError {
+    constructor(code, message) {
+        super({ type: "signature_verification_error", code, message });
+    }
+}