@digilogiclabs/platform-core 1.7.0 → 1.8.0

package/dist/{env-DerQ7Da-.d.mts → env-jqNJdZVt.d.mts}

@@ -1,5 +1,269 @@
 import { z } from 'zod';
 
+/**
+ * Beta Access Management Interface
+ *
+ * Provides a vendor-agnostic way to manage beta/early-access programs.
+ * Handles invite codes, access gating, settings, and analytics across
+ * all DLL Platform applications.
+ *
+ * Features:
+ * - Beta mode settings (mode, require code, custom message)
+ * - Invite code management (create, validate, consume, revoke)
+ * - Multi-use codes with usage tracking and expiration
+ * - Profile tagging (beta tester flag, join date)
+ * - Analytics (usage stats, per-code reports)
+ * - Live toggling (closed beta → open beta → public launch)
+ *
+ * @example
+ * ```typescript
+ * import { MemoryBeta } from '@digilogiclabs/platform-core';
+ *
+ * const beta = new MemoryBeta();
+ *
+ * // Check if beta is active
+ * const settings = await beta.getSettings();
+ * if (settings.requireInviteCode) {
+ *   const result = await beta.validateCode('BETA2026');
+ *   if (result.valid) {
+ *     await beta.consumeCode('BETA2026', 'user_123');
+ *   }
+ * }
+ *
+ * // Create invite codes
+ * const codes = await beta.createCodes({
+ *   count: 10,
+ *   prefix: 'DLL',
+ *   maxUses: 5,
+ *   createdBy: 'admin',
+ * });
+ *
+ * // Transition to public launch
+ * await beta.updateSettings({ betaMode: false, requireInviteCode: false });
+ * ```
+ */
+/** Beta program settings */
+interface BetaSettings {
+    /** Whether the app is in beta mode (shows beta messaging) */
+    betaMode: boolean;
+    /** Whether an invite code is required to sign up */
+    requireInviteCode: boolean;
+    /** Custom message to display during beta */
+    betaMessage: string;
+}
+/** Options for updating beta settings */
+interface UpdateBetaSettingsOptions {
+    betaMode?: boolean;
+    requireInviteCode?: boolean;
+    betaMessage?: string;
+    updatedBy?: string;
+}
+/** A beta invite code */
+interface BetaInviteCode {
+    /** Unique identifier */
+    id: string;
+    /** The invite code string (normalized to uppercase) */
+    code: string;
+    /** Maximum number of times this code can be used */
+    maxUses: number;
+    /** Current number of times this code has been used */
+    currentUses: number;
+    /** Optional expiration date */
+    expiresAt: Date | null;
+    /** Who created this code */
+    createdBy: string;
+    /** Admin notes about this code */
+    notes: string;
+    /** Whether this code is active (soft delete) */
+    isActive: boolean;
+    /** When this code was created */
+    createdAt: Date;
+}
+/** Options for creating invite codes */
+interface CreateBetaCodesOptions {
+    /** Number of codes to generate (max 50) */
+    count?: number;
+    /** Prefix for generated codes (e.g., 'DLL' → 'DLL-A1B2C3D4') */
+    prefix?: string;
+    /** Specific code string (for named codes like 'BETA2026') */
+    code?: string;
+    /** Maximum uses per code (default: 1) */
+    maxUses?: number;
+    /** Optional expiration date */
+    expiresAt?: Date;
+    /** Who is creating the codes */
+    createdBy: string;
+    /** Admin notes */
+    notes?: string;
+}
+/** Filter for listing invite codes */
+type BetaCodeStatus = "unused" | "partial" | "exhausted" | "expired" | "revoked";
+interface ListBetaCodesOptions {
+    /** Filter by status */
+    status?: BetaCodeStatus;
+    /** Filter by active state */
+    isActive?: boolean;
+    /** Pagination offset */
+    offset?: number;
+    /** Pagination limit */
+    limit?: number;
+}
+/** Result of validating a beta code (read-only, does not consume) */
+interface BetaValidationResult {
+    /** Whether the code is valid */
+    valid: boolean;
+    /** Human-readable message */
+    message: string;
+    /** The normalized code (if valid) */
+    code?: string;
+    /** Remaining uses (if valid) */
+    remainingUses?: number;
+}
+/** Result of consuming a beta code */
+interface BetaConsumeResult {
+    /** Whether the code was successfully consumed */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+}
+/** Beta tester profile metadata */
+interface BetaTester {
+    /** User identifier */
+    userId: string;
+    /** The invite code they used */
+    inviteCode: string;
+    /** Whether they are flagged as a beta tester */
+    isBetaTester: boolean;
+    /** When they joined beta */
+    betaJoinedAt: Date;
+}
+/** Aggregate beta program statistics */
+interface BetaStats {
+    /** Total number of beta testers */
+    totalBetaTesters: number;
+    /** Total invite codes created */
+    totalCodes: number;
+    /** Number of active (usable) codes */
+    activeCodes: number;
+    /** Total uses across all codes */
+    totalUses: number;
+    /** Total remaining capacity across all codes */
+    totalRemaining: number;
+    /** Earliest beta signup */
+    firstBetaSignup: Date | null;
+    /** Most recent beta signup */
+    latestBetaSignup: Date | null;
+}
+/** Per-code usage report */
+interface BetaCodeUsageReport {
+    /** The invite code */
+    code: string;
+    /** Admin notes */
+    notes: string;
+    /** Maximum uses */
+    maxUses: number;
+    /** Current uses */
+    currentUses: number;
+    /** Remaining uses */
+    remainingUses: number;
+    /** Usage percentage (0-100) */
+    usagePercent: number;
+    /** Whether the code is active */
+    isActive: boolean;
+    /** Expiration date */
+    expiresAt: Date | null;
+    /** Creation date */
+    createdAt: Date;
+}
+/** Configuration for beta adapters */
+interface BetaConfig {
+    /** Default beta mode on initialization */
+    defaultBetaMode?: boolean;
+    /** Default require invite code on initialization */
+    defaultRequireInviteCode?: boolean;
+    /** Default beta message */
+    defaultBetaMessage?: string;
+    /** Code prefix for generated codes (e.g., 'DLL', 'WIAN') */
+    codePrefix?: string;
+    /** Maximum codes per createCodes call (default: 50) */
+    maxCodesPerBatch?: number;
+}
+interface IBeta {
+    /** Get current beta program settings */
+    getSettings(): Promise<BetaSettings>;
+    /** Update beta program settings (live toggle, no redeploy needed) */
+    updateSettings(options: UpdateBetaSettingsOptions): Promise<void>;
+    /** Create one or more invite codes */
+    createCodes(options: CreateBetaCodesOptions): Promise<BetaInviteCode[]>;
+    /** List invite codes with optional filtering */
+    listCodes(options?: ListBetaCodesOptions): Promise<BetaInviteCode[]>;
+    /** Get a specific invite code by its code string */
+    getCode(code: string): Promise<BetaInviteCode | null>;
+    /** Revoke an invite code (soft delete — sets isActive to false) */
+    revokeCode(code: string): Promise<void>;
+    /**
+     * Validate an invite code (read-only, does not consume).
+     * If requireInviteCode is false, always returns { valid: true }.
+     */
+    validateCode(code: string): Promise<BetaValidationResult>;
+    /**
+     * Consume an invite code for a user (increments usage, tags user).
+     * Should be called after successful signup, not before.
+     */
+    consumeCode(code: string, userId: string): Promise<BetaConsumeResult>;
+    /** Check if a user is a beta tester */
+    isBetaTester(userId: string): Promise<boolean>;
+    /** Get beta tester details for a user */
+    getBetaTester(userId: string): Promise<BetaTester | null>;
+    /** List all beta testers */
+    listBetaTesters(options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<BetaTester[]>;
+    /** Get aggregate beta program statistics */
+    getStats(): Promise<BetaStats>;
+    /** Get per-code usage reports */
+    getCodeUsageReports(): Promise<BetaCodeUsageReport[]>;
+    /** Check beta service health */
+    healthCheck(): Promise<boolean>;
+}
+/** Generate a random hex code with prefix (e.g., 'DLL-A1B2C3D4') */
+declare function generateBetaCode(prefix?: string): string;
+/** Normalize a code for comparison (trim + uppercase) */
+declare function normalizeBetaCode(code: string): string;
+/** Generate a unique ID for beta records */
+declare function generateBetaId(): string;
+declare class MemoryBeta implements IBeta {
+    private settings;
+    private codes;
+    private testers;
+    private config;
+    constructor(config?: BetaConfig);
+    getSettings(): Promise<BetaSettings>;
+    updateSettings(options: UpdateBetaSettingsOptions): Promise<void>;
+    createCodes(options: CreateBetaCodesOptions): Promise<BetaInviteCode[]>;
+    listCodes(options?: ListBetaCodesOptions): Promise<BetaInviteCode[]>;
+    getCode(code: string): Promise<BetaInviteCode | null>;
+    revokeCode(code: string): Promise<void>;
+    validateCode(code: string): Promise<BetaValidationResult>;
+    consumeCode(code: string, userId: string): Promise<BetaConsumeResult>;
+    isBetaTester(userId: string): Promise<boolean>;
+    getBetaTester(userId: string): Promise<BetaTester | null>;
+    listBetaTesters(options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<BetaTester[]>;
+    getStats(): Promise<BetaStats>;
+    getCodeUsageReports(): Promise<BetaCodeUsageReport[]>;
+    healthCheck(): Promise<boolean>;
+    /** Clear all data (for testing) */
+    clear(): void;
+    /** Get the number of stored codes */
+    get codeCount(): number;
+    /** Get the number of beta testers */
+    get testerCount(): number;
+}
+
 /**
  * Security Utilities
  *
@@ -1279,6 +1543,100 @@ declare function createAuditLogger(options?: OpsAuditLoggerOptions): {
     };
 };
 
+/**
+ * Beta Client Utilities
+ *
+ * Shared client-side helpers for beta access management.
+ * These run in the browser and talk to your app's beta API endpoints.
+ *
+ * Standardizes the pattern used across DLL, WIAN, and future apps:
+ * - Fetch beta settings from API
+ * - Validate invite codes
+ * - Store/retrieve beta code across OAuth redirect flows (sessionStorage)
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   fetchBetaSettings,
+ *   validateBetaCode,
+ *   storeBetaCode,
+ *   getStoredBetaCode,
+ *   clearStoredBetaCode,
+ * } from '@digilogiclabs/platform-core/auth';
+ *
+ * // On sign-in page mount
+ * const settings = await fetchBetaSettings();
+ * if (settings.requireInviteCode) {
+ *   const result = await validateBetaCode(userInput);
+ *   if (result.valid) {
+ *     storeBetaCode(userInput); // Survives OAuth redirect
+ *     // Proceed with sign-in
+ *   }
+ * }
+ * ```
+ */
+
+interface BetaClientConfig {
+    /** Base URL for API calls (default: '' for same-origin) */
+    baseUrl?: string;
+    /** API endpoint for settings (default: '/api/beta-settings') */
+    settingsEndpoint?: string;
+    /** API endpoint for validation (default: '/api/validate-beta-code') */
+    validateEndpoint?: string;
+    /** sessionStorage key for storing beta code (default: 'beta_code') */
+    storageKey?: string;
+    /** Default settings to use when fetch fails */
+    failSafeDefaults?: Partial<BetaSettings>;
+}
+/**
+ * Create a configured beta client with app-specific settings.
+ *
+ * @example
+ * ```typescript
+ * // DLL app
+ * const betaClient = createBetaClient({
+ *   storageKey: 'dll_beta_code',
+ *   validateEndpoint: '/api/validate-beta-code',
+ * });
+ *
+ * // WIAN app
+ * const betaClient = createBetaClient({
+ *   storageKey: 'wian_beta_code',
+ *   validateEndpoint: '/api/validate-invite-code',
+ * });
+ * ```
+ */
+declare function createBetaClient(config?: BetaClientConfig): {
+    fetchSettings: () => Promise<BetaSettings>;
+    validateCode: (code: string) => Promise<BetaValidationResult>;
+    storeCode: (code: string) => void;
+    getStoredCode: () => string | null;
+    clearStoredCode: () => void;
+};
+/**
+ * Fetch beta settings from the server.
+ * Returns fail-safe defaults if the fetch fails.
+ */
+declare function fetchBetaSettings(config?: BetaClientConfig): Promise<BetaSettings>;
+/**
+ * Validate a beta invite code against the server.
+ * Handles rate limiting (429) gracefully.
+ */
+declare function validateBetaCode(code: string, config?: BetaClientConfig): Promise<BetaValidationResult>;
+/**
+ * Store a validated beta code in sessionStorage.
+ * Used to pass the code through OAuth redirect flows.
+ */
+declare function storeBetaCode(code: string, config?: BetaClientConfig): void;
+/**
+ * Retrieve stored beta code from sessionStorage.
+ */
+declare function getStoredBetaCode(config?: BetaClientConfig): string | null;
+/**
+ * Clear stored beta code from sessionStorage.
+ */
+declare function clearStoredBetaCode(config?: BetaClientConfig): void;
+
 /**
  * Environment Variable Helpers
  *
@@ -1364,4 +1722,4 @@ declare function checkEnvVars(config: EnvValidationConfig): EnvValidationResult;
  */
 declare function getEnvSummary(keys: string[]): Record<string, boolean>;
 
-export { type SecuritySession as $, ApiError as A, parseKeycloakRoles as B, CommonApiErrors as C, hasRole as D, type EnvValidationConfig as E, hasAnyRole as F, hasAllRoles as G, isTokenExpired as H, buildTokenRefreshParams as I, getTokenEndpoint as J, type KeycloakConfig as K, getEndSessionEndpoint as L, refreshKeycloakToken as M, type KeycloakCallbacksConfig as N, type KeycloakJwtFields as O, type AuthCookiesConfig as P, buildAuthCookies as Q, type RateLimitStore as R, type RedirectCallbackConfig as S, type TokenRefreshResult as T, buildRedirectCallback as U, buildKeycloakCallbacks as V, type AuthMethod as W, type RouteAuditConfig as X, type RateLimitPreset as Y, StandardRateLimitPresets as Z, type ApiSecurityConfig as _, type RateLimitRule as a, type ApiSecurityContext as a0, resolveRateLimitIdentifier as a1, extractClientIp as a2, buildRateLimitHeaders as a3, buildErrorBody as a4, WrapperPresets as a5, EmailSchema as a6, PasswordSchema as a7, SlugSchema as a8, PhoneSchema as a9, checkRateLimit as aA, getRateLimitStatus as aB, resetRateLimitForKey as aC, buildRateLimitResponseHeaders as aD, resolveIdentifier as aE, type OpsAuditActor as aF, type OpsAuditResource as aG, type OpsAuditEvent as aH, type OpsAuditRecord as aI, type OpsAuditLoggerOptions as aJ, type AuditRequest as aK, StandardAuditActions as aL, type StandardAuditActionType as aM, extractAuditIp as aN, extractAuditUserAgent as aO, extractAuditRequestId as aP, createAuditActor as aQ, createAuditLogger as aR, defangUrl as aS, sanitizeForEmail as aT, URL_PROTOCOL_PATTERN as aU, URL_DOMAIN_PATTERN as aV, HTML_TAG_PATTERN as aW, PG_ERROR_MAP as aX, PersonNameSchema as aa, createSafeTextSchema as ab, PaginationSchema as ac, DateRangeSchema as ad, SearchQuerySchema as ae, LoginSchema as af, SignupSchema as ag, type EmailInput as ah, type PaginationInput as ai, type DateRangeInput as aj, type SearchQueryInput as ak, type LoginInput as al, type SignupInput as am, type DeploymentStage as an, type FlagValue as ao, type FlagDefinition as ap, type FlagDefinitions as aq, type ResolvedFlags as ar, type AllowlistConfig as as, detectStage as at, createFeatureFlags as au, buildAllowlist as av, isAllowlisted as aw, type RateLimitCheckResult as ax, CommonRateLimits as ay, createMemoryRateLimitStore as az, type RateLimitOptions as b, constantTimeEqual as c, containsUrls as d, escapeHtml as e, containsHtml as f, sanitizeApiError as g, getCorrelationId as h, classifyError as i, isApiError as j, ApiErrorCode as k, buildPagination as l, type ApiErrorCodeType as m, type ApiSuccessResponse as n, type ApiPaginatedResponse as o, getRequiredEnv as p, getOptionalEnv as q, getBoolEnv as r, stripHtml as s, getIntEnv as t, checkEnvVars as u, validateEnvVars as v, getEnvSummary as w, type EnvValidationResult as x, type KeycloakTokenSet as y, KEYCLOAK_DEFAULT_ROLES as z };
+export { type SecuritySession as $, ApiError as A, parseKeycloakRoles as B, CommonApiErrors as C, hasRole as D, type EnvValidationConfig as E, hasAnyRole as F, hasAllRoles as G, isTokenExpired as H, buildTokenRefreshParams as I, getTokenEndpoint as J, type KeycloakConfig as K, getEndSessionEndpoint as L, refreshKeycloakToken as M, type KeycloakCallbacksConfig as N, type KeycloakJwtFields as O, type AuthCookiesConfig as P, buildAuthCookies as Q, type RateLimitStore as R, type RedirectCallbackConfig as S, type TokenRefreshResult as T, buildRedirectCallback as U, buildKeycloakCallbacks as V, type AuthMethod as W, type RouteAuditConfig as X, type RateLimitPreset as Y, StandardRateLimitPresets as Z, type ApiSecurityConfig as _, type RateLimitRule as a, type BetaSettings as a$, type ApiSecurityContext as a0, resolveRateLimitIdentifier as a1, extractClientIp as a2, buildRateLimitHeaders as a3, buildErrorBody as a4, WrapperPresets as a5, EmailSchema as a6, PasswordSchema as a7, SlugSchema as a8, PhoneSchema as a9, checkRateLimit as aA, getRateLimitStatus as aB, resetRateLimitForKey as aC, buildRateLimitResponseHeaders as aD, resolveIdentifier as aE, type OpsAuditActor as aF, type OpsAuditResource as aG, type OpsAuditEvent as aH, type OpsAuditRecord as aI, type OpsAuditLoggerOptions as aJ, type AuditRequest as aK, StandardAuditActions as aL, type StandardAuditActionType as aM, extractAuditIp as aN, extractAuditUserAgent as aO, extractAuditRequestId as aP, createAuditActor as aQ, createAuditLogger as aR, type BetaClientConfig as aS, createBetaClient as aT, fetchBetaSettings as aU, validateBetaCode as aV, storeBetaCode as aW, getStoredBetaCode as aX, clearStoredBetaCode as aY, type IBeta as aZ, type BetaConfig as a_, PersonNameSchema as aa, createSafeTextSchema as ab, PaginationSchema as ac, DateRangeSchema as ad, SearchQuerySchema as ae, LoginSchema as af, SignupSchema as ag, type EmailInput as ah, type PaginationInput as ai, type DateRangeInput as aj, type SearchQueryInput as ak, type LoginInput as al, type SignupInput as am, type DeploymentStage as an, type FlagValue as ao, type FlagDefinition as ap, type FlagDefinitions as aq, type ResolvedFlags as ar, type AllowlistConfig as as, detectStage as at, createFeatureFlags as au, buildAllowlist as av, isAllowlisted as aw, type RateLimitCheckResult as ax, CommonRateLimits as ay, createMemoryRateLimitStore as az, type RateLimitOptions as b, type UpdateBetaSettingsOptions as b0, type CreateBetaCodesOptions as b1, type BetaInviteCode as b2, type ListBetaCodesOptions as b3, type BetaValidationResult as b4, type BetaConsumeResult as b5, type BetaTester as b6, type BetaStats as b7, type BetaCodeUsageReport as b8, MemoryBeta as b9, generateBetaCode as ba, normalizeBetaCode as bb, generateBetaId as bc, type BetaCodeStatus as bd, defangUrl as be, sanitizeForEmail as bf, URL_PROTOCOL_PATTERN as bg, URL_DOMAIN_PATTERN as bh, HTML_TAG_PATTERN as bi, PG_ERROR_MAP as bj, constantTimeEqual as c, containsUrls as d, escapeHtml as e, containsHtml as f, sanitizeApiError as g, getCorrelationId as h, classifyError as i, isApiError as j, ApiErrorCode as k, buildPagination as l, type ApiErrorCodeType as m, type ApiSuccessResponse as n, type ApiPaginatedResponse as o, getRequiredEnv as p, getOptionalEnv as q, getBoolEnv as r, stripHtml as s, getIntEnv as t, checkEnvVars as u, validateEnvVars as v, getEnvSummary as w, type EnvValidationResult as x, type KeycloakTokenSet as y, KEYCLOAK_DEFAULT_ROLES as z };