@hotmeshio/long-tail 0.1.0

package/build/services/oauth/providers/types.d.ts

@@ -0,0 +1,13 @@
+import type { LTOAuthProviderConfig, LTOAuthUserInfo } from '../../../types/oauth';
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string | null;
+    accessTokenExpiresAt: Date | null;
+}
+export interface ProviderHandler {
+    config: LTOAuthProviderConfig;
+    createAuthorizationURL(state: string, codeVerifier: string): URL;
+    validateAuthorizationCode(code: string, codeVerifier: string): Promise<OAuthTokens>;
+    refreshAccessToken(refreshToken: string): Promise<OAuthTokens>;
+    fetchUserInfo(accessToken: string): Promise<LTOAuthUserInfo>;
+}

package/build/services/oauth/providers/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/services/oauth/state.d.ts

@@ -0,0 +1,30 @@
+interface OAuthState {
+    codeVerifier: string;
+    provider: string;
+    returnTo: string;
+    createdAt: number;
+    /** When true, this flow connects a credential provider for an existing user (not login). */
+    connectOnly?: boolean;
+    /** User ID for connect-only flows. */
+    userId?: string;
+    /** Credential label for connect-only flows (allows multiple per provider). */
+    label?: string;
+}
+/**
+ * Create an OAuth state parameter + PKCE code verifier.
+ * The state is stored in memory and expires after 5 minutes.
+ */
+export declare function createOAuthState(provider: string, returnTo?: string, options?: {
+    connectOnly?: boolean;
+    userId?: string;
+    label?: string;
+}): {
+    state: string;
+    codeVerifier: string;
+};
+/**
+ * Consume an OAuth state parameter (one-time use).
+ * Returns null if state is unknown, expired, or already consumed.
+ */
+export declare function consumeOAuthState(state: string): OAuthState | null;
+export {};

package/build/services/oauth/state.js

@@ -0,0 +1,83 @@
+"use strict";
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOAuthState = createOAuthState;
+exports.consumeOAuthState = consumeOAuthState;
+const crypto = __importStar(require("crypto"));
+const stateStore = new Map();
+const STATE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/**
+ * Create an OAuth state parameter + PKCE code verifier.
+ * The state is stored in memory and expires after 5 minutes.
+ */
+function createOAuthState(provider, returnTo = '/', options) {
+    const state = crypto.randomBytes(32).toString('hex');
+    const codeVerifier = crypto.randomBytes(32).toString('base64url');
+    stateStore.set(state, {
+        codeVerifier,
+        provider,
+        returnTo,
+        createdAt: Date.now(),
+        connectOnly: options?.connectOnly,
+        userId: options?.userId,
+        label: options?.label,
+    });
+    return { state, codeVerifier };
+}
+/**
+ * Consume an OAuth state parameter (one-time use).
+ * Returns null if state is unknown, expired, or already consumed.
+ */
+function consumeOAuthState(state) {
+    const entry = stateStore.get(state);
+    if (!entry)
+        return null;
+    stateStore.delete(state);
+    if (Date.now() - entry.createdAt > STATE_TTL_MS)
+        return null;
+    return entry;
+}
+// Periodic cleanup of expired entries (every 60s)
+const cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of stateStore) {
+        if (now - entry.createdAt > STATE_TTL_MS) {
+            stateStore.delete(key);
+        }
+    }
+}, 60_000);
+// Allow Node to exit without waiting for the interval
+if (cleanupInterval.unref)
+    cleanupInterval.unref();

package/build/services/orchestrator/index.d.ts

@@ -0,0 +1,23 @@
+import type { ExecuteLTOptions } from './types';
+/**
+ * Execute a Long Tail workflow with automatic task tracking.
+ *
+ * Uses `startChild` to spawn the child workflow (fire-and-forget),
+ * then `waitFor` to receive the result signal from the child's
+ * interceptor. The child can escalate, fail, and be re-run multiple
+ * times without affecting the parent — the orchestrator simply waits
+ * for the signal.
+ *
+ * Usage (from within an orchestrator workflow):
+ * ```typescript
+ * export async function myPipeline(envelope: LTEnvelope) {
+ *   return await executeLT({
+ *     workflowName: 'reviewContent',
+ *     args: [envelope],
+ *     taskQueue: 'long-tail-examples',
+ *     originId: envelope.data.orderId,
+ *   });
+ * }
+ * ```
+ */
+export declare function executeLT<T = any>(options: ExecuteLTOptions): Promise<T>;

package/build/services/orchestrator/index.js

@@ -0,0 +1,156 @@
+"use strict";
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeLT = executeLT;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const interceptorActivities = __importStar(require("../interceptor/activities"));
+const context_1 = require("../interceptor/context");
+const defaults_1 = require("../../modules/defaults");
+/**
+ * Default activity queue for LT interceptor operations.
+ * Must match the queue used when registering the activity worker.
+ */
+const LT_ACTIVITY_QUEUE = 'lt-interceptor';
+/**
+ * Execute a Long Tail workflow with automatic task tracking.
+ *
+ * Uses `startChild` to spawn the child workflow (fire-and-forget),
+ * then `waitFor` to receive the result signal from the child's
+ * interceptor. The child can escalate, fail, and be re-run multiple
+ * times without affecting the parent — the orchestrator simply waits
+ * for the signal.
+ *
+ * Usage (from within an orchestrator workflow):
+ * ```typescript
+ * export async function myPipeline(envelope: LTEnvelope) {
+ *   return await executeLT({
+ *     workflowName: 'reviewContent',
+ *     args: [envelope],
+ *     taskQueue: 'long-tail-examples',
+ *     originId: envelope.data.orderId,
+ *   });
+ * }
+ * ```
+ */
+async function executeLT(options) {
+    const { workflowName, args, taskQueue, expire } = options;
+    const { ltCreateTask, ltStartTask, ltCompleteTask, ltGetWorkflowConfig, ltGetProviderData, } = hotmesh_1.Durable.workflow.proxyActivities({
+        activities: interceptorActivities,
+        taskQueue: LT_ACTIVITY_QUEUE,
+        retryPolicy: { maximumAttempts: 3 },
+    });
+    // Derive child workflow ID deterministically from the parent context.
+    // Combines parent workflowId (globally unique) with the execution
+    // counter (unique per step within this workflow) — zero-cost, fully
+    // replay-safe, and self-documents its lineage.
+    const ctx = hotmesh_1.Durable.workflow.getContext();
+    const childWorkflowId = options.workflowId || `${workflowName}-${ctx.workflowId}-${ctx.counter}`;
+    const signalId = `lt-result-${childWorkflowId}`;
+    // Read orchestrator context (set by interceptor wrapping the container)
+    const orchCtx = (0, context_1.getOrchestratorContext)();
+    // Derive lineage: originId traces back to the root workflow,
+    // parentId identifies the immediate parent orchestrator.
+    const envelope0 = args[0];
+    const originId = options.originId
+        || envelope0?.lt?.originId
+        || orchCtx?.workflowId
+        || childWorkflowId;
+    const parentId = orchCtx?.workflowId || childWorkflowId;
+    // 1. Create task record with routing metadata for the interceptor
+    const taskId = await ltCreateTask({
+        workflowId: childWorkflowId,
+        workflowType: workflowName,
+        ltType: workflowName,
+        taskQueue,
+        signalId,
+        parentWorkflowId: orchCtx?.workflowId || childWorkflowId,
+        originId,
+        parentId,
+        envelope: JSON.stringify(args[0] || {}),
+        metadata: orchCtx
+            ? {
+                signalId,
+                parentWorkflowId: orchCtx.workflowId,
+                parentTaskQueue: orchCtx.taskQueue,
+                parentWorkflowType: orchCtx.workflowType,
+            }
+            : { signalId },
+        traceId: ctx.workflowTrace || undefined,
+        spanId: ctx.workflowSpan || undefined,
+        initiatedBy: orchCtx?.userId || envelope0?.lt?.userId,
+    });
+    await ltStartTask(taskId);
+    // 2. Load workflow config for provider injection
+    const wfConfig = await ltGetWorkflowConfig(workflowName);
+    // 3. Inject provider data into envelope if consumes are configured
+    if (wfConfig?.consumes?.length && originId) {
+        const providerData = await ltGetProviderData({
+            workflowName,
+            originId,
+        });
+        const envelope = args[0];
+        if (envelope && Object.keys(providerData).length > 0) {
+            envelope.lt = { ...envelope.lt, providers: providerData };
+        }
+    }
+    // 4. Inject task ID, lineage, and user context into the envelope so the
+    //    interceptor can find the task and propagate identity to child workflows
+    const envelope = args[0];
+    if (envelope) {
+        const userId = envelope.lt?.userId || orchCtx?.userId;
+        envelope.lt = { ...envelope.lt, taskId, originId, parentId, userId };
+    }
+    // 5. Start child workflow (fire-and-forget — only the start is awaited)
+    await hotmesh_1.Durable.workflow.startChild({
+        workflowName,
+        args,
+        taskQueue,
+        workflowId: childWorkflowId,
+        expire: expire || defaults_1.JOB_EXPIRE_SECS,
+        entity: workflowName,
+    });
+    // 6. Wait for the child's interceptor to signal back with the result
+    const result = await hotmesh_1.Durable.workflow.waitFor(signalId);
+    // 7. Complete the task — persist result data
+    await ltCompleteTask({
+        taskId,
+        data: JSON.stringify(result?.data),
+        milestones: result?.milestones || [],
+        workflowId: childWorkflowId,
+        workflowName,
+        taskQueue,
+    });
+    return result;
+}

package/build/services/orchestrator/types.d.ts

@@ -0,0 +1,15 @@
+/** Type definitions for the orchestrator service. */
+export interface ExecuteLTOptions {
+    /** Name of the child workflow function to execute */
+    workflowName: string;
+    /** Arguments to pass to the child workflow */
+    args: any[];
+    /** Task queue the child workflow is registered on */
+    taskQueue: string;
+    /** Explicit child workflow ID (auto-generated if omitted) */
+    workflowId?: string;
+    /** TTL in seconds for the child workflow */
+    expire?: number;
+    /** Correlation ID for provider data lookups across sibling tasks */
+    originId?: string;
+}

package/build/services/orchestrator/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the orchestrator service. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/services/role/index.d.ts

@@ -0,0 +1,47 @@
+import type { EscalationChain, RoleDetail } from './types';
+/**
+ * Get the roles a given source role can escalate to.
+ */
+export declare function getEscalationTargets(sourceRole: string): Promise<string[]>;
+/**
+ * Get all escalation chain pairs.
+ */
+export declare function getAllEscalationChains(): Promise<EscalationChain[]>;
+/**
+ * Add a single escalation chain entry.
+ */
+export declare function addEscalationChain(sourceRole: string, targetRole: string): Promise<void>;
+/**
+ * Remove a single escalation chain entry.
+ */
+export declare function removeEscalationChain(sourceRole: string, targetRole: string): Promise<boolean>;
+/**
+ * Replace all escalation targets for a source role.
+ */
+export declare function replaceEscalationTargets(sourceRole: string, targets: string[]): Promise<void>;
+/**
+ * Check whether a user can escalate from sourceRole to targetRole.
+ * Superadmins can escalate to any role.
+ * Others must hold the sourceRole AND the chain must exist.
+ */
+export declare function canEscalateTo(userId: string, sourceRole: string, targetRole: string): Promise<boolean>;
+/**
+ * List all distinct role names known to the system.
+ * lt_roles is the canonical source — all other tables reference it via FK.
+ */
+export declare function listDistinctRoles(): Promise<string[]>;
+/**
+ * List all roles with usage counts (users, escalation chains, workflows).
+ */
+export declare function listRolesWithDetails(): Promise<RoleDetail[]>;
+/**
+ * Create a standalone role entry.
+ */
+export declare function createRole(role: string): Promise<void>;
+/**
+ * Delete a role. Returns an error message if the role is referenced.
+ */
+export declare function deleteRole(role: string): Promise<{
+    deleted: boolean;
+    error?: string;
+}>;

package/build/services/role/index.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEscalationTargets = getEscalationTargets;
+exports.getAllEscalationChains = getAllEscalationChains;
+exports.addEscalationChain = addEscalationChain;
+exports.removeEscalationChain = removeEscalationChain;
+exports.replaceEscalationTargets = replaceEscalationTargets;
+exports.canEscalateTo = canEscalateTo;
+exports.listDistinctRoles = listDistinctRoles;
+exports.listRolesWithDetails = listRolesWithDetails;
+exports.createRole = createRole;
+exports.deleteRole = deleteRole;
+const db_1 = require("../db");
+const user_1 = require("../user");
+const sql_1 = require("./sql");
+/**
+ * Get the roles a given source role can escalate to.
+ */
+async function getEscalationTargets(sourceRole) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ESCALATION_TARGETS, [sourceRole]);
+    return rows.map((r) => r.target_role);
+}
+/**
+ * Get all escalation chain pairs.
+ */
+async function getAllEscalationChains() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ALL_ESCALATION_CHAINS);
+    return rows;
+}
+/**
+ * Add a single escalation chain entry.
+ */
+async function addEscalationChain(sourceRole, targetRole) {
+    const pool = (0, db_1.getPool)();
+    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [sourceRole]);
+    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [targetRole]);
+    await pool.query(sql_1.INSERT_ESCALATION_CHAIN, [sourceRole, targetRole]);
+}
+/**
+ * Remove a single escalation chain entry.
+ */
+async function removeEscalationChain(sourceRole, targetRole) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.DELETE_ESCALATION_CHAIN, [sourceRole, targetRole]);
+    return (rowCount ?? 0) > 0;
+}
+/**
+ * Replace all escalation targets for a source role.
+ */
+async function replaceEscalationTargets(sourceRole, targets) {
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(sql_1.ENSURE_ROLE_EXISTS, [sourceRole]);
+        for (const target of targets) {
+            await client.query(sql_1.ENSURE_ROLE_EXISTS, [target]);
+        }
+        await client.query(sql_1.DELETE_ESCALATION_CHAINS_BY_SOURCE, [sourceRole]);
+        for (const target of targets) {
+            await client.query(sql_1.INSERT_ESCALATION_CHAIN, [sourceRole, target]);
+        }
+        await client.query('COMMIT');
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Check whether a user can escalate from sourceRole to targetRole.
+ * Superadmins can escalate to any role.
+ * Others must hold the sourceRole AND the chain must exist.
+ */
+async function canEscalateTo(userId, sourceRole, targetRole) {
+    if (await (0, user_1.isSuperAdmin)(userId))
+        return true;
+    if (!(await (0, user_1.hasRole)(userId, sourceRole)))
+        return false;
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.CHECK_ESCALATION_CHAIN_EXISTS, [sourceRole, targetRole]);
+    return rows.length > 0;
+}
+/**
+ * List all distinct role names known to the system.
+ * lt_roles is the canonical source — all other tables reference it via FK.
+ */
+async function listDistinctRoles() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_ROLES);
+    return rows.map((r) => r.role);
+}
+/**
+ * List all roles with usage counts (users, escalation chains, workflows).
+ */
+async function listRolesWithDetails() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_ROLES_WITH_DETAILS);
+    return rows;
+}
+/**
+ * Create a standalone role entry.
+ */
+async function createRole(role) {
+    const pool = (0, db_1.getPool)();
+    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+}
+/**
+ * Delete a role. Returns an error message if the role is referenced.
+ */
+async function deleteRole(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows: userRefs } = await pool.query(sql_1.COUNT_USER_ROLE_REFS, [role]);
+    if (userRefs[0].cnt > 0) {
+        return { deleted: false, error: `Role is assigned to ${userRefs[0].cnt} user(s). Remove those assignments first.` };
+    }
+    const { rows: chainRefs } = await pool.query(sql_1.COUNT_CHAIN_REFS, [role]);
+    if (chainRefs[0].cnt > 0) {
+        return { deleted: false, error: `Role is referenced in ${chainRefs[0].cnt} escalation chain(s). Remove those chains first.` };
+    }
+    const { rows: wfRefs } = await pool.query(sql_1.COUNT_WORKFLOW_REFS, [role]);
+    if (wfRefs[0].cnt > 0) {
+        return { deleted: false, error: `Role is used by ${wfRefs[0].cnt} workflow config(s). Remove those references first.` };
+    }
+    const { rows: escRefs } = await pool.query(sql_1.COUNT_ACTIVE_ESCALATION_REFS, [role]);
+    if (escRefs[0].cnt > 0) {
+        return { deleted: false, error: `Role has ${escRefs[0].cnt} active escalation(s). Resolve them first.` };
+    }
+    const { rowCount } = await pool.query(sql_1.DELETE_ROLE, [role]);
+    return { deleted: (rowCount ?? 0) > 0 };
+}

package/build/services/role/sql.d.ts

@@ -0,0 +1,14 @@
+export declare const GET_ESCALATION_TARGETS = "\n  SELECT target_role\n  FROM lt_config_role_escalations\n  WHERE source_role = $1\n  ORDER BY target_role";
+export declare const GET_ALL_ESCALATION_CHAINS = "\n  SELECT source_role, target_role\n  FROM lt_config_role_escalations\n  ORDER BY source_role, target_role";
+export declare const INSERT_ESCALATION_CHAIN = "\n  INSERT INTO lt_config_role_escalations (source_role, target_role)\n  VALUES ($1, $2)\n  ON CONFLICT DO NOTHING";
+export declare const DELETE_ESCALATION_CHAIN = "\n  DELETE FROM lt_config_role_escalations\n  WHERE source_role = $1 AND target_role = $2";
+export declare const DELETE_ESCALATION_CHAINS_BY_SOURCE = "\n  DELETE FROM lt_config_role_escalations\n  WHERE source_role = $1";
+export declare const CHECK_ESCALATION_CHAIN_EXISTS = "\n  SELECT 1\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 AND target_role = $2";
+export declare const ENSURE_ROLE_EXISTS = "\n  INSERT INTO lt_roles (role) VALUES ($1)\n  ON CONFLICT DO NOTHING";
+export declare const LIST_ROLES = "\n  SELECT role FROM lt_roles ORDER BY role";
+export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  ORDER BY r.role";
+export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
+export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
+export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";
+export declare const COUNT_ACTIVE_ESCALATION_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_escalations\n  WHERE role = $1 AND status IN ('pending', 'claimed')";

package/build/services/role/sql.js

@@ -0,0 +1,80 @@
+"use strict";
+// ─── Escalation chain queries ───────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.GET_ESCALATION_TARGETS = `
+  SELECT target_role
+  FROM lt_config_role_escalations
+  WHERE source_role = $1
+  ORDER BY target_role`;
+exports.GET_ALL_ESCALATION_CHAINS = `
+  SELECT source_role, target_role
+  FROM lt_config_role_escalations
+  ORDER BY source_role, target_role`;
+exports.INSERT_ESCALATION_CHAIN = `
+  INSERT INTO lt_config_role_escalations (source_role, target_role)
+  VALUES ($1, $2)
+  ON CONFLICT DO NOTHING`;
+exports.DELETE_ESCALATION_CHAIN = `
+  DELETE FROM lt_config_role_escalations
+  WHERE source_role = $1 AND target_role = $2`;
+exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = `
+  DELETE FROM lt_config_role_escalations
+  WHERE source_role = $1`;
+exports.CHECK_ESCALATION_CHAIN_EXISTS = `
+  SELECT 1
+  FROM lt_config_role_escalations
+  WHERE source_role = $1 AND target_role = $2`;
+// ─── Role CRUD ──────────────────────────────────────────────────────────────
+exports.ENSURE_ROLE_EXISTS = `
+  INSERT INTO lt_roles (role) VALUES ($1)
+  ON CONFLICT DO NOTHING`;
+exports.LIST_ROLES = `
+  SELECT role FROM lt_roles ORDER BY role`;
+exports.DELETE_ROLE = `
+  DELETE FROM lt_roles WHERE role = $1`;
+// ─── Role detail aggregation ────────────────────────────────────────────────
+exports.LIST_ROLES_WITH_DETAILS = `
+  WITH
+  user_counts AS (
+    SELECT role, COUNT(DISTINCT user_id)::int AS cnt
+    FROM lt_user_roles
+    GROUP BY role
+  ),
+  chain_counts AS (
+    SELECT role, COUNT(*)::int AS cnt
+    FROM (
+      SELECT source_role AS role FROM lt_config_role_escalations
+      UNION ALL
+      SELECT target_role AS role FROM lt_config_role_escalations
+    ) c
+    GROUP BY role
+  ),
+  workflow_counts AS (
+    SELECT role, COUNT(*)::int AS cnt
+    FROM lt_config_roles
+    GROUP BY role
+  )
+  SELECT
+    r.role,
+    COALESCE(uc.cnt, 0) AS user_count,
+    COALESCE(cc.cnt, 0) AS chain_count,
+    COALESCE(wc.cnt, 0) AS workflow_count
+  FROM lt_roles r
+  LEFT JOIN user_counts uc ON uc.role = r.role
+  LEFT JOIN chain_counts cc ON cc.role = r.role
+  LEFT JOIN workflow_counts wc ON wc.role = r.role
+  ORDER BY r.role`;
+// ─── Reference checks (used before role deletion) ──────────────────────────
+exports.COUNT_USER_ROLE_REFS = `
+  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1`;
+exports.COUNT_CHAIN_REFS = `
+  SELECT COUNT(*)::int AS cnt
+  FROM lt_config_role_escalations
+  WHERE source_role = $1 OR target_role = $1`;
+exports.COUNT_WORKFLOW_REFS = `
+  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1`;
+exports.COUNT_ACTIVE_ESCALATION_REFS = `
+  SELECT COUNT(*)::int AS cnt
+  FROM lt_escalations
+  WHERE role = $1 AND status IN ('pending', 'claimed')`;

package/build/services/role/types.d.ts

@@ -0,0 +1,11 @@
+/** Type definitions for the role and escalation chain service. */
+export interface EscalationChain {
+    source_role: string;
+    target_role: string;
+}
+export interface RoleDetail {
+    role: string;
+    user_count: number;
+    chain_count: number;
+    workflow_count: number;
+}

package/build/services/role/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the role and escalation chain service. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/services/storage/index.d.ts

@@ -0,0 +1,12 @@
+import type { StorageBackend } from './types';
+export type { StorageBackend } from './types';
+/**
+ * Returns the singleton storage backend.
+ *
+ * Backend selection (via LT_STORAGE_BACKEND env var):
+ *   "local" (default) — filesystem storage under LT_FILE_STORAGE_DIR
+ *   "s3"              — S3-compatible (MinIO, AWS S3, GCP Cloud Storage)
+ */
+export declare function getStorageBackend(): StorageBackend;
+/** Reset the singleton (for testing). */
+export declare function resetStorageBackend(): void;