@wopr-network/platform-core 1.13.3 → 1.14.1

package/dist/db/schema/ledger.d.ts

@@ -0,0 +1,442 @@
+export declare const accountTypeEnum: import("drizzle-orm/pg-core").PgEnum<["asset", "liability", "equity", "revenue", "expense"]>;
+export declare const entrySideEnum: import("drizzle-orm/pg-core").PgEnum<["debit", "credit"]>;
+/**
+ * Chart of accounts — every account that can appear in a journal line.
+ *
+ * System accounts (tenant_id IS NULL) are seeded at migration time.
+ * Per-tenant liability accounts are created lazily on first transaction.
+ */
+export declare const accounts: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "accounts";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        code: import("drizzle-orm/pg-core").PgColumn<{
+            name: "code";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "type";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "asset" | "liability" | "equity" | "revenue" | "expense";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["asset", "liability", "equity", "revenue", "expense"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        normalSide: import("drizzle-orm/pg-core").PgColumn<{
+            name: "normal_side";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "debit" | "credit";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["debit", "credit"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "accounts";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Journal entries — the header for each balanced transaction.
+ * One business event = one journal entry = two or more journal lines that sum to zero.
+ */
+export declare const journalEntries: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "journal_entries";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        postedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "posted_at";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        entryType: import("drizzle-orm/pg-core").PgColumn<{
+            name: "entry_type";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        description: import("drizzle-orm/pg-core").PgColumn<{
+            name: "description";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        referenceId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "reference_id";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: import("drizzle-orm/pg-core").PgColumn<{
+            name: "metadata";
+            tableName: "journal_entries";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdBy: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_by";
+            tableName: "journal_entries";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Journal lines — the individual debits and credits within a journal entry.
+ * Invariant: for every journal_entry, SUM(debit amounts) = SUM(credit amounts).
+ * Amount is always positive; `side` determines the direction.
+ * Stored in nanodollars (Credit.toRaw()).
+ */
+export declare const journalLines: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "journal_lines";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "journal_lines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        journalEntryId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "journal_entry_id";
+            tableName: "journal_lines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        accountId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "account_id";
+            tableName: "journal_lines";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        amount: import("drizzle-orm/pg-core").PgColumn<{
+            name: "amount";
+            tableName: "journal_lines";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        side: import("drizzle-orm/pg-core").PgColumn<{
+            name: "side";
+            tableName: "journal_lines";
+            dataType: "string";
+            columnType: "PgEnumColumn";
+            data: "debit" | "credit";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["debit", "credit"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Materialized account balances — cache derived from journal_lines.
+ * Updated atomically within the same transaction as the journal line insert.
+ * Can always be reconstructed from journal_lines if corrupted.
+ */
+export declare const accountBalances: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "account_balances";
+    schema: undefined;
+    columns: {
+        accountId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "account_id";
+            tableName: "account_balances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        balance: import("drizzle-orm/pg-core").PgColumn<{
+            name: "balance";
+            tableName: "account_balances";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lastUpdated: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_updated";
+            tableName: "account_balances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/db/schema/ledger.js

@@ -0,0 +1,76 @@
+import { sql } from "drizzle-orm";
+import { bigint, index, jsonb, pgEnum, pgTable, text, uniqueIndex } from "drizzle-orm/pg-core";
+export const accountTypeEnum = pgEnum("account_type", ["asset", "liability", "equity", "revenue", "expense"]);
+export const entrySideEnum = pgEnum("entry_side", ["debit", "credit"]);
+/**
+ * Chart of accounts — every account that can appear in a journal line.
+ *
+ * System accounts (tenant_id IS NULL) are seeded at migration time.
+ * Per-tenant liability accounts are created lazily on first transaction.
+ */
+export const accounts = pgTable("accounts", {
+    id: text("id").primaryKey(),
+    code: text("code").notNull(),
+    name: text("name").notNull(),
+    type: accountTypeEnum("type").notNull(),
+    normalSide: entrySideEnum("normal_side").notNull(),
+    tenantId: text("tenant_id"), // NULL = system account
+    createdAt: text("created_at").notNull().default(sql `(now())`),
+}, (table) => [
+    uniqueIndex("idx_accounts_code").on(table.code),
+    index("idx_accounts_tenant").on(table.tenantId).where(sql `${table.tenantId} IS NOT NULL`),
+    index("idx_accounts_type").on(table.type),
+]);
+/**
+ * Journal entries — the header for each balanced transaction.
+ * One business event = one journal entry = two or more journal lines that sum to zero.
+ */
+export const journalEntries = pgTable("journal_entries", {
+    id: text("id").primaryKey(),
+    postedAt: text("posted_at").notNull().default(sql `(now())`),
+    entryType: text("entry_type").notNull(), // purchase, usage, grant, refund, dividend, expiry, correction
+    description: text("description"),
+    referenceId: text("reference_id"),
+    tenantId: text("tenant_id").notNull(),
+    metadata: jsonb("metadata"), // funding_source, attributed_user_id, stripe_fingerprint, etc.
+    createdBy: text("created_by"), // system, admin:<id>, cron:expiry, etc.
+}, (table) => [
+    uniqueIndex("idx_je_reference").on(table.referenceId).where(sql `${table.referenceId} IS NOT NULL`),
+    index("idx_je_tenant").on(table.tenantId),
+    index("idx_je_type").on(table.entryType),
+    index("idx_je_posted").on(table.postedAt),
+    index("idx_je_tenant_posted").on(table.tenantId, table.postedAt),
+]);
+/**
+ * Journal lines — the individual debits and credits within a journal entry.
+ * Invariant: for every journal_entry, SUM(debit amounts) = SUM(credit amounts).
+ * Amount is always positive; `side` determines the direction.
+ * Stored in nanodollars (Credit.toRaw()).
+ */
+export const journalLines = pgTable("journal_lines", {
+    id: text("id").primaryKey(),
+    journalEntryId: text("journal_entry_id")
+        .notNull()
+        .references(() => journalEntries.id),
+    accountId: text("account_id")
+        .notNull()
+        .references(() => accounts.id),
+    amount: bigint("amount", { mode: "number" }).notNull(), // nanodollars, always positive
+    side: entrySideEnum("side").notNull(),
+}, (table) => [
+    index("idx_jl_entry").on(table.journalEntryId),
+    index("idx_jl_account").on(table.accountId),
+    index("idx_jl_account_side").on(table.accountId, table.side),
+]);
+/**
+ * Materialized account balances — cache derived from journal_lines.
+ * Updated atomically within the same transaction as the journal line insert.
+ * Can always be reconstructed from journal_lines if corrupted.
+ */
+export const accountBalances = pgTable("account_balances", {
+    accountId: text("account_id")
+        .primaryKey()
+        .references(() => accounts.id),
+    balance: bigint("balance", { mode: "number" }).notNull().default(0), // net balance in nanodollars
+    lastUpdated: text("last_updated").notNull().default(sql `(now())`),
+});

package/dist/gateway/credit-gate.d.ts

@@ -5,11 +5,11 @@
  * (OpenAI, Anthropic) to ensure consistent credit billing across all
  * gateway endpoints.
  */
-import type { ICreditLedger } from "@wopr-network/platform-core/credits";
+import type { ILedger } from "@wopr-network/platform-core/credits";
 import type { Context } from "hono";
 import type { GatewayAuthEnv } from "./service-key-auth.js";
 export interface CreditGateDeps {
-    creditLedger?: ICreditLedger;
+    creditLedger?: ILedger;
     topUpUrl: string;
     /** Maximum negative balance allowed before hard-stop, in cents. Default: 50 (-$0.50). */
     graceBufferCents?: number;

package/dist/gateway/credit-gate.js

@@ -71,7 +71,11 @@ export async function debitCredits(deps, tenantId, costUsd, margin, capability,
         return;
     }
     try {
-        await deps.creditLedger.debit(tenantId, chargeCredit, "adapter_usage", `Gateway ${capability} via ${provider}`, undefined, true, attributedUserId);
+        await deps.creditLedger.debit(tenantId, chargeCredit, "adapter_usage", {
+            description: `Gateway ${capability} via ${provider}`,
+            allowNegative: true,
+            attributedUserId,
+        });
         // Only fire on first zero-crossing (balance was positive before, now ≤ 0)
         if (deps.onBalanceExhausted) {
             const newBalance = await deps.creditLedger.balance(tenantId);