@wtfalch/payments 0.2.0 → 0.3.0

package/dist/store.js

@@ -0,0 +1,534 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * 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 class PaymentStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(`payments store: ${message}`);
+        this.name = 'PaymentStoreError';
+        this.code = code;
+    }
+}
+/** Postgres' SQLSTATE for a unique-violation, surfaced identically by both
+ * `postgres.js` and PGlite (both speak the real wire protocol). */
+function isUniqueViolation(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === '23505';
+}
+function toDate(value) {
+    return value instanceof Date ? value : new Date(value);
+}
+function toIsoDate(value) {
+    if (value === null)
+        return null;
+    return value instanceof Date ? value.toISOString().slice(0, 10) : value;
+}
+function agreementFromRow(row) {
+    return {
+        id: row.id,
+        provider: row.provider,
+        providerAgreementId: row.provider_agreement_id,
+        externalReference: row.external_reference,
+        status: row.status,
+        confirmationUrl: row.confirmation_url,
+        maxAmountMinor: row.max_amount_minor,
+        currency: row.currency,
+        createdAt: toDate(row.created_at),
+        updatedAt: toDate(row.updated_at),
+    };
+}
+function chargeFromRow(row) {
+    return {
+        id: row.id,
+        provider: row.provider,
+        agreementId: row.agreement_id,
+        providerChargeId: row.provider_charge_id,
+        externalReference: row.external_reference,
+        status: row.status,
+        amountMinor: row.amount_minor,
+        currency: row.currency,
+        dueDate: toIsoDate(row.due_date),
+        createdAt: toDate(row.created_at),
+        updatedAt: toDate(row.updated_at),
+    };
+}
+function assertMoney(amount) {
+    if (!Number.isInteger(amount.value) || amount.value <= 0) {
+        throw new PaymentStoreError('invalid_request', `amount.value must be a positive integer (minor units), got ${amount.value}`);
+    }
+    if (!/^[A-Za-z]{3}$/.test(amount.currency)) {
+        throw new PaymentStoreError('invalid_request', `amount.currency must be a 3-letter ISO 4217 code, got ${JSON.stringify(amount.currency)}`);
+    }
+}
+function assertReference(externalReference) {
+    if (externalReference.length < 1 || externalReference.length > 500) {
+        throw new PaymentStoreError('invalid_request', 'externalReference must be between 1 and 500 characters');
+    }
+}
+/** The provider's idempotency key for a create-or-get call, namespaced by
+ * kind so an agreement and a charge that happen to share a caller-chosen
+ * `externalReference` string never collide on the provider's own
+ * idempotency store. */
+function idempotencyKeyFor(kind, externalReference) {
+    return `payments:${kind}:${externalReference}`;
+}
+/**
+ * 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 async function createOrGetAgreement(db, provider, input) {
+    assertReference(input.externalReference);
+    assertMoney(input.amount);
+    await db.query('begin');
+    try {
+        await db.query('select pg_advisory_xact_lock(1, hashtext($1))', [input.externalReference]);
+        const [existing] = await db.query('select * from payment_agreements where external_reference = $1', [input.externalReference]);
+        if (existing) {
+            const expectedMaxAmountMinor = input.variablePricing?.suggestedMaxAmount ?? input.amount.value;
+            const expectedCurrency = input.amount.currency.toUpperCase();
+            if (existing.max_amount_minor !== expectedMaxAmountMinor ||
+                existing.currency !== expectedCurrency) {
+                throw new PaymentStoreError('mismatched_retry', `externalReference "${input.externalReference}" already has an agreement (maxAmountMinor=${existing.max_amount_minor}, currency=${existing.currency}); this call asked for maxAmountMinor=${expectedMaxAmountMinor}, currency=${expectedCurrency}`);
+            }
+            await db.query('commit');
+            return agreementFromRow(existing);
+        }
+        const created = await provider.createRecurringAgreement({
+            reference: input.externalReference,
+            amount: input.amount,
+            productName: input.productName,
+            returnUrl: input.returnUrl,
+            managementUrl: input.managementUrl,
+            interval: input.interval,
+            variablePricing: input.variablePricing,
+            idempotencyKey: idempotencyKeyFor('agreement', input.externalReference),
+        });
+        const maxAmountMinor = input.variablePricing?.suggestedMaxAmount ?? input.amount.value;
+        const currency = input.amount.currency.toUpperCase();
+        let inserted;
+        try {
+            [inserted] = await db.query(`INSERT INTO payment_agreements
+           (id, provider, provider_agreement_id, external_reference, status, confirmation_url, max_amount_minor, currency)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+         ON CONFLICT (external_reference) DO NOTHING
+         RETURNING *`, [
+                randomUUID(),
+                provider.name,
+                created.agreementReference,
+                input.externalReference,
+                created.status,
+                created.confirmationUrl ?? null,
+                maxAmountMinor,
+                currency,
+            ]);
+        }
+        catch (error) {
+            if (isUniqueViolation(error)) {
+                throw new PaymentStoreError('provider_id_conflict', `provider "${provider.name}" agreement id "${created.agreementReference}" already belongs to a different externalReference`);
+            }
+            throw error;
+        }
+        if (inserted) {
+            await db.query('commit');
+            return agreementFromRow(inserted);
+        }
+        // Lost the race despite the advisory lock (a caller that skipped it, or
+        // a lock-key collision from `hashtext`) -- defense in depth, the same
+        // ON CONFLICT + read-back pattern `@wtfalch/billing`'s createCharge uses
+        // under its own row lock.
+        const [winner] = await db.query('select * from payment_agreements where external_reference = $1', [input.externalReference]);
+        await db.query('commit');
+        if (!winner) {
+            throw new Error('createOrGetAgreement: insert returned no row and no row to read back');
+        }
+        return agreementFromRow(winner);
+    }
+    catch (error) {
+        await db.query('rollback');
+        throw error;
+    }
+}
+/**
+ * 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 async function createOrGetCharge(db, provider, input) {
+    assertReference(input.externalReference);
+    assertMoney(input.amount);
+    await db.query('begin');
+    try {
+        await db.query('select pg_advisory_xact_lock(2, hashtext($1))', [input.externalReference]);
+        const [existing] = await db.query('select * from payment_charges where external_reference = $1', [input.externalReference]);
+        if (existing) {
+            const expectedCurrency = input.amount.currency.toUpperCase();
+            if (existing.agreement_id !== input.agreementId ||
+                existing.amount_minor !== input.amount.value ||
+                existing.currency !== expectedCurrency) {
+                throw new PaymentStoreError('mismatched_retry', `externalReference "${input.externalReference}" already has a charge (agreementId=${existing.agreement_id}, amountMinor=${existing.amount_minor}, currency=${existing.currency}); this call asked for agreementId=${input.agreementId}, amountMinor=${input.amount.value}, currency=${expectedCurrency}`);
+            }
+            await db.query('commit');
+            return chargeFromRow(existing);
+        }
+        const [agreement] = await db.query('select * from payment_agreements where id = $1 for update', [input.agreementId]);
+        if (!agreement) {
+            throw new PaymentStoreError('not_found', `agreement ${input.agreementId} not found`);
+        }
+        if (agreement.status !== 'active') {
+            throw new PaymentStoreError('agreement_not_active', `agreement ${input.agreementId} is "${agreement.status}", not "active"`);
+        }
+        const chargeCurrency = input.amount.currency.toUpperCase();
+        if (chargeCurrency !== agreement.currency) {
+            // Both adapters' chargeRecurringAgreement ignore a caller-supplied
+            // currency and always charge in the agreement's own currency (see
+            // vipps.ts's module doc comment) -- a mismatch here would silently
+            // store the wrong currency against a charge that was, in reality,
+            // billed in the agreement's currency.
+            throw new PaymentStoreError('invalid_request', `amount.currency "${chargeCurrency}" does not match agreement ${input.agreementId}'s currency "${agreement.currency}"`);
+        }
+        const charged = await provider.chargeRecurringAgreement(agreement.provider_agreement_id, {
+            amount: input.amount,
+            description: input.description,
+            dueDate: input.dueDate,
+            idempotencyKey: idempotencyKeyFor('charge', input.externalReference),
+        });
+        const currency = input.amount.currency.toUpperCase();
+        let inserted;
+        try {
+            [inserted] = await db.query(`INSERT INTO payment_charges
+           (id, provider, agreement_id, provider_charge_id, external_reference, status, amount_minor, currency, due_date)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         ON CONFLICT (external_reference) DO NOTHING
+         RETURNING *`, [
+                randomUUID(),
+                provider.name,
+                input.agreementId,
+                charged.providerReference,
+                input.externalReference,
+                charged.status,
+                input.amount.value,
+                currency,
+                input.dueDate ?? null,
+            ]);
+        }
+        catch (error) {
+            if (isUniqueViolation(error)) {
+                throw new PaymentStoreError('provider_id_conflict', `provider "${provider.name}" charge id "${charged.providerReference}" already belongs to a different externalReference`);
+            }
+            throw error;
+        }
+        if (inserted) {
+            await db.query('commit');
+            return chargeFromRow(inserted);
+        }
+        const [winner] = await db.query('select * from payment_charges where external_reference = $1', [input.externalReference]);
+        await db.query('commit');
+        if (!winner) {
+            throw new Error('createOrGetCharge: insert returned no row and no row to read back');
+        }
+        return chargeFromRow(winner);
+    }
+    catch (error) {
+        await db.query('rollback');
+        throw error;
+    }
+}
+export async function getAgreementById(db, id) {
+    const [row] = await db.query('select * from payment_agreements where id = $1', [
+        id,
+    ]);
+    return row ? agreementFromRow(row) : null;
+}
+export async function getAgreementByExternalReference(db, externalReference) {
+    const [row] = await db.query('select * from payment_agreements where external_reference = $1', [externalReference]);
+    return row ? agreementFromRow(row) : null;
+}
+export async function getChargeById(db, id) {
+    const [row] = await db.query('select * from payment_charges where id = $1', [id]);
+    return row ? chargeFromRow(row) : null;
+}
+export async function getChargeByExternalReference(db, externalReference) {
+    const [row] = await db.query('select * from payment_charges where external_reference = $1', [externalReference]);
+    return row ? chargeFromRow(row) : null;
+}
+/**
+ * The forward-transition graph both `applyWebhookEvent` and
+ * `refreshAgreementStatus` gate every write through: `ALLOWED_PREDECESSORS[X]`
+ * lists every status a row may currently hold for a write *to* `X` to be
+ * accepted -- always including `X` itself (an idempotent no-op redelivery
+ * or re-read is always "allowed"). A status with no entry pointing *to* it
+ * from anywhere else is terminal: `refunded`/`canceled`/`failed` for a
+ * charge, `stopped`/`expired` for an agreement never appear in any other
+ * status's list, so nothing can ever transition a row back out of them.
+ *
+ * This exists because a webhook transport is at-least-once and gives no
+ * ordering guarantee: a delayed, older event (e.g. `charge.reserved`,
+ * meaning "pending") can be redelivered *after* a newer one
+ * (`charge.captured`) already landed. Without this table, that stale
+ * delivery would move status backwards -- and a *second*, entirely normal
+ * redelivery of the original `captured` event would then see the row is no
+ * longer `captured` and report `changed: true` a second time, which is
+ * exactly the shape of bug that makes a caller invoicing on "changed &&
+ * captured" double-invoice. Comparing against `ALLOWED_PREDECESSORS` instead
+ * of a plain `!==` check is what keeps a redelivery-after-a-stale-write
+ * idempotent instead of a second "real" change.
+ */
+const CHARGE_ALLOWED_PREDECESSORS = {
+    pending: ['pending'],
+    requires_action: ['pending', 'requires_action'],
+    authorized: ['pending', 'requires_action', 'authorized'],
+    captured: ['pending', 'requires_action', 'authorized', 'captured'],
+    partially_refunded: ['captured', 'partially_refunded'],
+    refunded: ['captured', 'partially_refunded', 'refunded'],
+    canceled: ['pending', 'requires_action', 'authorized', 'canceled'],
+    failed: ['pending', 'requires_action', 'authorized', 'failed'],
+};
+const AGREEMENT_ALLOWED_PREDECESSORS = {
+    pending: ['pending'],
+    active: ['pending', 'active'],
+    stopped: ['pending', 'active', 'stopped'],
+    expired: ['pending', 'active', 'expired'],
+};
+/**
+ * Atomically reads `payment_charges`' current status and, only if it is one
+ * of `CHARGE_ALLOWED_PREDECESSORS[targetStatus]`, writes `targetStatus` --
+ * in one statement, so two concurrent deliveries of the same event can
+ * never both observe "not yet at the target" and both report a change: the
+ * `FOR UPDATE` inside the CTE serializes them onto the same row, and the
+ * loser re-evaluates its own `WHERE` against the winner's already-committed
+ * value.
+ */
+async function transitionCharge(db, providerName, providerChargeId, targetStatus) {
+    const predecessors = CHARGE_ALLOWED_PREDECESSORS[targetStatus];
+    const [updated] = await db.query(`WITH current AS (
+       SELECT status FROM payment_charges
+       WHERE provider = $1 AND provider_charge_id = $2
+       FOR UPDATE
+     )
+     UPDATE payment_charges c
+     SET status = $3,
+         updated_at = CASE WHEN current.status IS DISTINCT FROM $3 THEN now() ELSE c.updated_at END
+     FROM current
+     WHERE c.provider = $1 AND c.provider_charge_id = $2
+       AND current.status = ANY($4::text[])
+     RETURNING c.*, current.status AS previous_status`, [providerName, providerChargeId, targetStatus, predecessors]);
+    if (updated) {
+        return {
+            kind: 'applied',
+            row: updated,
+            previousStatus: updated.previous_status,
+            changed: updated.previous_status !== targetStatus,
+        };
+    }
+    const [row] = await db.query('select * from payment_charges where provider = $1 and provider_charge_id = $2', [providerName, providerChargeId]);
+    return row ? { kind: 'stale', row } : { kind: 'not_found' };
+}
+/** Same shape as `transitionCharge`, for `payment_agreements`. */
+async function transitionAgreement(db, providerName, providerAgreementId, targetStatus) {
+    const predecessors = AGREEMENT_ALLOWED_PREDECESSORS[targetStatus];
+    const [updated] = await db.query(`WITH current AS (
+       SELECT status FROM payment_agreements
+       WHERE provider = $1 AND provider_agreement_id = $2
+       FOR UPDATE
+     )
+     UPDATE payment_agreements a
+     SET status = $3,
+         updated_at = CASE WHEN current.status IS DISTINCT FROM $3 THEN now() ELSE a.updated_at END
+     FROM current
+     WHERE a.provider = $1 AND a.provider_agreement_id = $2
+       AND current.status = ANY($4::text[])
+     RETURNING a.*, current.status AS previous_status`, [providerName, providerAgreementId, targetStatus, predecessors]);
+    if (updated) {
+        return {
+            kind: 'applied',
+            row: updated,
+            previousStatus: updated.previous_status,
+            changed: updated.previous_status !== targetStatus,
+        };
+    }
+    const [row] = await db.query('select * from payment_agreements where provider = $1 and provider_agreement_id = $2', [providerName, providerAgreementId]);
+    return row ? { kind: 'stale', row } : { kind: 'not_found' };
+}
+/**
+ * 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 async function refreshAgreementStatus(db, provider, agreementId) {
+    const [existing] = await db.query('select * from payment_agreements where id = $1', [agreementId]);
+    if (!existing)
+        throw new PaymentStoreError('not_found', `agreement ${agreementId} not found`);
+    const fresh = await provider.getRecurringAgreement(existing.provider_agreement_id);
+    const predecessors = AGREEMENT_ALLOWED_PREDECESSORS[fresh.status];
+    const [updated] = await db.query(`WITH current AS (
+       SELECT status, confirmation_url FROM payment_agreements WHERE id = $1 FOR UPDATE
+     )
+     UPDATE payment_agreements a
+     SET status = $2,
+         confirmation_url = coalesce($3, a.confirmation_url),
+         updated_at = CASE
+           WHEN current.status IS DISTINCT FROM $2
+             OR current.confirmation_url IS DISTINCT FROM coalesce($3, current.confirmation_url)
+           THEN now() ELSE a.updated_at END
+     FROM current
+     WHERE a.id = $1 AND current.status = ANY($4::text[])
+     RETURNING a.*`, [agreementId, fresh.status, fresh.confirmationUrl ?? null, predecessors]);
+    if (updated)
+        return agreementFromRow(updated);
+    // Not a forward transition (or the provider's read raced a concurrent
+    // write past it) -- leave the row exactly as stored; terminal statuses
+    // never leave.
+    const [current] = await db.query('select * from payment_agreements where id = $1', [
+        agreementId,
+    ]);
+    if (!current)
+        throw new Error('refreshAgreementStatus: agreement disappeared mid-refresh');
+    return agreementFromRow(current);
+}
+/** What a webhook event, once matched to a row, means for that row's
+ * status. Deliberately provider-agnostic: Stripe's SetupIntent/PaymentIntent
+ * events and Vipps' Recurring events both normalize to these same type
+ * names (see stripe.ts's and vipps.ts's own `WEBHOOK_EVENT_TYPE`-shaped
+ * maps), so this store never branches on `event.provider`. An event type
+ * absent from a map (e.g. a one-off `payment.*` event with no agreement, or
+ * `unknown`) is simply not applied. */
+const CHARGE_STATUS_FROM_EVENT = {
+    'payment.created': 'pending',
+    'payment.authorized': 'authorized',
+    'payment.captured': 'captured',
+    'payment.refunded': 'refunded',
+    'payment.cancelled': 'canceled',
+    'payment.failed': 'failed',
+    'payment.expired': 'failed',
+    'charge.reserved': 'pending',
+    'charge.captured': 'captured',
+    'charge.canceled': 'canceled',
+    'charge.refunded': 'refunded',
+    'charge.failed': 'failed',
+};
+const AGREEMENT_STATUS_FROM_EVENT = {
+    'agreement.activated': 'active',
+    'agreement.rejected': 'stopped',
+    'agreement.stopped': 'stopped',
+    'agreement.expired': 'expired',
+};
+/**
+ * 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 async function applyWebhookEvent(db, event) {
+    const chargeStatus = CHARGE_STATUS_FROM_EVENT[event.type];
+    if (chargeStatus && event.paymentReference) {
+        const outcome = await transitionCharge(db, event.provider, event.paymentReference, chargeStatus);
+        if (outcome.kind === 'applied') {
+            return {
+                matched: 'charge',
+                changed: outcome.changed,
+                charge: chargeFromRow(outcome.row),
+                previousStatus: outcome.previousStatus,
+            };
+        }
+        if (outcome.kind === 'stale') {
+            return {
+                matched: 'charge',
+                changed: false,
+                ignored: 'stale',
+                charge: chargeFromRow(outcome.row),
+                previousStatus: outcome.row.status,
+            };
+        }
+        // 'not_found': this provider_charge_id names no charge this store
+        // tracks -- fall through in case it is instead an agreement event.
+    }
+    const agreementStatus = AGREEMENT_STATUS_FROM_EVENT[event.type];
+    if (agreementStatus && event.agreementReference) {
+        const outcome = await transitionAgreement(db, event.provider, event.agreementReference, agreementStatus);
+        if (outcome.kind === 'applied') {
+            return {
+                matched: 'agreement',
+                changed: outcome.changed,
+                agreement: agreementFromRow(outcome.row),
+                previousStatus: outcome.previousStatus,
+            };
+        }
+        if (outcome.kind === 'stale') {
+            return {
+                matched: 'agreement',
+                changed: false,
+                ignored: 'stale',
+                agreement: agreementFromRow(outcome.row),
+                previousStatus: outcome.row.status,
+            };
+        }
+    }
+    return { matched: 'none', changed: false };
+}

package/dist/stripe.js

@@ -202,6 +202,16 @@ export function createStripeProvider(options) {
             }, input.idempotencyKey);
             return toPaymentResult(pi);
         },
+        async getRecurringAgreement(agreementReference) {
+            const si = await get(`/setup_intents/${agreementReference}`);
+            return {
+                provider: 'stripe',
+                agreementReference: si.id,
+                status: SETUP_INTENT_STATUS[si.status] ?? 'pending',
+                clientSecret: si.client_secret,
+                raw: si,
+            };
+        },
     };
 }
 const WEBHOOK_EVENT_TYPE = {
@@ -213,6 +223,13 @@ const WEBHOOK_EVENT_TYPE = {
     'payment_intent.payment_failed': 'payment.failed',
     'charge.refunded': 'payment.refunded',
     'charge.refund.updated': 'payment.refunded',
+    // A SetupIntent is this adapter's recurring agreement (module doc
+    // comment): its own lifecycle events normalize to the same `agreement.*`
+    // names Vipps' Recurring API webhooks use, so `store.ts`'s
+    // `applyWebhookEvent` never branches on provider.
+    'setup_intent.succeeded': 'agreement.activated',
+    'setup_intent.canceled': 'agreement.stopped',
+    'setup_intent.setup_failed': 'agreement.rejected',
 };
 /**
  * Verifies a Stripe webhook's `Stripe-Signature` header against the raw
@@ -267,7 +284,13 @@ export function verifyStripeWebhook(rawBody, signatureHeader, webhookSecret, opt
         throw new WebhookVerificationError('stripe', 'payload is not valid JSON');
     }
     const object = event.data?.object;
-    const paymentReference = object?.payment_intent ?? object?.id ?? '';
+    // A `setup_intent.*` event is about the agreement itself, never a
+    // payment -- its object has neither a payment_intent nor anything this
+    // package would call a paymentReference. See `getRecurringAgreement`'s
+    // module doc comment and `WEBHOOK_EVENT_TYPE`'s `setup_intent.*` entries.
+    const isSetupIntentEvent = (event.type ?? '').startsWith('setup_intent.');
+    const paymentReference = isSetupIntentEvent ? '' : (object?.payment_intent ?? object?.id ?? '');
+    const agreementReference = isSetupIntentEvent ? object?.id : undefined;
     const amount = typeof object?.amount === 'number' && object.currency
         ? { value: object.amount, currency: object.currency.toUpperCase() }
         : undefined;
@@ -276,6 +299,7 @@ export function verifyStripeWebhook(rawBody, signatureHeader, webhookSecret, opt
         type: WEBHOOK_EVENT_TYPE[event.type ?? ''] ?? 'unknown',
         eventId: event.id ?? '',
         paymentReference,
+        agreementReference,
         amount,
         raw: event,
     };

package/dist/types.d.ts

@@ -116,15 +116,31 @@ export interface ChargeRecurringAgreementInput {
 }
 /** A closed set, plus `unknown`. A provider event type this package does not
  * yet recognise normalizes to `unknown` rather than throwing, so a new
- * Stripe or Vipps event is forward-compatible, not a crash. */
-export type NormalizedWebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.refunded' | 'payment.cancelled' | 'payment.failed' | 'payment.expired' | 'unknown';
+ * Stripe or Vipps event is forward-compatible, not a crash.
+ *
+ * `payment.*` is a one-off ePayment/PaymentIntent event (`createPayment`,
+ * `capturePayment`, `refundPayment`). `agreement.*` and `charge.*` are the
+ * recurring-agreement lifecycle `store.ts`'s `applyWebhookEvent` acts on --
+ * Vipps' own Recurring API webhook catalogue (`recurring.agreement-*.v1`,
+ * `recurring.charge-*.v1`); Stripe's SetupIntent events are normalized into
+ * the same `agreement.*` names (`succeeded`->`activated`,
+ * `canceled`->`stopped`, `setup_failed`->`rejected`) and its off-session
+ * PaymentIntent charge into the same `charge.*` names, so a caller of
+ * `applyWebhookEvent` never branches on provider. */
+export type NormalizedWebhookEventType = 'payment.created' | 'payment.authorized' | 'payment.captured' | 'payment.refunded' | 'payment.cancelled' | 'payment.failed' | 'payment.expired' | 'agreement.activated' | 'agreement.rejected' | 'agreement.stopped' | 'agreement.expired' | 'charge.reserved' | 'charge.captured' | 'charge.canceled' | 'charge.refunded' | 'charge.failed' | 'unknown';
 export interface NormalizedWebhookEvent {
     readonly provider: 'stripe' | 'vipps';
     readonly type: NormalizedWebhookEventType;
     /** The provider's own event id, for de-duplicating retried deliveries. */
     readonly eventId: string;
-    /** Matches `PaymentResult.providerReference` / the payment this event is about. */
+    /** Matches `PaymentResult.providerReference` -- the one-off payment or
+     * recurring charge this event is about. Empty string for an
+     * `agreement.*` event, which is about the agreement alone. */
     readonly paymentReference: string;
+    /** Matches `RecurringAgreementResult.agreementReference`. Present on every
+     * `agreement.*` and `charge.*` event; absent on a one-off `payment.*` event,
+     * which has no agreement. */
+    readonly agreementReference?: string;
     readonly amount?: Money;
     /** The provider's own event payload, for anything this shape does not carry. */
     readonly raw: unknown;

package/dist/vipps.d.ts

@@ -6,14 +6,37 @@ export interface VippsProviderOptions {
     readonly subscriptionKey: string;
     /** `Merchant-Serial-Number`: the sales unit's MSN. */
     readonly merchantSerialNumber: string;
-    /** A valid OAuth access token. The caller obtains and refreshes this
-     * (`POST /accesstoken/get`); this package never does, the same as it
-     * never resolves a Stripe secret key on its own -- see the module doc
-     * comment. */
-    readonly accessToken: string;
+    /**
+     * A valid OAuth access token, already fetched. Given this, the adapter
+     * never calls `POST /accesstoken/get` itself and never refreshes it --
+     * the caller must, on its own schedule. This is v1's shape (0.2.x and
+     * earlier), kept so an existing caller migrates by adding
+     * `clientId`/`clientSecret` on its own timeline rather than in lockstep
+     * with a version bump.
+     *
+     * Exactly one of `accessToken` or `clientId`+`clientSecret` must be given.
+     */
+    readonly accessToken?: string;
+    /** The sales unit's OAuth client id, for this adapter to fetch and cache
+     * its own access token. Requires `clientSecret`. See
+     * docs/adr/0007-vipps-access-token-caching.md. */
+    readonly clientId?: string;
+    /** The sales unit's OAuth client secret. Requires `clientId`. */
+    readonly clientSecret?: string;
+    /** Seconds of safety margin before a cached token's real expiry at which
+     * this adapter fetches a new one instead of reusing it, so a request that
+     * starts just under the deadline does not race the token's own expiry.
+     * Default: 60. */
+    readonly tokenRefreshMarginSeconds?: number;
     readonly fetch?: FetchLike;
     /** Override for testing. Defaults to `https://api.vipps.no`. */
     readonly baseUrl?: string;
+    /** Override for testing. Defaults to `https://api.vipps.no/accesstoken/get`. */
+    readonly tokenUrl?: string;
+    /** Aborts any request (including the token fetch) still pending after
+     * this many milliseconds, via `AbortSignal.timeout`. Default: 10 000
+     * (10s). A provider that never responds must not hang its caller forever. */
+    readonly timeoutMs?: number;
 }
 export declare function createVippsProvider(options: VippsProviderOptions): PaymentProvider;
 export interface VippsWebhookHeaders {