@wtfalch/payments 0.2.0 → 0.4.0

package/dist/vipps.js

@@ -5,22 +5,47 @@ import { PaymentProviderError, WebhookVerificationError, } from './types.js';
  * REST APIs -- no Vipps SDK (there is no single official Node one). See
  * docs/adr/0003-plain-http-no-provider-sdks.md.
  *
- * Sources (fetched 2026-09-23, primary docs, no live calls):
+ * Sources (fetched 2026-09-23/24, primary docs, no live calls):
  *   - https://developer.vippsmobilepay.com/api/epayment/ (create, capture, cancel, refund)
- *   - https://developer.vippsmobilepay.com/api/recurring/ (agreements, charges)
+ *   - https://developer.vippsmobilepay.com/api/recurring/ (agreements, charges, status enum)
  *   - https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/request-authentication/
+ *   - https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events/ (event catalogue)
+ *   - https://developer.vippsmobilepay.com/docs/knowledge-base/across-borders/ (Nordic markets)
+ *   - https://developer.vippsmobilepay.com/docs/APIs/recurring-api/recurring-api-guide/
  *
- * Two things v1 deliberately leaves to the caller, recorded here and in the
- * ledger's Fog rather than guessed at:
- *   - the OAuth access token (`POST /accesstoken/get`): this adapter takes
- *     an already-valid `accessToken` and never fetches or refreshes one
- *     itself, the same "caller resolves the credential" shape as `stripe.ts`.
- *   - the exact `state` enum on a payment/capture/refund response: the
- *     fetched docs were not fully explicit about it, so `derivePaymentStatus`
- *     below falls back to the `aggregate.*Amount` fields, which the docs did
- *     confirm, whenever `state` is absent or unrecognised.
+ * Re-fetched 2026-09-28 (still primary docs, no live calls) for
+ * `stopRecurringAgreement`/`updateRecurringAgreement` (`PATCH
+ * /recurring/v3/agreements/{id}`), `cancelRecurringCharge` (`DELETE
+ * /recurring/v3/agreements/{id}/charges/{chargeId}`) and `cancelPayment`
+ * (`POST /epayment/v1/payments/{reference}/cancel`) -- same two URLs above.
+ *
+ * One Recurring/ePayment API serves all three Nordic markets (see
+ * docs/adr/0006-payment-store.md's "MobilePay" section and this package's
+ * README, "MobilePay (Denmark, Finland)"): same base URL, same headers, same
+ * request/response shapes. What differs is the sales unit's own currency
+ * (NOK/DKK/EUR) and per-market amount ceiling, both the caller's concern
+ * (`Money.currency`, `CreateRecurringAgreementInput.amount`), never this
+ * adapter's -- `createVippsProvider` needs no market-specific option.
+ *
+ * `docs/adr/0007-vipps-access-token-caching.md` covers this adapter now
+ * fetching and caching its own OAuth access token (`POST /accesstoken/get`),
+ * superseding v1's "the caller resolves it" stance (see that ADR for why
+ * this does not force the service shape -- docs/adr/0001).
+ *
+ * Still not confirmed from primary docs: the exact `state` enum on an
+ * ePayment payment/capture/refund response (`derivePaymentStatus` below
+ * falls back to the `aggregate.*Amount` fields whenever `state` is absent
+ * or unrecognised), and the exact field carrying a Recurring webhook
+ * event's own id (`normalizeRecurringEvent` below synthesizes one the same
+ * way the ePayment side already did, for the same reason).
  */
 import { hmacSha256Base64, safeEqual, sha256Base64 } from './webhook-crypto.js';
+const AGREEMENT_STATUS = {
+    PENDING: 'pending',
+    ACTIVE: 'active',
+    STOPPED: 'stopped',
+    EXPIRED: 'expired',
+};
 const PAYMENT_STATE = {
     CREATED: 'pending',
     AUTHORIZED: 'authorized',
@@ -80,14 +105,80 @@ function tomorrowIsoDate() {
     return d.toISOString().slice(0, 10);
 }
 export function createVippsProvider(options) {
+    if (!options.accessToken && !(options.clientId && options.clientSecret)) {
+        throw new PaymentProviderError('vipps', 'createVippsProvider needs either accessToken, or both clientId and clientSecret');
+    }
     const fetchImpl = options.fetch ?? defaultFetch();
     const baseUrl = options.baseUrl ?? 'https://api.vipps.no';
-    function headers(idempotencyKey) {
+    const tokenUrl = options.tokenUrl ?? 'https://api.vipps.no/accesstoken/get';
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const refreshMarginMs = (options.tokenRefreshMarginSeconds ?? 60) * 1000;
+    // Token cache, scoped to this provider instance (one per `subscriptionKey`
+    // + `merchantSerialNumber` pair, ordinarily). `inFlight` is the one thing
+    // that makes this concurrency-safe: N callers racing `resolveAccessToken`
+    // while the cache is empty or expired share the same `POST
+    // /accesstoken/get` promise instead of each firing their own -- assigned
+    // before any `await`, so there is no gap between "check the cache" and
+    // "start a refresh" for a second caller to land in. Cleared in `finally`,
+    // on success and on failure alike: a failed refresh must not wedge every
+    // later call behind a promise that has already rejected.
+    let cached = null;
+    let inFlight = null;
+    async function fetchAccessToken() {
+        const response = await fetchImpl(tokenUrl, {
+            method: 'POST',
+            headers: {
+                client_id: options.clientId,
+                client_secret: options.clientSecret,
+                'Ocp-Apim-Subscription-Key': options.subscriptionKey,
+                'Merchant-Serial-Number': options.merchantSerialNumber,
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const parsed = await response.json();
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `access token request failed: HTTP ${response.status}`, {
+                status: response.status,
+                raw: parsed,
+            });
+        }
+        const body = parsed;
+        if (!body.access_token) {
+            throw new PaymentProviderError('vipps', 'access token response has no "access_token" field', {
+                raw: parsed,
+            });
+        }
+        const expiresInSeconds = Number(body.expires_in ?? 0);
+        cached = {
+            token: body.access_token,
+            // A missing/unparsable expires_in caches nothing usable: expiresAtMs
+            // stays in the past, so the very next call refreshes again rather
+            // than reusing a token whose real lifetime is unknown.
+            expiresAtMs: Number.isFinite(expiresInSeconds) && expiresInSeconds > 0
+                ? Date.now() + expiresInSeconds * 1000
+                : 0,
+        };
+        return cached.token;
+    }
+    async function resolveAccessToken() {
+        if (options.accessToken)
+            return options.accessToken; // v1 shape: caller-managed, never cached/refreshed here
+        if (cached && cached.expiresAtMs - refreshMarginMs > Date.now())
+            return cached.token;
+        if (!inFlight) {
+            inFlight = fetchAccessToken().finally(() => {
+                inFlight = null;
+            });
+        }
+        return inFlight;
+    }
+    async function resolveHeaders(idempotencyKey) {
+        const token = await resolveAccessToken();
         const h = {
             'Content-Type': 'application/json',
             'Ocp-Apim-Subscription-Key': options.subscriptionKey,
             'Merchant-Serial-Number': options.merchantSerialNumber,
-            Authorization: `Bearer ${options.accessToken}`,
+            Authorization: `Bearer ${token}`,
         };
         if (idempotencyKey)
             h['Idempotency-Key'] = idempotencyKey;
@@ -96,8 +187,9 @@ export function createVippsProvider(options) {
     async function post(path, body, idempotencyKey) {
         const response = await fetchImpl(`${baseUrl}${path}`, {
             method: 'POST',
-            headers: headers(idempotencyKey),
+            headers: await resolveHeaders(idempotencyKey),
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
         });
         const parsed = await response.json();
         if (!response.ok) {
@@ -111,7 +203,8 @@ export function createVippsProvider(options) {
     async function get(path) {
         const response = await fetchImpl(`${baseUrl}${path}`, {
             method: 'GET',
-            headers: headers(undefined),
+            headers: await resolveHeaders(undefined),
+            signal: AbortSignal.timeout(timeoutMs),
         });
         const parsed = await response.json();
         if (!response.ok) {
@@ -122,6 +215,68 @@ export function createVippsProvider(options) {
         }
         return parsed;
     }
+    /** Reads any error body a non-2xx response carries, but never throws on a
+     * body that fails to parse (used by `patch`/`del` below, whose *success*
+     * responses are documented as empty -- see each call site). */
+    async function readErrorBody(response) {
+        try {
+            return await response.json();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** `PATCH /recurring/v3/agreements/{id}` (`stopRecurringAgreement`,
+     * `updateRecurringAgreement`) documents a `204 No Content` success
+     * response -- https://developer.vippsmobilepay.com/api/recurring/
+     * (fetched 2026-09-28) -- so this never calls `response.json()` on the
+     * success path, unlike `post`/`get` above. */
+    async function patch(path, body, idempotencyKey) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'PATCH',
+            headers: await resolveHeaders(idempotencyKey),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: await readErrorBody(response),
+            });
+        }
+    }
+    /** `DELETE /recurring/v3/agreements/{id}/charges/{chargeId}`
+     * (`cancelRecurringCharge`) documents a `202 Accepted`/`204 No Content`
+     * success response with no body -- same source and fetch date as `patch`
+     * above. */
+    async function del(path, idempotencyKey) {
+        const response = await fetchImpl(`${baseUrl}${path}`, {
+            method: 'DELETE',
+            headers: await resolveHeaders(idempotencyKey),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new PaymentProviderError('vipps', `HTTP ${response.status}`, {
+                status: response.status,
+                raw: await readErrorBody(response),
+            });
+        }
+    }
+    /** Shared by `getRecurringAgreement` and the two `PATCH .../agreements`
+     * calls (`stopRecurringAgreement`, `updateRecurringAgreement`), neither of
+     * which gets its resulting status back in its own (empty) response body --
+     * both re-read the agreement the same way `getRecurringAgreement` always
+     * has. */
+    async function fetchAgreement(agreementReference) {
+        const agreement = await get(`/recurring/v3/agreements/${agreementReference}`);
+        return {
+            provider: 'vipps',
+            agreementReference: agreement.id,
+            status: (agreement.status ? AGREEMENT_STATUS[agreement.status] : undefined) ?? 'pending',
+            confirmationUrl: agreement.vippsConfirmationUrl,
+            raw: agreement,
+        };
+    }
     return {
         name: 'vipps',
         async createPayment(input) {
@@ -186,6 +341,39 @@ export function createVippsProvider(options) {
                 raw: payment,
             };
         },
+        async cancelPayment(providerReference, input = {}) {
+            // POST /epayment/v1/payments/{reference}/cancel --
+            // https://developer.vippsmobilepay.com/api/epayment/ (fetched
+            // 2026-09-28). Cancels a reserved, uncaptured payment; Vipps does not
+            // document an Idempotency-Key requirement here (unlike capture/refund),
+            // but this adapter still sends one, consistent with every other
+            // mutating call in this package.
+            const payment = await post(`/epayment/v1/payments/${providerReference}/cancel`, {}, input.idempotencyKey ?? `cnc:${providerReference}`);
+            // Same integrity check as capturePayment/refundPayment.
+            if (payment.reference !== providerReference) {
+                throw new PaymentProviderError('vipps', `cancel response reference "${payment.reference}" does not match the requested payment "${providerReference}"`, { raw: payment });
+            }
+            // The cancel response does not always carry an amount (neither
+            // `amount` nor `aggregate.authorizedAmount`) -- when it does not,
+            // re-read the payment rather than assume Vipps left it as-is. If the
+            // re-read also has no amount, a caller must never read a made-up
+            // amount as if Vipps reported it: a defaulted 0/NOK is simply wrong
+            // for a EUR or DKK merchant. Throw instead, with a distinct `code` so
+            // a caller can tell "cancelled, amount unknown, re-read later" apart
+            // from a plain cancel failure.
+            const resolved = (payment.amount ?? payment.aggregate?.authorizedAmount)
+                ? payment
+                : await get(`/epayment/v1/payments/${providerReference}`);
+            const knownAmount = resolved.amount ?? resolved.aggregate?.authorizedAmount;
+            if (!knownAmount) {
+                throw new PaymentProviderError('vipps', `cancel response for payment ${providerReference} carries no amount to report, even after re-reading the payment`, { raw: resolved, code: 'cancel_amount_unknown' });
+            }
+            const fallback = {
+                value: knownAmount.value,
+                currency: knownAmount.currency.toUpperCase(),
+            };
+            return toPaymentResult(resolved, fallback);
+        },
         async createRecurringAgreement(input) {
             // pricing.type LEGACY (fixed amount) vs VARIABLE (suggestedMaxAmount,
             // no fixed amount): https://developer.vippsmobilepay.com/api/recurring/
@@ -247,6 +435,74 @@ export function createVippsProvider(options) {
                 raw: charge,
             };
         },
+        async getRecurringAgreement(agreementReference) {
+            return fetchAgreement(agreementReference);
+        },
+        async stopRecurringAgreement(agreementReference, input = {}) {
+            // PATCH /recurring/v3/agreements/{id}, { status: 'STOPPED' } --
+            // https://developer.vippsmobilepay.com/api/recurring/ (fetched
+            // 2026-09-28). Idempotent on Vipps' side: stopping an already-STOPPED
+            // agreement returns 204 with no further effect. The response has no
+            // body, so this reads the resulting status back the same way
+            // `getRecurringAgreement` always has.
+            await patch(`/recurring/v3/agreements/${agreementReference}`, { status: 'STOPPED' }, input.idempotencyKey ?? `stop:${agreementReference}`);
+            return fetchAgreement(agreementReference);
+        },
+        async updateRecurringAgreement(agreementReference, input) {
+            // Same PATCH endpoint as stopRecurringAgreement. The update body's
+            // `pricing` is `UpdateAgreementPricingRequest` in Vipps' own Recurring
+            // v3 OpenAPI spec (recurring-swagger-id.yaml, "Recurring Payments
+            // Merchant API" 3.2.3, fetched 2026-09-29 from
+            // https://developer.vippsmobilepay.com/redocusaurus/recurring-swagger-id.yaml,
+            // linked from https://developer.vippsmobilepay.com/api/recurring/):
+            //
+            //   PricingUpdateRequest:
+            //     title: UpdateAgreementPricingRequest
+            //     type: object
+            //     properties:
+            //       amount: { type: integer, ... }
+            //       suggestedMaxAmount: { type: integer, ... }
+            //
+            // No `currency`, no `type` -- unlike `PricingRequestV3` (create), which
+            // requires both. An agreement's currency is fixed at creation and
+            // cannot be changed through this endpoint, so this checks the
+            // agreement's current currency (from a GET, `pricing.currency` on
+            // `AgreementResponseV3`) before sending anything, and refuses a
+            // currency change with a clear `PaymentProviderError` instead of
+            // sending a field Vipps' spec does not list and getting back a 400.
+            // This is the LEGACY (fixed-price) `amount` field; a VARIABLE
+            // agreement's `suggestedMaxAmount` cap is a separate, payer-driven
+            // value this method does not touch -- see
+            // `UpdateRecurringAgreementInput`'s doc comment. Vipps itself refuses
+            // (400) a price change on a stopped agreement; this adapter does not
+            // duplicate that check. It does refuse anything but a LEGACY
+            // agreement below, because Vipps applies `pricing.amount` only to a
+            // LEGACY one -- a PATCH against a VARIABLE or FLEXIBLE agreement
+            // returns 204 and changes nothing, which would otherwise read to this
+            // method's caller as a silent no-op success.
+            const nextCurrency = input.amount.currency.toUpperCase();
+            const current = await get(`/recurring/v3/agreements/${agreementReference}`);
+            if (current.pricing?.type !== 'LEGACY') {
+                throw new PaymentProviderError('vipps', `agreement ${agreementReference} has pricing.type "${current.pricing?.type ?? 'unknown'}"; updateRecurringAgreement's amount can only be updated on a LEGACY agreement`, { raw: current });
+            }
+            const currentCurrency = current.pricing?.currency?.toUpperCase();
+            if (currentCurrency && currentCurrency !== nextCurrency) {
+                throw new PaymentProviderError('vipps', `agreement ${agreementReference} is priced in ${currentCurrency}; updateRecurringAgreement cannot change its currency to ${nextCurrency} (Vipps’ update-agreement pricing body takes amount only)`, { raw: current });
+            }
+            await patch(`/recurring/v3/agreements/${agreementReference}`, { pricing: { amount: input.amount.value } }, input.idempotencyKey ?? `upd:${agreementReference}:${input.amount.value}:${nextCurrency}`);
+            return fetchAgreement(agreementReference);
+        },
+        async cancelRecurringCharge(agreementReference, chargeReference, input = {}) {
+            // DELETE /recurring/v3/agreements/{agreementId}/charges/{chargeId} --
+            // https://developer.vippsmobilepay.com/api/recurring/ (fetched
+            // 2026-09-28). Permitted for a PENDING/DUE/RESERVED charge; a
+            // PARTIALLY_CAPTURED charge has its remaining funds released back to
+            // the payer. Returns 202/204 with no body -- the caller learns the
+            // outcome via the resulting `recurring.charge-canceled.v1` webhook
+            // (`charge.canceled`, already wired to `applyWebhookEvent`), the same
+            // way a created charge's own outcome already arrives.
+            await del(`/recurring/v3/agreements/${agreementReference}/charges/${chargeReference}`, input.idempotencyKey ?? `dch:${chargeReference}`);
+        },
     };
 }
 const WEBHOOK_EVENT_NAME = {
@@ -259,6 +515,42 @@ const WEBHOOK_EVENT_NAME = {
     EXPIRED: 'payment.expired',
     ABORTED: 'payment.cancelled',
 };
+/** The Recurring API's own webhook event catalogue -- a different namespace
+ * from the ePayment `name` field `WEBHOOK_EVENT_NAME` above maps.
+ * https://developer.vippsmobilepay.com/docs/APIs/webhooks-api/events/
+ * (fetched 2026-09-24 via a documentation-summarizing tool, the same
+ * caveat docs/adr/0004 already carries for the ePayment side -- not
+ * checked against one real signed Vipps delivery). */
+const RECURRING_EVENT_TYPE = {
+    'recurring.agreement-activated.v1': 'agreement.activated',
+    'recurring.agreement-rejected.v1': 'agreement.rejected',
+    'recurring.agreement-stopped.v1': 'agreement.stopped',
+    'recurring.agreement-expired.v1': 'agreement.expired',
+    'recurring.charge-reserved.v1': 'charge.reserved',
+    'recurring.charge-captured.v1': 'charge.captured',
+    'recurring.charge-canceled.v1': 'charge.canceled',
+    'recurring.charge-refunded.v1': 'charge.refunded',
+    'recurring.charge-failed.v1': 'charge.failed',
+    'recurring.charge-creation-failed.v1': 'charge.failed',
+};
+/** A Recurring event names one agreement always, and a charge only for a
+ * `charge.*` type -- `paymentReference` (which `store.ts` matches against
+ * `payment_charges.provider_charge_id`) is empty for an `agreement.*` event,
+ * which has none. No documented event id field (unlike the ePayment side's
+ * `idempotencyKey`), so `eventId` is synthesized from what is documented,
+ * the same fallback shape the ePayment path below already uses. */
+function normalizeRecurringEvent(event) {
+    const amount = event.amountCaptured ?? event.amountCanceled ?? event.amountRefunded ?? event.amount;
+    return {
+        provider: 'vipps',
+        type: RECURRING_EVENT_TYPE[event.eventType] ?? 'unknown',
+        eventId: `${event.agreementId ?? 'unknown'}:${event.chargeId ?? ''}:${event.eventType}:${event.occurred ?? ''}`,
+        paymentReference: event.chargeId ?? '',
+        agreementReference: event.agreementId,
+        amount: amount ? { value: amount.value, currency: amount.currency.toUpperCase() } : undefined,
+        raw: event,
+    };
+}
 /**
  * Verifies a Vipps MobilePay webhook request, by hand, against the
  * Azure-API-Management-style HMAC scheme documented at
@@ -314,6 +606,12 @@ export function verifyVippsWebhook(rawBody, requestHeaders, webhookSecret, metho
     catch {
         throw new WebhookVerificationError('vipps', 'payload is not valid JSON');
     }
+    // Two payload shapes share this endpoint's signature scheme: ePayment's
+    // (`name`/`success`, handled below) and the Recurring API's (`eventType`,
+    // agreement/charge events -- see normalizeRecurringEvent's doc comment).
+    if (event.eventType) {
+        return normalizeRecurringEvent(event);
+    }
     const mapped = event.name ? WEBHOOK_EVENT_NAME[event.name] : undefined;
     const type = event.success === false ? 'payment.failed' : (mapped ?? 'unknown');
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wtfalch/payments",
-  "version": "0.2.0",
-  "description": "One PaymentProvider interface -- create a payment, capture, refund, set up and charge a recurring agreement, verify a webhook -- over Stripe and Vipps MobilePay. Holds no card data.",
+  "version": "0.4.0",
+  "description": "One PaymentProvider interface -- create a payment, capture, refund, set up and charge a recurring agreement, verify a webhook -- over Stripe and Vipps MobilePay, plus a provider-neutral Postgres store for agreements and charges. Holds no card data.",
   "repository": {
     "type": "git",
     "url": "https://github.com/wtfalch/payments",
@@ -9,16 +9,13 @@
   },
   "license": "MIT",
   "type": "module",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -28,14 +25,17 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-migrations.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm build"
+  },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "postgres": "^3.4.5",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
   }
-}
+}