@digilogiclabs/platform-core 1.7.0 → 1.9.0

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

@@ -1,91 +1,268 @@
 import { z } from 'zod';
 
 /**
- * Security Utilities
+ * Beta Access Management Interface
  *
- * HTML escaping, input detection, sanitization helpers,
- * timing-safe comparison, error sanitization, and request
- * correlation for safe, consistent security across all apps.
- */
-/** Regex for protocol-prefixed URLs */
-declare const URL_PROTOCOL_PATTERN: RegExp;
-/** Regex for bare domain names with common TLDs */
-declare const URL_DOMAIN_PATTERN: RegExp;
-/** Regex for HTML tags */
-declare const HTML_TAG_PATTERN: RegExp;
-/**
- * Escape HTML special characters to prevent injection.
- * Use when inserting user content into HTML email templates or rendered HTML.
- */
-declare function escapeHtml(str: string): string;
-/** Check if a string contains protocol-prefixed URLs or bare domains */
-declare function containsUrls(str: string): boolean;
-/** Check if a string contains HTML tags */
-declare function containsHtml(str: string): boolean;
-/** Strip all HTML tags from a string */
-declare function stripHtml(str: string): string;
-/**
- * Defang URLs to prevent auto-linking in email clients.
- * Converts https://evil.com → hxxps://evil[.]com
- */
-declare function defangUrl(str: string): string;
-/**
- * Sanitize user content for safe insertion into HTML email templates.
- * Escapes HTML entities AND defangs any URLs that slipped through validation.
- */
-declare function sanitizeForEmail(str: string): string;
-/**
- * Constant-time string comparison to prevent timing side-channel attacks.
- * Use for comparing secrets, tokens, API keys, HMAC signatures, etc.
+ * Provides a vendor-agnostic way to manage beta/early-access programs.
+ * Handles invite codes, access gating, settings, and analytics across
+ * all DLL Platform applications.
  *
- * Returns false (not throws) for length mismatches — still constant-time
- * relative to the shorter string to avoid leaking length info.
+ * 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
- * if (!constantTimeEqual(providedToken, expectedSecret)) {
- *   return { status: 401, error: 'Invalid token' }
- * }
- * ```
- */
-declare function constantTimeEqual(a: string, b: string): boolean;
-/**
- * Sanitize an error for client-facing API responses.
+ * import { MemoryBeta } from '@digilogiclabs/platform-core';
  *
- * - 4xx errors: returns the actual message (client needs to know what went wrong)
- * - 5xx errors: returns a generic message (never leak internals to clients)
- * - Development mode: optionally includes stack trace for debugging
+ * const beta = new MemoryBeta();
  *
- * @example
- * ```typescript
- * catch (error) {
- *   const { message, code } = sanitizeApiError(error, 500)
- *   return Response.json({ error: message, code }, { status: 500 })
+ * // 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');
+ *   }
  * }
- * ```
- */
-declare function sanitizeApiError(error: unknown, statusCode: number, isDevelopment?: boolean): {
-    message: string;
-    code?: string;
-    stack?: string;
-};
-/**
- * Extract a correlation/request ID from standard headers, or generate one.
  *
- * Checks (in order): X-Request-ID, X-Correlation-ID, then falls back to
- * crypto.randomUUID(). Works with any headers-like object (plain object,
- * Headers API, or a getter function).
+ * // Create invite codes
+ * const codes = await beta.createCodes({
+ *   count: 10,
+ *   prefix: 'DLL',
+ *   maxUses: 5,
+ *   createdBy: 'admin',
+ * });
  *
- * @example
- * ```typescript
- * // With Next.js request
- * const id = getCorrelationId((name) => request.headers.get(name))
- *
- * // With plain object
- * const id = getCorrelationId({ 'x-request-id': 'abc-123' })
+ * // Transition to public launch
+ * await beta.updateSettings({ betaMode: false, requireInviteCode: false });
  * ```
  */
-declare function getCorrelationId(headers: Record<string, string | string[] | undefined> | ((name: string) => string | null | undefined)): string;
+/** 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;
+}
 
 /**
  * API Utilities
@@ -1279,6 +1456,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 +1635,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 { EmailSchema as $, ApiError as A, getEndSessionEndpoint as B, CommonApiErrors as C, refreshKeycloakToken as D, type EnvValidationConfig as E, type KeycloakCallbacksConfig as F, type KeycloakJwtFields as G, type AuthCookiesConfig as H, buildAuthCookies as I, type RedirectCallbackConfig as J, type KeycloakConfig as K, buildRedirectCallback as L, buildKeycloakCallbacks as M, type AuthMethod as N, type RouteAuditConfig as O, type RateLimitPreset as P, type ApiSecurityConfig as Q, type RateLimitStore as R, StandardRateLimitPresets as S, type TokenRefreshResult as T, type SecuritySession as U, type ApiSecurityContext as V, resolveRateLimitIdentifier as W, extractClientIp as X, buildRateLimitHeaders as Y, buildErrorBody as Z, WrapperPresets as _, type RateLimitRule as a, type BetaTester as a$, PasswordSchema as a0, SlugSchema as a1, PhoneSchema as a2, PersonNameSchema as a3, createSafeTextSchema as a4, PaginationSchema as a5, DateRangeSchema as a6, SearchQuerySchema as a7, LoginSchema as a8, SignupSchema as a9, type OpsAuditEvent as aA, type OpsAuditRecord as aB, type OpsAuditLoggerOptions as aC, type AuditRequest as aD, StandardAuditActions as aE, type StandardAuditActionType as aF, extractAuditIp as aG, extractAuditUserAgent as aH, extractAuditRequestId as aI, createAuditActor as aJ, createAuditLogger as aK, type BetaClientConfig as aL, createBetaClient as aM, fetchBetaSettings as aN, validateBetaCode as aO, storeBetaCode as aP, getStoredBetaCode as aQ, clearStoredBetaCode as aR, type IBeta as aS, type BetaConfig as aT, type BetaSettings as aU, type UpdateBetaSettingsOptions as aV, type CreateBetaCodesOptions as aW, type BetaInviteCode as aX, type ListBetaCodesOptions as aY, type BetaValidationResult as aZ, type BetaConsumeResult as a_, type EmailInput as aa, type PaginationInput as ab, type DateRangeInput as ac, type SearchQueryInput as ad, type LoginInput as ae, type SignupInput as af, type DeploymentStage as ag, type FlagValue as ah, type FlagDefinition as ai, type FlagDefinitions as aj, type ResolvedFlags as ak, type AllowlistConfig as al, detectStage as am, createFeatureFlags as an, buildAllowlist as ao, isAllowlisted as ap, type RateLimitCheckResult as aq, CommonRateLimits as ar, createMemoryRateLimitStore as as, checkRateLimit as at, getRateLimitStatus as au, resetRateLimitForKey as av, buildRateLimitResponseHeaders as aw, resolveIdentifier as ax, type OpsAuditActor as ay, type OpsAuditResource as az, type RateLimitOptions as b, type BetaStats as b0, type BetaCodeUsageReport as b1, MemoryBeta as b2, generateBetaCode as b3, normalizeBetaCode as b4, generateBetaId as b5, type BetaCodeStatus as b6, PG_ERROR_MAP as b7, classifyError as c, ApiErrorCode as d, buildPagination as e, type ApiErrorCodeType as f, type ApiSuccessResponse as g, type ApiPaginatedResponse as h, isApiError as i, getRequiredEnv as j, getOptionalEnv as k, getBoolEnv as l, getIntEnv as m, checkEnvVars as n, getEnvSummary as o, type EnvValidationResult as p, type KeycloakTokenSet as q, KEYCLOAK_DEFAULT_ROLES as r, parseKeycloakRoles as s, hasRole as t, hasAnyRole as u, validateEnvVars as v, hasAllRoles as w, isTokenExpired as x, buildTokenRefreshParams as y, getTokenEndpoint as z };