@pithy-sh/payments 0.1.0

package/src/rails/paddle/api.ts

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PaymentsProviderUnavailableError, PaymentsRailNotConfiguredError } from "../../error/errors";
+
+/**
+ * The one door out to Paddle, and the mapping from how it answered to what that means.
+ *
+ * Reached with `fetch` and JSON rather than through `@paddle/paddle-node-sdk`, for the reason
+ * `stripe/api.ts` and `lemonSqueezy/api.ts` both give: a handful of calls are needed and each is one
+ * request. Every other third-party API in this repo is spoken to the same way — `fetch` out, Zod in — and
+ * a Node SDK in a Workers bundle buys nothing but weight.
+ *
+ * **Paddle Billing, not Paddle Classic.** `api.paddle.com` in production and `sandbox-api.paddle.com` in
+ * sandbox, with `Paddle-Version: 1` pinned on every request so a future default at Paddle cannot silently
+ * reshape a response this package parses.
+ *
+ * ## How an answer is read
+ *
+ * **A 5xx or a 429 is `payments/provider_unavailable` (503).** Paddle is up but not answering. The caller
+ * retries, and on the webhook path that code passes through the guard unchanged so Paddle redelivers
+ * rather than being told its signature was bad.
+ *
+ * **Every other 4xx is `payments/rail_not_configured` (404).** A 4xx here is never the buyer's fault:
+ * these requests are built from config, from the credential bundle, and from rows we wrote. A rejected
+ * API key, a price that is not in this account, a customer that is not ours — one statement, that this
+ * project's Paddle rail is not set up to do what it was asked.
+ *
+ * **A 404 is an absent resource only for a caller that said it was probing.** `absentOn404` is how a
+ * refresh distinguishes "Paddle no longer knows this subscription" — a normal answer, which the contract
+ * says is `undefined` — from "our API key is wrong". Only a caller that knows the difference may claim it.
+ *
+ * ## Two of Paddle's refusals are the adopter's account rather than their credentials
+ *
+ * `transactions.create` refuses account-wide with *"Cannot create a transaction or open a checkout as no
+ * default payment link has been set for this account"* until somebody sets one in the Paddle dashboard.
+ * Verified live against the assigned sandbox, where it is still true. It arrives as an ordinary 4xx and
+ * would read as "the rail is misconfigured", which is correct but useless — so {@link paddleSaid} keeps
+ * Paddle's own sentence in `detail`, and `pithy doctor` asks the same question before a buyer does.
+ *
+ * **Nothing in a refusal carries the API key.** `detail` is written to an operator's logs, so anything
+ * key-shaped in a message is redacted before it gets there.
+ */
+
+/** Paddle's production API. Public and stable, so it is pinned rather than configured. */
+export const PADDLE_API_BASE = "https://api.paddle.com";
+
+/** Paddle's sandbox API. A separate host, not a flag — sandbox and live are separate accounts entirely. */
+export const PADDLE_SANDBOX_API_BASE = "https://sandbox-api.paddle.com";
+
+/**
+ * The API version every request pins.
+ *
+ * Sent on every call so a future default at Paddle cannot reshape a response this package's schemas parse
+ * — the failure would be a webhook that stops projecting, discovered by a customer.
+ */
+export const PADDLE_API_VERSION = "1";
+
+/** Which Paddle account a deployment sells through. Two hosts, two sets of credentials, one code path. */
+export type PaddleEnvironment = "sandbox" | "production";
+
+/** The base URL for an environment. */
+export function paddleApiBase(environment: PaddleEnvironment): string {
+  return environment === "production" ? PADDLE_API_BASE : PADDLE_SANDBOX_API_BASE;
+}
+
+/** One outbound request, narrowed to what this rail's endpoints need. */
+export interface PaddleHttpRequest {
+  /** The HTTP method. */
+  method?: string;
+  /** Request headers — the bearer key, the pinned version, and any idempotency key. */
+  headers?: Record<string, string>;
+  /** The JSON body, on a POST. */
+  body?: string;
+}
+
+/** What this rail needs of a response. Structural, so a test can answer without building a `Response`. */
+export interface PaddleHttpResponse {
+  /** Whether the status is 2xx. */
+  ok: boolean;
+  /** The HTTP status. */
+  status: number;
+  /** The body as text — read once, then parsed here, so a non-JSON body is reportable rather than a throw. */
+  text(): Promise<string>;
+}
+
+/** The HTTP seam. One explicit parameter defaulting to the runtime's `fetch`, as every rail has. */
+export type PaddleHttpFetch = (url: string, init?: PaddleHttpRequest) => Promise<PaddleHttpResponse>;
+
+/** The runtime's own `fetch`, adapted to the seam. */
+export const paddleHttpFetch: PaddleHttpFetch = (url, init) =>
+  fetch(url, init as RequestInit) as unknown as Promise<PaddleHttpResponse>;
+
+/** Paddle's error envelope, of which only the human parts are worth reporting. */
+const PaddleApiError = z.object({
+  error: z
+    .object({
+      type: z.string().optional(),
+      code: z.string().optional(),
+      detail: z.string().optional(),
+    })
+    .loose(),
+});
+
+/** A Paddle success envelope: the entity under `data`, and pagination under `meta` for a list. */
+const PaddleEnvelope = z
+  .object({
+    data: z.unknown(),
+    meta: z
+      .object({ pagination: z.object({ has_more: z.boolean().optional() }).loose().optional() })
+      .loose()
+      .optional(),
+  })
+  .loose();
+
+/** What one call needs: what it is for, the key, and optionally a body, a query, or a probe flag. */
+export interface PaddleJsonOptions {
+  /** What was being asked for, in an operator's words. Lands in every refusal's `detail`. */
+  what: string;
+  /** The Paddle API key — `pdl_live_apikey_…` or `pdl_sdbx_apikey_…`. */
+  apiKey: string;
+  /** Which account to reach. Decides the host, and nothing else. */
+  environment: PaddleEnvironment;
+  /** The HTTP method. Defaults to GET, or POST when a body is present. */
+  method?: string;
+  /** The JSON request body. */
+  body?: unknown;
+  /**
+   * The query string as pairs, appended in order.
+   *
+   * Pairs rather than a record so order is this caller's to decide and a key may legitimately repeat.
+   * **An array parameter is not one of those cases.** Paddle documents every `array[string]` parameter as
+   * one key with comma-separated values — `event_type=a,b,c`, `include=x,y` — and a repeated key is a form
+   * it documents nowhere. Build the comma-separated value at the call site.
+   */
+  query?: readonly (readonly [string, string])[];
+  /**
+   * An idempotency key, so a request Paddle already performed is not performed twice.
+   *
+   * The one place this matters is checkout: a double-submitted buy button must create one transaction,
+   * not two, and Paddle's own header is what guarantees that rather than a check of ours.
+   */
+  idempotencyKey?: string;
+  /** Whether a 404 means "no such object" rather than "this rail is misconfigured". */
+  absentOn404?: boolean;
+}
+
+/** One Paddle answer: the entity, and whether the list it came from has more. */
+export interface PaddleAnswer {
+  /** The `data` member, unnarrowed — the caller parses it with its own Zod object. */
+  data: unknown;
+  /** Whether a paginated list has another page. False for a single entity. */
+  hasMore: boolean;
+}
+
+/**
+ * One call to Paddle. Returns the parsed envelope, or `undefined` for a probing caller's 404.
+ *
+ * `unknown` inside rather than a typed answer: what a subscription looks like is `objects.ts`'s business
+ * and not this module's.
+ */
+export async function paddleJson(
+  transport: PaddleHttpFetch,
+  path: string,
+  options: PaddleJsonOptions,
+): Promise<PaddleAnswer | undefined> {
+  const search = new URLSearchParams();
+  for (const [key, value] of options.query ?? []) search.append(key, value);
+  const query = [...search].length === 0 ? "" : `?${search.toString()}`;
+
+  const headers: Record<string, string> = {
+    authorization: `Bearer ${options.apiKey}`,
+    accept: "application/json",
+    "paddle-version": PADDLE_API_VERSION,
+  };
+  if (options.body !== undefined) headers["content-type"] = "application/json";
+  if (options.idempotencyKey !== undefined) headers["paddle-idempotency-key"] = options.idempotencyKey;
+
+  let response: PaddleHttpResponse;
+  try {
+    response = await transport(`${paddleApiBase(options.environment)}${path}${query}`, {
+      method: options.method ?? (options.body === undefined ? "GET" : "POST"),
+      headers,
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    });
+  } catch (cause) {
+    throw new PaymentsProviderUnavailableError(
+      { detail: `Paddle did not answer when asked for ${options.what}.` },
+      { cause },
+    );
+  }
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    if (response.status === 404 && options.absentOn404) return undefined;
+    throw refusal(response.status, text, options);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch (cause) {
+    throw new PaymentsProviderUnavailableError(
+      { detail: `Paddle answered with a non-JSON body when asked for ${options.what}.` },
+      { cause },
+    );
+  }
+
+  const envelope = PaddleEnvelope.safeParse(parsed);
+  if (!envelope.success) {
+    throw new PaymentsProviderUnavailableError({
+      detail: `Paddle answered for ${options.what} with a body carrying no \`data\`.`,
+    });
+  }
+  return { data: envelope.data.data, hasMore: envelope.data.meta?.pagination?.has_more === true };
+}
+
+/** The refusal for a non-2xx answer: retryable if Paddle is struggling, a configuration failure otherwise. */
+function refusal(status: number, body: string, options: PaddleJsonOptions): PaymentsProviderUnavailableError {
+  if (status === 429 || status >= 500) {
+    return new PaymentsProviderUnavailableError({
+      detail: `Paddle answered ${status} when asked for ${options.what}. ${paddleSaid(body)}`,
+    });
+  }
+
+  const key = status === 401 || status === 403 ? " Check the API key stored for this environment." : "";
+  return new PaymentsRailNotConfiguredError({
+    detail: `Paddle refused the request for ${options.what} with ${status}.${key} ${paddleSaid(body)}`,
+  });
+}
+
+/**
+ * Paddle's own account of the failure, redacted. Empty when the body was not its error envelope.
+ *
+ * Worth carrying rather than dropping, because Paddle's most consequential refusal is a sentence and not
+ * a code: *"Cannot create a transaction or open a checkout as no default payment link has been set for
+ * this account."* Without it an operator sees a 400 on `/transactions` and has nothing to act on.
+ */
+export function paddleSaid(body: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body) as unknown;
+  } catch {
+    return "";
+  }
+  const envelope = PaddleApiError.safeParse(parsed);
+  if (!envelope.success) return "";
+  const parts = [envelope.data.error.code, envelope.data.error.detail].filter(
+    (part): part is string => part !== undefined && part !== "",
+  );
+  return parts.length === 0 ? "" : `Paddle said: ${redactPaddleSecrets(parts.join(" / "))}.`;
+}
+
+/**
+ * Blank out anything key-shaped in text bound for a log.
+ *
+ * Paddle's credentials carry fixed prefixes, which makes this sharper than the Lemon Squeezy equivalent:
+ * an API key is `pdl_live_apikey_…` or `pdl_sdbx_apikey_…`, a destination secret is `pdl_ntfset_…`, and a
+ * client token is `live_…` or `test_…`. The token is publishable, but a log is not where it belongs
+ * either, and a rule with an exception is a rule somebody eventually reads wrong.
+ */
+export function redactPaddleSecrets(text: string): string {
+  return text.replace(/\bpdl_[A-Za-z0-9_]+/g, "…").replace(/\b(?:live|test)_[A-Za-z0-9]{16,}\b/g, "…");
+}

package/src/rails/paddle/checkout.ts

@@ -0,0 +1,240 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { encodeSubjectReference } from "../../data/subject";
+import { PaymentsDiscountInvalidError, PaymentsRailNotConfiguredError } from "../../error/errors";
+import type { PaymentsPaddleCredentials } from "../../secret/registry";
+import type { CheckoutHandoff, CheckoutSessionInput } from "../contract";
+import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch, paddleJson } from "./api";
+import {
+  accountReferenceProof,
+  PADDLE_CUSTOM_ACCOUNT,
+  PADDLE_CUSTOM_ENV,
+  PADDLE_CUSTOM_PROOF,
+  PaddleTransaction,
+} from "./objects";
+
+/**
+ * Checkout: one server path, three ways of handing it to a browser.
+ *
+ * The server does the same thing in every mode — `POST /transactions` with the price from the catalog,
+ * the customer when the buyer has one, the ownership stamp, and the resolved discount. What differs is
+ * only the handoff: `hosted` returns `transaction.checkout.url`, and `overlay` and `inline` return the
+ * transaction for Paddle.js to open in place.
+ *
+ * ## What this call stamps, and why each of them
+ *
+ * **The resolved subject, in `custom_data.pithy_user`.** A Paddle purchase is heard about through a webhook
+ * carrying `ctm_…` and no Pithy holder. This is the pairing, and it is why the `/checkout` route resolves the
+ * subject through the configured seam and never from a request body.
+ *
+ * The value is `encodeSubjectReference`'s output — `user:ada`, `organization:acme` — and **both halves travel
+ * or neither does**. Nothing keeps an organization id from equalling some user's, so a bare id read back at
+ * the far end would eventually hand one holder's subscription to the other. A bare id is also exactly what
+ * this rail stamped before subjects existed, and `decodeSubjectReference` refuses one on purpose: the
+ * purchase orphans, replayable, rather than being attributed to a stranger. The key name is unchanged
+ * through all of that — see `objects.ts`.
+ *
+ * **This deployment's environment, beside it.** `dev` is not publicly routable, so a dev checkout's
+ * webhooks land at `staging`, and both point at one Paddle sandbox with one set of destinations. The
+ * stamp is what lets each ignore the other's traffic.
+ *
+ * **A MAC over both, which is the only part that makes either mean anything.** `Paddle.Checkout.open`
+ * accepts `customData` beside an `items[]` array of price ids with nothing but the publishable client
+ * token — the token this rail ships to every browser that loads a paywall. So a stranger can write the
+ * first two values. They cannot write the third. See `objects.ts`.
+ *
+ * ## The idempotency key
+ *
+ * `Paddle-Idempotency-Key`, derived from the buyer, the price and the deployment. A double-submitted buy
+ * button then creates one transaction rather than two — enforced by Paddle rather than by a check here,
+ * which is the only place it can be enforced, since the two requests may land on different isolates.
+ *
+ * ## What it deliberately does not do
+ *
+ * No quantity and no amount. The price *is* the price — that is Paddle's model — and a checkout that could
+ * name an amount would be a checkout a client could name an amount on.
+ *
+ * **No plan change either, and that is now a fact about this module rather than about the kit.** #79's
+ * locked decision 2 was amended on 2026-08-28: a rail may invoke a plan change and pass the provider's own
+ * figures through unmodified, and this rail does — `rails/paddle/subscription.ts`, behind
+ * {@link SubscriptionRail}. It is a different verb on a subscription that already exists, so it does not
+ * belong on the call that creates one. Checkout still computes no proration and no tax; nothing here
+ * derives an amount from another amount, and `rails/contract.ts` states the line in full.
+ */
+
+/** What creating a checkout needs beyond the input. */
+export interface PaddleCheckoutOptions {
+  /** The rail's credentials. `apiKey` creates the transaction; `webhookSecret` keys the ownership proof. */
+  credentials: PaymentsPaddleCredentials;
+  /** Which Paddle account to sell through. */
+  environment: PaddleEnvironment;
+  /** The publishable client token a browser initializes Paddle.js with. */
+  clientToken: string;
+  /** Which of the three modes this project uses. */
+  checkout: "overlay" | "inline" | "hosted";
+  /** This deployment's `ENVIRONMENT`, stamped so its own webhooks are recognizable. */
+  deployment?: string;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: PaddleHttpFetch;
+}
+
+/** Paddle's discount list, narrowed to the id a transaction needs. */
+const PaddleDiscountMatches = z.array(z.object({ id: z.string().min(1) }).loose());
+
+/** Create a checkout for one product, and say how the browser reaches it. */
+export async function createPaddleCheckoutSession(
+  input: CheckoutSessionInput,
+  options: PaddleCheckoutOptions,
+): Promise<CheckoutHandoff> {
+  const transport = options.transport ?? paddleHttpFetch;
+
+  // Resolved before the transaction is created, so an unusable code is refused as a *code* rather than
+  // surfacing later as a checkout that failed with nothing to say.
+  const discountId =
+    input.discountCode === undefined ? undefined : await resolveDiscount(input.discountCode, options, transport);
+
+  // One encoding, from the one function. The webhook reads it back through `decodeSubjectReference`, and a
+  // second spelling anywhere is a purchase stamped by one code path and read by another.
+  const accountReference = encodeSubjectReference(input.subject);
+
+  const custom: Record<string, string> = { [PADDLE_CUSTOM_ACCOUNT]: accountReference };
+  if (options.deployment !== undefined) {
+    custom[PADDLE_CUSTOM_ENV] = options.deployment;
+    custom[PADDLE_CUSTOM_PROOF] = await accountReferenceProof(
+      accountReference,
+      options.deployment,
+      options.credentials.webhookSecret,
+    );
+  }
+
+  const answer = await paddleJson(transport, "/transactions", {
+    what: "a transaction",
+    apiKey: options.credentials.apiKey,
+    environment: options.environment,
+    // Derived, not random. A retry of the same buy click must carry the same key or the header buys
+    // nothing; two different buyers, prices or deployments must differ or one would suppress the other.
+    //
+    // **The discount code is in the key**, and its absence was a defect rather than a simplification: a
+    // buyer who starts a checkout, closes it, types a code and starts again would otherwise be handed back
+    // the transaction created *before* the code — charged full price by an idempotency key that was doing
+    // exactly what it was asked to.
+    //
+    // **The buyer is the encoded pair, not the id**, for the same reason and with a sharper edge: an
+    // organization that shares an id with a user is a different buyer entirely, and a key derived from the
+    // id alone would hand the second one back the first one's transaction. Deriving it from the reference
+    // this call already stamped is what keeps the two definitions of "the buyer" from drifting apart.
+    idempotencyKey: `pithy:${options.deployment ?? "unknown"}:${accountReference}:${input.providerProductId}:${input.discountCode ?? ""}`,
+    body: {
+      items: [{ price_id: input.providerProductId, quantity: 1 }],
+      // Reuse the buyer's existing Paddle customer, so one buyer keeps one account and their portal shows
+      // everything they have bought rather than only the last thing.
+      ...(input.providerAccountId ? { customer_id: input.providerAccountId } : {}),
+      ...(discountId === undefined ? {} : { discount_id: discountId }),
+      // Automatic, always. Manual collection raises an invoice and waits, which is a different product
+      // and one this rail does not sell through.
+      collection_mode: "automatic",
+      custom_data: custom,
+    },
+  });
+
+  const parsed = PaddleTransaction.safeParse(answer?.data);
+  if (!parsed.success) {
+    throw new PaymentsRailNotConfiguredError({
+      detail:
+        "Paddle created a transaction this build cannot read. Check `Paddle-Version: 1` against the account's default.",
+    });
+  }
+  const transaction = parsed.data;
+
+  if (options.checkout !== "hosted") {
+    return {
+      kind: "paddle",
+      transactionId: transaction.id,
+      clientToken: options.clientToken,
+      environment: options.environment,
+      displayMode: options.checkout,
+      // `config.paddle.successUrl` says of itself that it is "used as `settings.successUrl` for
+      // Paddle.js", and until this line nothing passed it — the overlay closed onto the page the buyer
+      // started from and the adopter's return screen was unreachable in two of the three modes. It
+      // travels on the handoff rather than being read in the browser for the reason every other return
+      // URL is config: a client that could name one could send a paying customer to a page it controls.
+      successUrl: input.successUrl,
+    };
+  }
+
+  const url = transaction.checkout?.url;
+  if (typeof url !== "string" || url === "") {
+    // Paddle returns a null `checkout.url` when the account has no default payment link. A checkout button
+    // that navigates nowhere is worse than a refusal naming the setting, and `pithy doctor` asks the same
+    // question before a buyer finds it.
+    throw new PaymentsRailNotConfiguredError({
+      detail: `Paddle created transaction ${transaction.id} with no checkout URL. Set a default payment link under Checkout → Checkout settings in the Paddle dashboard, or use \`paddle.checkout: "overlay"\`.`,
+    });
+  }
+  return { kind: "redirect", url };
+}
+
+/**
+ * Turn the code a customer typed into the discount id a transaction wants.
+ *
+ * Paddle's `discount_id` takes a `dsc_…`, not the customer-facing string, so this lookup is unavoidable.
+ * It is also where the code's validity is learned, and learning it *here* is what makes the refusal a good
+ * one: an unknown, expired or exhausted code is refused before a transaction exists, as
+ * `payments/discount_invalid` naming the code, rather than becoming a checkout that fails in front of the
+ * customer with nothing to say but that something went wrong.
+ *
+ * `status=active` is part of the query rather than a check afterwards, so an expired or exhausted code
+ * simply does not come back. Paddle decides what active means — nothing here reads `expires_at` or counts
+ * redemptions, for the same reason nothing here computes a discounted price.
+ *
+ * **One refusal for all three cases**, and that is a decision rather than an omission. Naming which of
+ * "no such code", "expired" and "limit reached" it was helps the buyer a little and tells an
+ * unauthenticated enumerator which codes exist, which is worth more to them.
+ */
+async function resolveDiscount(
+  code: string,
+  options: PaddleCheckoutOptions,
+  transport: PaddleHttpFetch,
+): Promise<string> {
+  let answer: Awaited<ReturnType<typeof paddleJson>>;
+  try {
+    answer = await paddleJson(transport, "/discounts", {
+      what: `the discount code ${code}`,
+      apiKey: options.credentials.apiKey,
+      environment: options.environment,
+      query: [
+        ["code", code],
+        ["status", "active"],
+        ["per_page", "1"],
+      ],
+    });
+  } catch (cause) {
+    // Paddle refuses a malformed code outright rather than answering an empty list — its codes are
+    // `^[a-zA-Z0-9]{1,32}$`, so anything with a dash or an underscore is a 400 with a bare "Invalid
+    // request." Left alone that surfaces as `rail_not_configured`, which tells a customer this payment
+    // method is unavailable when what happened is that their code was not one Paddle accepts.
+    if (cause instanceof PithyError && cause.payload.code === "payments/rail_not_configured") {
+      throw new PaymentsDiscountInvalidError(
+        {
+          message: `"${code}" is not a discount code we can accept.`,
+          detail: `Paddle refused a lookup of discount code "${code}". ${cause.payload.detail ?? ""}`,
+        },
+        { cause },
+      );
+    }
+    throw cause;
+  }
+
+  const matches = PaddleDiscountMatches.safeParse(answer?.data);
+  const found = matches.success ? matches.data[0] : undefined;
+  if (found === undefined) {
+    throw new PaymentsDiscountInvalidError({
+      message: `"${code}" is not a discount code we can accept.`,
+      detail: `Paddle has no active discount matching "${code}" — unknown, expired, or fully redeemed.`,
+    });
+  }
+  return found.id;
+}