Runtime

@paykernel/core is designed to run on Node ≥ 18, Bun ≥ 1, Deno, and Cloudflare Workers using Web APIs (fetch, TextEncoder, AbortController, Web Crypto) and pure portable crypto helpers. Production sources and the published dist/index.js entry do not static-import node:crypto, node:buffer, or other Node builtins.

Related: Webhooks, Composition, @paykernel/core.

PaymentRuntime

Injectable, secret-free dependency bag for portable HTTP and crypto:

import {
  createPaymentRuntime,
  createPaymentClient,
  stripeGateway,
  type PaymentRuntime,
} from "@paykernel/core";

declare const customFetch: typeof fetch;

const runtime: PaymentRuntime = createPaymentRuntime({
  fetch: customFetch,
  clock: { now: () => new Date(0), nowMs: () => 0 },
});

const client = createPaymentClient({
  gateways: {
    stripe: stripeGateway({ secretKey: process.env.STRIPE_SECRET_KEY! }),
  },
  runtime: {
    fetch: customFetch,
    clock: runtime.clock,
  },
});

resolveDefaultCrypto() prefers globalThis.crypto. If getRandomValues is missing, it throws. It does not fall back to Math.random. Auto idempotency keys and runtime UUIDs must be cryptographically strong.

On hosts without Web Crypto, inject an explicit CryptoProvider:

const client = createPaymentClient({
  gateways: { /* … */ },
  runtime: {
    crypto: {
      randomUUID: () => crypto.randomUUID(),
      getRandomValues: (a) => crypto.getRandomValues(a),
    },
  },
});

Do not ship a Math.random UUID path for lease tokens, idempotency keys, or any security-sensitive randomness.

exactOptionalPropertyTypes

Omit optional keys instead of assigning undefined:

declare const gateways: Parameters<typeof createPaymentClient>[0]["gateways"];
declare const mockFetch: typeof fetch;

// Good
createPaymentClient({ gateways, runtime: { fetch: mockFetch } });

// Avoid
createPaymentClient({
  gateways,
  runtime: { fetch: mockFetch, clock: undefined },
});

GatewayContext

GatewayContext extends PaymentRuntime and adds client-owned fields:

createDefaultGatewayContext({ runtime?, fetch?, crypto?, clock?, … }) builds defaults via createPaymentRuntime. Nested runtime is merged under top-level PaymentRuntime fields. Optional telemetry is attached only when provided. Built-in factories (stripeGateway, …) forward context runtime into gateway constructors so HTTP uses the injected fetch.

Telemetry

PaymentRuntime itself is fetch / crypto / clock / randomUUID only — it does not carry a telemetry bag. Optional diagnostics live on GatewayContext.telemetry and on structured OperationContext builders.

import {
  createDefaultGatewayContext,
  createRedactingTelemetrySink,
  createOperationContext,
  finalizeOperationContext,
  operationContextToTelemetryData,
  systemClock,
} from "@paykernel/core";

const telemetry = createRedactingTelemetrySink({
  emit(event, data) {
    console.info(event, data);
  },
});

const ctx = createDefaultGatewayContext({
  telemetry,
  clock: systemClock,
});

const started = createOperationContext({
  operationId: ctx.randomUUID(),
  gateway: "stripe",
  operationType: "payment.create",
});
const startMs = ctx.clock.nowMs();
// … work …
const finished = finalizeOperationContext(started, {
  durationMs: Math.max(0, ctx.clock.nowMs() - startMs),
  normalizedOutcome: "succeeded",
  providerRequestId: "req_abc",
});
ctx.telemetry?.emit?.(
  "payment.operation",
  operationContextToTelemetryData(finished),
);

Portable crypto (sync webhooks)

Pure implementations (no node:crypto, no npm crypto deps) keep verifyWebhook synchronous on Workers / Deno / Bun / Node:

Strategy: pure sync HMAC/SHA for sync verifyWebhook. Optional Web Crypto subtle remains on CryptoProvider for future async paths. hashWebhookPayload uses portable sha256Hex (redacted canonical JSON).

import { createPaymentClient, stripeGateway } from "@paykernel/core";

const secret = process.env.STRIPE_WEBHOOK_SECRET!;
const client = createPaymentClient({
  gateways: {
    stripe: stripeGateway({
      secretKey: process.env.STRIPE_SECRET_KEY!,
      webhookSecret: secret,
    }),
  },
});

const rawBody = /* exact request body string */;
const sig = request.headers.get("stripe-signature") ?? undefined;
const ok = client.gateway("stripe").verifyWebhook(rawBody, sig);

Prefer handleWebhook on the client for production verify + parse.

HTTP timeouts and AbortSignal

Built-in gateways cancel in-flight provider HTTP with a timeout signal from createTimeoutSignal (always AbortController + setTimeout so clear() cancels; unref() when the host timer supports it). AbortSignal.timeout is not used — its timer cannot be cancelled.

• Config knobs: per-gateway timeoutMs (defaults are provider-specific).
• Timeouts surface as NetworkError. For money mutations they are indeterminate — do not treat as definite failure. See Outcomes.
• Injected runtime.fetch must honor RequestInit.signal for timeouts to work.

Every network operation accepts optional signal?: AbortSignal on params (CreatePaymentParams, CaptureParams, RefundParams, VoidParams, GetPaymentParams, checkout session params, Moyasar STC OTP confirm).

import { money } from "@paykernel/core";

const controller = new AbortController();
const payment = client.createPayment({
  amount: money("10.00", "USD"),
  currency: "USD",
  callbackUrl: "https://example.com/cb",
  signal: controller.signal,
});
controller.abort();

Gateways merge caller signal + timeout on every HTTP call. Caller abort before submit → PaymentAbortedError. Caller abort after a mutating POST maps to NetworkError with afterProviderSubmit: true (same uncertainty class as a timeout). Timeout → NetworkError. Never convert uncertain transport outcomes into definite payment failure.

Injecting custom fetch / clock / crypto

Mock fetch in tests

import {
  createPaymentClient,
  stripeGateway,
  createDefaultGatewayContext,
} from "@paykernel/core";

const fetchCalls: string[] = [];
const mockFetch: typeof fetch = async (input, init) => {
  fetchCalls.push(String(input));
  return new Response(JSON.stringify({ id: "pi_test", status: "succeeded" }), {
    status: 200,
    headers: { "content-type": "application/json" },
  });
};

const client = createPaymentClient({
  gateways: {
    stripe: stripeGateway({ secretKey: "sk_test_…" }),
  },
  runtime: { fetch: mockFetch },
});

const ctx = createDefaultGatewayContext({ fetch: mockFetch });
void ctx;

Defaults delegate to live globalThis.fetch (not a frozen snapshot), so tests that only patch globalThis.fetch after construction still work. Prefer explicit runtime.fetch for deterministic harnesses.

Fake clock (webhook skew)

const fixedMs = Date.parse("2020-01-01T00:00:00.000Z");
const client = createPaymentClient({
  gateways: {
    stripe: stripeGateway({
      secretKey: "sk_test_…",
      webhookSecret: "whsec_…",
    }),
  },
  runtime: {
    clock: {
      now: () => new Date(fixedMs),
      nowMs: () => fixedMs,
    },
  },
});
// Stripe 5-minute signature window uses clock.nowMs()

For richer clocks in app tests, @paykernel/testkit exposes createFakeClock (testkit-only; core does not depend on testkit).

Custom crypto / UUID

createPaymentRuntime({
  randomUUID: () => "00000000-0000-4000-8000-000000000001",
  crypto: {
    randomUUID: () => "00000000-0000-4000-8000-000000000001",
    getRandomValues: (arr) => {
      /* fill arr */ return arr;
    },
  },
});

Supported runtimes

package.json engines: "node": ">=18", "bun": ">=1.0.0". Single ESM export entry (portable). CommonJS require() is not supported.

Portability CI (bun run check:runtime-portability) fails if node: / bun: / cloudflare: appear in production sources or dist/**/*.js for PORTABLE_PACKAGE_DIRS: packages/core, webhooks, reconciliation, observability, routing, store-contracts, sql-foundation, testkit, gateway-tap, gateway-myfatoorah, gateway-hesabe, integration-http, integration-hono, integration-elysia, integration-cloudflare-workers. (integration-express and the store adapters are not in that list.)

What is not supported

Design rules

1. No secrets on PaymentRuntime / GatewayContext.
2. Prefer Web APIs (fetch, TextEncoder, AbortController, Web Crypto).
3. Production packages/core/src must not static-import node: builtins (tests may).
4. Global fetch remains the default — injecting runtime is opt-in.
5. Gateways use injected this.fetch when context/runtime is available.
6. Never convert uncertain transport outcomes into definite payment failure.
7. verifyWebhook stays synchronous where possible.
8. exactOptionalPropertyTypes: omit optional keys; do not assign undefined.
9. Optional telemetry is additive only; prefer redacting sinks.
10. Core has no @opentelemetry/* dependency; observability is optional and external (@paykernel/opentelemetry).