@wtfalch/payments 0.2.0 → 0.3.0

package/dist/vipps.js

@@ -5,22 +5,41 @@ 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.
+ * 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 +99,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 +181,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 +197,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) {
@@ -247,6 +334,16 @@ export function createVippsProvider(options) {
                 raw: charge,
             };
         },
+        async getRecurringAgreement(agreementReference) {
+            const agreement = await get(`/recurring/v3/agreements/${agreementReference}`);
+            return {
+                provider: 'vipps',
+                agreementReference: agreement.agreementId,
+                status: (agreement.status ? AGREEMENT_STATUS[agreement.status] : undefined) ?? 'pending',
+                confirmationUrl: agreement.vippsConfirmationUrl,
+                raw: agreement,
+            };
+        },
     };
 }
 const WEBHOOK_EVENT_NAME = {
@@ -259,6 +356,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 +447,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.3.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"
   }
-}
+}