@authhero/adapter-interfaces 4.12.0 → 4.13.0

package/dist/types/adapters/TenantOperationRows.d.ts

@@ -0,0 +1,57 @@
+import { TenantOperationRow, TenantOperationRowCounts, TenantOperationRowInsert, TenantOperationRowOutcome, TenantOperationRowStatus } from "../types/TenantOperationRow";
+import { ListParams } from "../types/ListParams";
+export interface ListTenantOperationRowsParams extends ListParams {
+    /** Single status or a set (the errors endpoint queries `failed`). */
+    status?: TenantOperationRowStatus | TenantOperationRowStatus[];
+}
+export interface ListTenantOperationRowsResult {
+    rows: TenantOperationRow[];
+    start: number;
+    limit: number;
+    length: number;
+}
+/**
+ * Per-item checkpoints for batch tenant operations (issue #1325).
+ *
+ * Like `tenantOperations` this is a control-plane adapter, so it is
+ * unscoped — rows are addressed by `operation_id`, and the operation row
+ * carries the `tenant_id`.
+ *
+ * The contract that makes batch operations resumable: `createMany` stages
+ * every item as `pending`, `claimPending` hands a worker the next slice of
+ * unprocessed items, and `recordOutcomes` commits their terminal statuses.
+ * An interrupted run leaves its items `pending` and is retried verbatim,
+ * so implementations MUST make `recordOutcomes` atomic per call and MUST
+ * NOT mutate rows that already hold a terminal status.
+ */
+export interface TenantOperationRowsAdapter {
+    /**
+     * Stage items in bulk. Implementations should insert in batches rather
+     * than one statement per row — callers stage thousands at a time.
+     * Returns the number of rows written.
+     */
+    createMany(rows: TenantOperationRowInsert[]): Promise<number>;
+    /**
+     * Fetch the next `limit` items still awaiting processing, ordered by
+     * `seq` ascending. Does not itself lock — exclusivity between drivers
+     * comes from the lease on the parent operation
+     * (`TenantOperationsAdapter.claim`).
+     */
+    claimPending(operation_id: string, limit: number): Promise<TenantOperationRow[]>;
+    /**
+     * Commit terminal outcomes for processed items. Idempotent: applying an
+     * outcome to a row that is already terminal is a no-op, so a retried
+     * chunk cannot corrupt earlier results. Returns rows actually updated.
+     */
+    recordOutcomes(operation_id: string, outcomes: TenantOperationRowOutcome[]): Promise<number>;
+    /** Row counts per status, used to build the operation's summary. */
+    countByStatus(operation_id: string): Promise<TenantOperationRowCounts>;
+    /** Paginated read, ordered by `seq` ascending. Backs the errors endpoint. */
+    list(operation_id: string, params?: ListTenantOperationRowsParams): Promise<ListTenantOperationRowsResult>;
+    /**
+     * Retention cleanup. Also runs via the cascade when the parent operation
+     * is removed; exposed separately so a sweep can drop staged payloads
+     * without deleting the operation's audit record.
+     */
+    removeByOperation(operation_id: string): Promise<number>;
+}

package/dist/types/adapters/TenantOperations.d.ts

@@ -29,6 +29,36 @@ export interface TenantOperationsAdapter {
     list(params?: ListTenantOperationsParams): Promise<ListTenantOperationsResult>;
     /** Always bumps `updated_at`. */
     update(id: string, operation: TenantOperationUpdate): Promise<boolean>;
+    /**
+     * Atomically take the lease on an operation so only one driver advances
+     * it at a time. Succeeds when the operation is unclaimed or its existing
+     * lease has expired (or is already held by `worker_id`, making re-claim
+     * by the same worker a no-op); returns false when another live worker
+     * holds it.
+     *
+     * The lease is an efficiency guard, not a correctness guard — per-item
+     * checkpoints in `tenant_operation_rows` are what keep a batch operation
+     * correct if two drivers ever overlap. Implementations MUST perform the
+     * check and the write in a single conditional statement.
+     */
+    claim(id: string, worker_id: string, leaseMs: number): Promise<boolean>;
+    /**
+     * Release a lease held by `worker_id`. Returns false when the lease has
+     * since been taken by someone else, in which case the caller must not
+     * assume its own writes were the last ones.
+     */
+    release(id: string, worker_id: string): Promise<boolean>;
+    /**
+     * Operations that still have work to do and are free to be picked up:
+     * status `pending` or `running`, matching `kind`, whose lease is absent
+     * or expired. Ordered `created_at` ascending so the oldest unfinished
+     * work drains first. Backs the resume sweep that guarantees a batch
+     * completes even when every driver that touched it died.
+     */
+    listResumable(params: {
+        kind: TenantOperationKind;
+        limit: number;
+    }): Promise<TenantOperation[]>;
     /** Retention cleanup only — not exposed via routes; events cascade. */
     remove(id: string): Promise<boolean>;
 }

package/dist/types/adapters/index.d.ts

@@ -55,6 +55,7 @@ import { OutboxAdapter } from "./Outbox";
 import { RateLimitAdapter } from "./RateLimit";
 import { TenantOperationsAdapter } from "./TenantOperations";
 import { TenantOperationEventsAdapter } from "./TenantOperationEvents";
+import { TenantOperationRowsAdapter } from "./TenantOperationRows";
 import { RolloutsAdapter } from "./Rollouts";
 /**
  * Parameters for cleaning up expired sessions
@@ -162,6 +163,12 @@ export interface DataAdapters {
     tenantOperations?: TenantOperationsAdapter;
     /** Per-step history rows for `tenantOperations`; append-only. */
     tenantOperationEvents?: TenantOperationEventsAdapter;
+    /**
+     * Per-item checkpoints for batch operations (issue #1325). Required for
+     * the Auth0-compatible `POST /api/v2/jobs/users-imports` endpoints —
+     * without it, batch imports cannot be staged or resumed.
+     */
+    tenantOperationRows?: TenantOperationRowsAdapter;
     /**
      * Optional fleet rollout records (issue #1026). Phase 1 ships the table
      * and CRUD only; the wave/canary coordinator and routes come later.
@@ -287,4 +294,5 @@ export * from "./UserActivity";
 export * from "./Users";
 export * from "./TenantOperations";
 export * from "./TenantOperationEvents";
+export * from "./TenantOperationRows";
 export * from "./Rollouts";

package/dist/types/types/TenantOperation.d.ts

@@ -13,6 +13,7 @@ export declare const tenantOperationKindSchema: z.ZodEnum<{
     upgrade: "upgrade";
     backup: "backup";
     deprovision: "deprovision";
+    users_import: "users_import";
 }>;
 export type TenantOperationKind = z.infer<typeof tenantOperationKindSchema>;
 export declare const tenantOperationStatusSchema: z.ZodEnum<{
@@ -23,11 +24,22 @@ export declare const tenantOperationStatusSchema: z.ZodEnum<{
     cancelled: "cancelled";
 }>;
 export type TenantOperationStatus = z.infer<typeof tenantOperationStatusSchema>;
-export declare const tenantOperationEngineSchema: z.ZodEnum<{
-    inline: "inline";
-    "cloudflare-workflows": "cloudflare-workflows";
-}>;
+/**
+ * Which driver advances an operation. Deliberately an open string, not an
+ * enum: the engine name is recorded in a core database column, so closing
+ * it here would bake vendor names into the schema and lock out
+ * self-hosters running their own driver (pg-boss, BullMQ, SQS, a plain
+ * cron). The values AuthHero ships are {@link KNOWN_TENANT_OPERATION_ENGINES}.
+ *
+ * Durability never depends on this value. Operation progress is checkpointed
+ * in the database (for `users_import`, one `tenant_operation_rows` row per
+ * user), so a crashed driver loses nothing and any other driver can resume
+ * the work.
+ */
+export declare const tenantOperationEngineSchema: z.ZodString;
 export type TenantOperationEngine = z.infer<typeof tenantOperationEngineSchema>;
+/** Engines AuthHero ships. Not exhaustive — the column accepts any name. */
+export declare const KNOWN_TENANT_OPERATION_ENGINES: readonly ["inline", "cloudflare-workflows"];
 export declare const tenantOperationInsertSchema: z.ZodObject<{
     tenant_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     rollout_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -37,15 +49,14 @@ export declare const tenantOperationInsertSchema: z.ZodObject<{
         upgrade: "upgrade";
         backup: "backup";
         deprovision: "deprovision";
+        users_import: "users_import";
     }>;
-    engine: z.ZodEnum<{
-        inline: "inline";
-        "cloudflare-workflows": "cloudflare-workflows";
-    }>;
+    engine: z.ZodString;
     engine_instance_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     target_worker_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     target_database_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     initiated_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
 }, z.core.$strip>;
 export type TenantOperationInsert = z.input<typeof tenantOperationInsertSchema>;
 export declare const tenantOperationSchema: z.ZodObject<{
@@ -57,15 +68,14 @@ export declare const tenantOperationSchema: z.ZodObject<{
         upgrade: "upgrade";
         backup: "backup";
         deprovision: "deprovision";
+        users_import: "users_import";
     }>;
-    engine: z.ZodEnum<{
-        inline: "inline";
-        "cloudflare-workflows": "cloudflare-workflows";
-    }>;
+    engine: z.ZodString;
     engine_instance_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     target_worker_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     target_database_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     initiated_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     id: z.ZodString;
     status: z.ZodEnum<{
         pending: "pending";
@@ -76,6 +86,9 @@ export declare const tenantOperationSchema: z.ZodObject<{
     }>;
     current_step: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    result: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    claimed_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    claim_expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     created_at: z.ZodString;
     updated_at: z.ZodString;
     finished_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -94,6 +107,9 @@ export declare const tenantOperationUpdateSchema: z.ZodObject<{
     target_worker_version: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     target_database_version: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     current_step: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    result: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    claimed_by: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    claim_expires_at: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
     finished_at: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
 }, z.core.$strip>;
 export type TenantOperationUpdate = z.infer<typeof tenantOperationUpdateSchema>;

package/dist/types/types/TenantOperationRow.d.ts

@@ -0,0 +1,86 @@
+import { z } from "@hono/zod-openapi";
+/**
+ * Per-item checkpoint for a batch tenant operation (issue #1325).
+ *
+ * One row per item in the operation's input — for `users_import`, one per
+ * user in the uploaded file. This table is what makes a batch operation
+ * durable and resumable: an item is staged as `pending`, and its terminal
+ * status is committed in the same chunk that performs the write. A driver
+ * that dies mid-run leaves its unprocessed items `pending`, so any other
+ * driver (a cron sweep, a workflow step, a later request) resumes exactly
+ * where it stopped, without re-doing committed work.
+ *
+ * Durability therefore does not depend on the execution engine — engines
+ * only decide *who* advances the operation and *how fast*.
+ */
+export declare const tenantOperationRowStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    failed: "failed";
+    skipped: "skipped";
+    inserted: "inserted";
+    updated: "updated";
+}>;
+export type TenantOperationRowStatus = z.infer<typeof tenantOperationRowStatusSchema>;
+/** Terminal statuses — a row in any of these is never reprocessed. */
+export declare const TERMINAL_TENANT_OPERATION_ROW_STATUSES: readonly TenantOperationRowStatus[];
+export declare const tenantOperationRowInsertSchema: z.ZodObject<{
+    operation_id: z.ZodString;
+    seq: z.ZodNumber;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    status: z.ZodDefault<z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        skipped: "skipped";
+        inserted: "inserted";
+        updated: "updated";
+    }>>;
+    error_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    entity_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type TenantOperationRowInsert = z.input<typeof tenantOperationRowInsertSchema>;
+export declare const tenantOperationRowSchema: z.ZodObject<{
+    operation_id: z.ZodString;
+    seq: z.ZodNumber;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    error_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    entity_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        skipped: "skipped";
+        inserted: "inserted";
+        updated: "updated";
+    }>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strip>;
+export type TenantOperationRow = z.infer<typeof tenantOperationRowSchema>;
+/** The per-item outcome a processor reports back for one staged row. */
+export declare const tenantOperationRowOutcomeSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        skipped: "skipped";
+        inserted: "inserted";
+        updated: "updated";
+    }>;
+    error_code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    entity_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type TenantOperationRowOutcome = z.infer<typeof tenantOperationRowOutcomeSchema>;
+/** Count of rows in each status, used to build a job summary. */
+export interface TenantOperationRowCounts {
+    total: number;
+    pending: number;
+    inserted: number;
+    updated: number;
+    failed: number;
+    skipped: number;
+}

package/dist/types/types/index.d.ts

@@ -31,6 +31,7 @@ export * from "./SigningKey";
 export * from "./Tenant";
 export * from "./TenantOperation";
 export * from "./TenantOperationEvent";
+export * from "./TenantOperationRow";
 export * from "./Rollout";
 export * from "./Token";
 export * from "./User";

package/package.json

@@ -11,7 +11,7 @@
     "type": "git",
     "url": "https://github.com/markusahlstrand/authhero"
   },
-  "version": "4.12.0",
+  "version": "4.13.0",
   "files": [
     "dist"
   ],