@authhero/adapter-interfaces 3.4.1 → 3.6.0

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

@@ -0,0 +1,18 @@
+import { Rollout, RolloutInsert, RolloutUpdate } from "../types/Rollout";
+import { ListParams } from "../types/ListParams";
+export interface ListRolloutsResult {
+    rollouts: Rollout[];
+    start: number;
+    limit: number;
+    length: number;
+}
+export interface RolloutsAdapter {
+    /** Generates the `rol_<nanoid>` id and inserts with status `pending`. */
+    create(rollout: RolloutInsert): Promise<Rollout>;
+    get(id: string): Promise<Rollout | null>;
+    /** Default sort: `created_at` descending. */
+    list(params?: ListParams): Promise<ListRolloutsResult>;
+    /** Always bumps `updated_at`. */
+    update(id: string, rollout: RolloutUpdate): Promise<boolean>;
+    remove(id: string): Promise<boolean>;
+}

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

@@ -0,0 +1,18 @@
+import { TenantOperationEvent, TenantOperationEventInsert } from "../types/TenantOperationEvent";
+import { ListParams } from "../types/ListParams";
+export interface ListTenantOperationEventsResult {
+    events: TenantOperationEvent[];
+    start: number;
+    limit: number;
+    length: number;
+}
+/**
+ * Append-only step history for tenant operations — no update or remove;
+ * rows are deleted only via the cascade when their operation is removed.
+ */
+export interface TenantOperationEventsAdapter {
+    /** Generates the `evt_<nanoid>` id. */
+    create(event: TenantOperationEventInsert): Promise<TenantOperationEvent>;
+    /** Ordered `created_at` ascending (id as tiebreak). */
+    listByOperation(operation_id: string, params?: ListParams): Promise<ListTenantOperationEventsResult>;
+}

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

@@ -0,0 +1,34 @@
+import { TenantOperation, TenantOperationEngine, TenantOperationInsert, TenantOperationKind, TenantOperationStatus, TenantOperationUpdate } from "../types/TenantOperation";
+import { ListParams } from "../types/ListParams";
+/**
+ * Tenant operations are control-plane entities (like `tenants` itself), so
+ * the adapter is unscoped: `tenant_id` is a list filter, not a scoping
+ * argument, and is null for fleet-level operations.
+ */
+export interface ListTenantOperationsParams extends ListParams {
+    tenant_id?: string;
+    rollout_id?: string;
+    kind?: TenantOperationKind;
+    /** Single status or a set (the reconciler queries pending + running). */
+    status?: TenantOperationStatus | TenantOperationStatus[];
+    engine?: TenantOperationEngine;
+    /** Only operations whose `updated_at` is strictly before this ISO timestamp. */
+    updated_before?: string;
+}
+export interface ListTenantOperationsResult {
+    operations: TenantOperation[];
+    start: number;
+    limit: number;
+    length: number;
+}
+export interface TenantOperationsAdapter {
+    /** Generates the `op_<nanoid>` id and inserts with status `pending`. */
+    create(operation: TenantOperationInsert): Promise<TenantOperation>;
+    get(id: string): Promise<TenantOperation | null>;
+    /** Default sort: `created_at` descending. */
+    list(params?: ListTenantOperationsParams): Promise<ListTenantOperationsResult>;
+    /** Always bumps `updated_at`. */
+    update(id: string, operation: TenantOperationUpdate): Promise<boolean>;
+    /** Retention cleanup only — not exposed via routes; events cascade. */
+    remove(id: string): Promise<boolean>;
+}

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

@@ -0,0 +1,9 @@
+import { UserActivity, UserActivityUpdate } from "../types/UserActivity";
+export interface UserActivityAdapter {
+    get(tenantId: string, userId: string): Promise<UserActivity | null>;
+    /**
+     * Insert or merge-update the activity row for a user. Only the provided
+     * fields are written; previously-stored fields are preserved.
+     */
+    upsert(tenantId: string, userId: string, activity: UserActivityUpdate): Promise<void>;
+}

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

@@ -32,6 +32,7 @@ import { FormsAdapter } from "./Forms";
 import { ResourceServersAdapter } from "./ResourceServers";
 import { RolePermissionsAdapter } from "./RolePermissions";
 import { GrantsAdapter } from "./Grants";
+import { UserActivityAdapter } from "./UserActivity";
 import { UserPermissionsAdapter } from "./UserPermissions";
 import { RolesAdapter } from "./Roles";
 import { UserRolesAdapter } from "./UserRoles";
@@ -49,6 +50,9 @@ import { EmailServiceAdapter } from "./EmailService";
 import { SmsServiceAdapter } from "./SmsService";
 import { OutboxAdapter } from "./Outbox";
 import { RateLimitAdapter } from "./RateLimit";
+import { TenantOperationsAdapter } from "./TenantOperations";
+import { TenantOperationEventsAdapter } from "./TenantOperationEvents";
+import { RolloutsAdapter } from "./Rollouts";
 /**
  * Parameters for cleaning up expired sessions
  */
@@ -114,6 +118,14 @@ export interface DataAdapters {
      * `/api/v2/client-grants`, which is `clientGrants` above).
      */
     grants?: GrantsAdapter;
+    /**
+     * Optional write-often per-user activity counters (last_login, last_ip,
+     * login_count, …) split out of the `users` row (issue #1003). When set, the
+     * login flow double-writes these alongside the legacy `users` columns during
+     * the expand/contract migration. When undefined, only the legacy columns are
+     * written.
+     */
+    userActivity?: UserActivityAdapter;
     userPermissions: UserPermissionsAdapter;
     roles: RolesAdapter;
     sessions: SessionsAdapter;
@@ -125,6 +137,23 @@ export interface DataAdapters {
      */
     analytics?: AnalyticsAdapter;
     tenants: TenantsDataAdapter;
+    /**
+     * Optional control-plane log of durable tenant lifecycle operations
+     * (provision / seed / upgrade / backup / deprovision — issue #1026).
+     * The tenant row's provisioning fields remain the current-state snapshot;
+     * these rows are the append-only history explaining how it got there.
+     * When set (together with `tenantOperationEvents`), AuthHero mounts the
+     * `/api/v2/operations` and `/api/v2/tenants/:id/operations` management
+     * routes and lifecycle hooks record every provision run.
+     */
+    tenantOperations?: TenantOperationsAdapter;
+    /** Per-step history rows for `tenantOperations`; append-only. */
+    tenantOperationEvents?: TenantOperationEventsAdapter;
+    /**
+     * Optional fleet rollout records (issue #1026). Phase 1 ships the table
+     * and CRUD only; the wave/canary coordinator and routes come later.
+     */
+    rollouts?: RolloutsAdapter;
     themes: ThemesAdapter;
     universalLoginTemplates: UniversalLoginTemplatesAdapter;
     customText: CustomTextAdapter;
@@ -238,4 +267,8 @@ export * from "./TenantSettings";
 export * from "./Tenants";
 export * from "./Themes";
 export * from "./Grants";
+export * from "./UserActivity";
 export * from "./Users";
+export * from "./TenantOperations";
+export * from "./TenantOperationEvents";
+export * from "./Rollouts";

package/dist/types/types/Rollout.d.ts

@@ -0,0 +1,77 @@
+import { z } from "@hono/zod-openapi";
+/**
+ * Fleet operation coordinating per-tenant operations in waves with a canary
+ * and a health gate (issue #1026). Progress is derived by querying
+ * `tenant_operations` rows with this rollout's id — there are no
+ * denormalized counters.
+ */
+export declare const rolloutKindSchema: z.ZodEnum<{
+    upgrade: "upgrade";
+    backup: "backup";
+    reseed: "reseed";
+}>;
+export type RolloutKind = z.infer<typeof rolloutKindSchema>;
+export declare const rolloutStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    failed: "failed";
+    paused: "paused";
+    canary: "canary";
+    rolling: "rolling";
+    done: "done";
+}>;
+export type RolloutStatus = z.infer<typeof rolloutStatusSchema>;
+export declare const rolloutInsertSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        upgrade: "upgrade";
+        backup: "backup";
+        reseed: "reseed";
+    }>;
+    target_worker_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    target_database_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    wave_size: z.ZodDefault<z.ZodNumber>;
+    canary_tenant_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    filter: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    initiated_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type RolloutInsert = z.input<typeof rolloutInsertSchema>;
+export declare const rolloutSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        upgrade: "upgrade";
+        backup: "backup";
+        reseed: "reseed";
+    }>;
+    target_worker_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    target_database_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    wave_size: z.ZodDefault<z.ZodNumber>;
+    canary_tenant_ids: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    filter: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    initiated_by: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        paused: "paused";
+        canary: "canary";
+        rolling: "rolling";
+        done: "done";
+    }>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    finished_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type Rollout = z.infer<typeof rolloutSchema>;
+export declare const rolloutUpdateSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        paused: "paused";
+        canary: "canary";
+        rolling: "rolling";
+        done: "done";
+    }>>;
+    filter: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    finished_at: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    wave_size: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    canary_tenant_ids: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>>;
+}, z.core.$strip>;
+export type RolloutUpdate = z.infer<typeof rolloutUpdateSchema>;

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

@@ -0,0 +1,99 @@
+import { z } from "@hono/zod-openapi";
+/**
+ * Durable tenant lifecycle operations (issue #1026). Each row is one
+ * provision / seed / upgrade / backup / deprovision run against a tenant
+ * (or the whole fleet when `tenant_id` is null). The tenant row's
+ * `provisioning_state` / `worker_version` / `database_version` remain the
+ * current-state snapshot; operations are the append-only log explaining how
+ * the snapshot got there.
+ */
+export declare const tenantOperationKindSchema: z.ZodEnum<{
+    provision: "provision";
+    seed: "seed";
+    upgrade: "upgrade";
+    backup: "backup";
+    deprovision: "deprovision";
+}>;
+export type TenantOperationKind = z.infer<typeof tenantOperationKindSchema>;
+export declare const tenantOperationStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    failed: "failed";
+    running: "running";
+    succeeded: "succeeded";
+    cancelled: "cancelled";
+}>;
+export type TenantOperationStatus = z.infer<typeof tenantOperationStatusSchema>;
+export declare const tenantOperationEngineSchema: z.ZodEnum<{
+    inline: "inline";
+    "cloudflare-workflows": "cloudflare-workflows";
+}>;
+export type TenantOperationEngine = z.infer<typeof tenantOperationEngineSchema>;
+export declare const tenantOperationInsertSchema: z.ZodObject<{
+    tenant_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rollout_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodEnum<{
+        provision: "provision";
+        seed: "seed";
+        upgrade: "upgrade";
+        backup: "backup";
+        deprovision: "deprovision";
+    }>;
+    engine: z.ZodEnum<{
+        inline: "inline";
+        "cloudflare-workflows": "cloudflare-workflows";
+    }>;
+    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>>;
+}, z.core.$strip>;
+export type TenantOperationInsert = z.input<typeof tenantOperationInsertSchema>;
+export declare const tenantOperationSchema: z.ZodObject<{
+    tenant_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rollout_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodEnum<{
+        provision: "provision";
+        seed: "seed";
+        upgrade: "upgrade";
+        backup: "backup";
+        deprovision: "deprovision";
+    }>;
+    engine: z.ZodEnum<{
+        inline: "inline";
+        "cloudflare-workflows": "cloudflare-workflows";
+    }>;
+    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>>;
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+    }>;
+    current_step: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    finished_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type TenantOperation = z.infer<typeof tenantOperationSchema>;
+export declare const tenantOperationUpdateSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        running: "running";
+        succeeded: "succeeded";
+        cancelled: "cancelled";
+    }>>;
+    engine_instance_id: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    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>>>;
+    finished_at: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+}, z.core.$strip>;
+export type TenantOperationUpdate = z.infer<typeof tenantOperationUpdateSchema>;

package/dist/types/types/TenantOperationEvent.d.ts

@@ -0,0 +1,48 @@
+import { z } from "@hono/zod-openapi";
+/**
+ * Append-only per-step history for a tenant operation (issue #1026).
+ * One row per step boundary: started / succeeded / failed / retried /
+ * skipped, plus `reconciled` when the reconciler sweep copies a terminal
+ * engine state into the database after an instance died mid-run.
+ */
+export declare const tenantOperationEventOutcomeSchema: z.ZodEnum<{
+    failed: "failed";
+    succeeded: "succeeded";
+    started: "started";
+    retried: "retried";
+    skipped: "skipped";
+    reconciled: "reconciled";
+}>;
+export type TenantOperationEventOutcome = z.infer<typeof tenantOperationEventOutcomeSchema>;
+export declare const tenantOperationEventInsertSchema: z.ZodObject<{
+    operation_id: z.ZodString;
+    step: z.ZodString;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        succeeded: "succeeded";
+        started: "started";
+        retried: "retried";
+        skipped: "skipped";
+        reconciled: "reconciled";
+    }>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    attempt: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type TenantOperationEventInsert = z.input<typeof tenantOperationEventInsertSchema>;
+export declare const tenantOperationEventSchema: z.ZodObject<{
+    operation_id: z.ZodString;
+    step: z.ZodString;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        succeeded: "succeeded";
+        started: "started";
+        retried: "retried";
+        skipped: "skipped";
+        reconciled: "reconciled";
+    }>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    attempt: z.ZodDefault<z.ZodNumber>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type TenantOperationEvent = z.infer<typeof tenantOperationEventSchema>;

package/dist/types/types/UserActivity.d.ts

@@ -0,0 +1,17 @@
+import { z } from "@hono/zod-openapi";
+/**
+ * Write-often per-user counters split out of the `users` row (issue #1003) so
+ * the profile row isn't rewritten on every login / failed password attempt.
+ * 1:1 with a user, keyed by `(tenant_id, user_id)`.
+ */
+export declare const userActivitySchema: z.ZodObject<{
+    user_id: z.ZodString;
+    last_login: z.ZodOptional<z.ZodString>;
+    last_ip: z.ZodOptional<z.ZodString>;
+    login_count: z.ZodDefault<z.ZodNumber>;
+    failed_logins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    last_password_reset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UserActivity = z.infer<typeof userActivitySchema>;
+/** Partial payload for an upsert — only the provided fields are written. */
+export type UserActivityUpdate = Partial<Omit<UserActivity, "user_id">>;

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

@@ -29,6 +29,9 @@ export * from "./Password";
 export * from "./Session";
 export * from "./SigningKey";
 export * from "./Tenant";
+export * from "./TenantOperation";
+export * from "./TenantOperationEvent";
+export * from "./Rollout";
 export * from "./Token";
 export * from "./User";
 export * from "./Theme";
@@ -41,6 +44,7 @@ export * from "./SmsProvider";
 export * from "./ResourceServer";
 export * from "./RolePermission";
 export * from "./Grant";
+export * from "./UserActivity";
 export * from "./UserPermission";
 export * from "./UserRole";
 export * from "./Role";

package/package.json

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