@wtfalch/payments 0.2.0 → 0.4.0

package/README.md

@@ -22,7 +22,12 @@ case) and passes it in; this package never fetches or stores one.
 import { createStripeProvider, createVippsProvider } from '@wtfalch/payments';
 
 const stripe = createStripeProvider({ secretKey }); // sk_...
+
+// Either an already-valid access token (0.2.x shape, never refreshed here)...
 const vipps = createVippsProvider({ subscriptionKey, merchantSerialNumber, accessToken });
+// ...or let the adapter fetch and cache its own (recommended: it refreshes
+// before expiry and shares one in-flight refresh across concurrent calls).
+const vipps2 = createVippsProvider({ subscriptionKey, merchantSerialNumber, clientId, clientSecret });
 
 const payment = await stripe.createPayment({
   reference: 'order-123',
@@ -37,6 +42,7 @@ const payment = await stripe.createPayment({
 ```ts
 await stripe.capturePayment(payment.providerReference); // full capture
 await stripe.refundPayment(payment.providerReference, { reason: 'requested_by_customer' });
+await stripe.cancelPayment(payment.providerReference); // a reserved, uncaptured payment
 ```
 
 ### Recurring agreements
@@ -58,12 +64,98 @@ await vipps.chargeRecurringAgreement(agreement.agreementReference, {
   amount: { value: 29900, currency: 'NOK' },
   description: 'March invoice',
 });
+
+// Read the agreement's current status fresh from the provider (e.g. after
+// the payer approves it, or on a schedule) -- what refreshAgreementStatus
+// below calls under the hood.
+await vipps.getRecurringAgreement(agreement.agreementReference);
+
+// Stop it (e.g. Archon cancelling a company's subscription) and change its
+// price (a plan change). A caller also tracking this agreement in the store
+// below should follow stopRecurringAgreement with refreshAgreementStatus --
+// or let the resulting agreement.stopped webhook reach applyWebhookEvent --
+// to persist the transition; these two calls only reach the provider.
+await vipps.stopRecurringAgreement(agreement.agreementReference);
+await vipps.updateRecurringAgreement(agreement.agreementReference, {
+  amount: { value: 39900, currency: 'NOK' },
+});
+
+// Cancel a charge that was created but never settles (e.g. its period was
+// credited before it captured).
+await vipps.cancelRecurringCharge(agreement.agreementReference, chargeReference);
 ```
 
 For Stripe, `createRecurringAgreement` creates a SetupIntent
 (`agreement.clientSecret` -- confirm with Stripe.js) and
 `chargeRecurringAgreement` looks up the payment method it saved and charges
-it off-session.
+it off-session. `getRecurringAgreement` reads that same SetupIntent back.
+`stopRecurringAgreement` cancels that SetupIntent (there is no Subscription
+object here to cancel); `updateRecurringAgreement` keeps its
+`metadata[amount]` in sync, since a SetupIntent carries no real price of its
+own; `cancelRecurringCharge` cancels the PaymentIntent that
+`chargeRecurringAgreement` created (Stripe has no separate "recurring
+charge" resource).
+
+### Store
+
+A provider-neutral Postgres store for the agreement/charge rows a caller
+would otherwise keep in its own schema -- see
+[docs/adr/0006-payment-store.md](../../docs/adr/0006-payment-store.md) for
+the full design and its concurrency-safety argument.
+
+```ts
+import { migrate, createOrGetAgreement, createOrGetCharge, refreshAgreementStatus, applyWebhookEvent } from '@wtfalch/payments';
+
+// Once, at startup or in a migration step. `db` must be a single connection
+// (not a pool) -- see db.ts's doc comment.
+await migrate(db);
+
+// Idempotent: a second call with the same externalReference returns the
+// same row and never calls the provider again -- but only if the terms
+// match. A retry with a different amount/currency (or, for a charge, a
+// different agreementId) throws PaymentStoreError('mismatched_retry', ...)
+// instead of silently returning the first call's row.
+const agreement = await createOrGetAgreement(db, vipps, {
+  externalReference: subscription.id, // the caller's own key
+  amount: { value: 29900, currency: 'NOK' },
+  productName: 'Pro plan',
+  returnUrl: 'https://example.com/agreements/return',
+});
+// agreement.confirmationUrl -- send the payer here
+
+// After the payer approves it (e.g. on their return, or on a schedule):
+await refreshAgreementStatus(db, vipps, agreement.id);
+
+// Refuses with PaymentStoreError('agreement_not_active', ...) unless the
+// agreement's stored status is "active".
+const charge = await createOrGetCharge(db, vipps, {
+  agreementId: agreement.id,
+  externalReference: billingCharge.id,
+  amount: { value: 29900, currency: 'NOK' },
+  description: 'March invoice',
+});
+
+// In the webhook handler, after verify*Webhook:
+const applied = await applyWebhookEvent(db, event);
+if (applied.matched === 'charge' && applied.changed && applied.charge?.status === 'captured') {
+  // react to the newly captured charge
+}
+```
+
+Status transitions are monotonic: `applyWebhookEvent` and
+`refreshAgreementStatus` gate every write through an explicit per-entity
+allowed-predecessor table, so a delayed, out-of-order webhook delivery (or a
+stale provider read) can never move a charge or agreement's status
+backwards, and a terminal status (`refunded`/`canceled`/`failed`;
+`stopped`/`expired`) never leaves. A rejected transition reports
+`{ changed: false, ignored: 'stale' }` rather than being applied silently --
+this is what keeps a caller's "invoice when `changed && captured`" safe
+under redelivery-without-ordering, not merely defensive. Two concurrent
+deliveries of the same event report exactly one `changed: true`.
+
+`db` is a single-connection `Queryable` (`{ query(text, values?) }`) -- a
+`postgres.js` pool's `sql.reserve()`, not the pool itself; see `db.ts`'s doc
+comment for why every mutating store function needs this.
 
 ### Webhooks
 
@@ -110,18 +202,40 @@ From `packages/payments`:
 pnpm test
 ```
 
-Every test runs against recorded/fake fixtures (`src/fixtures/{stripe,vipps}`)
-and a fake `fetch` (`src/test/fake-fetch.ts`) -- never a live provider call,
-never a real key. Webhook verification tests build their own valid signature
-independently of the code under test (see `*-webhook.test.ts`), then check
-that a tampered payload, a tampered signature, a wrong secret, a wrong
-request path (Vipps), and a stale timestamp are all rejected.
-
-## Known gap
-
-The exact `state` enum on a Vipps ePayment response was not confirmed from
-primary docs at build time (see `src/vipps.ts`'s module doc comment).
-`derivePaymentStatus` falls back to the documented `aggregate.*Amount`
-fields when `state` is absent or unrecognised, but this adapter has not been
-exercised against a real Vipps sandbox response. Do that before relying on
-it for anything that pays out money.
+Adapter and webhook tests run against recorded/fake fixtures
+(`src/fixtures/{stripe,vipps}`) and a fake `fetch` (`src/test/fake-fetch.ts`)
+-- never a live provider call, never a real key. Webhook verification tests
+build their own valid signature independently of the code under test (see
+`*-webhook.test.ts`), then check that a tampered payload, a tampered
+signature, a wrong secret, a wrong request path (Vipps), and a stale
+timestamp are all rejected.
+
+Store tests (`store.test.ts`, `migrate.test.ts`) run against PGlite in
+memory by default and against a real Postgres with `TEST_DATABASE_URL` set
+-- against a throwaway container, never a shared one:
+
+```sh
+docker run -d --rm --name payments-pg -e POSTGRES_PASSWORD=postgres -p 5655:5432 postgres:16-alpine
+TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5655/postgres pnpm test
+docker stop payments-pg
+```
+
+## Known gaps
+
+- The exact `state` enum on a Vipps ePayment response was not confirmed from
+  primary docs at build time (see `src/vipps.ts`'s module doc comment).
+  `derivePaymentStatus` falls back to the documented `aggregate.*Amount`
+  fields when `state` is absent or unrecognised, but this adapter has not
+  been exercised against a real Vipps sandbox response. (The Recurring
+  agreement `status` enum the store depends on *is* confirmed --
+  docs/adr/0006.)
+- No webhook payload shape (ePayment's `name`/`success`, or the Recurring
+  API's `eventType`) has been checked against a real, signed Vipps delivery
+  -- see docs/adr/0004's "What is not yet confirmed".
+- Neither Recurring event's own event-id field is documented, so
+  `eventId` is synthesized from the fields that are (see `vipps.ts`'s
+  `normalizeRecurringEvent`) -- fine for logging, not guaranteed
+  collision-free the way a real event id would be.
+
+Do all of the above before relying on this adapter for anything that pays
+out money.

package/dist/db.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The minimal SQL surface the store needs, so it runs unmodified on PGlite
+ * (tests) and on `postgres` (production) without depending on either.
+ * Values are bound parameters.
+ *
+ * Deliberately a structural interface, not a dependency on `@wtfalch/db` --
+ * the same choice `@wtfalch/ledger` and `@wtfalch/billing` made in their own
+ * `db.ts`. A `Database`/pooled client from that package already satisfies it
+ * structurally, so the host injects one and this published package still
+ * declares no runtime dependency on it.
+ *
+ * **Single connection, not a pool.** Every store function in `store.ts`
+ * that mutates data issues its own `begin` / `pg_advisory_xact_lock` /
+ * `commit` as separate `query()` calls, exactly like `migrate.ts` does --
+ * that only wraps a real transaction, and only makes the advisory lock
+ * mean anything, when every call in one function invocation lands on the
+ * same backend session. A `Queryable` backed by a pool (each `query()` call
+ * free to grab a different connection) breaks both guarantees silently,
+ * the same trap `migrate()` already carries. Callers on `postgres.js` get
+ * one connection via `sql.reserve()`; `src/test/db.ts` shows the pattern.
+ */
+export interface Queryable {
+    query<T extends Record<string, unknown>>(text: string, values?: unknown[]): Promise<T[]>;
+}

package/dist/db.js

@@ -0,0 +1 @@
+export {};

package/dist/http.d.ts

@@ -10,6 +10,10 @@ export interface FetchInit {
     readonly method?: string;
     readonly headers?: Readonly<Record<string, string>>;
     readonly body?: string;
+    /** Aborts the request past a deadline -- every adapter request carries one,
+     * via `AbortSignal.timeout(...)` (see each adapter's `timeoutMs` option).
+     * Optional so a hand-written fake `fetch` in a test can ignore it. */
+    readonly signal?: AbortSignal;
 }
 export interface FetchResponseLike {
     readonly ok: boolean;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, Money, NormalizedWebhookEvent, NormalizedWebhookEventType, PaymentResult, PaymentStatus, RecurringAgreementResult, RecurringAgreementStatus, RefundInput, RefundResult, } from './types.js';
+export type { CancelPaymentInput, CancelRecurringChargeInput, CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, Money, NormalizedWebhookEvent, NormalizedWebhookEventType, PaymentResult, PaymentStatus, RecurringAgreementResult, RecurringAgreementStatus, RefundInput, RefundResult, StopRecurringAgreementInput, UpdateRecurringAgreementInput, } from './types.js';
 export { PaymentProviderError, WebhookVerificationError } from './types.js';
 export type { PaymentProvider } from './provider.js';
 export type { FetchInit, FetchLike, FetchResponseLike } from './http.js';
@@ -6,3 +6,7 @@ export type { StripeProviderOptions, StripeWebhookOptions } from './stripe.js';
 export { createStripeProvider, verifyStripeWebhook } from './stripe.js';
 export type { VippsProviderOptions, VippsWebhookHeaders, VippsWebhookOptions, } from './vipps.js';
 export { createVippsProvider, verifyVippsWebhook } from './vipps.js';
+export type { Queryable } from './db.js';
+export { migrate } from './migrate.js';
+export type { AppliedWebhookEvent, CreateOrGetAgreementInput, CreateOrGetChargeInput, PaymentAgreement, PaymentCharge, } from './store.js';
+export { applyWebhookEvent, createOrGetAgreement, createOrGetCharge, getAgreementByExternalReference, getAgreementById, getChargeByExternalReference, getChargeById, PaymentStoreError, refreshAgreementStatus, } from './store.js';

package/dist/index.js

@@ -1,3 +1,5 @@
 export { PaymentProviderError, WebhookVerificationError } from './types.js';
 export { createStripeProvider, verifyStripeWebhook } from './stripe.js';
 export { createVippsProvider, verifyVippsWebhook } from './vipps.js';
+export { migrate } from './migrate.js';
+export { applyWebhookEvent, createOrGetAgreement, createOrGetCharge, getAgreementByExternalReference, getAgreementById, getChargeByExternalReference, getChargeById, PaymentStoreError, refreshAgreementStatus, } from './store.js';

package/dist/migrate.d.ts

@@ -0,0 +1,12 @@
+import type { Queryable } from './db.js';
+/**
+ * Applies every migration this package ships that `payments_migrations`
+ * does not yet record, in file order, one transaction per file. Idempotent:
+ * a second call applies nothing and returns `[]`.
+ *
+ * `db` must be a single connection, not a pool -- a manual `begin`/`commit`
+ * issued as separate `query()` calls only wraps the statements between them
+ * when every call lands on the same session. `src/test/db.ts` gives this a
+ * dedicated connection for that reason.
+ */
+export declare function migrate(db: Queryable): Promise<string[]>;

package/dist/migrate.js

@@ -0,0 +1,88 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+const MIGRATIONS_DIR = join(here, 'migrations');
+const TABLE_SQL = `create table if not exists payments_migrations (
+  name text primary key,
+  applied_at timestamptz not null default now()
+)`;
+/**
+ * One migration file's statements: `--` line comments stripped, then split
+ * on `;` -- except inside a `$$...$$` (or `$tag$...$tag$`) dollar-quoted
+ * block, which is treated as opaque. Copied from `@wtfalch/ledger`'s (and
+ * `@wtfalch/billing`'s) `migrate.ts`, which fixed the same gap in
+ * package-template's own `packages/widget` toy splitter. This still assumes
+ * no string literal contains `--` or a stray, unmatched `$`.
+ */
+function statements(sql) {
+    const withoutComments = sql
+        .split('\n')
+        .map((line) => {
+        const index = line.indexOf('--');
+        return index === -1 ? line : line.slice(0, index);
+    })
+        .join('\n');
+    const parts = [];
+    let current = '';
+    let dollarTag = null;
+    let i = 0;
+    while (i < withoutComments.length) {
+        const tagMatch = /^\$[A-Za-z_]*\$/.exec(withoutComments.slice(i));
+        if (tagMatch) {
+            const tag = tagMatch[0];
+            current += tag;
+            i += tag.length;
+            dollarTag = dollarTag === null ? tag : dollarTag === tag ? null : dollarTag;
+            continue;
+        }
+        const ch = withoutComments[i];
+        if (ch === ';' && dollarTag === null) {
+            parts.push(current);
+            current = '';
+            i += 1;
+            continue;
+        }
+        current += ch;
+        i += 1;
+    }
+    if (current.trim().length > 0)
+        parts.push(current);
+    return parts.map((statement) => statement.trim()).filter((statement) => statement.length > 0);
+}
+/**
+ * Applies every migration this package ships that `payments_migrations`
+ * does not yet record, in file order, one transaction per file. Idempotent:
+ * a second call applies nothing and returns `[]`.
+ *
+ * `db` must be a single connection, not a pool -- a manual `begin`/`commit`
+ * issued as separate `query()` calls only wraps the statements between them
+ * when every call lands on the same session. `src/test/db.ts` gives this a
+ * dedicated connection for that reason.
+ */
+export async function migrate(db) {
+    await db.query(TABLE_SQL);
+    const applied = new Set((await db.query('select name from payments_migrations')).map((row) => row.name));
+    const files = readdirSync(MIGRATIONS_DIR)
+        .filter((name) => name.endsWith('.sql'))
+        .sort();
+    const ran = [];
+    for (const file of files) {
+        if (applied.has(file))
+            continue;
+        const sql = readFileSync(join(MIGRATIONS_DIR, file), 'utf8');
+        await db.query('begin');
+        try {
+            for (const statement of statements(sql))
+                await db.query(statement);
+            await db.query('insert into payments_migrations (name) values ($1)', [file]);
+            await db.query('commit');
+        }
+        catch (error) {
+            await db.query('rollback');
+            throw error;
+        }
+        ran.push(file);
+    }
+    return ran;
+}

package/dist/migrations/0001_payments.sql

@@ -0,0 +1,75 @@
+-- @wtfalch/payments: provider-neutral state for a recurring payment
+-- agreement and the charges made against it. One caller (Archon's billing,
+-- today; any other host tomorrow) creates and reads these rows through
+-- store.ts, never SQL of its own -- see docs/adr/0006-payment-store.md for
+-- why this exists (payments v1 shipped with none, docs/adr/0002).
+--
+-- Provider-neutral by design: `provider` is a value, not a table split, so
+-- Stripe, Vipps and a later MobilePay/Stripe-adjacent provider share one
+-- store and one caller-facing shape. Money is integer minor units
+-- (`Money.value` in types.ts), matching the wire format both adapters
+-- already speak -- unlike @wtfalch/ledger/@wtfalch/billing's micros, there
+-- is no larger-than-int4 range to worry about here (a subscription price
+-- never approaches 21 million currency units), so `integer` is enough and,
+-- unlike `numeric`, both PGlite and postgres.js already agree on returning
+-- it as a plain JS `number` -- matching `Money.value: number` with no
+-- driver-specific parsing in store.ts.
+--
+-- Applied by the host's own migrate script after copying this file into its
+-- migrations directory; never edited there. A host without one can instead
+-- apply this package's own migrate() against any Queryable, which is what
+-- src/test/db.ts and src/migrate.ts do.
+
+CREATE TABLE payment_agreements (
+  id uuid PRIMARY KEY,
+  provider text NOT NULL CHECK (provider IN ('stripe', 'vipps')),
+  -- The provider's own id for this agreement (Vipps: agreementId; Stripe:
+  -- the SetupIntent id). Unique per provider, not globally: Stripe and
+  -- Vipps mint ids from unrelated namespaces, so only the pair identifies
+  -- one real agreement.
+  provider_agreement_id text NOT NULL,
+  -- The caller's own key for this agreement, e.g. a billing subscription id.
+  -- Globally unique: it is how create-or-get finds "the same request retried"
+  -- before ever looking at the provider.
+  external_reference text NOT NULL,
+  status text NOT NULL CHECK (status IN ('pending', 'active', 'stopped', 'expired')),
+  confirmation_url text,
+  -- The agreement's price ceiling: the fixed amount for a LEGACY-pricing
+  -- agreement, or the payer-accepted suggestedMaxAmount for a VARIABLE one
+  -- (CreateRecurringAgreementInput's own doc comment). Every charge against
+  -- this agreement must fit under it -- the provider enforces that itself,
+  -- this column is this store's own record of what the payer agreed to.
+  max_amount_minor integer NOT NULL CHECK (max_amount_minor > 0),
+  currency text NOT NULL CHECK (currency ~ '^[A-Z]{3}$'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (provider, provider_agreement_id),
+  UNIQUE (external_reference)
+);
+
+CREATE TABLE payment_charges (
+  id uuid PRIMARY KEY,
+  provider text NOT NULL CHECK (provider IN ('stripe', 'vipps')),
+  agreement_id uuid NOT NULL REFERENCES payment_agreements (id),
+  -- The provider's own id for this charge (Vipps: chargeId; Stripe: the
+  -- PaymentIntent id created off-session against the agreement's saved
+  -- payment method). Unique per provider, same reasoning as the agreement's.
+  provider_charge_id text NOT NULL,
+  -- The caller's own key for this charge, e.g. a billing charge id.
+  external_reference text NOT NULL,
+  status text NOT NULL CHECK (
+    status IN (
+      'pending', 'requires_action', 'authorized', 'captured',
+      'partially_refunded', 'refunded', 'canceled', 'failed'
+    )
+  ),
+  amount_minor integer NOT NULL CHECK (amount_minor > 0),
+  currency text NOT NULL CHECK (currency ~ '^[A-Z]{3}$'),
+  due_date date,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (provider, provider_charge_id),
+  UNIQUE (external_reference)
+);
+
+CREATE INDEX payment_charges_agreement_id_idx ON payment_charges (agreement_id);

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-import type { CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, PaymentResult, RecurringAgreementResult, RefundInput, RefundResult } from './types.js';
+import type { CancelPaymentInput, CancelRecurringChargeInput, CapturePaymentInput, ChargeRecurringAgreementInput, CreatePaymentInput, CreateRecurringAgreementInput, PaymentResult, RecurringAgreementResult, RefundInput, RefundResult, StopRecurringAgreementInput, UpdateRecurringAgreementInput } from './types.js';
 /**
  * One shape, two adapters (`createStripeProvider`, `createVippsProvider`).
  * Webhook verification is deliberately not a method here: it needs no
@@ -12,6 +12,46 @@ export interface PaymentProvider {
     createPayment(input: CreatePaymentInput): Promise<PaymentResult>;
     capturePayment(providerReference: string, input?: CapturePaymentInput): Promise<PaymentResult>;
     refundPayment(providerReference: string, input?: RefundInput): Promise<RefundResult>;
+    /** Cancels a reserved, uncaptured payment (Vipps: `POST
+     * /epayment/v1/payments/{reference}/cancel`; Stripe: `POST
+     * /payment_intents/{id}/cancel`) -- a payment this store has not yet
+     * captured, left otherwise for the payer to see until it expires. Throws
+     * `PaymentProviderError` if the payment is not in a cancelable state
+     * (already captured, refunded, or already canceled). */
+    cancelPayment(providerReference: string, input?: CancelPaymentInput): Promise<PaymentResult>;
     createRecurringAgreement(input: CreateRecurringAgreementInput): Promise<RecurringAgreementResult>;
     chargeRecurringAgreement(agreementReference: string, input: ChargeRecurringAgreementInput): Promise<PaymentResult>;
+    /** The agreement's current status, read fresh from the provider -- what
+     * `store.ts`'s `refreshAgreementStatus` calls after creating an agreement,
+     * since neither adapter's create call itself learns of a payer's later
+     * approval/rejection (that arrives by webhook, or by polling this). */
+    getRecurringAgreement(agreementReference: string): Promise<RecurringAgreementResult>;
+    /** Stops the agreement (Vipps: `PATCH /recurring/v3/agreements/{id}`,
+     * `status: STOPPED`, idempotent -- stopping an already-stopped agreement
+     * is a no-op; Stripe: cancelling the SetupIntent that backs this
+     * adapter's agreement, `POST /setup_intents/{id}/cancel`). A caller that
+     * also tracks this agreement in `store.ts` should follow this with
+     * `refreshAgreementStatus` (or let the resulting webhook --
+     * `agreement.stopped` -- reach `applyWebhookEvent`) to persist the
+     * transition; this call only reaches the provider. */
+    stopRecurringAgreement(agreementReference: string, input?: StopRecurringAgreementInput): Promise<RecurringAgreementResult>;
+    /** Changes the agreement's price (Vipps: the same `PATCH
+     * .../agreements/{id}` as `stopRecurringAgreement`, with `pricing.amount`;
+     * Stripe: updates the SetupIntent's own `metadata[amount]`, kept in sync
+     * for symmetry with Vipps -- see `UpdateRecurringAgreementInput`'s doc
+     * comment). Required so a later `chargeRecurringAgreement` above the
+     * agreement's old amount is not refused by the provider. */
+    updateRecurringAgreement(agreementReference: string, input: UpdateRecurringAgreementInput): Promise<RecurringAgreementResult>;
+    /** Cancels a pending/reserved recurring charge that has not yet been
+     * captured -- e.g. one created for a billing period that is then credited
+     * before it settles (Vipps: `DELETE
+     * /recurring/v3/agreements/{agreementId}/charges/{chargeId}`, permitted
+     * for a PENDING/DUE/RESERVED charge; Stripe: the charge is a PaymentIntent
+     * -- see `chargeRecurringAgreement`'s doc comment -- so this is the same
+     * PaymentIntent cancel `cancelPayment` makes). Neither vendor's response
+     * gives a body worth normalizing (Vipps: 202/204, no body; Stripe's body
+     * is discarded for symmetry) -- the caller learns the resulting status the
+     * same way `chargeRecurringAgreement`'s caller already does, via a webhook
+     * (`charge.canceled` / `payment.cancelled`) reaching `applyWebhookEvent`. */
+    cancelRecurringCharge(agreementReference: string, chargeReference: string, input?: CancelRecurringChargeInput): Promise<void>;
 }

package/dist/store.d.ts

@@ -0,0 +1,181 @@
+import type { Queryable } from './db.js';
+import type { PaymentProvider } from './provider.js';
+import type { Money, NormalizedWebhookEvent, PaymentStatus, RecurringAgreementStatus } from './types.js';
+/**
+ * Provider-neutral store for a recurring payment agreement and the charges
+ * made against it -- one `payment_agreements` row per agreement, one
+ * `payment_charges` row per charge, `provider` a value on both rather than a
+ * table per provider. See docs/adr/0006-payment-store.md for why this
+ * exists (v1 shipped none: docs/adr/0002).
+ *
+ * Every mutating function here takes a single-connection `Queryable` (see
+ * `db.ts`'s doc comment) and issues its own `begin` / `pg_advisory_xact_lock`
+ * / `commit`, exactly like `migrate.ts`'s transaction-per-file discipline.
+ * The lock is what makes create-or-get safe under two callers racing the
+ * same `externalReference`: it serializes them onto one connection's
+ * transaction for the check, the provider call, and the insert together,
+ * so the loser sees the winner's committed row before ever calling the
+ * provider, and only the winner calls it at all. This does mean the
+ * connection (and the lock) stays held for the duration of one provider
+ * HTTP round trip -- deliberate, not an oversight: correctness (never
+ * double-creating an agreement/charge at the provider) is worth more here
+ * than one connection's throughput. A host running this in a pool must give
+ * that connection more room than its adapter's own request timeout
+ * (`VippsProviderOptions.timeoutMs` / equivalent), or a slow provider
+ * response can trip the pool's own idle-in-transaction guard first.
+ */
+/** A store operation refused, or found nothing to act on. Distinct from
+ * `PaymentProviderError` (a provider API call itself failed) and
+ * `WebhookVerificationError` (a webhook signature did not verify) -- this is
+ * the store's own precondition, checked before any provider call is made.
+ *
+ * `mismatched_retry`: an `externalReference` that already has a row was
+ * called again with materially different terms (amount/currency/agreement)
+ * -- refused rather than silently returning the first call's row, since a
+ * caller retrying with corrected terms (e.g. a fixed pricing bug) must not
+ * get back stale data with no indication anything is wrong.
+ *
+ * `provider_id_conflict`: the provider returned an agreement/charge id that
+ * already belongs to a *different* `externalReference` for the same
+ * provider -- a provider-side bug or an idempotency-key collision, surfaced
+ * as this typed error rather than a raw Postgres unique-violation. */
+export declare class PaymentStoreError extends Error {
+    readonly code: 'not_found' | 'agreement_not_active' | 'invalid_request' | 'mismatched_retry' | 'provider_id_conflict';
+    constructor(code: PaymentStoreError['code'], message: string);
+}
+export interface PaymentAgreement {
+    readonly id: string;
+    readonly provider: 'stripe' | 'vipps';
+    readonly providerAgreementId: string;
+    readonly externalReference: string;
+    readonly status: RecurringAgreementStatus;
+    readonly confirmationUrl: string | null;
+    /** The fixed price (LEGACY) or payer-accepted cap (VARIABLE) this
+     * agreement was created with -- see the migration's own doc comment. */
+    readonly maxAmountMinor: number;
+    readonly currency: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+export interface PaymentCharge {
+    readonly id: string;
+    readonly provider: 'stripe' | 'vipps';
+    readonly agreementId: string;
+    readonly providerChargeId: string;
+    readonly externalReference: string;
+    readonly status: PaymentStatus;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly dueDate: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+export interface CreateOrGetAgreementInput {
+    readonly externalReference: string;
+    readonly amount: Money;
+    readonly productName: string;
+    readonly returnUrl: string;
+    readonly managementUrl?: string;
+    readonly interval?: {
+        readonly unit: 'day' | 'week' | 'month';
+        readonly count: number;
+    };
+    readonly variablePricing?: {
+        readonly suggestedMaxAmount: number;
+    };
+}
+/**
+ * Finds the agreement for `input.externalReference`, creating it at the
+ * provider if this is the first call for that reference. Concurrency-safe
+ * under two callers racing the same `externalReference` on separate
+ * connections: `pg_advisory_xact_lock(1, hashtext(...))` serializes them,
+ * so the loser's check sees the winner's committed row and never calls the
+ * provider at all (see this module's doc comment).
+ */
+export declare function createOrGetAgreement(db: Queryable, provider: PaymentProvider, input: CreateOrGetAgreementInput): Promise<PaymentAgreement>;
+export interface CreateOrGetChargeInput {
+    /** The internal `payment_agreements.id` (not the provider's own id) this
+     * charge is against. Must already be `active`. */
+    readonly agreementId: string;
+    readonly externalReference: string;
+    readonly amount: Money;
+    readonly description: string;
+    /** ISO date (YYYY-MM-DD). Vipps requires at least one day ahead; Stripe ignores it. */
+    readonly dueDate?: string;
+}
+/**
+ * Finds the charge for `input.externalReference`, creating it at the
+ * provider (against `input.agreementId`) if this is the first call for that
+ * reference. Refuses with `PaymentStoreError('agreement_not_active', ...)`
+ * unless the agreement is `active` -- an agreement the payer has not yet
+ * approved, or one that has stopped or expired, has nothing to charge
+ * against. Same concurrency-safety shape as `createOrGetAgreement`, keyed
+ * on `externalReference` under lock namespace `2` (a charge and an
+ * agreement that happen to share a caller-chosen reference string never
+ * contend for the same lock).
+ */
+export declare function createOrGetCharge(db: Queryable, provider: PaymentProvider, input: CreateOrGetChargeInput): Promise<PaymentCharge>;
+export declare function getAgreementById(db: Queryable, id: string): Promise<PaymentAgreement | null>;
+export declare function getAgreementByExternalReference(db: Queryable, externalReference: string): Promise<PaymentAgreement | null>;
+export declare function getChargeById(db: Queryable, id: string): Promise<PaymentCharge | null>;
+export declare function getChargeByExternalReference(db: Queryable, externalReference: string): Promise<PaymentCharge | null>;
+/**
+ * Re-reads `agreementId`'s status from the provider (`getRecurringAgreement`)
+ * and persists it if it is a forward transition (`AGREEMENT_ALLOWED_PREDECESSORS`,
+ * same table `applyWebhookEvent` uses) from what is stored -- a `stopped`/
+ * `expired` agreement never reverts, even if the provider's own read races a
+ * webhook that already moved it on, or a bug reports a status that would
+ * regress it. No advisory lock: unlike create-or-get, there is no "only one
+ * caller may act" requirement here -- `getRecurringAgreement` is a GET,
+ * calling it twice concurrently is harmless -- but the write itself is still
+ * atomic (a `FOR UPDATE`-gated conditional `UPDATE`, like `transitionAgreement`),
+ * so two concurrent refreshes can't race each other into an inconsistent
+ * `updated_at`/`confirmation_url` pairing either.
+ */
+export declare function refreshAgreementStatus(db: Queryable, provider: PaymentProvider, agreementId: string): Promise<PaymentAgreement>;
+export interface AppliedWebhookEvent {
+    /** Which table (if either) the event matched a row in. `'none'` when
+     * neither `event.paymentReference` nor `event.agreementReference` named a
+     * row this store holds -- not an error, since a webhook may be about a
+     * one-off payment this store never tracked, or may arrive before the
+     * `createOrGetCharge`/`createOrGetAgreement` call that would have created
+     * the row it is about (the caller decides whether to retry later). */
+    readonly matched: 'agreement' | 'charge' | 'none';
+    /** False when the matched row's status already equalled what this event
+     * implies (an ordinary retried delivery), or when the transition was
+     * refused as stale (`ignored: 'stale'`) -- either way, no write happened
+     * and a caller may safely ignore both. */
+    readonly changed: boolean;
+    /** Set only when `changed` is false because the event's implied status is
+     * not a forward transition (`CHARGE_ALLOWED_PREDECESSORS`/
+     * `AGREEMENT_ALLOWED_PREDECESSORS`) from the row's current status -- a
+     * delayed, out-of-order delivery arriving after a newer event already
+     * moved the row on, or an attempt to leave a terminal status
+     * (refunded/canceled/failed; stopped/expired). The row returned is
+     * whatever is currently stored, unchanged. */
+    readonly ignored?: 'stale';
+    readonly agreement?: PaymentAgreement;
+    readonly charge?: PaymentCharge;
+    readonly previousStatus?: string;
+}
+/**
+ * Applies one normalized webhook event to whichever row it is about,
+ * idempotently and monotonically: a delivery retried with the same event
+ * body updates nothing the second time (`changed: false`), and an event
+ * whose implied status is not a forward transition from what is currently
+ * stored is refused as stale (`changed: false, ignored: 'stale'`) rather
+ * than applied -- see `CHARGE_ALLOWED_PREDECESSORS`'s doc comment for why a
+ * webhook transport's redelivery-without-ordering guarantee makes this
+ * necessary, not merely defensive. A caller may safely act on every
+ * `changed: true` result (e.g. a captured charge triggering an invoice)
+ * without its own separate de-duplication or sequencing, including under
+ * two concurrent deliveries of the same event (`transitionCharge`'s doc
+ * comment).
+ *
+ * Charge events are checked before agreement events: `event.paymentReference`
+ * (a charge id) is more specific than `event.agreementReference`, and the
+ * two are mutually exclusive per event in practice (an event about a charge
+ * always carries a payment/charge id; an event about the agreement alone
+ * never does -- see each adapter's webhook parsing).
+ */
+export declare function applyWebhookEvent(db: Queryable, event: NormalizedWebhookEvent): Promise<AppliedWebhookEvent>;