@cogenta/commerce 0.2.0

package/dist/payment/stripe.js

@@ -0,0 +1,419 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { CogentaError } from '@cogenta/core';
+/**
+ * The optimal payment driver: a real Stripe client, written against Stripe's
+ * REST API rather than the `stripe` npm package.
+ *
+ * Rule R9 — "préférer zéro dépendance à une petite dépendance". The `stripe`
+ * package is neither small nor free: it pulls a full HTTP stack and a very
+ * large set of generated types for the four calls this driver makes. The same
+ * precedent already exists in this codebase (`@cogenta/channels`' hand-written
+ * Telegram/Slack/Discord clients, `@cogenta/import`'s hand-rolled WXR parser).
+ *
+ * The wire format is not guessed: Stripe's API takes
+ * `application/x-www-form-urlencoded` in, answers JSON, and authenticates with
+ * `Authorization: Bearer <secret key>`. Nested keys use the bracket syntax
+ * (`metadata[order_reference]`), which `URLSearchParams` encodes correctly.
+ */
+const DEFAULT_API_BASE_URL = 'https://api.stripe.com';
+/** Stripe's own recommendation for a webhook freshness window. */
+const SIGNATURE_FRESHNESS_WINDOW_SECONDS = 5 * 60;
+/** Long enough for a real payment call, short enough that a hung TCP connection is not a hung checkout. */
+const REQUEST_TIMEOUT_MS = 20_000;
+/** An availability probe answers fast or it does not answer: the registry is waiting to fall through. */
+const AVAILABILITY_TIMEOUT_MS = 3_000;
+/**
+ * Stripe's PaymentIntent vocabulary, mapped onto the six statuses of the
+ * `PaymentGateway` contract. Everything before the money moves is `pending`;
+ * a manual-capture intent holding funds is `authorised`.
+ */
+const INTENT_STATUS_MAP = {
+    requires_payment_method: 'pending',
+    requires_confirmation: 'pending',
+    requires_action: 'pending',
+    processing: 'pending',
+    requires_capture: 'authorised',
+    succeeded: 'paid',
+    canceled: 'cancelled',
+};
+/** Stripe's Refund vocabulary, mapped onto the three a `DriverRefundResult` carries. */
+const REFUND_STATUS_MAP = {
+    pending: 'pending',
+    requires_action: 'pending',
+    succeeded: 'refunded',
+    failed: 'failed',
+    canceled: 'failed',
+};
+/**
+ * The inbound events this driver understands. Every one of them is a statement
+ * about where the money is; an event type outside this table is refused rather
+ * than mapped to a guess, because guessing "paid" is how goods leave for free.
+ */
+const EVENT_TYPE_STATUS = {
+    'payment_intent.succeeded': 'paid',
+    'payment_intent.payment_failed': 'failed',
+    'payment_intent.canceled': 'cancelled',
+    'charge.refunded': 'refunded',
+};
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function readString(source, key) {
+    const value = source?.[key];
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+function readNumber(source, key) {
+    const value = source?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * The one place a Stripe failure becomes a Cogenta failure.
+ *
+ * `details` carries the status code and Stripe's own error identifiers, and
+ * nothing else — never the request headers, never the URL with credentials,
+ * never the secret key (rule R7). An operator gets what they need to find the
+ * call in the Stripe dashboard; a log reader gets nothing they could spend.
+ */
+function paymentFailed(message, hint, details, cause) {
+    return new CogentaError({
+        code: 'COMMERCE_PAYMENT_FAILED',
+        message,
+        hint,
+        details,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function signatureInvalid(reason) {
+    return new CogentaError({
+        code: 'COMMERCE_PAYMENT_SIGNATURE_INVALID',
+        message: `The Stripe webhook signature was refused: ${reason}.`,
+        hint: 'Check that payment.webhookSecret matches the signing secret shown for this endpoint in the Stripe dashboard, that the raw request body is passed unparsed, and that the clock on this server is correct.',
+        details: { reason },
+    });
+}
+/**
+ * Constant-time comparison of two hex digests.
+ *
+ * Same discipline as `@cogenta/channels`' inbound webhook verification: length
+ * is checked first because `timingSafeEqual` throws on a mismatch, and the
+ * comparison itself never short-circuits on the first differing byte.
+ */
+function digestsMatch(expected, received) {
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(received, 'utf8');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Parses `t=1614556800,v1=<hex>,v1=<hex>`.
+ *
+ * More than one `v1` is normal, not an anomaly: during a signing-secret
+ * rotation Stripe signs each delivery with both secrets, and an endpoint that
+ * only looks at the first one goes deaf halfway through the rotation.
+ */
+function parseSignatureHeader(header) {
+    let timestamp = null;
+    const signatures = [];
+    for (const part of header.split(',')) {
+        const separator = part.indexOf('=');
+        if (separator === -1)
+            continue;
+        const key = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (key === 't') {
+            const parsed = Number(value);
+            if (Number.isFinite(parsed))
+                timestamp = parsed;
+        }
+        else if (key === 'v1' && value !== '') {
+            signatures.push(value);
+        }
+    }
+    return { timestamp, signatures };
+}
+/** Header names arrive however the HTTP server spelled them; Stripe's is `stripe-signature`. */
+function headerValue(headers, name) {
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * A real Stripe gateway.
+ *
+ * `stripePaymentDriver()` is the driver (selection, availability, health);
+ * this is the instance it hands back once a secret key is known to exist.
+ */
+function createStripeGateway(secretKey, baseUrl, webhookSecret, options) {
+    const now = options.now ?? Date.now;
+    const logger = options.logger;
+    async function call(path, init) {
+        let response;
+        try {
+            response = await fetch(`${baseUrl}${path}`, {
+                method: init.method,
+                headers: {
+                    authorization: `Bearer ${secretKey}`,
+                    ...(init.form === undefined
+                        ? {}
+                        : { 'content-type': 'application/x-www-form-urlencoded' }),
+                },
+                ...(init.form === undefined ? {} : { body: init.form.toString() }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw paymentFailed(`Stripe could not be reached for ${init.method} ${path}.`, 'Check outbound network access from this server, and whether Stripe is reporting an incident.', { path, method: init.method }, error);
+        }
+        const text = await response.text();
+        const parsed = text === '' ? null : safeJsonParse(text);
+        const body = asRecord(parsed);
+        if (!response.ok) {
+            const stripeError = asRecord(body?.error);
+            throw paymentFailed(`Stripe refused ${init.method} ${path} with HTTP ${response.status}: ${readString(stripeError, 'message') ?? 'no reason given'}`, 'Check the amount, the currency and the payment method in the Stripe dashboard; a 401 means the secret key is wrong or revoked.', {
+                path,
+                method: init.method,
+                status: response.status,
+                // Stripe's own identifiers for the failure. Never the key, never the
+                // request headers.
+                stripeErrorType: readString(stripeError, 'type'),
+                stripeErrorCode: readString(stripeError, 'code'),
+            });
+        }
+        if (body === null) {
+            throw paymentFailed(`Stripe answered ${init.method} ${path} with something that is not a JSON object.`, 'This is usually a proxy or a captive portal answering instead of Stripe; check payment.apiBaseUrl and the outbound route.', { path, method: init.method, status: response.status });
+        }
+        return body;
+    }
+    function safeJsonParse(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** An unknown status is reported, never guessed: `failed` is the safe reading. */
+    function mapIntentStatus(status, externalId) {
+        const mapped = status === null ? undefined : INTENT_STATUS_MAP[status];
+        if (mapped !== undefined)
+            return mapped;
+        logger?.warn('Stripe reported a payment intent status this driver does not know.', {
+            driver: 'stripe',
+            stripeStatus: status,
+            externalId,
+            mappedTo: 'failed',
+        });
+        return 'failed';
+    }
+    function toStartedPayment(intent) {
+        const externalId = readString(intent, 'id');
+        if (externalId === null) {
+            throw paymentFailed('Stripe returned a payment intent without an id.', 'Retry the payment; if it recurs, check the Stripe API version configured on the account.', { received: Object.keys(intent) });
+        }
+        return {
+            externalId,
+            status: mapIntentStatus(readString(intent, 'status'), externalId),
+            // The client secret is what the shopper's browser needs to finish the
+            // payment. It is scoped to this one intent and is meant to reach the
+            // front end — it is not an account credential.
+            instructions: readString(intent, 'client_secret'),
+        };
+    }
+    return {
+        name: 'stripe',
+        settlesOffline: false,
+        start: async (request) => {
+            const form = new URLSearchParams();
+            form.set('amount', String(request.amountMinor));
+            // Stripe rejects an upper-case code.
+            form.set('currency', request.currency.toLowerCase());
+            // The reference, not the internal id: this is what comes back on the
+            // webhook and what a human reads on a statement.
+            form.set('metadata[order_reference]', request.orderReference);
+            form.set('receipt_email', request.customerEmail);
+            // Lets the account's own payment-method settings decide what the shopper
+            // is offered, instead of hard-coding "card" here.
+            form.set('automatic_payment_methods[enabled]', 'true');
+            if (request.description !== undefined)
+                form.set('description', request.description);
+            return toStartedPayment(await call('/v1/payment_intents', { method: 'POST', form }));
+        },
+        fetch: async (externalId) => toStartedPayment(await call(`/v1/payment_intents/${encodeURIComponent(externalId)}`, { method: 'GET' })),
+        refund: async (request) => {
+            const form = new URLSearchParams();
+            form.set('payment_intent', request.externalId);
+            // Always explicit: omitting it refunds the whole intent, which is not
+            // what a partial refund asked for.
+            form.set('amount', String(request.amountMinor));
+            const refund = await call('/v1/refunds', { method: 'POST', form });
+            const status = readString(refund, 'status');
+            const mapped = status === null ? undefined : REFUND_STATUS_MAP[status];
+            if (mapped === undefined) {
+                logger?.warn('Stripe reported a refund status this driver does not know.', {
+                    driver: 'stripe',
+                    stripeStatus: status,
+                    paymentIntent: request.externalId,
+                    mappedTo: 'failed',
+                });
+            }
+            return { externalId: readString(refund, 'id'), status: mapped ?? 'failed' };
+        },
+        verifyEvent: async (payload, headers) => {
+            const header = headerValue(headers, 'stripe-signature');
+            if (header === undefined || header === '')
+                throw signatureInvalid('no stripe-signature header');
+            if (webhookSecret === undefined || webhookSecret === '') {
+                throw signatureInvalid('no webhook secret is configured for this site');
+            }
+            const { timestamp, signatures } = parseSignatureHeader(header);
+            if (timestamp === null)
+                throw signatureInvalid('the header carried no usable timestamp');
+            if (signatures.length === 0)
+                throw signatureInvalid('the header carried no v1 signature');
+            // Freshness before authenticity: a captured, genuinely-signed delivery
+            // stays genuinely signed forever, so the window is what stops a replay.
+            const ageSeconds = Math.abs(Math.floor(now() / 1000) - timestamp);
+            if (ageSeconds > SIGNATURE_FRESHNESS_WINDOW_SECONDS) {
+                throw signatureInvalid(`the signed timestamp is ${ageSeconds}s away from now, outside the ${SIGNATURE_FRESHNESS_WINDOW_SECONDS}s window`);
+            }
+            const expected = createHmac('sha256', webhookSecret)
+                .update(`${timestamp}.${payload}`)
+                .digest('hex');
+            // Every v1 is tried, and the loop never breaks early on a match, so the
+            // number of comparisons does not depend on which secret signed it.
+            let matched = false;
+            for (const candidate of signatures) {
+                if (digestsMatch(expected, candidate))
+                    matched = true;
+            }
+            if (!matched)
+                throw signatureInvalid('no v1 signature matched the configured secret');
+            const event = asRecord(safeJsonParse(payload));
+            const type = readString(event, 'type');
+            const status = type === null ? undefined : EVENT_TYPE_STATUS[type];
+            if (status === undefined) {
+                throw new CogentaError({
+                    code: 'COMMERCE_PAYMENT_UNSUPPORTED',
+                    message: `This driver has no reading for the Stripe event "${type ?? 'unknown'}".`,
+                    hint: `Narrow the endpoint in the Stripe dashboard to ${Object.keys(EVENT_TYPE_STATUS).join(', ')}.`,
+                    details: { eventType: type },
+                });
+            }
+            const object = asRecord(asRecord(event?.data)?.object);
+            // On a charge, the intent lives in `payment_intent`; on an intent, it is
+            // the object's own id. The store keys payments by the intent either way.
+            const externalId = type === 'charge.refunded'
+                ? (readString(object, 'payment_intent') ?? readString(object, 'id'))
+                : readString(object, 'id');
+            if (externalId === null) {
+                throw paymentFailed(`The Stripe event "${type}" carried no payment identifier.`, 'Check the API version configured on the Stripe account: an older version shapes this event differently.', { eventType: type });
+            }
+            const amountMinor = type === 'charge.refunded'
+                ? (readNumber(object, 'amount_refunded') ?? readNumber(object, 'amount'))
+                : readNumber(object, 'amount');
+            const currency = readString(object, 'currency');
+            return {
+                externalId,
+                orderReference: readString(asRecord(object?.metadata), 'order_reference'),
+                status,
+                amountMinor,
+                // Stripe sends a lower-case code; every stored record in this package
+                // holds the ISO 4217 upper-case one.
+                currency: currency === null ? null : currency.toUpperCase(),
+            };
+        },
+    };
+}
+export function stripePaymentDriver(options = {}) {
+    let gateway;
+    let probe;
+    const resolveBaseUrl = (config) => (config.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    return {
+        name: 'stripe',
+        tier: 'optimal',
+        /**
+         * Does Stripe actually answer with this key? Not "is a key configured?" —
+         * the registry reads a `false` as "fall through to the offline driver", so
+         * this must never throw, and must never hang a startup either.
+         */
+        available: async (config) => {
+            if (config.secretKey === undefined || config.secretKey === '')
+                return false;
+            try {
+                const response = await fetch(`${resolveBaseUrl(config)}/v1/balance`, {
+                    method: 'GET',
+                    headers: { authorization: `Bearer ${config.secretKey}` },
+                    signal: AbortSignal.timeout(AVAILABILITY_TIMEOUT_MS),
+                });
+                // The body is drained so the socket is released rather than left open
+                // for the timeout to reap.
+                await response.text();
+                return response.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+        init: async (config) => {
+            if (config.secretKey === undefined || config.secretKey === '') {
+                throw new CogentaError({
+                    code: 'CONFIG_INVALID',
+                    message: 'The Stripe payment driver needs a secret key.',
+                    hint: 'Set payment.secretKey (or the COGENTA_PAYMENT_SECRET_KEY environment variable), or leave payment.driver unset to be paid by bank transfer.',
+                });
+            }
+            const baseUrl = resolveBaseUrl(config);
+            probe = { secretKey: config.secretKey, baseUrl };
+            gateway ??= createStripeGateway(config.secretKey, baseUrl, config.webhookSecret, options);
+            return gateway;
+        },
+        dispose: async () => {
+            // Nothing to close: every call is a one-shot `fetch`.
+            gateway = undefined;
+            probe = undefined;
+        },
+        health: async () => {
+            if (probe === undefined) {
+                return { status: 'down', driver: 'stripe', tier: 'optimal', message: 'Not configured.' };
+            }
+            const startedAt = Date.now();
+            try {
+                const response = await fetch(`${probe.baseUrl}/v1/balance`, {
+                    method: 'GET',
+                    headers: { authorization: `Bearer ${probe.secretKey}` },
+                    signal: AbortSignal.timeout(AVAILABILITY_TIMEOUT_MS),
+                });
+                await response.text();
+                return response.ok
+                    ? {
+                        status: 'ok',
+                        driver: 'stripe',
+                        tier: 'optimal',
+                        latencyMs: Date.now() - startedAt,
+                        // The key is never named, not even partially.
+                        message: 'Stripe answered.',
+                    }
+                    : {
+                        status: 'down',
+                        driver: 'stripe',
+                        tier: 'optimal',
+                        latencyMs: Date.now() - startedAt,
+                        message: `Stripe refused the account check with HTTP ${response.status}.`,
+                        details: { status: response.status },
+                    };
+            }
+            catch {
+                return {
+                    status: 'down',
+                    driver: 'stripe',
+                    tier: 'optimal',
+                    message: 'Stripe did not answer.',
+                };
+            }
+        },
+    };
+}
+//# sourceMappingURL=stripe.js.map

package/dist/payment/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","sourceRoot":"","sources":["../../src/payment/stripe.ts"],"names":[],"mappings":"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"}

package/dist/payment/types.d.ts

@@ -0,0 +1,124 @@
+import type { Driver, DriverChoice } from '@cogenta/core';
+/**
+ * Where a payment is in its life. Deliberately small.
+ *
+ * A gateway has dozens of internal states; a shop needs to know whether it has
+ * the money. Every driver maps its own vocabulary onto these six, so the order
+ * store never branches on a gateway-specific string.
+ */
+export declare const PAYMENT_STATUSES: readonly [
+/** Created, waiting for the shopper (or for a bank transfer to arrive). */
+'pending', 
+/** The gateway holds the funds but has not moved them. */
+'authorised', 'paid', 'failed', 'cancelled', 'refunded'];
+export type PaymentStatus = (typeof PAYMENT_STATUSES)[number];
+export interface PaymentRecord {
+    readonly id: string;
+    readonly orderId: string;
+    readonly driver: string;
+    /** The gateway's own identifier, or null for a driver that has none yet. */
+    readonly externalId: string | null;
+    readonly status: PaymentStatus;
+    readonly amountMinor: number;
+    readonly currency: string;
+    /** Shown to the shopper: bank details, or a URL to finish the payment. */
+    readonly instructions: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface RefundRecord {
+    readonly id: string;
+    readonly paymentId: string;
+    readonly orderId: string;
+    readonly externalId: string | null;
+    readonly status: 'pending' | 'refunded' | 'failed';
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly reason: string | null;
+    readonly createdAt: string;
+}
+export interface StartPaymentRequest {
+    readonly orderId: string;
+    readonly orderReference: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly customerEmail: string;
+    /** Where the shopper should end up after a redirect, if the driver uses one. */
+    readonly returnUrl?: string;
+    readonly description?: string;
+}
+/** What a driver hands back. Never a record: the store owns persistence. */
+export interface StartedPayment {
+    readonly externalId: string | null;
+    readonly status: PaymentStatus;
+    readonly instructions: string | null;
+}
+export interface DriverRefundRequest {
+    readonly externalId: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly reason?: string;
+}
+export interface DriverRefundResult {
+    readonly externalId: string | null;
+    readonly status: 'pending' | 'refunded' | 'failed';
+}
+/**
+ * A payment event that arrived from outside, already proven authentic.
+ *
+ * `orderReference` rather than `orderId`: what comes back from a gateway is
+ * whatever was put in when the payment started, and a reference is what a
+ * human reads on a bank statement.
+ */
+export interface PaymentEvent {
+    readonly externalId: string;
+    readonly orderReference: string | null;
+    readonly status: PaymentStatus;
+    readonly amountMinor: number | null;
+    readonly currency: string | null;
+}
+/**
+ * One payment gateway.
+ *
+ * Interface plus at least two implementations, exactly like cache, queue and
+ * storage (R1, ADR-0005). The degraded one — bank transfer — depends on no
+ * external service at all, which is what makes R2 true for a shop: no Stripe
+ * key, and the till still works. It is not a stub: plenty of real businesses
+ * are paid by transfer and nothing else.
+ */
+export interface PaymentGateway {
+    readonly name: string;
+    /**
+     * True when money moves outside any API and a human confirms it.
+     *
+     * The order store branches on this rather than on the driver's name, so a
+     * second offline driver (cash on delivery, cheque) needs no new condition
+     * anywhere.
+     */
+    readonly settlesOffline: boolean;
+    start(request: StartPaymentRequest): Promise<StartedPayment>;
+    /** Re-reads a payment from the gateway. Offline drivers report unchanged. */
+    fetch(externalId: string): Promise<StartedPayment>;
+    refund(request: DriverRefundRequest): Promise<DriverRefundResult>;
+    /**
+     * Verifies and decodes an inbound notification.
+     *
+     * Throws `COMMERCE_PAYMENT_UNSUPPORTED` for a driver that has no inbound
+     * channel, and `COMMERCE_PAYMENT_SIGNATURE_INVALID` for one that does and is
+     * handed something unsigned. Never returns an unverified event: an
+     * unauthenticated "paid" notification is a way to get goods for free.
+     */
+    verifyEvent(payload: string, headers: Readonly<Record<string, string>>): Promise<PaymentEvent>;
+}
+export interface PaymentConfig extends DriverChoice {
+    /** Stripe's secret key. Absent on any site that has not configured one. */
+    readonly secretKey?: string;
+    /** The signing secret Stripe shows when a webhook endpoint is created. */
+    readonly webhookSecret?: string;
+    /** Overridden by tests to point at a local server. Never set in production. */
+    readonly apiBaseUrl?: string;
+    /** Shown to the shopper by the offline driver. Free text, per site. */
+    readonly transferInstructions?: string;
+}
+export type PaymentDriver = Driver<PaymentGateway, PaymentConfig>;
+//# sourceMappingURL=types.d.ts.map

package/dist/payment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/payment/types.ts"],"names":[],"mappings":"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"}

package/dist/payment/types.js

@@ -0,0 +1,18 @@
+/**
+ * Where a payment is in its life. Deliberately small.
+ *
+ * A gateway has dozens of internal states; a shop needs to know whether it has
+ * the money. Every driver maps its own vocabulary onto these six, so the order
+ * store never branches on a gateway-specific string.
+ */
+export const PAYMENT_STATUSES = [
+    /** Created, waiting for the shopper (or for a bank transfer to arrive). */
+    'pending',
+    /** The gateway holds the funds but has not moved them. */
+    'authorised',
+    'paid',
+    'failed',
+    'cancelled',
+    'refunded',
+];
+//# sourceMappingURL=types.js.map

package/dist/payment/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/payment/types.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,2EAA2E;IAC3E,SAAS;IACT,0DAA0D;IAC1D,YAAY;IACZ,MAAM;IACN,QAAQ;IACR,WAAW;IACX,UAAU;CACF,CAAA"}

package/dist/rows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading numbers back out of three databases that disagree about them.
+ *
+ * `bigint` columns do not come back as JavaScript numbers everywhere: `pg`
+ * hands back `int8` as a **string** (deliberately — it refuses to lose
+ * precision silently), `mysql2` may hand back a `bigint`, and `node:sqlite`
+ * gives a plain number. Reading `row.total_minor` and trusting it is therefore
+ * a bug that only appears on Postgres, which is exactly the kind of thing this
+ * project tests three dialects to catch.
+ *
+ * Every integer read in this package goes through here.
+ */
+export declare function toInt(value: unknown, what: string): number;
+/**
+ * Booleans, likewise.
+ *
+ * Postgres has a real `boolean`, MySQL stores `tinyint`, and SQLite stores
+ * whatever it was handed. `0`, `'0'`, `false` and `'false'` all mean false.
+ */
+export declare function toBool(value: unknown): boolean;
+/** The value a boolean is written as. Postgres wants a real boolean. */
+export declare function fromBool(value: boolean, dialect: string): boolean | number;
+export declare function toText(value: unknown, what: string): string;
+export declare function toNullableText(value: unknown): string | null;
+export declare function toNullableInt(value: unknown, what: string): number | null;
+//# sourceMappingURL=rows.d.ts.map

package/dist/rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../src/rows.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB1D;AAWD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM9C;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAE1E;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAS3D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI5D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzE"}