@fin-integrity/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fin-integrity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @fin-integrity/node
+
+**Reconciliation-as-you-code.** Capture your Stripe (and any processor) events _and_ your internal ledger entries from your backend, and fin·integrity continuously matches them — surfacing missing entries, duplicates, missing refunds, and amount/currency mismatches as incidents, in real time.
+
+Think **"Sentry for money movement"**: add a few lines, keep your own ledger, and catch every payment that doesn't reconcile before your customers, finance team, or auditors do.
+
+- 🪶 Tiny, zero-runtime-dependency, dual **ESM + CJS**, fully typed
+- 🔌 **Processor-agnostic** core (`processor.record` / `ledger.record`) with a Stripe adapter
+- 🧯 **Fail-open by design** — the SDK can never throw into or block your money path
+- ⚡ Async, batched, non-blocking capture with graceful serverless flush
+- 🔑 Server-side secret keys; you send transaction metadata, never card data
+
+> Status: early (`0.1.x`). The API surface below is stable; internals may change.
+
+## Install
+
+```bash
+npm install @fin-integrity/node
+# Stripe auto-instrumentation is an optional peer dependency:
+npm install stripe
+```
+
+## Quickstart
+
+```ts
+import Stripe from "stripe";
+import { init, instrumentStripe } from "@fin-integrity/node";
+
+const fi = init({ apiKey: process.env.FIN_INTEGRITY_KEY! });
+
+// 1) Auto-capture the processor side by wrapping your Stripe client
+const stripe = instrumentStripe(new Stripe(process.env.STRIPE_KEY!), fi);
+const charge = await stripe.charges.create({ amount: 4999, currency: "usd", metadata: { reference: "order_10432" } });
+
+// 2) Report the ledger side where you write to your own books
+fi.ledger.record({
+  type: "payment",
+  reference: "order_10432",           // the shared key both sides agree on
+  external_id: journalEntry.id,
+  amount: { minor: 4999, currency: "usd" },
+});
+
+// fin·integrity matches the two by `reference` and flags any mismatch.
+```
+
+That's it. Any processor works — for non-Stripe sources, capture the processor side explicitly:
+
+```ts
+fi.processor.record({
+  type: "payment",
+  source: "adyen",
+  reference: "order_10432",
+  external_id: "8536214598321",
+  amount: { minor: 4999, currency: "usd" },
+});
+```
+
+## The model: two sides, one reference
+
+fin·integrity reconciles two streams:
+
+| Side | What it is | You send it with |
+|---|---|---|
+| **processor** | The money actually moved (Stripe/Adyen/bank …) | `fi.processor.record(...)` (or `instrumentStripe`) |
+| **ledger** | Your internal books / system of record | `fi.ledger.record(...)` |
+
+Both sides carry a shared **`reference`** (an order id, invoice id, whatever both systems agree on). fin·integrity **matches on `reference` + `type`**, then **compares** `amount` and `currency` — so a wrong amount surfaces as an incident instead of silently failing to match.
+
+## Money
+
+Always integer **minor units** + an ISO-4217 currency code — never floats.
+
+```ts
+{ minor: 4999, currency: "usd" }   // $49.99
+{ minor: 1000, currency: "jpy" }   // ¥1000 (zero-decimal)
+{ minor: 10000, currency: "bhd", exponent: 3 } // 10.000 BHD
+```
+
+`minor` accepts a `number` or a `bigint` (for very large values). Non-integer amounts are rejected (routed to `onError`, never thrown).
+
+## API
+
+### `init(config?) → FinIntegrityClient`
+Creates the client and stores it as a module singleton (also returned).
+
+| Option | Default | Description |
+|---|---|---|
+| `apiKey` | `env FIN_INTEGRITY_KEY` | Secret key `fi_sk_live_…` / `fi_sk_test_…`. |
+| `endpoint` | hosted default | Ingest base URL. Point at your own for self-host/local. |
+| `environment` | `NODE_ENV` | Tag events with an environment. |
+| `idempotency` | `"deterministic"` | `"deterministic"` (content hash, retry-safe) or `"uuid"`. |
+| `batch` | `{ maxSize: 50, flushMs: 2000 }` | Flush on size **or** interval. |
+| `maxQueueSize` | `1000` | Bounded queue; oldest events drop first (counted + reported). |
+| `retries` | `3` | Network retry attempts (exp backoff; honors `Retry-After`). |
+| `sampleRate` | `1.0` | Keep everything by default — never silently drop money events. |
+| `beforeSend` | — | Mutate or drop (`return null`) each envelope, e.g. redact PII. |
+| `debug` | `false` | Log transport activity. |
+| `dryRun` | `false` | Build/validate but never hit the network; inspect via `inspect()`. |
+| `onError` | warns in debug | Called on any internal/transport error. The SDK never throws into your code. |
+
+### `fi.processor.record(input)` / `fi.ledger.record(input)`
+```ts
+interface RecordInput {
+  type: "payment" | "refund";
+  source?: string;              // e.g. "stripe", "adyen"; defaults per side
+  reference: string;            // shared cross-side key
+  external_id: string;          // this side's native id
+  amount: { minor: number | bigint; currency: string; exponent?: number };
+  occurred_at?: string | Date;  // defaults to now
+  status?: string;
+  direction?: "credit" | "debit";
+  metadata?: Record<string, unknown>;
+}
+```
+
+### `fi.capture(input & { side })`
+Low-level escape hatch used by the adapters — full control over `side`.
+
+### `instrumentStripe(stripe, fi) → stripe`
+Wraps the **exact Stripe instance you pass in** so `charges.create`, `paymentIntents.create`, and `refunds.create` are captured automatically. No global monkey-patching, so it's ESM/bundler-safe. Capture runs off the hot path and **never blocks or alters your Stripe call**. Set `metadata.reference` on your Stripe calls to control the reconciliation key.
+
+### `await fi.flush()` / `await fi.shutdown()`
+`flush()` sends everything queued now. `shutdown()` drains and stops the client. In **serverless**, flush before the function returns:
+
+```ts
+export const handler = async (event) => {
+  try { return await doWork(event); }
+  finally { await fi.flush(); }   // don't let the runtime freeze before the batch sends
+};
+```
+
+### `fi.inspect() → EventEnvelope[]`
+Returns captured envelopes (in `dryRun` or with a custom transport) — the easiest way to **unit-test** that your integration emits the right events, no HTTP mocking:
+
+```ts
+const fi = init({ dryRun: true });
+placeOrder();
+expect(fi.inspect()).toContainEqual(expect.objectContaining({ reference: "order_10432" }));
+```
+
+## Reliability & safety
+
+- **Fail-open:** every internal path is wrapped; SDK errors degrade to `onError` + a no-op. Your payment code is never affected.
+- **Bounded, observable:** the queue is capped (drop-oldest); dropped counts ride along on the next batch so loss is never silent.
+- **Idempotent:** each event carries an `Idempotency-Key`; retries never create duplicate rows. The default deterministic key means even a crash-then-retry collapses to one event.
+- **Backpressure-aware:** honors `429` + `Retry-After` instead of retry-storming.
+
+## Security & data
+
+Send **transaction metadata** — ids, amounts, currency, timestamps, status, your own `metadata`. **Do not send card numbers / PANs or secrets.** Use `beforeSend` to redact anything sensitive before it leaves your process. Keys are server-side secrets — never ship them to a browser.
+
+## Local development
+
+Point the SDK at a local ingest endpoint:
+
+```ts
+const fi = init({ apiKey: "fi_sk_test_…", endpoint: "http://localhost:3005" });
+```
+
+## License
+
+[MIT](./LICENSE) © fin-integrity

package/dist/index.cjs

@@ -0,0 +1,476 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigError: () => ConfigError,
+  FinIntegrityClient: () => FinIntegrityClient,
+  FinIntegrityError: () => FinIntegrityError,
+  RejectedEventsError: () => RejectedEventsError,
+  getClient: () => getClient,
+  init: () => init,
+  instrumentStripe: () => instrumentStripe
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/environment.ts
+var MAX_LEN = 64;
+var INVALID = /[\s/]/;
+function cleanEnvironment(raw) {
+  if (typeof raw !== "string") return void 0;
+  const v = raw.trim();
+  if (!v || v.length > MAX_LEN || INVALID.test(v) || v.toLowerCase() === "none") return void 0;
+  return v;
+}
+
+// src/errors.ts
+var FinIntegrityError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FinIntegrityError";
+  }
+};
+var ConfigError = class extends FinIntegrityError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+
+// src/idempotency.ts
+var import_node_crypto = require("crypto");
+function deterministicKey(e) {
+  const basis = [
+    e.source,
+    e.side,
+    e.external_id,
+    e.event_type,
+    // Environment is part of identity: the same external_id in staging vs
+    // production are distinct facts that must not collapse to one row.
+    e.environment ?? "",
+    // Mutable state. Absent fields collapse to "" so unused ones cost nothing.
+    e.status ?? "",
+    e.amount?.minor ?? "",
+    e.current_period_end ?? "",
+    e.arrival_at ?? ""
+  ].join(":");
+  return "fi_" + (0, import_node_crypto.createHash)("sha256").update(basis).digest("hex").slice(0, 40);
+}
+function uuidKey() {
+  return "fi_" + (0, import_node_crypto.randomUUID)();
+}
+
+// src/transport.ts
+var HttpTransport = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  async send(batch, meta) {
+    const url = this.opts.endpoint.replace(/\/+$/, "") + "/v1/events";
+    const body = JSON.stringify({ sent_at: (/* @__PURE__ */ new Date()).toISOString(), dropped: meta.dropped, events: batch });
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      try {
+        res = await fetch(url, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.opts.apiKey}`,
+            "idempotency-key": batch[0]?.idempotency_key ?? ""
+          },
+          body
+        });
+      } catch (netErr) {
+        if (attempt >= this.opts.retries) throw netErr;
+        await sleep(backoff(attempt));
+        continue;
+      }
+      if (res.ok) {
+        const rejected = await rejectedFrom(res);
+        if (rejected.length > 0) {
+          throw new RejectedEventsError(rejected, batch.length);
+        }
+        if (this.opts.debug) console.log(`[fin-integrity] delivered ${batch.length} event(s)`);
+        return;
+      }
+      if (res.status === 429 || res.status >= 500) {
+        if (attempt >= this.opts.retries) throw new Error(`fin-integrity ingest ${res.status}`);
+        const ra = Number(res.headers.get("retry-after"));
+        await sleep(Number.isFinite(ra) && ra > 0 ? ra * 1e3 : backoff(attempt));
+        continue;
+      }
+      throw new Error(`fin-integrity ingest ${res.status}: ${await safeText(res)}`);
+    }
+  }
+};
+var MemoryTransport = class {
+  sent = [];
+  async send(batch) {
+    this.sent.push(...batch);
+  }
+};
+function backoff(n) {
+  return Math.min(1e3 * 2 ** n, 15e3) + Math.random() * 250;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+var RejectedEventsError = class extends FinIntegrityError {
+  constructor(rejected, batchSize) {
+    const detail = rejected.map((r) => `${r.event_id}: ${r.error}`).join("; ");
+    super(`fin-integrity: ingest rejected ${rejected.length}/${batchSize} event(s) \u2014 ${detail}`);
+    this.rejected = rejected;
+    this.batchSize = batchSize;
+    this.name = "RejectedEventsError";
+  }
+  rejected;
+  batchSize;
+};
+async function rejectedFrom(res) {
+  try {
+    const body = await res.clone().json();
+    if (!Array.isArray(body?.results)) return [];
+    return body.results.filter((r) => r?.status === "rejected").map((r) => ({ event_id: r.event_id ?? "unknown", error: r.error ?? "unknown error" }));
+  } catch {
+    return [];
+  }
+}
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+// src/client.ts
+var DEFAULT_ENDPOINT = "https://ingest.fin-integrity.com";
+var FinIntegrityClient = class {
+  apiKey;
+  endpoint;
+  idempotencyMode;
+  maxSize;
+  flushMs;
+  maxQueueSize;
+  sampleRate;
+  environment;
+  beforeSend;
+  debug;
+  onError;
+  transport;
+  memory;
+  queue = [];
+  dropped = 0;
+  timer;
+  /** Capture money-movement observed from a payment processor (Stripe, Adyen, bank, …). */
+  processor;
+  /** Capture entries from your own internal ledger / books. */
+  ledger;
+  constructor(config = {}) {
+    const dryRun = config.dryRun ?? false;
+    const apiKey = config.apiKey ?? process.env.FIN_INTEGRITY_KEY;
+    if (!apiKey && !dryRun && !config.transport) {
+      throw new ConfigError(
+        "fin-integrity: apiKey is required (pass config.apiKey or set FIN_INTEGRITY_KEY). Use { dryRun: true } to test without a key."
+      );
+    }
+    this.apiKey = apiKey ?? "dry-run";
+    this.endpoint = config.endpoint ?? process.env.FIN_INTEGRITY_ENDPOINT ?? DEFAULT_ENDPOINT;
+    this.idempotencyMode = config.idempotency ?? "deterministic";
+    this.maxSize = config.batch?.maxSize ?? 50;
+    this.flushMs = config.batch?.flushMs ?? 2e3;
+    this.maxQueueSize = config.maxQueueSize ?? 1e3;
+    this.sampleRate = config.sampleRate ?? 1;
+    this.environment = cleanEnvironment(config.environment ?? process.env.NODE_ENV);
+    this.beforeSend = config.beforeSend;
+    this.debug = config.debug ?? false;
+    this.onError = config.onError ?? ((e) => {
+      if (this.debug) console.warn("[fin-integrity]", e);
+    });
+    if (config.transport) {
+      this.transport = config.transport;
+    } else if (dryRun) {
+      this.memory = new MemoryTransport();
+      this.transport = this.memory;
+    } else {
+      this.transport = new HttpTransport({
+        endpoint: this.endpoint,
+        apiKey: this.apiKey,
+        retries: config.retries ?? 3,
+        debug: this.debug
+      });
+    }
+    this.processor = {
+      record: (input) => this.record("processor", input),
+      recordPayout: (input) => this.recordPayout(input),
+      recordSubscription: (input) => this.recordSubscription(input)
+    };
+    this.ledger = { record: (input) => this.record("ledger", input) };
+    this.timer = setInterval(() => void this.flush(), this.flushMs);
+    if (typeof this.timer.unref === "function") this.timer.unref();
+    process.once("beforeExit", () => void this.flush());
+    process.once("SIGTERM", () => this.onSigterm());
+  }
+  /**
+   * Drain on SIGTERM, then hand the process back its normal fate.
+   *
+   * Node disables its default terminate-on-SIGTERM as soon as ANY listener is
+   * registered, so simply attaching one made this library silently decide that
+   * SIGTERM no longer kills the host process — a bare script would ignore
+   * `docker stop` and hang until SIGKILL, which is also when the queued events
+   * we were trying to protect get dropped anyway.
+   *
+   * So: flush, then exit ourselves — but only if nothing else is listening. If
+   * the app registered its own handler it owns the shutdown sequence, and a
+   * library must not exit out from under it. `once` has already removed our own
+   * listener by the time this runs, so any remaining count is the app's.
+   */
+  onSigterm() {
+    const appHandlesIt = process.listenerCount("SIGTERM") > 0;
+    void this.flush().finally(() => {
+      if (!appHandlesIt) process.exit(143);
+    });
+  }
+  /** Low-level escape hatch: capture a fully-specified event (both adapters use this). */
+  capture(input) {
+    this.record(input.side, input);
+  }
+  record(side, input) {
+    try {
+      const env = {
+        schema_version: "1.0",
+        event_id: uuidKey(),
+        idempotency_key: "",
+        side,
+        source: input.source ?? (side === "ledger" ? "ledger.internal" : "custom"),
+        event_type: input.type,
+        reference: input.reference,
+        external_id: input.external_id,
+        amount: {
+          minor: toMinorString(input.amount.minor),
+          currency: input.amount.currency.toLowerCase(),
+          ...input.amount.exponent != null ? { exponent: input.amount.exponent } : {}
+        },
+        ...input.fee != null ? { fee: { minor: toMinorString(input.fee.minor), currency: input.fee.currency.toLowerCase() } } : {},
+        ...input.traceId != null ? { trace_id: input.traceId } : {},
+        ...input.payoutId != null ? { payout_id: input.payoutId } : {},
+        ...input.subscriptionId != null ? { subscription_id: input.subscriptionId } : {},
+        ...input.parentExternalId != null ? { parent_external_id: input.parentExternalId } : {},
+        occurred_at: toIso(input.occurred_at),
+        captured_at: (/* @__PURE__ */ new Date()).toISOString(),
+        ...input.status != null ? { status: input.status } : {},
+        ...input.direction != null ? { direction: input.direction } : {},
+        ...this.envFields(input.environment),
+        ...input.metadata != null ? { metadata: input.metadata } : {}
+      };
+      env.idempotency_key = this.idempotencyMode === "uuid" ? uuidKey() : deterministicKey(env);
+      this.enqueue(env);
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+  /**
+   * Capture a recurring billing container. Not money movement — this is what a
+   * charge is expected to arrive in, which is what lets reconciliation catch a
+   * billing period that produced no charge at all.
+   *
+   * Send it whenever the subscription changes (created, renewed, status change)
+   * so `currentPeriodEnd` stays current.
+   */
+  recordSubscription(input) {
+    try {
+      const env = {
+        schema_version: "1.0",
+        event_id: uuidKey(),
+        idempotency_key: "",
+        side: "processor",
+        source: input.source ?? "custom",
+        event_type: "subscription",
+        reference: input.external_id,
+        external_id: input.external_id,
+        amount: {
+          minor: toMinorString(input.amount.minor),
+          currency: input.amount.currency.toLowerCase(),
+          ...input.amount.exponent != null ? { exponent: input.amount.exponent } : {}
+        },
+        status: input.status,
+        ...input.interval != null ? { interval: input.interval } : {},
+        ...input.currentPeriodStart != null ? { current_period_start: toIso(input.currentPeriodStart) } : {},
+        ...input.currentPeriodEnd != null ? { current_period_end: toIso(input.currentPeriodEnd) } : {},
+        ...input.traceId != null ? { trace_id: input.traceId } : {},
+        occurred_at: toIso(input.occurred_at),
+        captured_at: (/* @__PURE__ */ new Date()).toISOString(),
+        ...this.envFields(input.environment),
+        ...input.metadata != null ? { metadata: input.metadata } : {}
+      };
+      env.idempotency_key = this.idempotencyMode === "uuid" ? uuidKey() : deterministicKey(env);
+      this.enqueue(env);
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+  /** Capture a processor payout (processor → bank). Stored separately; links to
+   *  transactions via their payoutId. */
+  recordPayout(input) {
+    try {
+      const env = {
+        schema_version: "1.0",
+        event_id: uuidKey(),
+        idempotency_key: "",
+        side: "processor",
+        source: input.source ?? "custom",
+        event_type: "payout",
+        reference: input.external_id,
+        external_id: input.external_id,
+        amount: {
+          minor: toMinorString(input.amount.minor),
+          currency: input.amount.currency.toLowerCase(),
+          ...input.amount.exponent != null ? { exponent: input.amount.exponent } : {}
+        },
+        ...input.traceId != null ? { trace_id: input.traceId } : {},
+        ...input.arrivalAt != null ? { arrival_at: toIso(input.arrivalAt) } : {},
+        occurred_at: toIso(input.occurred_at),
+        captured_at: (/* @__PURE__ */ new Date()).toISOString(),
+        ...input.status != null ? { status: input.status } : {},
+        ...this.envFields(input.environment),
+        ...input.metadata != null ? { metadata: input.metadata } : {}
+      };
+      env.idempotency_key = this.idempotencyMode === "uuid" ? uuidKey() : deterministicKey(env);
+      this.enqueue(env);
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+  /** Per-event override wins over the client default; an invalid value falls back
+   *  to the default (and, if that's absent too, the server defaults to production). */
+  envFields(perEvent) {
+    const environment = cleanEnvironment(perEvent) ?? this.environment;
+    return environment != null ? { environment } : {};
+  }
+  enqueue(env) {
+    if (this.sampleRate < 1 && Math.random() > this.sampleRate) return;
+    let out = env;
+    if (this.beforeSend) out = this.beforeSend(env);
+    if (!out) return;
+    if (this.queue.length >= this.maxQueueSize) {
+      this.queue.shift();
+      this.dropped++;
+    }
+    this.queue.push(out);
+    if (this.queue.length >= this.maxSize) void this.flush();
+  }
+  /** Send all queued events now. Safe to await (e.g. in a serverless `finally`). */
+  async flush() {
+    if (this.queue.length === 0) return;
+    const batch = this.queue.splice(0, this.queue.length);
+    const dropped = this.dropped;
+    this.dropped = 0;
+    try {
+      await this.transport.send(batch, { dropped });
+    } catch (err) {
+      this.onError(err);
+    }
+  }
+  /** Drain and stop the client (call before a long-lived process exits). */
+  async shutdown() {
+    if (this.timer) clearInterval(this.timer);
+    await this.flush();
+  }
+  /** Envelopes captured so far (dryRun / MemoryTransport only). Great for tests. */
+  inspect() {
+    return this.memory ? [...this.memory.sent, ...this.queue] : [...this.queue];
+  }
+};
+function toMinorString(m) {
+  if (typeof m === "bigint") return m.toString();
+  if (!Number.isInteger(m)) {
+    throw new FinIntegrityError(`amount.minor must be an integer in minor units, got ${m}`);
+  }
+  return String(m);
+}
+function toIso(v) {
+  if (!v) return (/* @__PURE__ */ new Date()).toISOString();
+  return v instanceof Date ? v.toISOString() : v;
+}
+
+// src/stripe.ts
+function instrumentStripe(stripe, fi) {
+  const s = stripe;
+  wrap(s?.charges, "create", fi, "payment");
+  wrap(s?.paymentIntents, "create", fi, "payment");
+  wrap(s?.refunds, "create", fi, "refund");
+  return stripe;
+}
+function wrap(resource, method, fi, type) {
+  if (!resource || typeof resource[method] !== "function") return;
+  const original = resource[method];
+  if (original.__fiWrapped) return;
+  const wrapped = async function(...args) {
+    const result = await original.apply(this, args);
+    queueMicrotask(() => {
+      try {
+        captureStripe(fi, type, result);
+      } catch {
+      }
+    });
+    return result;
+  };
+  wrapped.__fiWrapped = true;
+  resource[method] = wrapped;
+}
+function captureStripe(fi, type, obj) {
+  if (!obj || typeof obj !== "object" || typeof obj.id !== "string") return;
+  const amount = type === "refund" ? obj.amount : obj.amount_received ?? obj.amount;
+  const reference = obj.metadata?.reference ?? obj.metadata?.order_id ?? obj.metadata?.reconciliation_id ?? (type === "refund" ? obj.charge ?? obj.payment_intent ?? obj.id : obj.id);
+  fi.capture({
+    side: "processor",
+    type,
+    source: "stripe",
+    reference: String(reference),
+    external_id: obj.id,
+    amount: { minor: typeof amount === "number" ? amount : 0, currency: String(obj.currency ?? "") },
+    ...obj.status ? { status: String(obj.status) } : {},
+    ...typeof obj.created === "number" ? { occurred_at: new Date(obj.created * 1e3) } : {},
+    metadata: { stripe_object: obj.object }
+  });
+}
+
+// src/index.ts
+var current;
+function init(config) {
+  current = new FinIntegrityClient(config);
+  return current;
+}
+function getClient() {
+  if (!current) throw new Error("fin-integrity: call init() before getClient()");
+  return current;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigError,
+  FinIntegrityClient,
+  FinIntegrityError,
+  RejectedEventsError,
+  getClient,
+  init,
+  instrumentStripe
+});
+//# sourceMappingURL=index.cjs.map