appos 0.2.1 → 0.2.2-0

package/dist/exports/tests/packages/appos/src/api/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/tests/packages/appos/src/api/auth.d.mts

@@ -0,0 +1,398 @@
+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>;
+/**
+ * Standard audit log actions following OCSF/CADF standards.
+ * Zod enum provides both runtime validation and TypeScript type.
+ *
+ * Actions:
+ * - Data ops: INSERT, UPDATE, DELETE, TRUNCATE, SELECT
+ * - Auth ops: LOGIN, LOGOUT, LOGIN_FAILED, PASSWORD_CHANGE
+ * - Custom: CUSTOM (use customAction field for app-specific events)
+ */
+declare const auditActionSchema: z.ZodEnum<{
+  DELETE: "DELETE";
+  LOGIN: "LOGIN";
+  LOGOUT: "LOGOUT";
+  INSERT: "INSERT";
+  PASSWORD_CHANGE: "PASSWORD_CHANGE";
+  TRUNCATE: "TRUNCATE";
+  UPDATE: "UPDATE";
+}>;
+/**
+ * TypeScript type extracted from Zod enum.
+ * Use this type for type annotations.
+ */
+type AuditAction = z.infer<typeof auditActionSchema>;
+/**
+ * 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$1<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> = ReturnType<typeof defineAuth<AuthConfig, TDb>>;
+//#endregion
+export { AccessControlRoles, AccessController, AuditAction, Auth$1 as Auth, AuthConfig, AuthPasskeyConfig, AuthSessionConfig, DefineAuthOptions, type Role, auditActionSchema, createAccessControl, defineAuth };

package/dist/exports/tests/packages/appos/src/api/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, DefineCacheOptions, defineCache };

package/dist/exports/tests/packages/appos/src/api/config.d.mts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+//#region src/api/config.d.ts
+
+/**
+ * The config base schema.
+ */
+declare const baseSchema: z.ZodObject<{
+  APP_NAME: z.ZodDefault<z.ZodString>;
+  APP_DESC: z.ZodDefault<z.ZodString>;
+  APP_VERSION: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Creates a configuration object by merging base config with user-defined schema.
+ *
+ * Variables in default values are expanded after defaults are applied.
+ * For example: `DATABASE_URL: z.string().default("postgres://{{DB_HOST}}:5432")`
+ *
+ * @param userSchema User-defined Zod schema to merge with base config.
+ * @returns Parsed and validated configuration object.
+ */
+declare function defineConfig<T extends z.ZodRawShape = {}>(userSchema: z.ZodObject<T>): Config<T>;
+/**
+ * The configuration type inferred from the merged schema.
+ */
+type Config<T extends z.ZodRawShape = {}> = z.infer<ReturnType<typeof baseSchema.extend<T>>>;
+//#endregion
+export { Config, baseSchema, defineConfig };

package/dist/exports/tests/packages/appos/src/api/container.d.mts

@@ -0,0 +1,210 @@
+import { Logger } from "./logger.mjs";
+import { Database } from "./database.mjs";
+import { Auth } from "./auth.mjs";
+import { Cache } from "./cache.mjs";
+import { Config } from "./config.mjs";
+import { EventBus } from "./event.mjs";
+import { Mailer } from "./mailer.mjs";
+import { Storage } from "./storage.mjs";
+import { CorsOptions } from "cors";
+import { Options } from "express-rate-limit";
+import { HelmetOptions } from "helmet";
+import { i18n } from "i18next";
+
+//#region src/api/container.d.ts
+
+/**
+ * Server configuration for the HTTP server.
+ */
+interface ServerConfig {
+  /**
+   * The host address the server will bind to.
+   *
+   * @default "0.0.0.0"
+   */
+  host?: string;
+  /**
+   * The port number the server will listen on.
+   */
+  port: number;
+  /**
+   * Request timeout in milliseconds. Requests exceeding this duration
+   * will receive a 408 Request Timeout response.
+   *
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * Maximum request body size for JSON and URL-encoded payloads.
+   * Supports bytes.js format strings (e.g., "1mb", "500kb", "10mb").
+   *
+   * @default "1mb"
+   */
+  bodyLimit?: string;
+  /**
+   * The path for the health check endpoint.
+   *
+   * @default "/health"
+   */
+  healthPath?: string;
+  /**
+   * CORS configuration. Omit or set to undefined to disable.
+   *
+   * @example
+   * cors: { origin: "https://example.com", credentials: true }
+   */
+  cors?: CorsOptions;
+  /**
+   * Security headers configuration (via helmet). Omit or set to undefined to disable.
+   * Recommended for production deployments.
+   *
+   * @example
+   * helmet: { contentSecurityPolicy: false }  // Enable with CSP disabled
+   * helmet: {}  // Enable with all defaults
+   */
+  helmet?: HelmetOptions;
+  /**
+   * Rate limiting configuration. Array of express-rate-limit options.
+   * Each config is applied as a separate middleware - use `skip` function for path-specific limits.
+   * Redis store is automatically configured if `redisUrl` is provided.
+   *
+   * @example
+   * // Global rate limit
+   * rateLimit: [{ windowMs: 60000, limit: 100 }]
+   *
+   * @example
+   * // Path-specific rate limits
+   * rateLimit: [
+   *   { windowMs: 900000, limit: 5, skip: (req) => !req.path.startsWith("/api/auth") },
+   *   { windowMs: 60000, limit: 100 },  // Default for all other routes
+   * ]
+   */
+  rateLimit?: Options[];
+  /**
+   * Redis URL for rate limiting store (for multi-instance deployments).
+   * Server auto-connects and cleans up on shutdown.
+   * If omitted, uses in-memory store (not suitable for production clusters).
+   *
+   * @example
+   * redisUrl: "redis://localhost:6379"
+   */
+  redisUrl?: string;
+}
+/**
+ * Worker configuration for the DBOS workflow worker.
+ */
+interface WorkerConfig {
+  /**
+   * The system database URL for DBOS.
+   */
+  dbUrl: string;
+}
+/**
+ * The base application container type that holds required services like
+ * config, databases, and caches.
+ */
+interface AppContainer<TDb extends Record<"primary", Database> & Record<string, Database> = Record<"primary", Database> & Record<string, Database>> {
+  /**
+   * The application auth configuration.
+   */
+  auth: Auth<TDb>;
+  /**
+   * A map of caches available in the application.
+   */
+  cache: Record<string, Cache>;
+  /**
+   * The application configuration.
+   */
+  config: Config;
+  /**
+   * A map of databases available in the application.
+   */
+  db: TDb;
+  /**
+   * The i18n instance for internationalization.
+   */
+  i18n: i18n;
+  /**
+   * The logger instance for logging messages.
+   */
+  logger: Logger;
+  /**
+   * The event bus for in-memory and Redis pub/sub messaging.
+   */
+  eventBus: EventBus;
+  /**
+   * The mailer instance for sending emails.
+   */
+  mailer: Mailer;
+  /**
+   * Server configuration for the HTTP server.
+   */
+  server: ServerConfig;
+  /**
+   * A map of storage services available in the application.
+   */
+  storage: Record<"primary", Storage> & Record<string, Storage>;
+  /**
+   * Worker configuration for the DBOS workflow worker.
+   */
+  worker: WorkerConfig;
+}
+/**
+ * Global namespace for user container augmentation.
+ * Users can extend Container interface in their container.ts file.
+ */
+declare global {
+  namespace AppOS {
+    interface Container {}
+  }
+}
+/**
+ * The container type used throughout the application.
+ * Merges base AppContainer with user's custom Container augmentations.
+ */
+type Container = AppContainer & AppOS.Container;
+/**
+ * Defines an application container with type-safe validation and inference.
+ *
+ * This helper function ensures that:
+ * 1. All required base fields (config, cache, db) are provided
+ * 2. Custom fields are fully preserved in the inferred type
+ * 3. TypeScript provides autocomplete for all fields in commands/routes
+ *
+ * @template T - The container type extending AppContainer
+ * @param container - The container object with required and custom fields
+ * @returns The same container object with full type inference
+ *
+ * @example
+ * ```typescript
+ * // In your api/main.ts file:
+ * export async function defineContainer() {
+ *   const config = defineConfig(z.object({
+ *     PORT: z.coerce.number().default(3000),
+ *     EVENTS_DB_URL: z.string(),
+ *     WORKER_DB_URL: z.string(),
+ *   }));
+ *   const logger = defineLogger({ level: config.LOG_LEVEL });
+ *
+ *   return defineAppContainer({
+ *     auth: defineAuth({ config }),
+ *     cache: {},
+ *     config,
+ *     db: {},
+ *     eventBus: defineEventBus({ dbUrl: config.EVENTS_DB_URL, logger }),
+ *     i18n: await defineI18n({ ... }),
+ *     logger,
+ *     mailer: defineMailer({ ... }),
+ *     server: {
+ *       port: config.PORT,
+ *     },
+ *     worker: {
+ *       dbUrl: config.WORKER_DB_URL,
+ *     },
+ *   });
+ * }
+ * ```
+ */
+declare function defineAppContainer<T extends AppContainer>(container: T): T;
+//#endregion
+export { AppContainer, Container, ServerConfig, WorkerConfig, defineAppContainer };