@ductape/sdk 0.0.4-v51 → 0.0.4-v52

package/dist/secrets/secrets.types.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Secrets Types
+ *
+ * Type definitions for the workspace secrets system that allows
+ * users to reference secrets using $Secret{key} syntax.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretResolutionError = exports.SecretRevokedError = exports.SecretExpiredError = exports.SecretEnvironmentError = exports.SecretScopeError = exports.SecretNotFoundError = exports.SECRET_PATTERN_GLOBAL = exports.SECRET_PATTERN = void 0;
+/**
+ * Regex pattern to detect $Secret{key} syntax (full string match)
+ * Matches: $Secret{my-key}, $Secret{api_key}, $Secret{DB_PASSWORD}
+ */
+exports.SECRET_PATTERN = /^\$Secret\{([a-zA-Z0-9._-]+)\}$/;
+/**
+ * Regex pattern to find all $Secret{key} occurrences in a string
+ */
+exports.SECRET_PATTERN_GLOBAL = /\$Secret\{([a-zA-Z0-9._-]+)\}/g;
+/**
+ * Error thrown when a secret is not found
+ */
+class SecretNotFoundError extends Error {
+    constructor(key) {
+        super(`Secret '${key}' not found`);
+        this.key = key;
+        this.name = 'SecretNotFoundError';
+    }
+}
+exports.SecretNotFoundError = SecretNotFoundError;
+/**
+ * Error thrown when secret scope doesn't match
+ */
+class SecretScopeError extends Error {
+    constructor(key, app) {
+        super(`Secret '${key}' is not accessible by app '${app}'`);
+        this.key = key;
+        this.app = app;
+        this.name = 'SecretScopeError';
+    }
+}
+exports.SecretScopeError = SecretScopeError;
+/**
+ * Error thrown when secret environment doesn't match
+ */
+class SecretEnvironmentError extends Error {
+    constructor(key, env) {
+        super(`Secret '${key}' is not available in environment '${env}'`);
+        this.key = key;
+        this.env = env;
+        this.name = 'SecretEnvironmentError';
+    }
+}
+exports.SecretEnvironmentError = SecretEnvironmentError;
+/**
+ * Error thrown when secret has expired
+ */
+class SecretExpiredError extends Error {
+    constructor(key) {
+        super(`Secret '${key}' has expired`);
+        this.key = key;
+        this.name = 'SecretExpiredError';
+    }
+}
+exports.SecretExpiredError = SecretExpiredError;
+/**
+ * Error thrown when secret has been revoked
+ */
+class SecretRevokedError extends Error {
+    constructor(key) {
+        super(`Secret '${key}' has been revoked`);
+        this.key = key;
+        this.name = 'SecretRevokedError';
+    }
+}
+exports.SecretRevokedError = SecretRevokedError;
+/**
+ * Error thrown when secret resolution fails
+ */
+class SecretResolutionError extends Error {
+    constructor(message, failedKeys) {
+        super(message);
+        this.failedKeys = failedKeys;
+        this.name = 'SecretResolutionError';
+    }
+}
+exports.SecretResolutionError = SecretResolutionError;
+//# sourceMappingURL=secrets.types.js.map

package/dist/secrets/secrets.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.types.js","sourceRoot":"","sources":["../../src/secrets/secrets.types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH;;;GAGG;AACU,QAAA,cAAc,GAAG,iCAAiC,CAAC;AAEhE;;GAEG;AACU,QAAA,qBAAqB,GAAG,gCAAgC,CAAC;AA6ItE;;GAEG;AACH,MAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAA4B,GAAW;QACrC,KAAK,CAAC,WAAW,GAAG,aAAa,CAAC,CAAC;QADT,QAAG,GAAH,GAAG,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AALD,kDAKC;AAED;;GAEG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YACkB,GAAW,EACX,GAAW;QAE3B,KAAK,CAAC,WAAW,GAAG,+BAA+B,GAAG,GAAG,CAAC,CAAC;QAH3C,QAAG,GAAH,GAAG,CAAQ;QACX,QAAG,GAAH,GAAG,CAAQ;QAG3B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AARD,4CAQC;AAED;;GAEG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YACkB,GAAW,EACX,GAAW;QAE3B,KAAK,CAAC,WAAW,GAAG,sCAAsC,GAAG,GAAG,CAAC,CAAC;QAHlD,QAAG,GAAH,GAAG,CAAQ;QACX,QAAG,GAAH,GAAG,CAAQ;QAG3B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AARD,wDAQC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAA4B,GAAW;QACrC,KAAK,CAAC,WAAW,GAAG,eAAe,CAAC,CAAC;QADX,QAAG,GAAH,GAAG,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAA4B,GAAW;QACrC,KAAK,CAAC,WAAW,GAAG,oBAAoB,CAAC,CAAC;QADhB,QAAG,GAAH,GAAG,CAAQ;QAErC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED;;GAEG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,YACE,OAAe,EACC,UAAoB;QAEpC,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,eAAU,GAAV,UAAU,CAAU;QAGpC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AARD,sDAQC"}

package/dist/sessions/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ductape Sessions Module
+ *
+ * Provides a unified API for JWT-based session management including
+ * creating, refreshing, verifying, and revoking sessions.
+ *
+ * @example
+ * ```ts
+ * import { SessionsService } from '@ductape/sdk';
+ *
+ * const sessions = new SessionsService({
+ *   workspace_id: 'your-workspace-id',
+ *   public_key: 'your-public-key',
+ *   user_id: 'your-user-id',
+ *   token: 'your-token',
+ *   env_type: 'prd',
+ * });
+ *
+ * // Create a session
+ * const result = await sessions.create({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   data: { userId: '123', email: 'user@example.com' },
+ * });
+ *
+ * // Verify a session
+ * const verifyResult = await sessions.verify({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   token: result.token,
+ * });
+ *
+ * // Refresh a session
+ * const refreshResult = await sessions.refresh({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   refreshToken: result.refreshToken,
+ * });
+ * ```
+ */
+export { SessionsService, SessionError } from './sessions.service';
+export { default as SessionsServiceDefault } from './sessions.service';
+export { SESSION_PATTERN, SESSION_PATTERN_GLOBAL, parseSessionToken, isSessionReference, containsSessionReferences, extractSessionReferences, getNestedValue, verifySessionToken, extractSessionContext, mightContainSessions, findAllSessionReferences, createSessionsResolver, SessionResolutionError, } from './sessions.resolver';
+export type { ISessionTokenParts, ISessionData, ISessionCheck, IResolveSessionOptions, ISessionResolutionResult, ISessionContext, } from './sessions.resolver';
+export { verifyAndExtractSession, getSessionLogFields, resolveSessionReferences, processSessionForExecution, } from './sessions.helper';
+export type { ISessionVerificationResult, ISessionLogFields, } from './sessions.helper';
+export * from './types';

package/dist/sessions/index.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Ductape Sessions Module
+ *
+ * Provides a unified API for JWT-based session management including
+ * creating, refreshing, verifying, and revoking sessions.
+ *
+ * @example
+ * ```ts
+ * import { SessionsService } from '@ductape/sdk';
+ *
+ * const sessions = new SessionsService({
+ *   workspace_id: 'your-workspace-id',
+ *   public_key: 'your-public-key',
+ *   user_id: 'your-user-id',
+ *   token: 'your-token',
+ *   env_type: 'prd',
+ * });
+ *
+ * // Create a session
+ * const result = await sessions.create({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   data: { userId: '123', email: 'user@example.com' },
+ * });
+ *
+ * // Verify a session
+ * const verifyResult = await sessions.verify({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   token: result.token,
+ * });
+ *
+ * // Refresh a session
+ * const refreshResult = await sessions.refresh({
+ *   product: 'my-product',
+ *   env: 'production',
+ *   tag: 'user-session',
+ *   refreshToken: result.refreshToken,
+ * });
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processSessionForExecution = exports.resolveSessionReferences = exports.getSessionLogFields = exports.verifyAndExtractSession = exports.SessionResolutionError = exports.createSessionsResolver = exports.findAllSessionReferences = exports.mightContainSessions = exports.extractSessionContext = exports.verifySessionToken = exports.getNestedValue = exports.extractSessionReferences = exports.containsSessionReferences = exports.isSessionReference = exports.parseSessionToken = exports.SESSION_PATTERN_GLOBAL = exports.SESSION_PATTERN = exports.SessionsServiceDefault = exports.SessionError = exports.SessionsService = void 0;
+// Main service
+var sessions_service_1 = require("./sessions.service");
+Object.defineProperty(exports, "SessionsService", { enumerable: true, get: function () { return sessions_service_1.SessionsService; } });
+Object.defineProperty(exports, "SessionError", { enumerable: true, get: function () { return sessions_service_1.SessionError; } });
+var sessions_service_2 = require("./sessions.service");
+Object.defineProperty(exports, "SessionsServiceDefault", { enumerable: true, get: function () { return __importDefault(sessions_service_2).default; } });
+// Session resolver
+var sessions_resolver_1 = require("./sessions.resolver");
+Object.defineProperty(exports, "SESSION_PATTERN", { enumerable: true, get: function () { return sessions_resolver_1.SESSION_PATTERN; } });
+Object.defineProperty(exports, "SESSION_PATTERN_GLOBAL", { enumerable: true, get: function () { return sessions_resolver_1.SESSION_PATTERN_GLOBAL; } });
+Object.defineProperty(exports, "parseSessionToken", { enumerable: true, get: function () { return sessions_resolver_1.parseSessionToken; } });
+Object.defineProperty(exports, "isSessionReference", { enumerable: true, get: function () { return sessions_resolver_1.isSessionReference; } });
+Object.defineProperty(exports, "containsSessionReferences", { enumerable: true, get: function () { return sessions_resolver_1.containsSessionReferences; } });
+Object.defineProperty(exports, "extractSessionReferences", { enumerable: true, get: function () { return sessions_resolver_1.extractSessionReferences; } });
+Object.defineProperty(exports, "getNestedValue", { enumerable: true, get: function () { return sessions_resolver_1.getNestedValue; } });
+Object.defineProperty(exports, "verifySessionToken", { enumerable: true, get: function () { return sessions_resolver_1.verifySessionToken; } });
+Object.defineProperty(exports, "extractSessionContext", { enumerable: true, get: function () { return sessions_resolver_1.extractSessionContext; } });
+Object.defineProperty(exports, "mightContainSessions", { enumerable: true, get: function () { return sessions_resolver_1.mightContainSessions; } });
+Object.defineProperty(exports, "findAllSessionReferences", { enumerable: true, get: function () { return sessions_resolver_1.findAllSessionReferences; } });
+Object.defineProperty(exports, "createSessionsResolver", { enumerable: true, get: function () { return sessions_resolver_1.createSessionsResolver; } });
+Object.defineProperty(exports, "SessionResolutionError", { enumerable: true, get: function () { return sessions_resolver_1.SessionResolutionError; } });
+// Session helper for executors
+var sessions_helper_1 = require("./sessions.helper");
+Object.defineProperty(exports, "verifyAndExtractSession", { enumerable: true, get: function () { return sessions_helper_1.verifyAndExtractSession; } });
+Object.defineProperty(exports, "getSessionLogFields", { enumerable: true, get: function () { return sessions_helper_1.getSessionLogFields; } });
+Object.defineProperty(exports, "resolveSessionReferences", { enumerable: true, get: function () { return sessions_helper_1.resolveSessionReferences; } });
+Object.defineProperty(exports, "processSessionForExecution", { enumerable: true, get: function () { return sessions_helper_1.processSessionForExecution; } });
+// Types
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/sessions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sessions/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;;;;;;;;;;;;;;;;;;;;AAEH,eAAe;AACf,uDAAmE;AAA1D,mHAAA,eAAe,OAAA;AAAE,gHAAA,YAAY,OAAA;AACtC,uDAAuE;AAA9D,2IAAA,OAAO,OAA0B;AAE1C,mBAAmB;AACnB,yDAc6B;AAb3B,oHAAA,eAAe,OAAA;AACf,2HAAA,sBAAsB,OAAA;AACtB,sHAAA,iBAAiB,OAAA;AACjB,uHAAA,kBAAkB,OAAA;AAClB,8HAAA,yBAAyB,OAAA;AACzB,6HAAA,wBAAwB,OAAA;AACxB,mHAAA,cAAc,OAAA;AACd,uHAAA,kBAAkB,OAAA;AAClB,0HAAA,qBAAqB,OAAA;AACrB,yHAAA,oBAAoB,OAAA;AACpB,6HAAA,wBAAwB,OAAA;AACxB,2HAAA,sBAAsB,OAAA;AACtB,2HAAA,sBAAsB,OAAA;AAWxB,+BAA+B;AAC/B,qDAK2B;AAJzB,0HAAA,uBAAuB,OAAA;AACvB,sHAAA,mBAAmB,OAAA;AACnB,2HAAA,wBAAwB,OAAA;AACxB,6HAAA,0BAA0B,OAAA;AAO5B,QAAQ;AACR,0CAAwB"}

package/dist/sessions/sessions.helper.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Sessions Helper
+ *
+ * Utility functions for session verification and context extraction
+ * to be used across all executors (actions, database, graph, vector, etc.)
+ *
+ * Session token format: session_tag:jwt_token
+ * The token contains both the session tag and JWT in a single string.
+ */
+import { ISessionData, ISessionContext } from './sessions.resolver';
+/**
+ * Result of session verification for an executor
+ */
+export interface ISessionVerificationResult {
+    /** Whether session was provided and is valid */
+    valid: boolean;
+    /** Session data if valid */
+    sessionData?: ISessionData;
+    /** Session context for logging (identifier, session_id, session_tag) */
+    context?: ISessionContext;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Log fields extracted from session for ILogData
+ */
+export interface ISessionLogFields {
+    identifier?: string;
+    session_id?: string;
+    session_tag?: string;
+}
+/**
+ * Verify a session token and extract context for logging
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param env - Current environment slug
+ * @param selector - Optional selector path for identifier extraction
+ * @returns Session verification result with context for logging
+ */
+export declare function verifyAndExtractSession(sessionToken: string | undefined, privateKey: string, env?: string, selector?: string): Promise<ISessionVerificationResult>;
+/**
+ * Extract log fields from session context
+ */
+export declare function getSessionLogFields(context: ISessionContext | undefined): ISessionLogFields;
+/**
+ * Resolve $Session{key}{...} references in input data
+ *
+ * @param input - Input data that may contain session references
+ * @param sessionData - Verified session data
+ * @returns Resolved input with session references replaced
+ */
+export declare function resolveSessionReferences<T>(input: T, sessionData: ISessionData | undefined): T;
+/**
+ * Combined helper that verifies session and resolves references in one call
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param input - Input data that may contain $Session{} references
+ * @param env - Current environment slug
+ * @param selector - Optional selector path for identifier extraction
+ */
+export declare function processSessionForExecution<T>(sessionToken: string | undefined, privateKey: string, input: T, env?: string, selector?: string): Promise<{
+    input: T;
+    logFields: ISessionLogFields;
+    sessionData?: ISessionData;
+    error?: string;
+}>;

package/dist/sessions/sessions.helper.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Sessions Helper
+ *
+ * Utility functions for session verification and context extraction
+ * to be used across all executors (actions, database, graph, vector, etc.)
+ *
+ * Session token format: session_tag:jwt_token
+ * The token contains both the session tag and JWT in a single string.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyAndExtractSession = verifyAndExtractSession;
+exports.getSessionLogFields = getSessionLogFields;
+exports.resolveSessionReferences = resolveSessionReferences;
+exports.processSessionForExecution = processSessionForExecution;
+const sessions_resolver_1 = require("./sessions.resolver");
+/**
+ * Verify a session token and extract context for logging
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param env - Current environment slug
+ * @param selector - Optional selector path for identifier extraction
+ * @returns Session verification result with context for logging
+ */
+async function verifyAndExtractSession(sessionToken, privateKey, env, selector) {
+    // No session provided - return valid (session is optional)
+    if (!sessionToken) {
+        return { valid: true };
+    }
+    // Parse the token format (session_tag:jwt)
+    const parts = (0, sessions_resolver_1.parseSessionToken)(sessionToken);
+    if (!parts) {
+        return {
+            valid: false,
+            error: 'Invalid session token format. Expected format: session_tag:jwt_token',
+        };
+    }
+    // Verify the JWT
+    const sessionData = await (0, sessions_resolver_1.verifySessionToken)(sessionToken, privateKey, parts.tag, env);
+    if (!sessionData) {
+        return {
+            valid: false,
+            error: 'Session token verification failed. Token may be invalid or expired.',
+        };
+    }
+    // Extract session context for logging
+    const context = (0, sessions_resolver_1.extractSessionContext)(sessionData, selector);
+    return {
+        valid: true,
+        sessionData,
+        context,
+    };
+}
+/**
+ * Extract log fields from session context
+ */
+function getSessionLogFields(context) {
+    if (!context) {
+        return {};
+    }
+    return {
+        identifier: context.identifier,
+        session_id: context.session_id,
+        session_tag: context.session_tag,
+    };
+}
+/**
+ * Resolve $Session{key}{...} references in input data
+ *
+ * @param input - Input data that may contain session references
+ * @param sessionData - Verified session data
+ * @returns Resolved input with session references replaced
+ */
+function resolveSessionReferences(input, sessionData) {
+    if (!sessionData || !(0, sessions_resolver_1.mightContainSessions)(input)) {
+        return input;
+    }
+    const resolver = (0, sessions_resolver_1.createSessionsResolver)(sessionData);
+    const result = resolver.resolveObject(input);
+    return result.value;
+}
+/**
+ * Combined helper that verifies session and resolves references in one call
+ *
+ * @param sessionToken - Session token string in format: session_tag:jwt_token
+ * @param privateKey - Product private key for JWT verification
+ * @param input - Input data that may contain $Session{} references
+ * @param env - Current environment slug
+ * @param selector - Optional selector path for identifier extraction
+ */
+async function processSessionForExecution(sessionToken, privateKey, input, env, selector) {
+    // No session - return input as-is
+    if (!sessionToken) {
+        return { input, logFields: {} };
+    }
+    // Verify session
+    const verification = await verifyAndExtractSession(sessionToken, privateKey, env, selector);
+    if (!verification.valid) {
+        return {
+            input,
+            logFields: {},
+            error: verification.error,
+        };
+    }
+    // Resolve session references in input
+    const resolvedInput = resolveSessionReferences(input, verification.sessionData);
+    // Get log fields
+    const logFields = getSessionLogFields(verification.context);
+    return {
+        input: resolvedInput,
+        logFields,
+        sessionData: verification.sessionData,
+    };
+}
+//# sourceMappingURL=sessions.helper.js.map

package/dist/sessions/sessions.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.helper.js","sourceRoot":"","sources":["../../src/sessions/sessions.helper.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA4CH,0DAqCC;AAKD,kDAUC;AASD,4DAWC;AAWD,gEAsCC;AAnKD,2DAQ6B;AAyB7B;;;;;;;;GAQG;AACI,KAAK,UAAU,uBAAuB,CAC3C,YAAgC,EAChC,UAAkB,EAClB,GAAY,EACZ,QAAiB;IAEjB,2DAA2D;IAC3D,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,2CAA2C;IAC3C,MAAM,KAAK,GAAG,IAAA,qCAAiB,EAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,sEAAsE;SAC9E,CAAC;IACJ,CAAC;IAED,iBAAiB;IACjB,MAAM,WAAW,GAAG,MAAM,IAAA,sCAAkB,EAAC,YAAY,EAAE,UAAU,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvF,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,qEAAqE;SAC7E,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,MAAM,OAAO,GAAG,IAAA,yCAAqB,EAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAE7D,OAAO;QACL,KAAK,EAAE,IAAI;QACX,WAAW;QACX,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CAAC,OAAoC;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,wBAAwB,CACtC,KAAQ,EACR,WAAqC;IAErC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAA,wCAAoB,EAAC,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,IAAA,0CAAsB,EAAC,WAAW,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,0BAA0B,CAC9C,YAAgC,EAChC,UAAkB,EAClB,KAAQ,EACR,GAAY,EACZ,QAAiB;IAOjB,kCAAkC;IAClC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;IAED,iBAAiB;IACjB,MAAM,YAAY,GAAG,MAAM,uBAAuB,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5F,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QACxB,OAAO;YACL,KAAK;YACL,SAAS,EAAE,EAAE;YACb,KAAK,EAAE,YAAY,CAAC,KAAK;SAC1B,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,MAAM,aAAa,GAAG,wBAAwB,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;IAEhF,iBAAiB;IACjB,MAAM,SAAS,GAAG,mBAAmB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAE5D,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,SAAS;QACT,WAAW,EAAE,YAAY,CAAC,WAAW;KACtC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,150 @@
+/**
+ * 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
+ */
+/**
+ * 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}
+ */
+export declare const SESSION_PATTERN: RegExp;
+/**
+ * Regex pattern to find all $Session{key}{...} occurrences in a string
+ */
+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
+ */
+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
+ */
+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);
+}