@pithy-sh/payments 0.1.0

package/src/migrations/0001_purchases.ts

@@ -0,0 +1,312 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Kysely, sql } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Payments' six tables: the purchase projection, the materialized entitlement read model, the
+ * provider-identity map, the raw webhook log, the reconciliation run log, and the sync cursors.
+ *
+ * camelCase identifiers; `CamelCasePlugin` snake-cases them in the DDL. `down` is the tested inverse.
+ *
+ * Two constraints carry the design. `UNIQUE (rail, providerTransactionId)` on purchases is what makes
+ * three write paths converge on one row — a replayed webhook violates it and the write becomes a
+ * no-op update rather than a second purchase. `UNIQUE (subjectType, subjectId, entitlement)` on
+ * entitlements is what makes the read model a read model: one row per subject per entitlement, whichever
+ * purchase currently grants it. Correctness lives in the schema, not in a hopeful application-level check
+ * a race could skip.
+ *
+ * The holder of a purchase is a **pair** — a kind and an id — and both columns are in that key, ahead of
+ * the entitlement, so the per-subject read is a covering prefix of it. Keying on the id alone would let an
+ * organization whose id equalled some user's read that user's grants, and nothing anywhere makes those two
+ * namespaces disjoint. The kind is closed at the database with a CHECK on all three subject-bearing
+ * tables, for the reason `environment` is: a value the whole schema is keyed on is not something to trust
+ * from whatever wrote the row.
+ *
+ * The indexes come in two families. Three serve the questions the capability asks of itself — a buyer's
+ * own purchases, the reconciliation sweep, the pending-delivery queue. Three serve the control-plane
+ * reads (#247), which ask a different question: the newest rows across every account. The purchases
+ * primary key is a **text UUID**, deliberately, so it is unique but not monotonic and is no use as a
+ * sort; without those three, every page of a purchases pane sorts a customer's entire order history to
+ * return twenty-five rows, and does it again for the next page. That is not a slow query so much as a
+ * defect shipped into other people's production databases, which is why the reads' indexes are part of
+ * the schema rather than a note about it.
+ *
+ * This is the whole payments schema, in one migration — see `CONTRIBUTING.md` §Migrations for why that
+ * is the shape while nothing is published, and what changes the day something is.
+ */
+export const payments_0001_purchases: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyPaymentsPurchases")
+      // Text UUID: these surface in API responses, and sequential ids would leak order volume.
+      .addColumn("id", "text", (c) => c.primaryKey())
+      // The owner, as a pair. Adjacent and both not-null, because half a subject identifies nobody.
+      .addColumn("subjectType", "text", (c) => c.notNull())
+      .addColumn("subjectId", "text", (c) => c.notNull())
+      .addColumn("rail", "text", (c) => c.notNull())
+      .addColumn("providerTransactionId", "text", (c) => c.notNull())
+      .addColumn("productId", "text", (c) => c.notNull())
+      .addColumn("providerProductId", "text", (c) => c.notNull())
+      .addColumn("type", "text", (c) => c.notNull())
+      .addColumn("status", "text", (c) => c.notNull())
+      // Defaulted in SQL as well as in the Zod object: three of the four rails never mention it, and a
+      // row written by one of them must not depend on the writer remembering to set it.
+      .addColumn("role", "text", (c) => c.notNull().defaultTo("charge"))
+      .addColumn("environment", "text", (c) => c.notNull())
+      .addColumn("purchasedAt", "integer", (c) => c.notNull())
+      .addColumn("expiresAt", "integer")
+      .addColumn("revokedAt", "integer")
+      // When a paused subscription resumes, as the provider stated it. Nullable, because "paused
+      // indefinitely" is a real state on every rail that pauses at all — see `data/pause.ts`.
+      .addColumn("resumesAt", "integer")
+      .addColumn("originalTransactionId", "text")
+      .addColumn("amountMinor", "integer")
+      .addColumn("currency", "text")
+      .addColumn("providerEventAt", "integer", (c) => c.notNull())
+      .addColumn("payload", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      // The idempotency guard all three write paths rely on. A replay's insert violates it, which routes
+      // the write into its `ON CONFLICT` branch, so one provider transaction is one row forever.
+      .addUniqueConstraint("pithyPaymentsPurchasesProviderIdx", ["rail", "providerTransactionId"])
+      // A sandbox transaction must never grant a production entitlement, so the value is constrained at
+      // the database rather than trusted from a provider payload.
+      .addCheckConstraint("pithyPaymentsPurchasesEnvironment", sql`environment in ('production', 'sandbox')`)
+      // Amounts are integer minor units, never floats, and never negative.
+      .addCheckConstraint("pithyPaymentsPurchasesAmount", sql`amount_minor is null or amount_minor >= 0`)
+      // A `state` row never fulfills a `grants` clause, so a typo here would credit a ledger for a
+      // subscription's standing. Constrained at the database for the same reason `environment` is.
+      .addCheckConstraint("pithyPaymentsPurchasesRole", sql`role in ('charge', 'state')`)
+      // A resume date only means anything on a paused row. Constrained at the database because it is what
+      // makes the column's null readable: on a paused row null is the provider saying "indefinitely", and
+      // everywhere else it is "not paused" — two facts a consumer has to tell apart, and a rail that wrote
+      // a renewal date or a period end into it would silently collapse them.
+      .addCheckConstraint("pithyPaymentsPurchasesResumes", sql`resumes_at is null or status = 'paused'`)
+      // The subject kind is closed, and closed here rather than only in Zod: every ownership check in the
+      // capability compares both halves, and a third spelling of "organization" would be a holder no gate
+      // ever matches. snake_case in the raw fragment — `CamelCasePlugin` does not reach inside one.
+      .addCheckConstraint("pithyPaymentsPurchasesSubjectType", sql`subject_type in ('user', 'organization')`)
+      .execute();
+
+    // The owner read: one subject's purchases, newest first. Both halves lead, in the order they are
+    // always known in — the kind comes from config, the id from the caller — so the index answers the
+    // whole question rather than filtering a kind out afterwards.
+    await db.schema
+      .createIndex("pithyPaymentsPurchasesOwnerIdx")
+      .on("pithyPaymentsPurchases")
+      .columns(["subjectType", "subjectId", "purchasedAt"])
+      .execute();
+
+    // The reconciliation read: subscriptions near expiry, oldest verification first.
+    await db.schema
+      .createIndex("pithyPaymentsPurchasesExpiryIdx")
+      .on("pithyPaymentsPurchases")
+      .columns(["status", "expiresAt"])
+      .execute();
+
+    // The purchase log, newest first: `GET {base}/admin/purchases`. The keyset resumes on
+    // `(purchasedAt, id)`, and `purchasedAt` leading is what makes the page a range scan the LIMIT can
+    // genuinely stop.
+    await db.schema
+      .createIndex("pithyPaymentsPurchasesPurchasedIdx")
+      .on("pithyPaymentsPurchases")
+      .columns(["purchasedAt", "id"])
+      .execute();
+
+    // The subscriptions listing: `GET {base}/admin/subscriptions`. `type` is an equality and
+    // `purchasedAt` is the ordering column, so the filtered page is a range scan of its own rather than a
+    // scan of the whole log looking for the rows that renew. A project selling mostly consumables is
+    // exactly the one where the difference is large.
+    await db.schema
+      .createIndex("pithyPaymentsPurchasesTypePurchasedIdx")
+      .on("pithyPaymentsPurchases")
+      .columns(["type", "purchasedAt", "id"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyPaymentsEntitlements")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      // The holder, as a pair, exactly as the purchase carries it.
+      .addColumn("subjectType", "text", (c) => c.notNull())
+      .addColumn("subjectId", "text", (c) => c.notNull())
+      .addColumn("entitlement", "text", (c) => c.notNull())
+      .addColumn("active", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("expiresAt", "integer")
+      .addColumn("sourcePurchaseId", "text")
+      // A human's decision, held against the projection. Every other row here is derived from the purchases
+      // table on every write that touches its key, which is what keeps the read model honest — and what would
+      // otherwise erase a support comp the moment the user's next renewal arrived.
+      .addColumn("manual", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      // One row per subject per entitlement — the upsert conflict target that makes this a read model.
+      // Both subject columns lead the key: a user and an organization may hold the same key at once, and
+      // they are two rows, while one subject holding it twice is the thing this refuses.
+      .addUniqueConstraint("pithyPaymentsEntitlementsOwnerIdx", ["subjectType", "subjectId", "entitlement"])
+      .addCheckConstraint("pithyPaymentsEntitlementsActive", sql`active in (0, 1)`)
+      .addCheckConstraint("pithyPaymentsEntitlementsManual", sql`manual in (0, 1)`)
+      .addCheckConstraint("pithyPaymentsEntitlementsSubjectType", sql`subject_type in ('user', 'organization')`)
+      .execute();
+
+    // The entitlement listing: `GET {base}/admin/entitlements`. `createdAt` rather than `updatedAt`,
+    // because the projection re-derives every affected row on every purchase write — ordering on
+    // `updatedAt` would shuffle rows under a reader for reasons that have nothing to do with the grant.
+    // The per-holder read needs no index of its own: `UNIQUE (subjectType, subjectId, entitlement)`
+    // already serves it, because the subject columns lead.
+    await db.schema
+      .createIndex("pithyPaymentsEntitlementsCreatedIdx")
+      .on("pithyPaymentsEntitlements")
+      .columns(["createdAt", "id"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyPaymentsProviderAccounts")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("rail", "text", (c) => c.notNull())
+      .addColumn("providerAccountId", "text", (c) => c.notNull())
+      // What the identity maps back to: the subject pair, not a user id.
+      .addColumn("subjectType", "text", (c) => c.notNull())
+      .addColumn("subjectId", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      // A webhook arrives carrying `cus_123`, and names no holder of ours. This is the only mapping back, so it
+      // must be one-to-one per rail.
+      //
+      // **Deliberately not widened by the subject.** Adding the pair to this key would make a rebind a
+      // legal insert, and the second row would collect the first subject's renewals. One provider
+      // identity, one holder, until somebody deletes the row on purpose.
+      .addUniqueConstraint("pithyPaymentsProviderAccountsIdx", ["rail", "providerAccountId"])
+      .addCheckConstraint("pithyPaymentsProviderAccountsSubjectType", sql`subject_type in ('user', 'organization')`)
+      .execute();
+
+    await db.schema
+      .createTable("pithyPaymentsWebhookEvents")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("rail", "text", (c) => c.notNull())
+      .addColumn("providerEventId", "text", (c) => c.notNull())
+      .addColumn("payload", "text", (c) => c.notNull())
+      .addColumn("receivedAt", "integer", (c) => c.notNull())
+      // When this delivery was **finished with** — projected, or deliberately nothing to project. The one
+      // column the webhook guard short-circuits on, so it says "we have finished this" and never "we have
+      // seen this". Three writers once disagreed about that and two of them stopped purchases from ever
+      // being projected (#337).
+      .addColumn("processedAt", "integer")
+      // When a repair pass gave up on this event so its stream could advance.
+      //
+      // **A second timestamp rather than a status column, and beside `processedAt` rather than replacing
+      // it.** Abandoning is the sweep's decision about its own progress; finishing is a fact about the
+      // purchase. Collapsing them into one column is what #337 was. A `status` enum would have made the
+      // writers exhaustive and left every reader free to spell out its own predicate — which is where the
+      // defect actually lived — so the state is derived in `data/webhookEvent.ts` and asked for by name,
+      // and the storage stays timestamps: they answer *when*, which is what this table is read for, and
+      // they cannot contradict each other the way an enum can contradict the timestamp beside it.
+      .addColumn("abandonedAt", "integer")
+      .addColumn("error", "text")
+      // How many times a repair pass has tried this event and failed.
+      //
+      // **Here rather than in a table of its own, because the count is a fact about this row's handling.**
+      // `processedAt` and `error` are already the other two, and the three are only ever read together:
+      // "it arrived, it was tried N times, here is why it still has not gone through". A side table would
+      // add a second row per event, a join for the one question anybody asks, and a way for the two to
+      // disagree about an event that exists in one and not the other. KV would add a second store with no
+      // transactional relationship to the row it counts. The count also has to survive exactly as long as
+      // the row does and no longer, which is what a column gets for free and every alternative has to
+      // arrange.
+      //
+      // Defaulted, so the webhook path — which does not retry and does not count — inserts as it always
+      // did.
+      .addColumn("attempts", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      // Every provider delivers at-least-once and retries, so a redelivery is expected and must be
+      // recognized rather than reprocessed.
+      .addUniqueConstraint("pithyPaymentsWebhookEventsIdx", ["rail", "providerEventId"])
+      .execute();
+
+    // The "why didn't this renew" read: everything not yet finished with, oldest first — pending, failed,
+    // and abandoned alike, because all three are deliveries whose purchase has not been projected. That
+    // an abandoned event appears here is deliberate: it is exactly the row an operator has to be able to
+    // find, and `abandonedAt` beside it says which of the three it is.
+    await db.schema
+      .createIndex("pithyPaymentsWebhookEventsPendingIdx")
+      .on("pithyPaymentsWebhookEvents")
+      .columns(["processedAt", "receivedAt"])
+      .execute();
+
+    // One row per reconciliation pass. Counts, timestamps and enums — there is deliberately no column a
+    // provider payload could be written into, which is a stronger control than never selecting one.
+    await db.schema
+      .createTable("pithyPaymentsReconcileRuns")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("startedAt", "integer", (c) => c.notNull())
+      .addColumn("finishedAt", "integer", (c) => c.notNull())
+      .addColumn("environment", "text", (c) => c.notNull())
+      // Null is the scheduled behavior — every enabled rail. A value means somebody narrowed the pass.
+      .addColumn("rail", "text")
+      .addColumn("pages", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("scanned", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("unchanged", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("drifted", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("superseded", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("skipped", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("failed", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("truncated", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("dryRun", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      // Same rule the purchases table states: a sandbox pass and a production pass are facts about
+      // different money, and the database is where that is constrained rather than trusted.
+      .addCheckConstraint("pithyPaymentsReconcileRunsEnvironment", sql`environment in ('production', 'sandbox')`)
+      .addCheckConstraint("pithyPaymentsReconcileRunsTruncated", sql`truncated in (0, 1)`)
+      .addCheckConstraint("pithyPaymentsReconcileRunsDryRun", sql`dry_run in (0, 1)`)
+      // A tally cannot be negative, and a run that reported one is a bug in the pass rather than a fact.
+      .addCheckConstraint(
+        "pithyPaymentsReconcileRunsCounts",
+        sql`pages >= 0 and scanned >= 0 and unchanged >= 0 and drifted >= 0 and superseded >= 0 and skipped >= 0 and failed >= 0`,
+      )
+      .execute();
+
+    // The runs listing: `GET {base}/admin/reconcile-runs`, newest first, and the retention prune's own
+    // range delete. Both read `startedAt` leading; the id is the keyset tiebreak, as everywhere else here.
+    await db.schema
+      .createIndex("pithyPaymentsReconcileRunsStartedIdx")
+      .on("pithyPaymentsReconcileRuns")
+      .columns(["startedAt", "id"])
+      .execute();
+
+    // Where a resumable sweep left off. One row per `(rail, name)`, because a rail may sweep more than
+    // one stream and a name is what tells them apart.
+    //
+    // This is **not** a copy of a provider's data and is not a cache of one: it is a single opaque
+    // pointer into somebody else's stream, which is the minimum state a resumable read can have. The
+    // alternative to storing it is re-reading ninety days of events on every run.
+    await db.schema
+      .createTable("pithyPaymentsSyncCursors")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("rail", "text", (c) => c.notNull())
+      .addColumn("name", "text", (c) => c.notNull())
+      // The provider's own resume token — Paddle's `evt_…`. Nullable, because a cursor that has never
+      // advanced is a real state: it means "start at the oldest event this provider still retains".
+      .addColumn("cursor", "text")
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      // One cursor per stream. Two rows for one stream would let two runs each believe they were
+      // authoritative, and the sweep would silently skip whatever fell between them.
+      .addUniqueConstraint("pithyPaymentsSyncCursorsIdx", ["rail", "name"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropTable("pithyPaymentsSyncCursors").execute();
+    await db.schema.dropIndex("pithyPaymentsReconcileRunsStartedIdx").execute();
+    await db.schema.dropTable("pithyPaymentsReconcileRuns").execute();
+    await db.schema.dropIndex("pithyPaymentsWebhookEventsPendingIdx").execute();
+    await db.schema.dropTable("pithyPaymentsWebhookEvents").execute();
+    await db.schema.dropTable("pithyPaymentsProviderAccounts").execute();
+    await db.schema.dropIndex("pithyPaymentsEntitlementsCreatedIdx").execute();
+    await db.schema.dropTable("pithyPaymentsEntitlements").execute();
+    await db.schema.dropIndex("pithyPaymentsPurchasesTypePurchasedIdx").execute();
+    await db.schema.dropIndex("pithyPaymentsPurchasesPurchasedIdx").execute();
+    await db.schema.dropIndex("pithyPaymentsPurchasesExpiryIdx").execute();
+    await db.schema.dropIndex("pithyPaymentsPurchasesOwnerIdx").execute();
+    await db.schema.dropTable("pithyPaymentsPurchases").execute();
+  },
+};

package/src/pricing/location.ts

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Where a price quote's location comes from, decided in one place.
+ *
+ * **A customer is charged from their billing address.** Paddle settles tax on the transaction's address,
+ * not on where the browser happened to be — so the browser's IP is a *provisional estimate* and the
+ * address on file is the authority. Both are legitimate answers; which one a screen got is a fact the
+ * screen has to be able to state, because one of them is what the card will be charged and the other is
+ * a guess that resolves at checkout.
+ *
+ * That is the whole of this module. It takes what a caller knows about a visitor, picks the best source
+ * available, and says which one it picked. Nothing here fetches, renders, or formats.
+ *
+ * **One resolver, not a decision at each call site.** A pricing screen, a paywall and a cart all have to
+ * answer "where does this person live", and three answers is how a page quotes from an address the
+ * checkout does not charge from. Every site that derives a location for a Paddle price quote calls
+ * {@link resolvePriceLocation}, and the honesty label comes off the same object.
+ *
+ * **No imports, deliberately.** This compiles inside the Worker's program *and* inside an adopter's
+ * DOM-typed browser program — `../client/api.ts` explains at length why those are two programs — so it
+ * names its own shapes rather than reaching for Zod, for core's codecs, or for Paddle's types. The
+ * scaffolded pricing screen hands {@link priceQueryFor}'s answer straight to `usePricePreview`, so
+ * TypeScript pins the shape against the real `PaddlePriceQuery` at the one place it matters.
+ *
+ * **No price, no currency, no country table.** Figures come from Paddle, rendered by Paddle. Nothing in
+ * this file knows what anything costs, and nothing in it may learn: a table of amounts here would be
+ * wrong in every country it did not list and wrong silently in the ones it did.
+ */
+
+/**
+ * Where a quote's location came from, in order of authority.
+ *
+ * - `customer` — a Paddle customer id. Paddle prices from the address it holds for them, which is the
+ *   address the checkout charges. The best answer there is, and the only one that is not a guess.
+ * - `address` — a billing address the caller holds but Paddle does not yet. Better than the network,
+ *   still not proof of what the checkout will settle on, because the buyer may enter another.
+ * - `ip` — nobody said. Paddle resolves the country from the browser's own IP. Right for a marketing
+ *   page a stranger is reading, and an estimate every time.
+ */
+export type PriceLocationSource = "customer" | "address" | "ip";
+
+/** A billing address, as far as a price quote cares about one. */
+export interface PriceAddress {
+  /** ISO 3166-1 alpha-2 — `"US"`, `"GB"`, `"JP"`. Paddle takes it verbatim. */
+  countryCode: string;
+  /**
+   * The postal code, where the caller has one.
+   *
+   * Load-bearing rather than decorative. United States tax resolves below the country — 15% in Chicago,
+   * 8.875% in New York, 0% in Oregon — and Paddle answers a country-only request with 0% rather than
+   * with an error, so a quote without one can be short of what the card is charged.
+   */
+  postalCode?: string;
+}
+
+/**
+ * What the caller knows about this visitor. Every field optional, because "nothing" is a real answer.
+ *
+ * A stranger on a marketing page is `null`. A signed-in visitor whose account has never bought anything
+ * carries an address and no customer. A returning customer carries the `ctm_…` the webhook path recorded
+ * against them, which is the same value `POST /payments/checkout` hands Paddle as `customer_id`.
+ */
+export interface PriceVisitor {
+  /** The Paddle customer this visitor is, or null. An identifier, not a credential. */
+  customerId?: string | null;
+  /** A billing address the caller holds, or null. */
+  address?: PriceAddress | null;
+}
+
+/**
+ * The decision: which source was used, and what to send.
+ *
+ * Both halves matter to a screen. The `customerId`/`address` pair is what goes to Paddle; `source` is
+ * what the sentence under the figure has to be true about.
+ */
+export interface PriceLocation {
+  /** Which source won. */
+  source: PriceLocationSource;
+  /** The Paddle customer to price as, or null. */
+  customerId: string | null;
+  /** The address to price at, or null. */
+  address: PriceAddress | null;
+  /**
+   * Whether this location is a guess about where the buyer lives rather than the address they are
+   * charged from.
+   *
+   * True exactly when `source` is `ip`. Kept as a field rather than left to every reader to derive,
+   * because "is this provisional" is the question, and re-deriving it from the union is how a fourth
+   * source arrives one day and half the readers keep answering for three.
+   */
+  provisional: boolean;
+}
+
+/**
+ * Pick the best location available, and say which one it is.
+ *
+ * Precedence is authority, not convenience: a Paddle customer beats an address the caller holds, because
+ * Paddle prices the customer from the address it will actually charge — and if the two disagree, a
+ * traveler or a VPN, the billing address wins for what they are charged, so it wins for what they are
+ * shown.
+ *
+ * **Never a silent default.** `null`, `undefined`, an empty customer id and an address with no country
+ * all resolve to `ip` *and say so*, so a caller that meant to pass something and passed nothing gets an
+ * estimate labeled as one rather than a guess wearing the authority of an address.
+ */
+export function resolvePriceLocation(visitor: PriceVisitor | null | undefined): PriceLocation {
+  const customerId = visitor?.customerId;
+  if (typeof customerId === "string" && customerId.length > 0) {
+    return { source: "customer", customerId, address: null, provisional: false };
+  }
+  const address = visitor?.address;
+  if (address && typeof address.countryCode === "string" && address.countryCode.length > 0) {
+    // Rebuilt rather than passed through, so an empty postal code — the shape an unfilled form field
+    // arrives in — does not reach Paddle as though somebody had typed one.
+    const postalCode =
+      typeof address.postalCode === "string" && address.postalCode.length > 0 ? address.postalCode : undefined;
+    return {
+      source: "address",
+      customerId: null,
+      address:
+        postalCode === undefined
+          ? { countryCode: address.countryCode }
+          : { countryCode: address.countryCode, postalCode },
+      provisional: false,
+    };
+  }
+  return { source: "ip", customerId: null, address: null, provisional: true };
+}
+
+/** One line of a price request: what to quote, and how many. */
+export interface PriceQuoteItem {
+  /** The Paddle price — `pri_…`. */
+  priceId: string;
+  /** How many units. */
+  quantity: number;
+}
+
+/**
+ * What to ask Paddle, for these items at this location.
+ *
+ * Structurally a `PaddlePriceQuery`, and deliberately not typed as one — see this module's header. The
+ * absent fields are absent rather than `undefined`-valued: `priceQueryKey` serializes the query into an
+ * effect dependency, and a key that changed shape between "no address" and "an address of undefined"
+ * would re-quote a page that asked the same question twice.
+ */
+export function priceQueryFor(
+  items: readonly PriceQuoteItem[],
+  location: PriceLocation,
+): { items: readonly PriceQuoteItem[]; customerId?: string; address?: PriceAddress } {
+  if (location.customerId !== null) return { items, customerId: location.customerId };
+  if (location.address !== null) return { items, address: location.address };
+  return { items };
+}
+
+/**
+ * Whether the figure has to be labeled an estimate.
+ *
+ * Two independent reasons, and either one is enough:
+ *
+ * **The location is provisional.** An IP says where a browser connected from, not where a card is
+ * registered. The buyer enters a billing address at the card form and the total settles then — which is
+ * how commerce works everywhere, and is expected rather than a broken promise, *provided the figure said
+ * it was an estimate first*.
+ *
+ * **The tax is not fully resolved.** `priceSummary().estimated` is true when Paddle resolved no postal
+ * code, and United States tax lives below the country. Pass it in; this is where the two facts meet.
+ *
+ * Deriving the label from the postal code alone made it right by accident — Paddle resolves no postal
+ * code from an IP today — and an accident is not a rule. This states the rule.
+ */
+export function quoteIsEstimated(location: PriceLocation, taxUnresolved: boolean): boolean {
+  return location.provisional || taxUnresolved;
+}

package/src/pricing/visitor.ts

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { callPayments, type PaymentsClientOptions } from "../client/api";
+import type { PriceVisitor } from "./location";
+
+/**
+ * Where a signed-in visitor's Paddle customer comes from: `GET {basePath}/pricing`, asked of this
+ * project's own Worker.
+ *
+ * **The same value the checkout charges, from the same row.** That route reads the provider-account map
+ * keyed on the subject the seam resolved — `providerAccountForSubject(db, "paddle", subject)` — and so does
+ * `POST /payments/checkout`, which hands it to Paddle as `customer_id`. One reader, one row, so the
+ * figure quoted and the figure charged cannot resolve location differently. A screen that derived a
+ * customer id any other way would move this problem rather than solve it.
+ *
+ * **`ctm_…` is an identifier, not a credential.** It names a Paddle customer; it authorizes nothing.
+ * Paddle's `PricePreview` reads a price with it and the publishable client token, which is the pair
+ * Paddle publishes for exactly this. Nothing here widens what reaches a browser: the route is
+ * `requireAuth()` and answers only about its own caller, so a visitor learns their own customer id and
+ * no one else's.
+ *
+ * **Hand-written guard, no schema library, no absolute URL.** For the reason `../client/api.ts` gives at
+ * length: this compiles into an adopter's browser program, and dragging the Worker's Zod graph in behind
+ * it would break their build. The server's half of this response *is* a Zod object — `http/responses.ts`
+ * — so the boundary is validated on both sides, each in the vocabulary its own program can carry.
+ *
+ * **The request itself is not written here.** `callPayments` is the one producer of a same-origin,
+ * cookie-bearing call to this Worker, and this module routes through it like every other reader. It used
+ * to own a second fetch — its own base-path default, its own `credentials: "include"`, its own three
+ * failure directions — which is the drift this kit keeps paying for (#346).
+ *
+ * **A failure is not an answer, and this one fails honest.** Unreachable, refused, or unreadable all
+ * return `null`, which resolves to the IP location and renders the figure labeled `Estimated.` A guess
+ * that says it is a guess is the safe direction; the unsafe one would be treating a failed read as
+ * proof there is no address on file.
+ */
+
+/**
+ * Where to ask, and what to ask with — the same options every other call on this side of the wire takes.
+ *
+ * An alias rather than a second declaration. The two shapes agreed by hand until this read started going
+ * through `callPayments`; now there is one of them, and a name a scaffolded screen already imports.
+ */
+export type PriceVisitorOptions = PaymentsClientOptions;
+
+/** Whether a value is a plain record — the first step of the guard. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The Paddle customer on a `GET /pricing` body, or null.
+ *
+ * Total, and refusing rather than coercing. `quotedFrom` is absent on an older Worker than this bundle,
+ * null for a caller who has never bought anything, and a record naming a rail otherwise — three shapes
+ * that all mean "no Paddle customer to price as" unless the third names `paddle` and carries a string.
+ */
+export function readPaddleCustomer(body: unknown): string | null {
+  if (!isRecord(body)) return null;
+  const quotedFrom = body.quotedFrom;
+  if (!isRecord(quotedFrom)) return null;
+  if (quotedFrom.rail !== "paddle") return null;
+  const providerAccountId = quotedFrom.providerAccountId;
+  return typeof providerAccountId === "string" && providerAccountId.length > 0 ? providerAccountId : null;
+}
+
+/**
+ * Ask this project's Worker who Paddle prices the signed-in caller as.
+ *
+ * Never throws, and never reports a failure: the caller's only sensible response to one is to quote from
+ * the IP and say so, which is what `null` already means.
+ */
+export async function fetchPriceVisitor(options?: PriceVisitorOptions): Promise<PriceVisitor | null> {
+  // `isRecord` is the whole guard, and deliberately so: `readPaddleCustomer` is total over anything, so
+  // narrowing harder here would only move the same refusal a line earlier. What matters is that a
+  // refusal, an unreachable Worker and an unreadable body all land in the same `!ok` branch.
+  const result = await callPayments("/pricing", {}, options, isRecord);
+  if (!result.ok) return null;
+  const customerId = readPaddleCustomer(result.value);
+  return customerId === null ? null : { customerId };
+}