@arcblock/payment-service 1.29.1

package/dist/drivers.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @arcblock/payment-service/drivers — Phase 8 (W2-1a) db / locks slot contracts.
+ *
+ * Re-exports the driver contracts and reference implementations. Same transition
+ * boundary as the root module (D4): the implementations physically live in
+ * blocklets/core/api/src for now; the package surface is the contract hosts
+ * (arc, standalone worker) build their slots against.
+ */
+export type DbDriverKind = 'node' | 'd1';
+export interface DbExecResult {
+    changes: number;
+}
+export interface DbBatchOp {
+    sql: string;
+    params?: any[];
+}
+export interface DbDriver {
+    kind: DbDriverKind;
+    exec(sql: string, params?: any[]): Promise<DbExecResult>;
+    all<T = any>(sql: string, params?: any[]): Promise<T[]>;
+    get<T = any>(sql: string, params?: any[]): Promise<T | null>;
+    batch(ops: DbBatchOp[]): Promise<any[]>;
+    sequelize?: any;
+}
+export interface LockHandle {
+    name: string;
+    locked: boolean;
+    acquire(maxWaitMs?: number): Promise<true>;
+    release(): void;
+}
+export type LocksDriverKind = 'memory' | 'd1';
+export interface LocksDriver {
+    kind: LocksDriverKind;
+    getLock(name: string, options?: {
+        ttl?: number;
+    }): LockHandle;
+}
+export type LockScope = 'tenant' | 'global';
+export interface SqlMigration {
+    name: string;
+    sql: string;
+}
+export declare function applySqlMigrations(driver: DbDriver, migrations: SqlMigration[]): Promise<string[]>;
+export declare function applyPaymentCoreMigrations(driver: DbDriver): Promise<string[]>;
+export declare function getPaymentCoreSqlMigrations(): SqlMigration[];
+export declare function createNodeDbDriver(sequelize: any): DbDriver;
+export declare function createD1DbDriver(binding: any): DbDriver;
+export declare function createMemoryLocksDriver(): LocksDriver;
+export declare function createD1LocksDriver(getBinding: () => any): LocksDriver;
+export declare function scopedLockName(name: string, instanceDid: string | null, scope: LockScope): string;
+export declare function createAuthStorage(driver: DbDriver): any;
+export interface QueueOptions<T = any> {
+    id?: (job: T) => string;
+    concurrency?: number;
+    maxRetries?: number;
+    maxTimeout?: number;
+    retryDelay?: number;
+    enableScheduledJob?: boolean;
+}
+export interface PushParams<T = any> {
+    job: T;
+    id?: string;
+    persist?: boolean;
+    delay?: number;
+    runAt?: number;
+    skipDuplicateCheck?: boolean;
+    fromStore?: boolean;
+}
+/** per-job event channel (emits queued/finished/failed/retry/cancelled) */
+export interface JobEvents {
+    id?: string;
+    on(event: string, listener: (data: any) => void): this;
+    once(event: string, listener: (data: any) => void): this;
+    emit(event: string, data: any): boolean;
+}
+export type ResolvedQueueOptions = Required<Omit<QueueOptions, 'id'>>;
+export interface QueueHandle<T = any> {
+    push(params: PushParams<T>): JobEvents;
+    pushAndWait(params: PushParams<T>): Promise<{
+        id: string;
+        job: T;
+        result: any;
+    }>;
+    get(id: string): Promise<T | null>;
+    delete(id: string, knownExists?: boolean): Promise<boolean>;
+    cancel(id: string): Promise<T | null>;
+    update(id: string, updates: any): Promise<any>;
+    options: ResolvedQueueOptions;
+}
+export type QueueFactory = <T = any>(params: {
+    name: string;
+    onJob: (job: T) => Promise<any>;
+    options?: QueueOptions<T>;
+}) => QueueHandle<T> & JobEvents;
+export interface QueueHostHooks {
+    flush(): Promise<void>;
+}
+export interface CronJob {
+    name: string;
+    time: string;
+    fn: () => Promise<any> | any;
+    options?: {
+        runOnInit?: boolean;
+    };
+}
+export interface CronDriver {
+    kind: 'node-cron' | 'cf-cron';
+    register(jobs: CronJob[], onError?: (err: Error, name: string) => void): void;
+    addJob(name: string, time: string, fn: CronJob['fn'], options?: CronJob['options']): void;
+    runDue(now?: Date): Promise<{
+        ran: string[];
+        skipped: string[];
+    }>;
+    runJob(name: string): Promise<void>;
+    getJobNames(): string[];
+}
+export declare const nodeQueueHostHooks: QueueHostHooks;
+export declare function setQueueHostHooks(hooks: QueueHostHooks): void;
+export declare function getQueueHostHooks(): QueueHostHooks;
+export declare function createCronRegistry(kind: CronDriver['kind']): CronDriver;
+export interface IdentityDriver {
+    resolveInstanceDidForHost(host: string | undefined): Promise<string | null> | string | null;
+    getAppEk?(instanceDid: string): Promise<string> | string;
+}
+export declare function createDefaultIdentityDriver(): IdentityDriver;
+export declare function setIdentityDriver(driver: IdentityDriver): void;
+export declare function getIdentityDriver(): IdentityDriver;
+export interface SecretsDriver {
+    encrypt(instanceDid: string, value: string): Promise<string>;
+    decrypt(instanceDid: string, value: string): Promise<string>;
+    encryptSync(instanceDid: string, value: string): string;
+    decryptSync(instanceDid: string, value: string): string;
+    warmup(instanceDid: string): Promise<void>;
+}
+export declare function createDefaultSecretsDriver(): SecretsDriver;
+export declare function createKeyringSecretsDriver(identity: IdentityDriver, opts?: {
+    ttlMs?: number;
+}): SecretsDriver;
+export declare function setSecretsDriver(driver: SecretsDriver): void;
+export declare function getSecretsDriver(): SecretsDriver;
+export declare function setCronDriver(driver: CronDriver): void;
+export declare function getCronDriver(): CronDriver;
+export declare function matchesCron(expr: string, date: Date): boolean;
+export declare function shouldRunInWindow(expr: string, date: Date): boolean;