@ductape/sdk 0.0.4 → 0.0.6

package/dist/sessions/sessions.resolver.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Sessions Resolver
+ *
+ * Utility for detecting and resolving $Session{key}{...path} patterns at runtime.
+ * This module handles:
+ * - Pattern detection in strings and objects
+ * - Session token verification and data extraction
+ * - Nested key path resolution (e.g., $Session{user}{address}{city})
+ * - Recursive resolution of nested objects
+ * - Internal caching of verified session tokens to avoid repeated JWT verification
+ */
+/**
+ * Redis client interface (compatible with ioredis)
+ */
+interface IRedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, exMode?: string, exValue?: number): Promise<string | null>;
+    setex(key: string, seconds: number, value: string): Promise<string | null>;
+}
+/**
+ * Set the Redis client for 2-tier session caching
+ * When set, oldest local cache entries will be moved to Redis when local cache fills up
+ */
+export declare function setSessionCacheRedisClient(client: IRedisClient | null): void;
+/**
+ * Clear all cached sessions (local and Redis)
+ */
+export declare function clearSessionCache(): void;
+/**
+ * Get session cache statistics (for debugging/monitoring)
+ */
+export declare function getSessionCacheStats(): {
+    localSize: number;
+    maxLocalSize: number;
+    hasRedis: boolean;
+};
+/**
+ * Regex pattern to detect $Session{key} or $Session{key}{nested}{path} syntax (full string match)
+ * Matches: $Session{user}, $Session{user}{id}, $Session{user}{address}{city}
+ * Also supports array indices: $Session{users}{0}{name}, $Session{data}{items}{2}{value}
+ */
+export declare const SESSION_PATTERN: RegExp;
+/**
+ * Regex pattern to find all $Session{key}{...} occurrences in a string
+ * Supports both object keys and array indices
+ */
+export declare const SESSION_PATTERN_GLOBAL: RegExp;
+/**
+ * Result of parsing a session token
+ */
+export interface ISessionTokenParts {
+    /** The session tag extracted from the token */
+    tag: string;
+    /** The JWT portion of the token */
+    jwt: string;
+}
+/**
+ * Result of verifying and decoding a session token
+ */
+export interface ISessionData {
+    /** The session tag */
+    tag: string;
+    /** The session ID */
+    sessionId: string;
+    /** The user identifier from session creation */
+    identifier?: string;
+    /** The session data payload */
+    data: Record<string, unknown>;
+    /** Session expiration timestamp */
+    expiresAt?: number;
+    /** Environment slug */
+    env?: string;
+}
+/**
+ * Result of checking if a value is a session reference
+ */
+export interface ISessionCheck {
+    /** Whether the value is a session reference */
+    isSession: boolean;
+    /** The key path segments if it's a session reference */
+    keyPath?: string[];
+}
+/**
+ * Options for resolving sessions at runtime
+ */
+export interface IResolveSessionOptions {
+    /** Current environment slug */
+    env?: string;
+}
+/**
+ * Result of session resolution
+ */
+export interface ISessionResolutionResult<T = unknown> {
+    /** The resolved value with session references replaced */
+    value: T;
+    /** Keys that were resolved */
+    resolvedKeys: string[];
+    /** Keys that failed to resolve */
+    failedKeys: string[];
+}
+/**
+ * Session context containing identifier and session metadata
+ */
+export interface ISessionContext {
+    /** User identifier from session */
+    identifier: string;
+    /** Session ID */
+    session_id: string;
+    /** Session tag */
+    session_tag: string;
+    /** Session data payload */
+    data: Record<string, unknown>;
+}
+/**
+ * Parse a session token in format "session_tag:jwt_token"
+ */
+export declare function parseSessionToken(token: string): ISessionTokenParts | null;
+/**
+ * Check if a string value is a session reference
+ */
+export declare function isSessionReference(value: string): ISessionCheck;
+/**
+ * Check if a string contains any session references (partial matches)
+ */
+export declare function containsSessionReferences(value: string): boolean;
+/**
+ * Extract all session references from a string
+ */
+export declare function extractSessionReferences(value: string): Array<{
+    full: string;
+    keyPath: string[];
+}>;
+/**
+ * Get a nested value from an object using a key path
+ * Supports both object keys and array indices (numeric keys)
+ *
+ * @example
+ * getNestedValue({ users: [{ name: 'John' }] }, ['users', '0', 'name']) // returns 'John'
+ * getNestedValue({ data: { items: ['a', 'b', 'c'] } }, ['data', 'items', '1']) // returns 'b'
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, keyPath: string[]): unknown;
+/**
+ * Verify and decode a session JWT token
+ * Returns the session data if valid, null otherwise
+ *
+ * Uses 2-tier caching (local memory + Redis) to avoid repeated JWT verification.
+ * Cache entries expire 30 seconds before the actual session expiration.
+ * When local cache fills up (100 entries), oldest 50 are moved to Redis.
+ */
+export declare function verifySessionToken(token: string, privateKey: string, expectedTag?: string, expectedEnv?: string): Promise<ISessionData | null>;
+/**
+ * Extract session context from a verified session
+ * This includes identifier, session_id, session_tag for logging
+ */
+export declare function extractSessionContext(sessionData: ISessionData, selector?: string): ISessionContext;
+/**
+ * Type guard to check if a value might contain session references
+ */
+export declare function mightContainSessions(value: unknown): boolean;
+/**
+ * Recursively find all session references in an object
+ */
+export declare function findAllSessionReferences(obj: unknown): Array<{
+    full: string;
+    keyPath: string[];
+}>;
+/**
+ * Replace a single session reference with its resolved value
+ */
+export declare function replaceSessionInString(value: string, reference: string, resolvedValue: unknown): string;
+/**
+ * Create a sessions resolver instance
+ */
+export declare function createSessionsResolver(sessionData: ISessionData): {
+    resolveReference: (keyPath: string[]) => unknown;
+    resolveString: (value: string) => ISessionResolutionResult<string>;
+    resolveObject: <T>(obj: T) => ISessionResolutionResult<T>;
+    getSessionData: () => ISessionData;
+};
+/**
+ * Error class for session resolution
+ */
+export declare class SessionResolutionError extends Error {
+    code: string;
+    details?: unknown;
+    constructor(message: string, code: string, details?: unknown);
+}
+export {};