appos 0.2.1 → 0.2.3-0

package/dist/exports/api/workflow.d.mts

@@ -0,0 +1,250 @@
+import { Container } from "./container.mjs";
+import { z } from "zod";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+//#region src/api/workflow.d.ts
+
+/**
+ * Context available to workflow functions.
+ */
+interface WorkflowContext<TInput = unknown> {
+  /**
+   * The application container with access to db, mailer, logger, etc.
+   */
+  container: Container;
+  /**
+   * The validated input passed to this workflow.
+   */
+  input: TInput;
+  /**
+   * Execute a checkpointed step within the workflow.
+   * Steps are retried on failure and their results are durably stored.
+   *
+   * @param name - Unique name for this step within the workflow
+   * @param fn - The step function to execute
+   * @returns The result of the step function
+   */
+  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * The unique ID of this workflow execution.
+   */
+  workflowId: string;
+}
+/**
+ * Context available to scheduled workflow functions.
+ */
+interface ScheduledWorkflowContext {
+  /**
+   * The application container with access to db, mailer, logger, etc.
+   */
+  container: Container;
+  /**
+   * The time this workflow execution was scheduled for.
+   */
+  scheduledTime: Date;
+  /**
+   * Execute a checkpointed step within the workflow.
+   * Steps are retried on failure and their results are durably stored.
+   *
+   * @param name - Unique name for this step within the workflow
+   * @param fn - The step function to execute
+   * @returns The result of the step function
+   */
+  step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * The unique ID of this workflow execution.
+   */
+  workflowId: string;
+}
+/**
+ * Handle to a running or completed workflow.
+ */
+interface WorkflowHandle<TOutput> {
+  /**
+   * Get the current status of the workflow.
+   */
+  getStatus(): Promise<unknown>;
+  /**
+   * Wait for the workflow to complete and return its result.
+   */
+  getResult(): Promise<TOutput>;
+  /**
+   * The unique ID of this workflow execution.
+   */
+  workflowId: string;
+}
+/**
+ * Options for defining a workflow.
+ */
+interface DefineWorkflowOptions<TInput extends z.ZodType, TOutput> {
+  /**
+   * Optional configuration for the workflow.
+   */
+  config?: {
+    /**
+     * Maximum number of times to attempt recovery after failure.
+     */
+    maxRecoveryAttempts?: number;
+  };
+  /**
+   * Zod schema for validating workflow input.
+   */
+  input: TInput;
+  /**
+   * The workflow function to execute.
+   *
+   * @param ctx - Workflow context with container, input, and step helper
+   * @returns The workflow result
+   */
+  run: (ctx: WorkflowContext<z.infer<TInput>>) => Promise<TOutput>;
+}
+/**
+ * Defines a durable workflow that can be triggered with type-safe input.
+ *
+ * Workflows are:
+ * - Durable: Automatically resume after crashes or restarts
+ * - Type-safe: Input and output types are inferred from the schema
+ * - Container-aware: Access to db, mailer, logger via ctx.container
+ *
+ * @example
+ * ```typescript
+ * // api/workflows/send-welcome-email.ts
+ * export default defineWorkflow({
+ *   input: z.object({
+ *     userId: z.string(),
+ *     email: z.string().email(),
+ *   }),
+ *   async run(ctx) {
+ *     const user = await ctx.container.db.primary.query.users.findFirst({
+ *       where: eq(users.id, ctx.input.userId),
+ *     });
+ *
+ *     await ctx.container.mailer.send({
+ *       to: ctx.input.email,
+ *       subject: "Welcome!",
+ *     });
+ *
+ *     return { sent: true };
+ *   },
+ * });
+ *
+ * // Triggering from a route:
+ * import sendWelcomeEmail from "#api/workflows/send-welcome-email.ts";
+ * const handle = await sendWelcomeEmail.start({ userId: "123", email: "..." });
+ * ```
+ */
+declare function defineWorkflow<TInput extends z.ZodType, TOutput>(options: DefineWorkflowOptions<TInput, TOutput>): {
+  /**
+   * The Zod schema for validating input.
+   */
+  inputSchema: TInput;
+  /**
+   * The workflow name (set during registration from filename).
+   */
+  readonly name: string | null;
+  /**
+   * Register this workflow with DBOS. Called by the workflow loader.
+   *
+   * @param c - The application container
+   * @param name - The workflow name (derived from filename)
+   * @param dbos - The DBOS instance to use for registration
+   */
+  register(c: Container, name: string, dbos: typeof DBOS): void;
+  /**
+   * Start this workflow with the given input.
+   *
+   * @param input - Input matching the workflow's input schema
+   * @returns A handle to track and retrieve the workflow result
+   */
+  start(input: z.infer<TInput>): Promise<WorkflowHandle<TOutput>>;
+};
+/**
+ * Options for defining a scheduled workflow.
+ */
+interface DefineScheduledWorkflowOptions {
+  /**
+   * Cron expression for when to run the workflow.
+   * Supports 5-spot (minute hour day month weekday) or
+   * 6-spot (second minute hour day month weekday) format.
+   *
+   * Examples:
+   * - "0 9 * * *" - Every day at 9am
+   * - "0,30 * * * *" - Every 30 minutes
+   * - "0 0 * * * *" - Every hour (6-spot with seconds)
+   */
+  crontab: string;
+  /**
+   * The workflow function to execute on schedule.
+   *
+   * @param ctx - Workflow context with container, scheduledTime, and step helper
+   */
+  run: (ctx: ScheduledWorkflowContext) => Promise<void>;
+}
+/**
+ * Defines a scheduled workflow that runs on a cron schedule.
+ *
+ * @example
+ * ```typescript
+ * // api/workflows/daily-report.ts
+ * export default defineScheduledWorkflow({
+ *   crontab: "0 9 * * *", // 9am daily
+ *   async run(ctx) {
+ *     const stats = await ctx.container.db.primary.query.stats.findMany();
+ *     await ctx.container.mailer.send({
+ *       to: "team@company.com",
+ *       subject: `Daily Report - ${ctx.scheduledTime.toDateString()}`,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function defineScheduledWorkflow(options: DefineScheduledWorkflowOptions): {
+  /**
+   * The cron expression for this workflow.
+   */
+  crontab: string;
+  /**
+   * The workflow name (set during registration from filename).
+   */
+  readonly name: string | null;
+  /**
+   * Register this workflow with DBOS. Called by the workflow loader.
+   *
+   * @param c - The application container
+   * @param name - The workflow name (derived from filename)
+   * @param dbos - The DBOS instance to use for registration
+   */
+  register(c: Container, name: string, dbos: typeof DBOS): void;
+};
+/**
+ * Options for loading workflows.
+ */
+interface LoadWorkflowsOptions {
+  /**
+   * The application container.
+   */
+  container: Container;
+  /**
+   * The DBOS instance to use for registration.
+   */
+  dbos: typeof DBOS;
+  /**
+   * Optional custom workflows directory path.
+   */
+  workflowsDir?: string;
+}
+/**
+ * Auto-discovers and registers all workflows.
+ *
+ * Algorithm:
+ * 1. Register built-in workflows (extractBlobMetadata, generateImageVariant, etc.)
+ * 2. Register scheduled workflows (purgeAuditLogs, purgeUnattachedBlobs)
+ * 3. Glob all .ts files in the directory (excluding test files)
+ * 4. Import each module's default export
+ * 5. If it has a register method, call register(container, name, dbos)
+ *
+ * @param opts - Load workflows options
+ */
+declare function loadWorkflows(opts: LoadWorkflowsOptions): Promise<void>;
+//#endregion
+export { ScheduledWorkflowContext, WorkflowContext, WorkflowHandle, defineScheduledWorkflow, defineWorkflow, loadWorkflows };

package/dist/exports/api/workflow.mjs

@@ -0,0 +1 @@
+import{APPOS_DIR as e,WORKFLOWS_DIR as t}from"./packages/appos/src/constants.mjs";import{basename as n,join as r}from"node:path";import{glob as i}from"node:fs/promises";import{camelCase as a}from"es-toolkit";function o(e){let t=null,n=null,r=null,i=null,a=async i=>{if(!t||!r)throw Error(`Workflow "${n}" not registered`);let a=r,o=a.workflowID;if(!o)throw Error(`DBOS.workflowID is not available in this context`);let s={container:t,workflowId:o,input:i,step:(e,t)=>a.runStep(t,{name:e})};return e.run(s)};return{inputSchema:e.input,get name(){return n},register(o,s,c){t=o,n=s,r=c,i=c.registerWorkflow(a,{name:s,...e.config})},async start(t){if(!i||!n||!r)throw Error(`Workflow not registered. Ensure the worker is started before triggering workflows.`);let a=e.input.parse(t),o=await r.startWorkflow(i)(a);return{workflowId:o.workflowID,getStatus:()=>o.getStatus(),getResult:()=>o.getResult()}}}}function s(e){let t=null,n=null,r=null,i=async(i,a)=>{if(!t||!r)throw Error(`Workflow "${n}" not registered`);let o=r,s=o.workflowID;if(!s)throw Error(`DBOS.workflowID is not available in this context`);let c={container:t,workflowId:s,scheduledTime:i,step:(e,t)=>o.runStep(t,{name:e})};return e.run(c)};return{crontab:e.crontab,get name(){return n},register(a,o,s){t=a,n=o,r=s,s.registerScheduled(s.registerWorkflow(i,{name:o}),{crontab:e.crontab})}}}function c(e){return a(n(e,`.ts`))}async function l(n){let{container:a,dbos:o}=n,s=n.workflowsDir??r(process.cwd(),e,t),l=(e,t)=>{try{e.register(a,t,o)}catch(e){if(!(e instanceof Error)||!e.message.includes(`already registered`))throw e}},{extractBlobMetadata:u}=await import(`./workflows/extract-blob-metadata.mjs`),{generateImageVariant:d}=await import(`./workflows/generate-image-variant.mjs`),{generatePreview:f}=await import(`./workflows/generate-preview.mjs`),{purgeAttachment:p}=await import(`./workflows/purge-attachment.mjs`),{trackDbChanges:m}=await import(`./workflows/track-db-changes.mjs`),{definePurgeAuditLogs:h}=await import(`./workflows/purge-audit-logs.mjs`),{definePurgeUnattachedBlobs:g}=await import(`./workflows/purge-unattached-blobs.mjs`);l(u,`extractBlobMetadata`),l(d,`generateImageVariant`),l(f,`generatePreview`),l(p,`purgeAttachment`),l(m,`trackDbChanges`),l(h(a.auth.auditLog?.purgeCron),`purgeAuditLogs`),l(g(a.storage.primary.purgeCron),`purgeUnattachedBlobs`);let _=await Array.fromAsync(i(`${s}/**/*.ts`,{exclude:[`**/*.test.ts`,`**/*.spec.ts`]}));for(let e of _){let t=await import(e);if(t.default&&typeof t.default==`object`&&`register`in t.default){let n=c(e);l(t.default,n)}}}export{s as defineScheduledWorkflow,o as defineWorkflow,l as loadWorkflows};

package/dist/exports/api/workflows/_virtual/rolldown_runtime.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=Object.getOwnPropertyDescriptor,n=Object.getOwnPropertyNames,r=Object.prototype.hasOwnProperty,i=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n&&e(r,Symbol.toStringTag,{value:`Module`}),r},a=(i,a,o,s)=>{if(a&&typeof a==`object`||typeof a==`function`)for(var c=n(a),l=0,u=c.length,d;l<u;l++)d=c[l],!r.call(i,d)&&d!==o&&e(i,d,{get:(e=>a[e]).bind(null,d),enumerable:!(s=t(a,d))||s.enumerable});return i},o=(e,t,n)=>(a(e,t,`default`),n&&a(n,t,`default`));export{i as __export,o as __reExport};

package/dist/exports/api/workflows/auth-schema.mjs

@@ -0,0 +1 @@
+import{sql as e}from"drizzle-orm";import{pgTable as t}from"drizzle-orm/pg-core";function n(){let n=t(`accounts`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),accessToken:t.text(`access_token`),accessTokenExpiresAt:t.timestamp(`access_token_expires_at`,{mode:`string`,withTimezone:!0}),accountId:t.text(`account_id`).notNull(),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),idToken:t.text(`id_token`),providerId:t.text(`provider_id`).notNull(),password:t.text(`password`),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`}),refreshToken:t.text(`refresh_token`),refreshTokenExpiresAt:t.timestamp(`refresh_token_expires_at`,{mode:`string`,withTimezone:!0}),scope:t.text(`scope`),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),r=t(`api_keys`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),name:t.text(`name`),enabled:t.boolean(`enabled`).default(!0),expiresAt:t.timestamp(`expires_at`,{mode:`string`,withTimezone:!0}),key:t.text(`key`).notNull(),lastRefillAt:t.timestamp(`last_refill_at`,{mode:`string`,withTimezone:!0}),lastRequest:t.timestamp(`last_request`,{mode:`string`,withTimezone:!0}),lastUsedAt:t.timestamp(`last_used_at`,{mode:`string`,withTimezone:!0}),metadata:t.text(`metadata`),permissions:t.text(`permissions`),prefix:t.text(`prefix`),rateLimitEnabled:t.boolean(`rate_limit_enabled`).default(!0),rateLimitTimeWindow:t.integer(`rate_limit_time_window`).default(864e5),rateLimitMax:t.integer(`rate_limit_max`).default(10),refillInterval:t.integer(`refill_interval`),refillAmount:t.integer(`refill_amount`),requestCount:t.integer(`request_count`),remaining:t.integer(`remaining`),start:t.text(`start`),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`}),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),i=t(`invitations`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),email:t.text(`email`).notNull(),expiresAt:t.timestamp(`expires_at`,{mode:`string`,withTimezone:!0}).notNull(),inviterId:t.text(`inviter_id`).notNull().references(()=>l.id,{onDelete:`cascade`}),organizationId:t.text(`organization_id`).notNull().references(()=>o.id,{onDelete:`cascade`}),role:t.text(`role`),status:t.text(`status`).default(`pending`).notNull(),teamId:t.text(`team_id`),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),a=t(`members`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),organizationId:t.text(`organization_id`).notNull().references(()=>o.id,{onDelete:`cascade`}),role:t.text(`role`).default(`member`).notNull(),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`}),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),o=t(`organizations`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),name:t.text(`name`).notNull(),slug:t.text(`slug`).unique(),logo:t.text(`logo`),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),metadata:t.text(`metadata`)}),e=>[]),s=t(`sessions`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),activeOrganizationId:t.text(`active_organization_id`).references(()=>o.id,{onDelete:`set null`}),activeTeamId:t.text(`active_team_id`),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),expiresAt:t.timestamp(`expires_at`,{mode:`string`,withTimezone:!0}).notNull(),impersonatedBy:t.text(`impersonated_by`).references(()=>l.id,{onDelete:`set null`}),ipAddress:t.text(`ip_address`),token:t.text(`token`).notNull().unique(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),userAgent:t.text(`user_agent`),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`})}),e=>[]),c=t(`sso_providers`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),domain:t.text(`domain`).notNull(),issuer:t.text(`issuer`).notNull(),oidcConfig:t.text(`oidc_config`),organizationId:t.text(`organization_id`).references(()=>o.id,{onDelete:`cascade`}),providerId:t.text(`provider_id`).notNull().unique(),samlConfig:t.text(`saml_config`),userId:t.text(`user_id`).references(()=>l.id,{onDelete:`cascade`})}),e=>[]),l=t(`users`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),banExpires:t.timestamp(`ban_expires`,{mode:`string`,withTimezone:!0}),banReason:t.text(`ban_reason`),banned:t.boolean(`banned`).default(!1),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),displayUsername:t.text(`display_username`),email:t.text(`email`).notNull().unique(),emailVerified:t.boolean(`email_verified`).default(!1).notNull(),image:t.text(`image`),isAnonymous:t.boolean(`is_anonymous`),lastLoginMethod:t.text(`last_login_method`),name:t.text(`name`).notNull(),phoneNumber:t.text(`phone_number`).unique(),phoneNumberVerified:t.boolean(`phone_number_verified`),role:t.text(`role`),twoFactorEnabled:t.boolean(`two_factor_enabled`).default(!1),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),username:t.text(`username`).unique()}),e=>[]),u=t(`teams`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),name:t.text(`name`).notNull(),organizationId:t.text(`organization_id`).notNull().references(()=>o.id,{onDelete:`cascade`}),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),d=t(`team_members`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),teamId:t.text(`team_id`).notNull().references(()=>u.id,{onDelete:`cascade`}),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`}),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),f=t(`two_factors`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),secret:t.text(`secret`).notNull(),backupCodes:t.text(`backup_codes`).notNull(),userId:t.text(`user_id`).notNull().references(()=>l.id,{onDelete:`cascade`})}),e=>[]),p=t(`verifications`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),expiresAt:t.timestamp(`expires_at`,{mode:`string`,withTimezone:!0}).notNull(),identifier:t.text(`identifier`).notNull(),updatedAt:t.timestamp(`updated_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull(),value:t.text(`value`).notNull()}),e=>[]);return{tables:{accounts:n,apiKeys:r,auditLogs:t(`audit_logs`,t=>({id:t.text(`id`).primaryKey().default(e`uuidv7()`),tableName:t.text(`table_name`),action:t.text(`action`).notNull(),customAction:t.text(`custom_action`),oldData:t.jsonb(`old_data`),newData:t.jsonb(`new_data`),metadata:t.jsonb(`metadata`),organizationId:t.text(`organization_id`).references(()=>o.id,{onDelete:`set null`}),userId:t.text(`user_id`).references(()=>l.id,{onDelete:`set null`}),sessionId:t.text(`session_id`).references(()=>s.id,{onDelete:`set null`}),requestId:t.text(`request_id`),createdAt:t.timestamp(`created_at`,{mode:`string`,withTimezone:!0}).default(e`NOW()`).notNull()}),e=>[]),invitations:i,members:a,organizations:o,sessions:s,ssoProviders:c,teams:u,teamMembers:d,twoFactors:f,users:l,verifications:p},relations:e=>({users:{sessions:e.many.sessions({from:e.users.id,to:e.sessions.userId}),accounts:e.many.accounts({from:e.users.id,to:e.accounts.userId}),apiKeys:e.many.apiKeys({from:e.users.id,to:e.apiKeys.userId}),memberships:e.many.members({from:e.users.id,to:e.members.userId}),invitations:e.many.invitations({from:e.users.id,to:e.invitations.inviterId}),ssoProvider:e.one.ssoProviders({from:e.users.id,to:e.ssoProviders.userId}),twoFactor:e.one.twoFactors({from:e.users.id,to:e.twoFactors.userId})},sessions:{user:e.one.users({from:e.sessions.userId,to:e.users.id})},accounts:{user:e.one.users({from:e.accounts.userId,to:e.users.id})},apiKeys:{user:e.one.users({from:e.apiKeys.userId,to:e.users.id})},organizations:{members:e.many.members({from:e.organizations.id,to:e.members.organizationId}),invitations:e.many.invitations({from:e.organizations.id,to:e.invitations.organizationId}),teams:e.many.teams({from:e.organizations.id,to:e.teams.organizationId})},members:{organization:e.one.organizations({from:e.members.organizationId,to:e.organizations.id}),user:e.one.users({from:e.members.userId,to:e.users.id})},invitations:{organization:e.one.organizations({from:e.invitations.organizationId,to:e.organizations.id}),inviter:e.one.users({from:e.invitations.inviterId,to:e.users.id})},teams:{organization:e.one.organizations({from:e.teams.organizationId,to:e.organizations.id})},ssoProviders:{user:e.one.users({from:e.ssoProviders.userId,to:e.users.id})},verifications:{},twoFactors:{user:e.one.users({from:e.twoFactors.userId,to:e.users.id})},auditLogs:{organization:e.one.organizations({from:e.auditLogs.organizationId,to:e.organizations.id}),user:e.one.users({from:e.auditLogs.userId,to:e.users.id}),session:e.one.sessions({from:e.auditLogs.sessionId,to:e.sessions.id})}})}}export{n as defineAuthSchema};

package/dist/exports/api/workflows/auth.d.mts

@@ -0,0 +1,375 @@
+import { Database, QualifiedTableNames } from "./database.mjs";
+import { z } from "zod";
+import { betterAuth } from "better-auth";
+import { Role, createAccessControl } from "better-auth/plugins/access";
+
+//#region src/api/auth.d.ts
+
+/**
+ * Type for access controller created via createAccessControl().
+ * Used for RBAC on both server and client.
+ */
+type AccessController = ReturnType<typeof createAccessControl>;
+/**
+ * Type for roles created via ac.newRole().
+ * Uses Role type from better-auth for compatibility.
+ */
+type AccessControlRoles = Record<string, Role>;
+/**
+ * Type-safe audit log options for defineAuth().
+ * Generic over db object to provide autocomplete for excludeTables.
+ *
+ * @template TDb - Database record type for table name inference
+ */
+type AuditLogOptions<TDb> = {
+  /**
+   * Tables to exclude from audit logging.
+   */
+  excludeTables?: QualifiedTableNames<TDb>[];
+  /**
+   * Cron expression for purge schedule.
+   *
+   * @default "0 0 * * *"
+   */
+  purgeCron?: string;
+  /**
+   * Retention period in days. Audit logs older than this are auto-deleted.
+   * @default 90
+   */
+  retentionDays?: number;
+};
+/**
+ * Neutral auth configuration - shared between server and client.
+ * Contains ONLY fields that affect both sides (UI + server features).
+ *
+ * PRESENCE-BASED CONFIG: If a key exists, it's enabled. No redundant `enabled` fields.
+ * Server-only fields (appName, session) are passed via DefineAuthOptions.
+ */
+interface AuthConfig {
+  /**
+   * Base URL where auth server is hosted.
+   *
+   * @default "" (same origin - client uses relative URLs)
+   * @example "http://localhost:8000" for cross-origin
+   */
+  baseURL?: string;
+  /**
+   * Base path for auth routes.
+   *
+   * @default "/auth"
+   */
+  basePath?: string;
+  /** Authentication methods - if defined, it's enabled */
+  methods?: {
+    /** Email/password auth. If defined, enabled. */
+    emailPassword?: {
+      requireEmailVerification?: boolean;
+      minPasswordLength?: number;
+      maxPasswordLength?: number;
+    };
+    /** Magic link auth. If defined, enabled. */
+    magicLink?: {
+      expiresIn?: number;
+    };
+    /** Passkey auth. If defined (even as empty object), enabled. */
+    passkey?: Record<string, never>;
+    /** Phone OTP auth. If defined, enabled. */
+    phoneOtp?: {
+      otpLength?: number;
+      expiresIn?: number;
+    };
+    /** Email OTP auth. If defined, enabled. */
+    emailOtp?: {
+      otpLength?: number;
+      expiresIn?: number;
+    };
+  };
+  /** OAuth providers - true = enabled, undefined/false = disabled */
+  oauth?: {
+    google?: boolean;
+    github?: boolean;
+    apple?: boolean;
+    facebook?: boolean;
+  };
+  /** Plugins - if defined, it's enabled */
+  plugins?: {
+    /** Admin plugin. If defined, enabled. Includes RBAC for both server and client. */
+    admin?: {
+      defaultRole?: string;
+      adminRoles?: string[];
+      /** Access controller created via createAccessControl() - shared between server and client */
+      ac: AccessController;
+      /** Role definitions created via ac.newRole() - shared between server and client */
+      roles: AccessControlRoles;
+    };
+    /** API key plugin. If defined, enabled. */
+    apiKey?: {
+      defaultPrefix?: string;
+      defaultKeyLength?: number;
+      rateLimit?: {
+        maxRequests?: number;
+        timeWindow?: number;
+      };
+    };
+    /** Two-factor plugin. If defined, enabled. Sub-features also presence-based. */
+    twoFactor?: {
+      issuer?: string;
+      totp?: {
+        digits?: 6 | 8;
+        period?: number;
+      };
+      otp?: boolean;
+      backupCodes?: {
+        amount?: number;
+        length?: number;
+      };
+    };
+    /** Multi-session plugin. If defined, enabled. */
+    multiSession?: {
+      maximumSessions?: number;
+    };
+    /** Username plugin. If defined, enabled. */
+    username?: {
+      minUsernameLength?: number;
+      maxUsernameLength?: number;
+    };
+    /** Anonymous auth plugin. If defined, enabled. */
+    anonymous?: {
+      emailDomainName?: string;
+    };
+    /** SSO plugin. If defined, enabled. Import from @better-auth/sso */
+    sso?: {
+      providersLimit?: number;
+      trustEmailVerified?: boolean;
+      domainVerification?: boolean;
+    };
+  };
+}
+/** Base hook types for reference */
+type EmailHook = (params: {
+  email: string;
+  url: string;
+  token: string;
+}) => Promise<void>;
+type OtpHook = (params: {
+  email: string;
+  otp: string;
+}) => Promise<void>;
+type PhoneOtpHook = (params: {
+  phoneNumber: string;
+  otp: string;
+}) => Promise<void>;
+/**
+ * Conditionally required hooks based on config.
+ * Uses PRESENCE-BASED detection - if key exists, hook is REQUIRED.
+ */
+type RequiredHooks<T extends AuthConfig> = (T["methods"] extends {
+  emailPassword: {
+    requireEmailVerification: true;
+  };
+} ? {
+  sendVerificationEmail: EmailHook;
+} : {
+  sendVerificationEmail?: EmailHook;
+}) & (T["methods"] extends {
+  emailPassword: object;
+} ? {
+  sendResetPasswordEmail: EmailHook;
+} : {
+  sendResetPasswordEmail?: EmailHook;
+}) & (T["methods"] extends {
+  magicLink: object;
+} ? {
+  sendMagicLink: EmailHook;
+} : {
+  sendMagicLink?: EmailHook;
+}) & (T["methods"] extends {
+  emailOtp: object;
+} ? {
+  sendEmailOTP: OtpHook;
+} : {
+  sendEmailOTP?: OtpHook;
+}) & (T["methods"] extends {
+  phoneOtp: object;
+} ? {
+  sendPhoneOTP: PhoneOtpHook;
+} : {
+  sendPhoneOTP?: PhoneOtpHook;
+}) & (T["plugins"] extends {
+  twoFactor: {
+    otp: true;
+  };
+} ? {
+  send2FAOTP: OtpHook;
+} : {
+  send2FAOTP?: OtpHook;
+});
+/**
+ * Conditionally required OAuth credentials based on config.
+ * If an OAuth provider is enabled in config, its credentials are REQUIRED.
+ */
+type RequiredOAuth<T extends AuthConfig> = (T["oauth"] extends {
+  google: true;
+} ? {
+  google: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  google?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  github: true;
+} ? {
+  github: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  github?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  apple: true;
+} ? {
+  apple: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  apple?: {
+    clientId: string;
+    clientSecret: string;
+  };
+}) & (T["oauth"] extends {
+  facebook: true;
+} ? {
+  facebook: {
+    clientId: string;
+    clientSecret: string;
+  };
+} : {
+  facebook?: {
+    clientId: string;
+    clientSecret: string;
+  };
+});
+/** Check if any OAuth provider is enabled */
+type HasOAuthEnabled<T extends AuthConfig> = T["oauth"] extends {
+  google: true;
+} | {
+  github: true;
+} | {
+  apple: true;
+} | {
+  facebook: true;
+} ? true : false;
+/** Check if passkey is enabled */
+type HasPasskeyEnabled<T extends AuthConfig> = T["methods"] extends {
+  passkey: object;
+} ? true : false;
+/**
+ * Server-only session configuration.
+ */
+interface AuthSessionConfig {
+  /**
+   * Session duration in seconds.
+   *
+   * @default 604800 (7 days)
+   */
+  expiresIn?: number;
+  /**
+   * How often to update session in seconds.
+   *
+   * @default 86400 (1 day)
+   */
+  updateAge?: number;
+  /**
+   * Session freshness in seconds for sensitive ops.
+   *
+   * @default 86400 (1 day)
+   */
+  freshAge?: number;
+}
+/**
+ * Server-only passkey configuration (required if passkey is enabled).
+ */
+interface AuthPasskeyConfig {
+  /**
+   * Relying Party ID - domain for passkey (e.g., "example.com" or "localhost").
+   */
+  rpID: string;
+  /**
+   * Origin URL for passkey verification (e.g., "http://localhost:8000").
+   */
+  origin: string;
+}
+/**
+ * Fully type-safe options for defineAuth().
+ *
+ * Server-only fields:
+ * - `appName` - Application name for passkey rpName, TOTP issuer, emails
+ * - `auditLog` - Audit logging configuration
+ * - `session` - Session duration and freshness settings
+ *
+ * Conditional requirements:
+ * - If config has `oauth.google: true`, then `oauth.google` credentials are REQUIRED
+ * - If config has `methods.magicLink` defined, then `hooks.sendMagicLink` is REQUIRED
+ *
+ * @template T - Auth config type
+ * @template TDb - Database record type for type-safe excludeTables
+ */
+type DefineAuthOptions<T extends AuthConfig, TDb = unknown> = {
+  /**
+   * The application name.
+   */
+  appName: string;
+  /**
+   * Audit logging configuration (server-only). Use qualified table names: "dbName.tableName".
+   */
+  auditLog?: AuditLogOptions<TDb>;
+  /**
+   * The neutral auth configuration.
+   */
+  config: T;
+  /**
+   * Full db object (container.db) for type inference.
+   */
+  db: TDb;
+  /**
+   * Primary database for Better Auth storage.
+   */
+  database: Database;
+  /**
+   * Hooks for email sending and OTP delivery.
+   */
+  hooks: RequiredHooks<T>;
+  /**
+   * Session configuration.
+   */
+  session?: AuthSessionConfig;
+} & (HasOAuthEnabled<T> extends true ? {
+  oauth: RequiredOAuth<T>;
+} : {
+  oauth?: RequiredOAuth<T>;
+}) & (HasPasskeyEnabled<T> extends true ? {
+  passkey: AuthPasskeyConfig;
+} : {
+  passkey?: AuthPasskeyConfig;
+});
+/**
+ * Defines Better Auth instance from neutral config + server dependencies.
+ */
+declare function defineAuth<T extends AuthConfig, TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>>(opts: DefineAuthOptions<T, TDb>): ReturnType<typeof betterAuth> & {
+  auditLog?: AuditLogOptions<TDb>;
+  shouldAudit(tableName: QualifiedTableNames<TDb>): boolean;
+};
+/**
+ * The auth instance type.
+ */
+type Auth<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> = ReturnType<typeof defineAuth<AuthConfig, TDb>>;
+//#endregion
+export { Auth };

package/dist/exports/api/workflows/cache.d.mts

@@ -0,0 +1,44 @@
+import { Logger } from "./logger.mjs";
+import * as keyv0 from "keyv";
+import { KeyvRedisOptions } from "@keyv/redis";
+
+//#region src/api/cache.d.ts
+/**
+ * The cache instance type.
+ */
+type Cache = ReturnType<typeof defineCache>;
+/**
+ * Options for defining the cache.
+ */
+type DefineCacheOptions = {
+  /**
+   * Redis URL(s). Single or comma-separated for cluster.
+   */
+  url: string;
+  /**
+   * The logger instance.
+   */
+  logger: Logger;
+  /**
+   * The Keyv Redis options.
+   */
+  options?: KeyvRedisOptions;
+};
+/**
+ * Define the cache instance using shared Redis client.
+ * Connection is lazy - only connects when first cache operation is performed.
+ *
+ * Algorithm:
+ * 1. Create Redis client using defineRedisClient() (lazy connection)
+ * 2. Pass client to createKeyv() - connection happens on first use
+ *
+ * @param opts - The options for defining the cache.
+ * @returns The cache instance.
+ */
+declare function defineCache({
+  url,
+  logger,
+  options
+}: DefineCacheOptions): keyv0.Keyv<any>;
+//#endregion
+export { Cache };