@pay-normalize/core 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 pay-normalize contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @pay-normalize/core
+
+The contract. Every connector depends on this package and nothing else; hosts import the shared types, the money helpers, and the ordering/dedupe primitives from here.
+
+- Data model & design rationale: [../../docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
+- Host wiring: [../../docs/INTEGRATION.md](../../docs/INTEGRATION.md)
+
+```ts
+import {
+  validateTransaction, type StandardizedTransaction,
+  parseNairaDecimalString, parseKoboInteger, asKobo, koboToNairaString, type Kobo,
+  shouldApplyStatusTransition, STATUS_RANK, statusRank, type TransactionStatus,
+  type PaymentChannel,
+  composeDedupeKey,
+  toRawBody, rawBodyFromString, type RawBody,
+  type Connector, type ParseResult, type SettlementFileParseResult, summarizeRows,
+  NormalizationError, MalformedPayloadError, AmountParseError,
+  SignatureVerificationError, UnsupportedFileFormatError, type NormalizationErrorCode,
+} from "@pay-normalize/core";
+```
+
+---
+
+## Schema
+
+### `StandardizedTransaction`
+The single output shape of every connector. Full field table in [ARCHITECTURE.md](../../docs/ARCHITECTURE.md#the-output-standardizedtransaction). Key invariant, enforced at runtime: `netAmountInKobo === amountInKobo - feeInKobo`.
+
+### `validateTransaction(input: unknown): StandardizedTransaction`
+Runtime gate (Zod) every connector output passes through before leaving the library. Throws a `ZodError` if the shape or the money invariant is violated — this is an internal guard, so a connector bug surfaces loudly rather than emitting a bad row.
+
+### `StandardizedTransactionSchema`
+The Zod schema itself, exported for hosts that want to re-validate at their own boundary.
+
+---
+
+## Money
+
+Integer minor units only; conversion happens once, at the connector boundary, with BigInt/string math. `Kobo` is a branded `number` so unconverted amounts can't leak.
+
+| Export | Signature | Notes |
+|---|---|---|
+| `asKobo` | `(value: number) => Kobo` | Assert an already-integer, non-negative value is `Kobo`. Throws `AmountParseError` otherwise. |
+| `parseKoboInteger` | `(input: number \| string) => Kobo` | For providers that send kobo integers. Rejects decimals and values over `MAX_SAFE_INTEGER`. |
+| `parseNairaDecimalString` | `(input: string \| number) => Kobo` | For main-unit decimals (`"5,000.00"`, `5000`, `1500.25`, `"₦5000"`). Rejects negatives, >2dp, scientific notation, and over-long input. |
+| `koboToNairaString` | `(kobo: Kobo) => string` | Display only. Never feed back into parsing. |
+
+```ts
+parseKoboInteger(10000);           // 10000 (already kobo)
+parseNairaDecimalString(120);      // 12000
+parseNairaDecimalString("1500.25");// 150025  (no float drift)
+asKobo(0);                         // 0
+```
+
+---
+
+## Status ordering
+
+`TransactionStatus = "PENDING" | "FAILED" | "SUCCESSFUL" | "REVERSED"`, ranked `0 < 1 < 2 < 3`.
+
+| Export | Signature | Notes |
+|---|---|---|
+| `STATUS_RANK` | `Readonly<Record<TransactionStatus, number>>` | Frozen rank map. |
+| `statusRank` | `(status) => number` | Rank lookup. |
+| `shouldApplyStatusTransition` | `(current, incoming) => boolean` | `true` iff `rank(incoming) > rank(current)`. Equal rank → `false` (idempotent redelivery). |
+
+Use it in your upsert to make out-of-order and duplicate delivery safe. See [INTEGRATION.md §4b](../../docs/INTEGRATION.md#4b-a-rank-guard-on-status--for-out-of-order-delivery).
+
+---
+
+## Dedupe identity
+
+| Export | Signature | Notes |
+|---|---|---|
+| `composeDedupeKey` | `(provider: string, reference: string) => string` | Returns `${provider}:${reference}` (provider lowercased, both trimmed). Throws on empty input. |
+
+Connectors namespace the reference by family (`charge:…`, `transfer:…`, `transaction:…`) so a charge and its refund, or a webhook and its API-record twin, share one key. The host enforces uniqueness with a DB index.
+
+---
+
+## Raw body
+
+| Export | Signature | Notes |
+|---|---|---|
+| `RawBody` | `Buffer & { __brand: "RawBody" }` | Branded — only way to satisfy `verifyWebhookSignature`. |
+| `toRawBody` | `(buf: Buffer) => RawBody` | Production path. Throws `TypeError` if not a `Buffer`. |
+| `rawBodyFromString` | `(s: string, enc?) => RawBody` | Tests / fixture replay only. |
+
+---
+
+## Connector & results
+
+| Export | Notes |
+|---|---|
+| `Connector` | The interface every provider package implements. See [ARCHITECTURE.md](../../docs/ARCHITECTURE.md#the-connector-interface). |
+| `ParseResult` | `transaction \| unknown_event \| parse_error`. Never `null`, never a throw. |
+| `SettlementFileParseResult` | Row-isolated file result with a `summary` of counts. |
+| `summarizeRows` | `(rows: ParseResult[]) => summary` | Counts by outcome. |
+
+---
+
+## Errors
+
+All extend `NormalizationError` and carry a stable `code: NormalizationErrorCode` — **route on `code`, not `message`.**
+
+| Class | `code` |
+|---|---|
+| `SignatureVerificationError` | `ERR_SIGNATURE_VERIFICATION` |
+| `MalformedPayloadError` | `ERR_MALFORMED_PAYLOAD` (or narrowed `ERR_TIMESTAMP_MISSING`) |
+| `AmountParseError` | `ERR_AMOUNT_PARSE` |
+| `UnsupportedFileFormatError` | `ERR_UNSUPPORTED_FILE_FORMAT` |
+
+```ts
+if (result.kind === "parse_error" && result.error.code === "ERR_TIMESTAMP_MISSING") {
+  // retry via the fetch-time overload
+}
+```
+
+---
+
+## Dependencies
+
+`zod` (runtime validation). Node 18+, ESM.

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+import { z } from 'zod';
+
+/**
+ * Kobo — the ONLY representation of money inside this library.
+ *
+ * Branded type: a plain `number` will not typecheck where `Kobo` is required,
+ * so unconverted provider amounts cannot leak past the connector boundary.
+ *
+ * Rules (NOT_DOING.md §9):
+ *  - Integers only. Floats are banned; all parsing below uses string/BigInt math,
+ *    so `"5000.10"` can never become `500009.999...` via IEEE-754.
+ *  - Conversion happens exactly ONCE, at the connector boundary, via the
+ *    parsers in this file. Core and hosts only ever see Kobo.
+ */
+type Kobo = number & {
+    readonly __brand: "Kobo";
+};
+/** Assert an already-integer amount is valid Kobo (e.g. Paystack's `amount` field). */
+declare function asKobo(value: number): Kobo;
+/**
+ * Parse a kobo amount that arrives as an integer-looking value.
+ * Accepts `500000` or `"500000"`. Rejects decimals — if a provider sends
+ * decimals, it is a naira amount and MUST go through parseNairaDecimalString.
+ */
+declare function parseKoboInteger(input: number | string): Kobo;
+/**
+ * Parse naira expressed as a decimal string or number into Kobo, using
+ * string math only (never parseFloat).
+ *
+ * Accepts the shapes actually seen across Nigerian providers:
+ *   "5000"      -> 500000
+ *   "5000.00"   -> 500000
+ *   "5000.5"    -> 500050   (one decimal place = tens of kobo)
+ *   "5,000.00"  -> 500000   (thousands separators)
+ *   5000        -> 500000   (numeric naira, e.g. Monnify amounts)
+ *   "₦5,000.00" -> 500000
+ *
+ * Rejects: negatives, >2 decimal places (no such thing as half a kobo),
+ * empty strings, scientific notation, over-long input, and anything ambiguous.
+ */
+declare function parseNairaDecimalString(input: string | number): Kobo;
+/** Display helper only. Never feed its output back into parsing logic. */
+declare function koboToNairaString(kobo: Kobo): string;
+
+declare const StandardizedTransactionSchema: z.ZodObject<{
+    dedupeKey: z.ZodString;
+    provider: z.ZodString;
+    providerReference: z.ZodString;
+    providerEventId: z.ZodOptional<z.ZodString>;
+    amountInKobo: z.ZodNumber;
+    feeInKobo: z.ZodNumber;
+    netAmountInKobo: z.ZodNumber;
+    currency: z.ZodString;
+    status: z.ZodEnum<{
+        PENDING: "PENDING";
+        FAILED: "FAILED";
+        SUCCESSFUL: "SUCCESSFUL";
+        REVERSED: "REVERSED";
+    }>;
+    channel: z.ZodEnum<{
+        card: "card";
+        bank_transfer: "bank_transfer";
+        ussd: "ussd";
+        qr: "qr";
+        wallet: "wallet";
+        pos: "pos";
+        unknown: "unknown";
+    }>;
+    direction: z.ZodEnum<{
+        credit: "credit";
+        debit: "debit";
+    }>;
+    occurredAt: z.ZodDate;
+    occurredAtRaw: z.ZodOptional<z.ZodString>;
+    settlementDate: z.ZodNullable<z.ZodDate>;
+    rawProviderPayload: z.ZodUnknown;
+}, z.core.$strict>;
+type StandardizedTransaction = Omit<z.infer<typeof StandardizedTransactionSchema>, "amountInKobo" | "feeInKobo" | "netAmountInKobo"> & {
+    amountInKobo: Kobo;
+    feeInKobo: Kobo;
+    netAmountInKobo: Kobo;
+};
+/** Runtime gate every connector output passes through before leaving the library. */
+declare function validateTransaction(input: unknown): StandardizedTransaction;
+
+/**
+ * The four terminal-ish states every provider vocabulary maps down to.
+ * Connectors own the mapping table (e.g. OPay "SUCCESS", Paystack "success",
+ * Monnify "PAID" -> SUCCESSFUL) — explicitly, per NOT_DOING.md §9:
+ * no status inference from amount presence or absence of error fields.
+ */
+declare const TransactionStatusSchema: z.ZodEnum<{
+    PENDING: "PENDING";
+    FAILED: "FAILED";
+    SUCCESSFUL: "SUCCESSFUL";
+    REVERSED: "REVERSED";
+}>;
+type TransactionStatus = z.infer<typeof TransactionStatusSchema>;
+/**
+ * STATUS_RANK — the ordering that makes out-of-order webhook delivery safe.
+ *
+ * Why this exists (distributed-systems reality, not theory):
+ *  - Providers deliver webhooks with retries + exponential backoff. Retries mean
+ *    DUPLICATES; parallel delivery paths + network partitions mean REORDERING.
+ *    A "pending" emitted at T0 can arrive AFTER the "successful" emitted at T1.
+ *  - You cannot fix this with timestamps: provider clocks skew, and several
+ *    providers send unlabeled local-time (WAT) strings. Ordering by rank is
+ *    deterministic; ordering by clock is a race condition wearing a watch.
+ *
+ * REVERSED outranks SUCCESSFUL deliberately: success->reversal is a legitimate
+ * forward progression (refunds, chargebacks). PENDING can never overwrite anything.
+ * FAILED -> SUCCESSFUL is allowed (rank 1 -> 2): some providers emit a failure
+ * then succeed on an internal retry under the same reference.
+ */
+declare const STATUS_RANK: Readonly<Record<TransactionStatus, number>>;
+declare function statusRank(status: TransactionStatus): number;
+/**
+ * The one-line correctness rule for host applications:
+ *
+ *   if (!shouldApplyStatusTransition(stored.status, incoming.status)) skip;
+ *
+ * Equal rank returns false — re-delivery of the same status is a no-op
+ * (idempotency). Host must pair this with:
+ *   1. a UNIQUE index on dedupeKey (hard idempotency at the storage layer), and
+ *   2. optimistic locking (version column / compare-and-swap) or
+ *      SELECT ... FOR UPDATE when applying the transition, because two webhook
+ *      deliveries for the same transaction WILL race on concurrent workers.
+ * This library is stateless by design (NOT_DOING.md §6) — it hands you the
+ * rule; your database enforces it.
+ */
+declare function shouldApplyStatusTransition(current: TransactionStatus, incoming: TransactionStatus): boolean;
+
+/**
+ * How the money moved. 'unknown' is a legitimate value — bank statement rows
+ * frequently do not disclose the channel, and guessing violates NOT_DOING.md §9.
+ * 'pos' covers agent/terminal collections (OPay, PalmPay, Moniepoint territory).
+ */
+declare const PaymentChannelSchema: z.ZodEnum<{
+    card: "card";
+    bank_transfer: "bank_transfer";
+    ussd: "ussd";
+    qr: "qr";
+    wallet: "wallet";
+    pos: "pos";
+    unknown: "unknown";
+}>;
+type PaymentChannel = z.infer<typeof PaymentChannelSchema>;
+
+/**
+ * RawBody — a branded Buffer that connectors require for signature verification.
+ *
+ * THE #1 INTEGRATION BUG THIS PREVENTS:
+ * Providers compute webhook signatures (HMAC-SHA512 for Paystack, provider-specific
+ * schemes elsewhere) over the EXACT BYTES they sent. If a host runs the request
+ * through `express.json()` and later re-serializes (`JSON.stringify(req.body)`),
+ * key order, whitespace, and unicode escaping can change — the HMAC no longer
+ * matches, and the host spends a night debugging "invalid signature" on
+ * perfectly valid webhooks.
+ *
+ * By requiring `RawBody` (constructible only from a Buffer via `toRawBody`),
+ * a host that only has parsed JSON gets a COMPILE ERROR instead of a 2am mystery.
+ *
+ * Express hosts: mount `express.raw({ type: "application/json" })` on webhook
+ * routes (route-scoped, before any json middleware), then `toRawBody(req.body)`.
+ * Parse to JSON only AFTER verification, from these same bytes.
+ */
+type RawBody = Buffer & {
+    readonly __brand: "RawBody";
+};
+declare function toRawBody(buf: Buffer): RawBody;
+/**
+ * Escape hatch for tests and fixture replay ONLY. Constructing a RawBody from a
+ * string in production risks re-serialization drift — fixtures store the
+ * original bytes precisely so this stays faithful.
+ */
+declare function rawBodyFromString(s: string, encoding?: BufferEncoding): RawBody;
+
+/**
+ * Typed errors so hosts can route failures without string-matching messages.
+ * Connectors throw these ONLY inside their own boundary; parseWebhook /
+ * parseSettlementFile catch them and return `parse_error` results instead
+ * (see connector/result.ts) — a malformed payload from one provider must never
+ * crash a host's webhook endpoint (that would turn one bad payload into an
+ * availability incident: the provider retries, you 500, backoff kicks in,
+ * and every later event for that endpoint queues behind the poison message).
+ */
+/**
+ * Machine-readable error codes — stable API, unlike messages, which may be
+ * reworded in a PATCH release. Route on `error.code` (or instanceof), never
+ * on `error.message`.
+ */
+type NormalizationErrorCode = "ERR_SIGNATURE_VERIFICATION" | "ERR_MALFORMED_PAYLOAD" | "ERR_AMOUNT_PARSE" | "ERR_UNSUPPORTED_FILE_FORMAT" | "ERR_TIMESTAMP_MISSING";
+declare class NormalizationError extends Error {
+    readonly code: NormalizationErrorCode;
+    constructor(message: string, code: NormalizationErrorCode);
+}
+/** Signature header missing, malformed, or HMAC mismatch. Host should respond 401 and NOT process. */
+declare class SignatureVerificationError extends NormalizationError {
+    readonly provider?: string | undefined;
+    constructor(message: string, provider?: string | undefined);
+}
+/**
+ * Payload structurally unusable: not JSON, missing required fields, wrong
+ * shapes. `code` may be narrowed (e.g. ERR_TIMESTAMP_MISSING) when the defect
+ * is specific enough for a host — or a caller — to act on programmatically.
+ */
+declare class MalformedPayloadError extends NormalizationError {
+    readonly raw?: unknown | undefined;
+    constructor(message: string, raw?: unknown | undefined, code?: NormalizationErrorCode);
+}
+/** Amount could not be converted to Kobo safely. Carries the offending input for logs. */
+declare class AmountParseError extends NormalizationError {
+    readonly input?: unknown | undefined;
+    constructor(message: string, input?: unknown | undefined);
+}
+/** Settlement/statement file is not a format this connector version supports. */
+declare class UnsupportedFileFormatError extends NormalizationError {
+    readonly provider?: string | undefined;
+    constructor(message: string, provider?: string | undefined);
+}
+
+/**
+ * Every parse returns one of these — connectors NEVER throw on weird input and
+ * NEVER return null. The type system enforces NOT_DOING.md §9:
+ * "no swallowing unknown events."
+ *
+ * Host handling guidance:
+ *  - 'transaction'   -> idempotent upsert (unique dedupeKey + STATUS_RANK guard), ACK 200.
+ *  - 'unknown_event' -> log + store raw, ACK 200. Unknown ≠ error: providers add
+ *                       event types without notice; NACKing them makes the provider
+ *                       retry forever (their backoff, your log spam).
+ *  - 'parse_error'   -> the poison-message case. ACK 200 (do NOT make the provider
+ *                       retry a payload that will fail identically), park the raw
+ *                       payload in your own dead-letter store, alert. This library
+ *                       ships no queue (NOT_DOING.md §6) — the DLQ is yours.
+ */
+type ParseResult = {
+    kind: "transaction";
+    transaction: StandardizedTransaction;
+} | {
+    kind: "unknown_event";
+    provider: string;
+    /** Provider's own event-type string when discoverable, else "unrecognized". */
+    eventType: string;
+    raw: unknown;
+} | {
+    kind: "parse_error";
+    provider: string;
+    error: MalformedPayloadError | AmountParseError;
+    raw: unknown;
+};
+/**
+ * Result of parsing a settlement/statement file. Row-level isolation: one
+ * mangled row (bank exports love those) yields one parse_error result — the
+ * other 4,999 rows still normalize. All-or-nothing file parsing punishes the
+ * host for the provider's data quality.
+ */
+interface SettlementFileParseResult {
+    provider: string;
+    /** e.g. 'nomba-settlement-csv-v1' — which fixture-tested format matched. */
+    format: string;
+    rows: ParseResult[];
+    /** Row counts by outcome, so hosts can alert on anomaly ratios cheaply. */
+    summary: {
+        transactions: number;
+        unknown: number;
+        errors: number;
+    };
+}
+declare function summarizeRows(rows: ParseResult[]): SettlementFileParseResult["summary"];
+
+/**
+ * Connector — the constitution. One implementation per provider, in its own
+ * package (@scope/nomba, @scope/paystack, ...), each independently semver'd:
+ * a Paystack format change is a paystack@2.0.0, and nobody's Nomba code moves.
+ *
+ * Design constraints (enforced by NOT_DOING.md, restated here because this is
+ * the file contributors actually read):
+ *  - PURE. No HTTP calls, no polling, no provider SDKs, no env vars, no clocks
+ *    (timestamps come from payloads). Same input, same output, forever.
+ *  - STATELESS. Dedupe enforcement, status transitions, retries, backpressure,
+ *    and queueing are the host's (or the future hosted product's) concern.
+ *  - SECRETS ARE ARGUMENTS. Passed in per call, never read, stored, or logged.
+ */
+interface Connector {
+    /** Lowercase identifier matching StandardizedTransaction.provider: 'nomba', 'paystack'... */
+    readonly provider: string;
+    /** Semver of this connector implementation, surfaced for host diagnostics/logging. */
+    readonly version: string;
+    /**
+     * Verify the webhook came from the provider. MUST compute over the raw bytes
+     * (RawBody brand exists precisely because express.json() destroys them) and
+     * MUST use a constant-time comparison (crypto.timingSafeEqual) — string `===`
+     * on HMACs leaks timing.
+     *
+     * Returns boolean rather than throwing: "unverified" is a routine hostile-
+     * internet event (host responds 401), not an exceptional program state.
+     */
+    verifyWebhookSignature(input: {
+        /** Node-style header map; connectors do case-insensitive lookups internally. */
+        headers: Record<string, string | string[] | undefined>;
+        rawBody: RawBody;
+        /** The provider webhook secret. An argument, never an env read. */
+        secret: string;
+    }): boolean;
+    /**
+     * Normalize one webhook delivery. Total function over arbitrary bytes:
+     * malformed input returns { kind: 'parse_error' }, never throws.
+     * Call ONLY after verifyWebhookSignature returned true — parsing unverified
+     * payloads is processing attacker-controlled input by choice.
+     */
+    parseWebhook(rawBody: RawBody): ParseResult;
+    /**
+     * Normalize a settlement/statement export (CSV/XLSX bytes). Row-isolated:
+     * bad rows become parse_error results, good rows still flow. Throws
+     * UnsupportedFileFormatError only when the FILE ITSELF is not a format this
+     * connector version knows (wrong provider's file, new column layout) —
+     * that is a configuration/version problem, not a data problem.
+     */
+    parseSettlementFile(file: Buffer): SettlementFileParseResult;
+    /**
+     * Identity for idempotent ingestion. Default composition is
+     * `${provider}:${providerReference}` via composeDedupeKey; connectors
+     * override when a provider's reference is not 1:1 with a transaction —
+     * a quirk that must be documented and fixture-proven in the connector.
+     */
+    dedupeKey(txn: StandardizedTransaction): string;
+}
+
+/**
+ * Dedupe keys — idempotency for a world where providers retry webhooks.
+ *
+ * Webhook delivery is at-least-once everywhere: providers retry on timeout with
+ * exponential backoff, and some (OPay callbacks, observed) simply double-fire.
+ * The ONLY reliable defense is idempotent ingestion:
+ *
+ *   CREATE UNIQUE INDEX ux_txn_dedupe ON transactions (dedupe_key);
+ *
+ * then INSERT ... ON CONFLICT DO NOTHING (or the equivalent upsert guarded by
+ * shouldApplyStatusTransition for status updates). Enforcing uniqueness in
+ * application code alone is a race condition — two workers processing the same
+ * redelivered webhook concurrently will both pass an "does it exist?" check.
+ * The database constraint is the lock.
+ *
+ * Key shape: `${provider}:${providerReference}` — namespaced so Paystack ref
+ * "TX123" and Nomba ref "TX123" never collide. Connectors may override
+ * dedupeKey() when a provider's reference is not unique per transaction
+ * (e.g. one reference spanning multiple settlement rows) — that quirk knowledge
+ * lives in the connector, backed by fixtures.
+ */
+declare function composeDedupeKey(provider: string, providerReference: string): string;
+
+export { AmountParseError, type Connector, type Kobo, MalformedPayloadError, NormalizationError, type NormalizationErrorCode, type ParseResult, type PaymentChannel, PaymentChannelSchema, type RawBody, STATUS_RANK, type SettlementFileParseResult, SignatureVerificationError, type StandardizedTransaction, StandardizedTransactionSchema, type TransactionStatus, TransactionStatusSchema, UnsupportedFileFormatError, asKobo, composeDedupeKey, koboToNairaString, parseKoboInteger, parseNairaDecimalString, rawBodyFromString, shouldApplyStatusTransition, statusRank, summarizeRows, toRawBody, validateTransaction };

package/dist/index.js

@@ -0,0 +1,258 @@
+// src/schema/transaction.ts
+import { z as z3 } from "zod";
+
+// src/schema/status.ts
+import { z } from "zod";
+var TransactionStatusSchema = z.enum([
+  "PENDING",
+  "FAILED",
+  "SUCCESSFUL",
+  "REVERSED"
+]);
+var STATUS_RANK = Object.freeze({
+  PENDING: 0,
+  FAILED: 1,
+  SUCCESSFUL: 2,
+  REVERSED: 3
+});
+function statusRank(status) {
+  return STATUS_RANK[status];
+}
+function shouldApplyStatusTransition(current, incoming) {
+  return STATUS_RANK[incoming] > STATUS_RANK[current];
+}
+
+// src/schema/channel.ts
+import { z as z2 } from "zod";
+var PaymentChannelSchema = z2.enum([
+  "card",
+  "bank_transfer",
+  "ussd",
+  "qr",
+  "wallet",
+  "pos",
+  "unknown"
+]);
+
+// src/schema/transaction.ts
+var KoboSchema = z3.number().int("money must be integer kobo \u2014 parse at the connector boundary, never float").nonnegative();
+var StandardizedTransactionSchema = z3.object({
+  /** Deterministic identity for idempotency: `${provider}:${providerReference}` (see util/dedupe). */
+  dedupeKey: z3.string().min(3),
+  /** Connector identifier, lowercase: 'nomba' | 'paystack' | 'monnify' | 'opay' | 'palmpay' | 'flutterwave' | ... open set by design — new providers must not require a core release. */
+  provider: z3.string().min(1).regex(/^[a-z0-9_-]+$/),
+  /** The provider's own transaction reference (txref / transactionReference / orderNo...). */
+  providerReference: z3.string().min(1),
+  /** Provider's per-DELIVERY event id when one exists — distinguishes redelivery of one event from two events about one transaction. */
+  providerEventId: z3.string().min(1).optional(),
+  /** Money — integer kobo only. Branded at the type level. */
+  amountInKobo: KoboSchema,
+  feeInKobo: KoboSchema,
+  /** MUST equal amountInKobo - feeInKobo; enforced below so no connector can drift. */
+  netAmountInKobo: KoboSchema,
+  /** ISO-4217 uppercase. Non-NGN is tagged and passed through untouched — no FX, no conversion (NOT_DOING.md §10). */
+  currency: z3.string().regex(/^[A-Z]{3}$/),
+  status: TransactionStatusSchema,
+  channel: PaymentChannelSchema,
+  /** credit = money in (collections, VA funding); debit = money out rows encountered when parsing bank statements. Parsing debits ≠ initiating them. */
+  direction: z3.enum(["credit", "debit"]),
+  /**
+   * When the provider says it happened. CLOCK SKEW WARNING: provider clocks
+   * are not your clock, and several send unlabeled WAT strings. Connectors
+   * apply an explicit, fixture-tested timezone rule per provider. Hosts must
+   * NEVER use this for ordering decisions — that is what STATUS_RANK is for.
+   */
+  occurredAt: z3.date(),
+  /** The provider's original timestamp string, preserved verbatim for audit/debugging. */
+  occurredAtRaw: z3.string().optional(),
+  /** Settlement date when the payload/file carries one; null when unknown. Crucial for recon + accounting. */
+  settlementDate: z3.date().nullable(),
+  /**
+   * The untouched provider payload (or file row). The escape hatch that makes
+   * the schema non-lossy (NOT_DOING.md §9). Contains PII — hosts own
+   * encryption-at-rest and retention policy for whatever column stores this.
+   */
+  rawProviderPayload: z3.unknown()
+}).strict().superRefine((t, ctx) => {
+  if (t.netAmountInKobo !== t.amountInKobo - t.feeInKobo) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["netAmountInKobo"],
+      message: `netAmountInKobo (${t.netAmountInKobo}) must equal amountInKobo (${t.amountInKobo}) - feeInKobo (${t.feeInKobo})`
+    });
+  }
+});
+function validateTransaction(input) {
+  return StandardizedTransactionSchema.parse(input);
+}
+
+// src/errors.ts
+var NormalizationError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  code;
+};
+var SignatureVerificationError = class extends NormalizationError {
+  constructor(message, provider) {
+    super(message, "ERR_SIGNATURE_VERIFICATION");
+    this.provider = provider;
+  }
+  provider;
+};
+var MalformedPayloadError = class extends NormalizationError {
+  constructor(message, raw, code = "ERR_MALFORMED_PAYLOAD") {
+    super(message, code);
+    this.raw = raw;
+  }
+  raw;
+};
+var AmountParseError = class extends NormalizationError {
+  constructor(message, input) {
+    super(message, "ERR_AMOUNT_PARSE");
+    this.input = input;
+  }
+  input;
+};
+var UnsupportedFileFormatError = class extends NormalizationError {
+  constructor(message, provider) {
+    super(message, "ERR_UNSUPPORTED_FILE_FORMAT");
+    this.provider = provider;
+  }
+  provider;
+};
+
+// src/schema/money.ts
+var MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+var MAX_AMOUNT_LEN = 40;
+function asKobo(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new AmountParseError(
+      `Expected a non-negative safe integer kobo amount, got: ${String(value)}`,
+      value
+    );
+  }
+  return value;
+}
+function parseKoboInteger(input) {
+  if (typeof input === "number") return asKobo(input);
+  const trimmed = input.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new AmountParseError(
+      `Expected integer kobo string, got: "${input}". If this is a naira decimal, use parseNairaDecimalString().`,
+      input
+    );
+  }
+  const big = BigInt(trimmed);
+  if (big > MAX_SAFE) {
+    throw new AmountParseError(`Kobo amount exceeds MAX_SAFE_INTEGER: "${input}"`, input);
+  }
+  return Number(big);
+}
+function parseNairaDecimalString(input) {
+  const s = typeof input === "number" ? numberToPlainString(input) : input;
+  if (s.length > MAX_AMOUNT_LEN) {
+    throw new AmountParseError(
+      `Naira amount string too long (${s.length} chars); no real amount exceeds ${MAX_AMOUNT_LEN}`,
+      input
+    );
+  }
+  const t = s.trim();
+  const m = /^(?:₦|NGN)?\s*(\d{1,3}(?:,\d{3})+|\d+)(?:\.(\d{1,2}))?$/.exec(t);
+  const wholeGroup = m?.[1];
+  if (!m || wholeGroup === void 0) {
+    throw new AmountParseError(
+      `Cannot parse naira amount: "${String(input)}"`,
+      input
+    );
+  }
+  const whole = BigInt(wholeGroup.replace(/,/g, ""));
+  const fracRaw = m[2] ?? "";
+  const frac = BigInt(fracRaw.padEnd(2, "0") || "0");
+  const kobo = whole * 100n + frac;
+  if (kobo > MAX_SAFE) {
+    throw new AmountParseError(`Amount exceeds MAX_SAFE_INTEGER: "${String(input)}"`, input);
+  }
+  return Number(kobo);
+}
+function koboToNairaString(kobo) {
+  const whole = Math.trunc(kobo / 100);
+  const frac = kobo % 100;
+  return `${whole.toLocaleString("en-NG")}.${String(frac).padStart(2, "0")}`;
+}
+function numberToPlainString(n) {
+  if (!Number.isFinite(n) || n < 0) {
+    throw new AmountParseError(`Cannot parse naira amount: ${String(n)}`, n);
+  }
+  if (Number.isInteger(n)) return String(n);
+  const fixed = n.toFixed(2);
+  if (Math.abs(Number(fixed) - n) > Number.EPSILON * Math.max(1, Math.abs(n))) {
+    throw new AmountParseError(
+      `Naira amount has more than 2 decimal places: ${String(n)}`,
+      n
+    );
+  }
+  return fixed;
+}
+
+// src/connector/result.ts
+function summarizeRows(rows) {
+  const summary = { transactions: 0, unknown: 0, errors: 0 };
+  for (const r of rows) {
+    if (r.kind === "transaction") summary.transactions++;
+    else if (r.kind === "unknown_event") summary.unknown++;
+    else summary.errors++;
+  }
+  return summary;
+}
+
+// src/util/raw-body.ts
+function toRawBody(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new TypeError(
+      "toRawBody expects a Buffer of the exact request bytes. If you only have a parsed object, your middleware consumed the raw body \u2014 use express.raw() (or your framework's equivalent) on webhook routes."
+    );
+  }
+  return buf;
+}
+function rawBodyFromString(s, encoding = "utf8") {
+  return Buffer.from(s, encoding);
+}
+
+// src/util/dedupe.ts
+function composeDedupeKey(provider, providerReference) {
+  const p = provider.trim().toLowerCase();
+  const r = providerReference.trim();
+  if (!p || !r) {
+    throw new Error(
+      `composeDedupeKey requires non-empty provider and reference, got provider="${provider}" reference="${providerReference}"`
+    );
+  }
+  return `${p}:${r}`;
+}
+export {
+  AmountParseError,
+  MalformedPayloadError,
+  NormalizationError,
+  PaymentChannelSchema,
+  STATUS_RANK,
+  SignatureVerificationError,
+  StandardizedTransactionSchema,
+  TransactionStatusSchema,
+  UnsupportedFileFormatError,
+  asKobo,
+  composeDedupeKey,
+  koboToNairaString,
+  parseKoboInteger,
+  parseNairaDecimalString,
+  rawBodyFromString,
+  shouldApplyStatusTransition,
+  statusRank,
+  summarizeRows,
+  toRawBody,
+  validateTransaction
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/transaction.ts","../src/schema/status.ts","../src/schema/channel.ts","../src/errors.ts","../src/schema/money.ts","../src/connector/result.ts","../src/util/raw-body.ts","../src/util/dedupe.ts"],"sourcesContent":["import { z } from \"zod\";\r\nimport { TransactionStatusSchema } from \"./status\";\r\nimport { PaymentChannelSchema } from \"./channel\";\r\nimport type { Kobo } from \"./money\";\r\n\r\n/**\r\n * StandardizedTransaction v1 — the single output shape of every connector.\r\n *\r\n * SCHEMA VERSIONING CONTRACT (NOT_DOING.md §9): v1 fields are frozen.\r\n * Additions ship as OPTIONAL fields in minor versions; renames/removals are v2\r\n * and a new major of every package (semver is the API contract here — hosts\r\n * pin `@scope/core@^1` and must never be broken by a minor).\r\n */\r\n\r\nconst KoboSchema = z\r\n  .number()\r\n  .int(\"money must be integer kobo — parse at the connector boundary, never float\")\r\n  .nonnegative();\r\n\r\nexport const StandardizedTransactionSchema = z\r\n  .object({\r\n    /** Deterministic identity for idempotency: `${provider}:${providerReference}` (see util/dedupe). */\r\n    dedupeKey: z.string().min(3),\r\n\r\n    /** Connector identifier, lowercase: 'nomba' | 'paystack' | 'monnify' | 'opay' | 'palmpay' | 'flutterwave' | ... open set by design — new providers must not require a core release. */\r\n    provider: z.string().min(1).regex(/^[a-z0-9_-]+$/),\r\n\r\n    /** The provider's own transaction reference (txref / transactionReference / orderNo...). */\r\n    providerReference: z.string().min(1),\r\n\r\n    /** Provider's per-DELIVERY event id when one exists — distinguishes redelivery of one event from two events about one transaction. */\r\n    providerEventId: z.string().min(1).optional(),\r\n\r\n    /** Money — integer kobo only. Branded at the type level. */\r\n    amountInKobo: KoboSchema,\r\n    feeInKobo: KoboSchema,\r\n    /** MUST equal amountInKobo - feeInKobo; enforced below so no connector can drift. */\r\n    netAmountInKobo: KoboSchema,\r\n\r\n    /** ISO-4217 uppercase. Non-NGN is tagged and passed through untouched — no FX, no conversion (NOT_DOING.md §10). */\r\n    currency: z.string().regex(/^[A-Z]{3}$/),\r\n\r\n    status: TransactionStatusSchema,\r\n    channel: PaymentChannelSchema,\r\n\r\n    /** credit = money in (collections, VA funding); debit = money out rows encountered when parsing bank statements. Parsing debits ≠ initiating them. */\r\n    direction: z.enum([\"credit\", \"debit\"]),\r\n\r\n    /**\r\n     * When the provider says it happened. CLOCK SKEW WARNING: provider clocks\r\n     * are not your clock, and several send unlabeled WAT strings. Connectors\r\n     * apply an explicit, fixture-tested timezone rule per provider. Hosts must\r\n     * NEVER use this for ordering decisions — that is what STATUS_RANK is for.\r\n     */\r\n    occurredAt: z.date(),\r\n    /** The provider's original timestamp string, preserved verbatim for audit/debugging. */\r\n    occurredAtRaw: z.string().optional(),\r\n\r\n    /** Settlement date when the payload/file carries one; null when unknown. Crucial for recon + accounting. */\r\n    settlementDate: z.date().nullable(),\r\n\r\n    /**\r\n     * The untouched provider payload (or file row). The escape hatch that makes\r\n     * the schema non-lossy (NOT_DOING.md §9). Contains PII — hosts own\r\n     * encryption-at-rest and retention policy for whatever column stores this.\r\n     */\r\n    rawProviderPayload: z.unknown(),\r\n  })\r\n  .strict()\r\n  .superRefine((t, ctx) => {\r\n    if (t.netAmountInKobo !== t.amountInKobo - t.feeInKobo) {\r\n      ctx.addIssue({\r\n        code: z.ZodIssueCode.custom,\r\n        path: [\"netAmountInKobo\"],\r\n        message: `netAmountInKobo (${t.netAmountInKobo}) must equal amountInKobo (${t.amountInKobo}) - feeInKobo (${t.feeInKobo})`,\r\n      });\r\n    }\r\n  });\r\n\r\nexport type StandardizedTransaction = Omit<\r\n  z.infer<typeof StandardizedTransactionSchema>,\r\n  \"amountInKobo\" | \"feeInKobo\" | \"netAmountInKobo\"\r\n> & {\r\n  amountInKobo: Kobo;\r\n  feeInKobo: Kobo;\r\n  netAmountInKobo: Kobo;\r\n};\r\n\r\n/** Runtime gate every connector output passes through before leaving the library. */\r\nexport function validateTransaction(input: unknown): StandardizedTransaction {\r\n  return StandardizedTransactionSchema.parse(input) as StandardizedTransaction;\r\n}\r\n","import { z } from \"zod\";\r\n\r\n/**\r\n * The four terminal-ish states every provider vocabulary maps down to.\r\n * Connectors own the mapping table (e.g. OPay \"SUCCESS\", Paystack \"success\",\r\n * Monnify \"PAID\" -> SUCCESSFUL) — explicitly, per NOT_DOING.md §9:\r\n * no status inference from amount presence or absence of error fields.\r\n */\r\nexport const TransactionStatusSchema = z.enum([\r\n  \"PENDING\",\r\n  \"FAILED\",\r\n  \"SUCCESSFUL\",\r\n  \"REVERSED\",\r\n]);\r\nexport type TransactionStatus = z.infer<typeof TransactionStatusSchema>;\r\n\r\n/**\r\n * STATUS_RANK — the ordering that makes out-of-order webhook delivery safe.\r\n *\r\n * Why this exists (distributed-systems reality, not theory):\r\n *  - Providers deliver webhooks with retries + exponential backoff. Retries mean\r\n *    DUPLICATES; parallel delivery paths + network partitions mean REORDERING.\r\n *    A \"pending\" emitted at T0 can arrive AFTER the \"successful\" emitted at T1.\r\n *  - You cannot fix this with timestamps: provider clocks skew, and several\r\n *    providers send unlabeled local-time (WAT) strings. Ordering by rank is\r\n *    deterministic; ordering by clock is a race condition wearing a watch.\r\n *\r\n * REVERSED outranks SUCCESSFUL deliberately: success->reversal is a legitimate\r\n * forward progression (refunds, chargebacks). PENDING can never overwrite anything.\r\n * FAILED -> SUCCESSFUL is allowed (rank 1 -> 2): some providers emit a failure\r\n * then succeed on an internal retry under the same reference.\r\n */\r\nexport const STATUS_RANK: Readonly<Record<TransactionStatus, number>> = Object.freeze({\r\n  PENDING: 0,\r\n  FAILED: 1,\r\n  SUCCESSFUL: 2,\r\n  REVERSED: 3,\r\n});\r\n\r\nexport function statusRank(status: TransactionStatus): number {\r\n  return STATUS_RANK[status];\r\n}\r\n\r\n/**\r\n * The one-line correctness rule for host applications:\r\n *\r\n *   if (!shouldApplyStatusTransition(stored.status, incoming.status)) skip;\r\n *\r\n * Equal rank returns false — re-delivery of the same status is a no-op\r\n * (idempotency). Host must pair this with:\r\n *   1. a UNIQUE index on dedupeKey (hard idempotency at the storage layer), and\r\n *   2. optimistic locking (version column / compare-and-swap) or\r\n *      SELECT ... FOR UPDATE when applying the transition, because two webhook\r\n *      deliveries for the same transaction WILL race on concurrent workers.\r\n * This library is stateless by design (NOT_DOING.md §6) — it hands you the\r\n * rule; your database enforces it.\r\n */\r\nexport function shouldApplyStatusTransition(\r\n  current: TransactionStatus,\r\n  incoming: TransactionStatus\r\n): boolean {\r\n  return STATUS_RANK[incoming] > STATUS_RANK[current];\r\n}\r\n","import { z } from \"zod\";\r\n\r\n/**\r\n * How the money moved. 'unknown' is a legitimate value — bank statement rows\r\n * frequently do not disclose the channel, and guessing violates NOT_DOING.md §9.\r\n * 'pos' covers agent/terminal collections (OPay, PalmPay, Moniepoint territory).\r\n */\r\nexport const PaymentChannelSchema = z.enum([\r\n  \"card\",\r\n  \"bank_transfer\",\r\n  \"ussd\",\r\n  \"qr\",\r\n  \"wallet\",\r\n  \"pos\",\r\n  \"unknown\",\r\n]);\r\nexport type PaymentChannel = z.infer<typeof PaymentChannelSchema>;\r\n","/**\n * Typed errors so hosts can route failures without string-matching messages.\n * Connectors throw these ONLY inside their own boundary; parseWebhook /\n * parseSettlementFile catch them and return `parse_error` results instead\n * (see connector/result.ts) — a malformed payload from one provider must never\n * crash a host's webhook endpoint (that would turn one bad payload into an\n * availability incident: the provider retries, you 500, backoff kicks in,\n * and every later event for that endpoint queues behind the poison message).\n */\n\n/**\n * Machine-readable error codes — stable API, unlike messages, which may be\n * reworded in a PATCH release. Route on `error.code` (or instanceof), never\n * on `error.message`.\n */\nexport type NormalizationErrorCode =\n  | \"ERR_SIGNATURE_VERIFICATION\"\n  | \"ERR_MALFORMED_PAYLOAD\"\n  | \"ERR_AMOUNT_PARSE\"\n  | \"ERR_UNSUPPORTED_FILE_FORMAT\"\n  | \"ERR_TIMESTAMP_MISSING\";\n\nexport class NormalizationError extends Error {\n  constructor(message: string, public readonly code: NormalizationErrorCode) {\n    super(message);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Signature header missing, malformed, or HMAC mismatch. Host should respond 401 and NOT process. */\nexport class SignatureVerificationError extends NormalizationError {\n  constructor(message: string, public readonly provider?: string) {\n    super(message, \"ERR_SIGNATURE_VERIFICATION\");\n  }\n}\n\n/**\n * Payload structurally unusable: not JSON, missing required fields, wrong\n * shapes. `code` may be narrowed (e.g. ERR_TIMESTAMP_MISSING) when the defect\n * is specific enough for a host — or a caller — to act on programmatically.\n */\nexport class MalformedPayloadError extends NormalizationError {\n  constructor(\n    message: string,\n    public readonly raw?: unknown,\n    code: NormalizationErrorCode = \"ERR_MALFORMED_PAYLOAD\"\n  ) {\n    super(message, code);\n  }\n}\n\n/** Amount could not be converted to Kobo safely. Carries the offending input for logs. */\nexport class AmountParseError extends NormalizationError {\n  constructor(message: string, public readonly input?: unknown) {\n    super(message, \"ERR_AMOUNT_PARSE\");\n  }\n}\n\n/** Settlement/statement file is not a format this connector version supports. */\nexport class UnsupportedFileFormatError extends NormalizationError {\n  constructor(message: string, public readonly provider?: string) {\n    super(message, \"ERR_UNSUPPORTED_FILE_FORMAT\");\n  }\n}\n","import { AmountParseError } from \"../errors\";\r\n\r\n/**\r\n * Kobo — the ONLY representation of money inside this library.\r\n *\r\n * Branded type: a plain `number` will not typecheck where `Kobo` is required,\r\n * so unconverted provider amounts cannot leak past the connector boundary.\r\n *\r\n * Rules (NOT_DOING.md §9):\r\n *  - Integers only. Floats are banned; all parsing below uses string/BigInt math,\r\n *    so `\"5000.10\"` can never become `500009.999...` via IEEE-754.\r\n *  - Conversion happens exactly ONCE, at the connector boundary, via the\r\n *    parsers in this file. Core and hosts only ever see Kobo.\r\n */\r\nexport type Kobo = number & { readonly __brand: \"Kobo\" };\r\n\r\nconst MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);\r\n\r\n/**\r\n * Hard length ceiling for amount strings. The largest representable value —\r\n * MAX_SAFE_INTEGER kobo (~90 trillion naira) with thousands separators, two\r\n * decimals, and a currency prefix — is ~24 chars. 40 leaves generous slack\r\n * while making any hostile megabyte-long string an O(1) rejection BEFORE it\r\n * reaches the regex below (defense against ReDoS; see parseNairaDecimalString).\r\n */\r\nconst MAX_AMOUNT_LEN = 40;\r\n\r\n/** Assert an already-integer amount is valid Kobo (e.g. Paystack's `amount` field). */\r\nexport function asKobo(value: number): Kobo {\r\n  if (!Number.isSafeInteger(value) || value < 0) {\r\n    throw new AmountParseError(\r\n      `Expected a non-negative safe integer kobo amount, got: ${String(value)}`,\r\n      value\r\n    );\r\n  }\r\n  return value as Kobo;\r\n}\r\n\r\n/**\r\n * Parse a kobo amount that arrives as an integer-looking value.\r\n * Accepts `500000` or `\"500000\"`. Rejects decimals — if a provider sends\r\n * decimals, it is a naira amount and MUST go through parseNairaDecimalString.\r\n */\r\nexport function parseKoboInteger(input: number | string): Kobo {\r\n  if (typeof input === \"number\") return asKobo(input);\r\n  const trimmed = input.trim();\r\n  if (!/^\\d+$/.test(trimmed)) {\r\n    throw new AmountParseError(\r\n      `Expected integer kobo string, got: \"${input}\". ` +\r\n        `If this is a naira decimal, use parseNairaDecimalString().`,\r\n      input\r\n    );\r\n  }\r\n  const big = BigInt(trimmed);\r\n  if (big > MAX_SAFE) {\r\n    throw new AmountParseError(`Kobo amount exceeds MAX_SAFE_INTEGER: \"${input}\"`, input);\r\n  }\r\n  return Number(big) as Kobo;\r\n}\r\n\r\n/**\r\n * Parse naira expressed as a decimal string or number into Kobo, using\r\n * string math only (never parseFloat).\r\n *\r\n * Accepts the shapes actually seen across Nigerian providers:\r\n *   \"5000\"      -> 500000\r\n *   \"5000.00\"   -> 500000\r\n *   \"5000.5\"    -> 500050   (one decimal place = tens of kobo)\r\n *   \"5,000.00\"  -> 500000   (thousands separators)\r\n *   5000        -> 500000   (numeric naira, e.g. Monnify amounts)\r\n *   \"₦5,000.00\" -> 500000\r\n *\r\n * Rejects: negatives, >2 decimal places (no such thing as half a kobo),\r\n * empty strings, scientific notation, over-long input, and anything ambiguous.\r\n */\r\nexport function parseNairaDecimalString(input: string | number): Kobo {\r\n  const s = typeof input === \"number\" ? numberToPlainString(input) : input;\r\n  if (s.length > MAX_AMOUNT_LEN) {\r\n    throw new AmountParseError(\r\n      `Naira amount string too long (${s.length} chars); no real amount exceeds ${MAX_AMOUNT_LEN}`,\r\n      input\r\n    );\r\n  }\r\n  // ReDoS-safe matching: trim once so the pattern carries a SINGLE internal\r\n  // \\s* run. The prior `^\\s*…\\s*$` form let leading and trailing whitespace\r\n  // runs trade off against each other, backtracking O(n²) on inputs like\r\n  // \"   …   x\". Trimming + one \\s* keeps it linear; the length cap above is\r\n  // belt-and-suspenders.\r\n  const t = s.trim();\r\n  const m = /^(?:₦|NGN)?\\s*(\\d{1,3}(?:,\\d{3})+|\\d+)(?:\\.(\\d{1,2}))?$/.exec(t);\r\n  const wholeGroup = m?.[1];\r\n  if (!m || wholeGroup === undefined) {\r\n    throw new AmountParseError(\r\n      `Cannot parse naira amount: \"${String(input)}\"`,\r\n      input\r\n    );\r\n  }\r\n  const whole = BigInt(wholeGroup.replace(/,/g, \"\"));\r\n  const fracRaw = m[2] ?? \"\";\r\n  const frac = BigInt(fracRaw.padEnd(2, \"0\") || \"0\");\r\n  const kobo = whole * 100n + frac;\r\n  if (kobo > MAX_SAFE) {\r\n    throw new AmountParseError(`Amount exceeds MAX_SAFE_INTEGER: \"${String(input)}\"`, input);\r\n  }\r\n  return Number(kobo) as Kobo;\r\n}\r\n\r\n/** Display helper only. Never feed its output back into parsing logic. */\r\nexport function koboToNairaString(kobo: Kobo): string {\r\n  const whole = Math.trunc(kobo / 100);\r\n  const frac = kobo % 100;\r\n  return `${whole.toLocaleString(\"en-NG\")}.${String(frac).padStart(2, \"0\")}`;\r\n}\r\n\r\n/**\r\n * Numeric naira input (e.g. Monnify sends `amount: 5000.5`) is converted to a\r\n * plain decimal string first so that BigInt string math — not float math —\r\n * performs the kobo conversion. toFixed(2) here is safe: provider amounts are\r\n * far below the ~2^53/100 threshold where representation error could shift a kobo,\r\n * and >2dp inputs are rejected as invalid money anyway.\r\n */\r\nfunction numberToPlainString(n: number): string {\r\n  if (!Number.isFinite(n) || n < 0) {\r\n    throw new AmountParseError(`Cannot parse naira amount: ${String(n)}`, n);\r\n  }\r\n  if (Number.isInteger(n)) return String(n);\r\n  const fixed = n.toFixed(2);\r\n  // Guard: reject inputs with >2dp of real precision (e.g. 5000.505)\r\n  if (Math.abs(Number(fixed) - n) > Number.EPSILON * Math.max(1, Math.abs(n))) {\r\n    throw new AmountParseError(\r\n      `Naira amount has more than 2 decimal places: ${String(n)}`,\r\n      n\r\n    );\r\n  }\r\n  return fixed;\r\n}\r\n","import type { StandardizedTransaction } from \"../schema/transaction\";\r\nimport type { MalformedPayloadError, AmountParseError } from \"../errors\";\r\n\r\n/**\r\n * Every parse returns one of these — connectors NEVER throw on weird input and\r\n * NEVER return null. The type system enforces NOT_DOING.md §9:\r\n * \"no swallowing unknown events.\"\r\n *\r\n * Host handling guidance:\r\n *  - 'transaction'   -> idempotent upsert (unique dedupeKey + STATUS_RANK guard), ACK 200.\r\n *  - 'unknown_event' -> log + store raw, ACK 200. Unknown ≠ error: providers add\r\n *                       event types without notice; NACKing them makes the provider\r\n *                       retry forever (their backoff, your log spam).\r\n *  - 'parse_error'   -> the poison-message case. ACK 200 (do NOT make the provider\r\n *                       retry a payload that will fail identically), park the raw\r\n *                       payload in your own dead-letter store, alert. This library\r\n *                       ships no queue (NOT_DOING.md §6) — the DLQ is yours.\r\n */\r\nexport type ParseResult =\r\n  | { kind: \"transaction\"; transaction: StandardizedTransaction }\r\n  | {\r\n      kind: \"unknown_event\";\r\n      provider: string;\r\n      /** Provider's own event-type string when discoverable, else \"unrecognized\". */\r\n      eventType: string;\r\n      raw: unknown;\r\n    }\r\n  | {\r\n      kind: \"parse_error\";\r\n      provider: string;\r\n      error: MalformedPayloadError | AmountParseError;\r\n      raw: unknown;\r\n    };\r\n\r\n/**\r\n * Result of parsing a settlement/statement file. Row-level isolation: one\r\n * mangled row (bank exports love those) yields one parse_error result — the\r\n * other 4,999 rows still normalize. All-or-nothing file parsing punishes the\r\n * host for the provider's data quality.\r\n */\r\nexport interface SettlementFileParseResult {\r\n  provider: string;\r\n  /** e.g. 'nomba-settlement-csv-v1' — which fixture-tested format matched. */\r\n  format: string;\r\n  rows: ParseResult[];\r\n  /** Row counts by outcome, so hosts can alert on anomaly ratios cheaply. */\r\n  summary: { transactions: number; unknown: number; errors: number };\r\n}\r\n\r\nexport function summarizeRows(rows: ParseResult[]): SettlementFileParseResult[\"summary\"] {\r\n  const summary = { transactions: 0, unknown: 0, errors: 0 };\r\n  for (const r of rows) {\r\n    if (r.kind === \"transaction\") summary.transactions++;\r\n    else if (r.kind === \"unknown_event\") summary.unknown++;\r\n    else summary.errors++;\r\n  }\r\n  return summary;\r\n}\r\n","/**\r\n * RawBody — a branded Buffer that connectors require for signature verification.\r\n *\r\n * THE #1 INTEGRATION BUG THIS PREVENTS:\r\n * Providers compute webhook signatures (HMAC-SHA512 for Paystack, provider-specific\r\n * schemes elsewhere) over the EXACT BYTES they sent. If a host runs the request\r\n * through `express.json()` and later re-serializes (`JSON.stringify(req.body)`),\r\n * key order, whitespace, and unicode escaping can change — the HMAC no longer\r\n * matches, and the host spends a night debugging \"invalid signature\" on\r\n * perfectly valid webhooks.\r\n *\r\n * By requiring `RawBody` (constructible only from a Buffer via `toRawBody`),\r\n * a host that only has parsed JSON gets a COMPILE ERROR instead of a 2am mystery.\r\n *\r\n * Express hosts: mount `express.raw({ type: \"application/json\" })` on webhook\r\n * routes (route-scoped, before any json middleware), then `toRawBody(req.body)`.\r\n * Parse to JSON only AFTER verification, from these same bytes.\r\n */\r\nexport type RawBody = Buffer & { readonly __brand: \"RawBody\" };\r\n\r\nexport function toRawBody(buf: Buffer): RawBody {\r\n  if (!Buffer.isBuffer(buf)) {\r\n    throw new TypeError(\r\n      \"toRawBody expects a Buffer of the exact request bytes. \" +\r\n        \"If you only have a parsed object, your middleware consumed the raw body — \" +\r\n        \"use express.raw() (or your framework's equivalent) on webhook routes.\"\r\n    );\r\n  }\r\n  return buf as RawBody;\r\n}\r\n\r\n/**\r\n * Escape hatch for tests and fixture replay ONLY. Constructing a RawBody from a\r\n * string in production risks re-serialization drift — fixtures store the\r\n * original bytes precisely so this stays faithful.\r\n */\r\nexport function rawBodyFromString(s: string, encoding: BufferEncoding = \"utf8\"): RawBody {\r\n  return Buffer.from(s, encoding) as RawBody;\r\n}\r\n","/**\r\n * Dedupe keys — idempotency for a world where providers retry webhooks.\r\n *\r\n * Webhook delivery is at-least-once everywhere: providers retry on timeout with\r\n * exponential backoff, and some (OPay callbacks, observed) simply double-fire.\r\n * The ONLY reliable defense is idempotent ingestion:\r\n *\r\n *   CREATE UNIQUE INDEX ux_txn_dedupe ON transactions (dedupe_key);\r\n *\r\n * then INSERT ... ON CONFLICT DO NOTHING (or the equivalent upsert guarded by\r\n * shouldApplyStatusTransition for status updates). Enforcing uniqueness in\r\n * application code alone is a race condition — two workers processing the same\r\n * redelivered webhook concurrently will both pass an \"does it exist?\" check.\r\n * The database constraint is the lock.\r\n *\r\n * Key shape: `${provider}:${providerReference}` — namespaced so Paystack ref\r\n * \"TX123\" and Nomba ref \"TX123\" never collide. Connectors may override\r\n * dedupeKey() when a provider's reference is not unique per transaction\r\n * (e.g. one reference spanning multiple settlement rows) — that quirk knowledge\r\n * lives in the connector, backed by fixtures.\r\n */\r\nexport function composeDedupeKey(provider: string, providerReference: string): string {\r\n  const p = provider.trim().toLowerCase();\r\n  const r = providerReference.trim();\r\n  if (!p || !r) {\r\n    throw new Error(\r\n      `composeDedupeKey requires non-empty provider and reference, got provider=\"${provider}\" reference=\"${providerReference}\"`\r\n    );\r\n  }\r\n  return `${p}:${r}`;\r\n}\r\n"],"mappings":"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","names":["z","z","z"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pay-normalize/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "pay-normalize-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --sourcemap",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p .",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "The contract for pay-normalize: schema, money (Kobo), status ordering, dedupe, errors, and the Connector interface.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lordisrael1/pay-normalize.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/lordisrael1/pay-normalize/issues",
+  "homepage": "https://github.com/lordisrael1/pay-normalize/tree/main/packages/core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  }
+}