@downcity/services 0.1.6

package/bin/balance/service.d.ts

@@ -0,0 +1,880 @@
+/**
+ * Downcity 官方 Balance 服务实现。
+ *
+ * 设计边界：
+ * - 余额是用户级全局钱包，不与 product 绑定
+ * - 服务只负责账户、流水、充值单、redeem_code 与原子加减款
+ * - 真正的计费策略应由业务方在 hook 中直接调用本服务
+ */
+import { InstallableService, type ServiceInstallContext } from "@downcity/infra";
+import type { BalanceAccount, BalanceCreateRedeemCodeInput, BalanceExtra, BalanceHistoryQuery, BalanceLedgerEntry, BalanceServiceOptions, BalanceRedeemCode, BalanceRedeemCodeIssueResult, BalanceRedeemCodeQuery, BalanceRedeemCodeRedeemResult, BalanceTopup, BalanceTopupQuery } from "./types.js";
+/**
+ * Balance 服务实例。
+ *
+ * 业务方应保存返回实例，并在 hook 中直接调用它的 `require()` / `sub()` / `add()`。
+ */
+export declare class BalanceService extends InstallableService {
+    readonly id = "balance";
+    readonly name = "Balance";
+    readonly version = "0.1.0";
+    readonly schema: {
+        accounts: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+            name: "service_balance_accounts";
+            schema: undefined;
+            columns: {
+                user_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "user_id";
+                    tableName: "service_balance_accounts";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: true;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                balance: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "balance";
+                    tableName: "service_balance_accounts";
+                    dataType: "number";
+                    columnType: "SQLiteInteger";
+                    data: number;
+                    driverParam: number;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: undefined;
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {}>;
+                unit: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "unit";
+                    tableName: "service_balance_accounts";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "created_at";
+                    tableName: "service_balance_accounts";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                updated_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "updated_at";
+                    tableName: "service_balance_accounts";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+            };
+            dialect: "sqlite";
+        }>;
+        ledger: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+            name: "service_balance_ledger";
+            schema: undefined;
+            columns: {
+                entry_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "entry_id";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: true;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                user_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "user_id";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                kind: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "kind";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                amount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "amount";
+                    tableName: "service_balance_ledger";
+                    dataType: "number";
+                    columnType: "SQLiteInteger";
+                    data: number;
+                    driverParam: number;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: undefined;
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {}>;
+                balance_after: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "balance_after";
+                    tableName: "service_balance_ledger";
+                    dataType: "number";
+                    columnType: "SQLiteInteger";
+                    data: number;
+                    driverParam: number;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: undefined;
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {}>;
+                unit: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "unit";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                note: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "note";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                ref: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "ref";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                metadata_json: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "metadata_json";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "created_at";
+                    tableName: "service_balance_ledger";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+            };
+            dialect: "sqlite";
+        }>;
+        topups: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+            name: "service_balance_topups";
+            schema: undefined;
+            columns: {
+                topup_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "topup_id";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: true;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                user_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "user_id";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                amount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "amount";
+                    tableName: "service_balance_topups";
+                    dataType: "number";
+                    columnType: "SQLiteInteger";
+                    data: number;
+                    driverParam: number;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: undefined;
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {}>;
+                unit: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "unit";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "status";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                note: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "note";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                ref: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "ref";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                metadata_json: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "metadata_json";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "created_at";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                updated_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "updated_at";
+                    tableName: "service_balance_topups";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+            };
+            dialect: "sqlite";
+        }>;
+        redeem_codes: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+            name: "service_balance_redeem_codes";
+            schema: undefined;
+            columns: {
+                redeem_code_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "redeem_code_id";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: true;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                code_hash: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "code_hash";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                code_mask: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "code_mask";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                amount: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "amount";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "number";
+                    columnType: "SQLiteInteger";
+                    data: number;
+                    driverParam: number;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: undefined;
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {}>;
+                unit: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "unit";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "status";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                note: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "note";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                ref: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "ref";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                metadata_json: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "metadata_json";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                redeemed_by_user_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "redeemed_by_user_id";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                redeemed_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "redeemed_at";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "created_at";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+                updated_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+                    name: "updated_at";
+                    tableName: "service_balance_redeem_codes";
+                    dataType: "string";
+                    columnType: "SQLiteText";
+                    data: string;
+                    driverParam: string;
+                    notNull: true;
+                    hasDefault: false;
+                    isPrimaryKey: false;
+                    isAutoincrement: false;
+                    hasRuntimeDefault: false;
+                    enumValues: [string, ...string[]];
+                    baseColumn: never;
+                    identity: undefined;
+                    generated: undefined;
+                }, {}, {
+                    length: number | undefined;
+                }>;
+            };
+            dialect: "sqlite";
+        }>;
+    };
+    private readonly initAmount;
+    private readonly unitName;
+    constructor(options?: BalanceServiceOptions);
+    install(ctx: ServiceInstallContext): void;
+    /**
+     * 读取用户余额。
+     *
+     * 若账户不存在，会自动开户并按配置发放初始余额。
+     */
+    read(user_id: string): Promise<BalanceAccount>;
+    /**
+     * 检查用户余额是否足够。
+     *
+     * 余额不足时会抛出 `402 insufficient balance`。
+     */
+    require(user_id: string, amount: number): Promise<BalanceAccount>;
+    /**
+     * 给用户加余额，并写入 `add` 流水。
+     */
+    add(user_id: string, amount: number, extra?: BalanceExtra): Promise<BalanceAccount>;
+    /**
+     * 给用户扣余额，并写入 `sub` 流水。
+     */
+    sub(user_id: string, amount: number, extra?: BalanceExtra): Promise<BalanceAccount>;
+    /**
+     * 查询某个用户的流水。
+     */
+    history(user_id: string, limit?: number | string): Promise<BalanceLedgerEntry[]>;
+    /**
+     * 读取一笔充值单。
+     *
+     * 关键说明（中文）
+     * - 这是给支付桥接层使用的公开只读能力
+     * - 充值单的状态流转仍然只能通过 finishTopup / cancelTopup 完成
+     */
+    readTopup(topup_id: string): Promise<BalanceTopup>;
+    /**
+     * 创建充值单。
+     *
+     * 这一步不会直接入账，只会生成 `pending` 充值单。
+     */
+    createTopup(user_id: string, amount: number | undefined, extra?: BalanceExtra): Promise<BalanceTopup>;
+    /**
+     * 将充值单标记为完成，并真正给用户加余额。
+     */
+    finishTopup(topup_id: string, extra?: BalanceExtra): Promise<BalanceTopup>;
+    /**
+     * 取消待处理充值单。
+     */
+    cancelTopup(topup_id: string, extra?: BalanceExtra): Promise<BalanceTopup>;
+    /**
+     * 创建一个新的 redeem_code。
+     */
+    createRedeemCode(input: BalanceCreateRedeemCodeInput): Promise<BalanceRedeemCodeIssueResult>;
+    /**
+     * 用户兑换 redeem_code，并立刻给余额入账。
+     */
+    redeemCode(user_id: string, code: unknown, extra?: BalanceExtra): Promise<BalanceRedeemCodeRedeemResult>;
+    /**
+     * 停用一个尚未兑换的 redeem_code。
+     */
+    disableRedeemCode(redeem_code_id: string, extra?: BalanceExtra): Promise<BalanceRedeemCode>;
+    /**
+     * 列出余额账户。
+     */
+    listUsers(limit?: number | string): Promise<BalanceAccount[]>;
+    /**
+     * 列出流水。
+     */
+    listHistory(query?: BalanceHistoryQuery): Promise<BalanceLedgerEntry[]>;
+    /**
+     * 列出充值单。
+     */
+    listTopups(query?: BalanceTopupQuery): Promise<BalanceTopup[]>;
+    /**
+     * 列出 redeem_code。
+     */
+    listRedeemCodes(query?: BalanceRedeemCodeQuery): Promise<BalanceRedeemCode[]>;
+    /**
+     * 关键说明（中文）
+     * - 正数表示加款，负数表示扣款
+     * - 扣款走 SQL 条件更新，避免把余额扣成负数
+     * - 扣费策略本身不写在服务里，而是由业务 hook 调用本方法
+     */
+    private applyDelta;
+    /**
+     * 首次见到某用户时自动开户。
+     */
+    private ensureAccount;
+    /**
+     * 读取账户；不存在时报错。
+     */
+    private readAccountRequired;
+    /**
+     * 读取充值单；不存在时报错。
+     */
+    private readTopupRequired;
+    /**
+     * 按 ID 读取 redeem_code；不存在时报错。
+     */
+    private readRedeemCodeRequired;
+    /**
+     * 按哈希读取 redeem_code；不存在时返回空。
+     */
+    private readRedeemCodeByHash;
+    /**
+     * 写入流水。
+     */
+    private insertLedger;
+    /**
+     * 拿到底层原始数据库对象。
+     */
+    private resolveRaw;
+}
+/**
+ * 创建 Balance 服务实例。
+ */
+export declare function balanceService(options?: BalanceServiceOptions): BalanceService;
+//# sourceMappingURL=service.d.ts.map