@hotmeshio/long-tail 0.1.7 → 0.1.9

package/README.md

@@ -251,7 +251,9 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](docs/
 
 **Adapters:** [Auth](docs/auth.md) · [Events](docs/events.md) · [Telemetry](docs/telemetry.md) · [Logging](docs/logging.md) · [Maintenance](docs/maintenance.md) · [OAuth](docs/oauth-and-delegation.md)
 
-**API:** [Workflows](docs/api/workflows.md) · [Tasks](docs/api/tasks.md) · [Escalations](docs/api/escalations.md) · [YAML Workflows](docs/api/yaml-workflows.md) · [Users](docs/api/users.md) · [Roles](docs/api/roles.md) · [Service Accounts](docs/api/service-accounts.md) · [MCP Servers](docs/api/mcp-servers.md) · [MCP Runs](docs/api/mcp-runs.md) · [Exports](docs/api/exports.md)
+**HTTP API:** [Workflows](docs/api/http/workflows.md) · [Tasks](docs/api/http/tasks.md) · [Escalations](docs/api/http/escalations.md) · [YAML Workflows](docs/api/http/yaml-workflows.md) · [Users](docs/api/http/users.md) · [Roles](docs/api/http/roles.md) · [Service Accounts](docs/api/http/service-accounts.md) · [MCP Servers](docs/api/http/mcp-servers.md) · [MCP Runs](docs/api/http/mcp-runs.md) · [Exports](docs/api/http/exports.md)
+
+**SDK:** [Overview](docs/sdk.md) · [Workflows](docs/api/sdk/workflows.md) · [Tasks](docs/api/sdk/tasks.md) · [Escalations](docs/api/sdk/escalations.md) · [YAML Workflows](docs/api/sdk/yaml-workflows.md) · [MCP](docs/api/sdk/mcp.md) · [Events](docs/api/sdk/events.md)
 
 ## Contributing
 

package/build/api/auth.d.ts

@@ -1,4 +1,15 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * Authenticate a user by username and password.
+ *
+ * Verifies credentials against the user store and returns a signed JWT
+ * with the user's roles and highest privilege level. The token is valid
+ * for 24 hours.
+ *
+ * @param input.username — login identifier (external_id)
+ * @param input.password — plaintext password
+ * @returns `{ status: 200, data: { token, user: { id, external_id, display_name, roles } } }`
+ */
 export declare function login(input: {
     username: string;
     password: string;

package/build/api/auth.js

@@ -3,6 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.login = login;
 const user_1 = require("../services/user");
 const auth_1 = require("../modules/auth");
+/**
+ * Authenticate a user by username and password.
+ *
+ * Verifies credentials against the user store and returns a signed JWT
+ * with the user's roles and highest privilege level. The token is valid
+ * for 24 hours.
+ *
+ * @param input.username — login identifier (external_id)
+ * @param input.password — plaintext password
+ * @returns `{ status: 200, data: { token, user: { id, external_id, display_name, roles } } }`
+ */
 async function login(input) {
     try {
         const { username, password } = input;

package/build/api/bot-accounts.d.ts

@@ -1,11 +1,37 @@
 import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * List all bot accounts with pagination.
+ *
+ * @param input.limit — maximum number of bots to return (default 50)
+ * @param input.offset — number of bots to skip for pagination (default 0)
+ * @returns `{ status: 200, data: Bot[] }` paginated list of bots
+ */
 export declare function listBots(input: {
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve a single bot account by ID.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: Bot }` the bot record, or 404 if not found
+ */
 export declare function getBot(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Create a new bot account with optional roles.
+ *
+ * Validates that each provided role has a valid type (superadmin, admin, member).
+ * Returns 409 if a bot with the same name already exists.
+ *
+ * @param input.name — unique bot name (required)
+ * @param input.description — optional text description of the bot
+ * @param input.display_name — optional human-friendly display name
+ * @param input.roles — optional list of roles to assign at creation, each with a role name and type
+ * @param auth — authenticated user context; userId is recorded as the bot creator
+ * @returns `{ status: 201, data: Bot }` the newly created bot record
+ */
 export declare function createBot(input: {
     name: string;
     description?: string;
@@ -15,36 +41,97 @@ export declare function createBot(input: {
         type: string;
     }[];
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Update mutable fields on an existing bot account.
+ *
+ * @param input.id — unique identifier of the bot to update
+ * @param input.display_name — new display name
+ * @param input.description — new description
+ * @param input.status — new status value
+ * @returns `{ status: 200, data: Bot }` the updated bot record, or 404 if not found
+ */
 export declare function updateBot(input: {
     id: string;
     display_name?: string;
     description?: string;
     status?: string;
 }): Promise<LTApiResult>;
+/**
+ * Delete a bot account by ID.
+ *
+ * @param input.id — unique identifier of the bot to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or 404 if not found
+ */
 export declare function deleteBot(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * List all roles assigned to a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: { roles: Role[] } }` the bot's roles, or 404 if bot not found
+ */
 export declare function getBotRoles(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Assign a role to a bot account.
+ *
+ * Validates that the role type is one of superadmin, admin, or member.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.role — role name to assign
+ * @param input.type — role type (superadmin, admin, or member)
+ * @returns `{ status: 201, data: Role }` the newly assigned role, or 404 if bot not found
+ */
 export declare function addBotRole(input: {
     id: string;
     role: string;
     type: string;
 }): Promise<LTApiResult>;
+/**
+ * Remove a role from a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.role — role name to remove
+ * @returns `{ status: 200, data: { removed: true } }` on success, or 404 if role not found
+ */
 export declare function removeBotRole(input: {
     id: string;
     role: string;
 }): Promise<LTApiResult>;
+/**
+ * List all API keys for a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: { keys: ApiKey[] } }` the bot's API keys, or 404 if bot not found
+ */
 export declare function listBotKeys(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Create a new API key for a bot account.
+ *
+ * Returns 409 if an API key with the same name already exists for this bot.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.name — human-readable name for the API key (required)
+ * @param input.scopes — optional list of permission scopes to restrict the key
+ * @param input.expires_at — optional ISO 8601 expiration timestamp
+ * @returns `{ status: 201, data: ApiKey }` the newly created API key (includes the secret)
+ */
 export declare function createBotKey(input: {
     id: string;
     name: string;
     scopes?: string[];
     expires_at?: string;
 }): Promise<LTApiResult>;
+/**
+ * Revoke an existing bot API key.
+ *
+ * @param input.keyId — unique identifier of the API key to revoke
+ * @returns `{ status: 200, data: { revoked: true } }` on success, or 404 if key not found
+ */
 export declare function revokeBotKey(input: {
     keyId: string;
 }): Promise<LTApiResult>;

package/build/api/bot-accounts.js

@@ -46,6 +46,13 @@ exports.createBotKey = createBotKey;
 exports.revokeBotKey = revokeBotKey;
 const iam = __importStar(require("../services/iam"));
 const user_1 = require("../services/user");
+/**
+ * List all bot accounts with pagination.
+ *
+ * @param input.limit — maximum number of bots to return (default 50)
+ * @param input.offset — number of bots to skip for pagination (default 0)
+ * @returns `{ status: 200, data: Bot[] }` paginated list of bots
+ */
 async function listBots(input) {
     try {
         const limit = input.limit ?? 50;
@@ -57,6 +64,12 @@ async function listBots(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve a single bot account by ID.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: Bot }` the bot record, or 404 if not found
+ */
 async function getBot(input) {
     try {
         const bot = await iam.getBot(input.id);
@@ -69,6 +82,19 @@ async function getBot(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Create a new bot account with optional roles.
+ *
+ * Validates that each provided role has a valid type (superadmin, admin, member).
+ * Returns 409 if a bot with the same name already exists.
+ *
+ * @param input.name — unique bot name (required)
+ * @param input.description — optional text description of the bot
+ * @param input.display_name — optional human-friendly display name
+ * @param input.roles — optional list of roles to assign at creation, each with a role name and type
+ * @param auth — authenticated user context; userId is recorded as the bot creator
+ * @returns `{ status: 201, data: Bot }` the newly created bot record
+ */
 async function createBot(input, auth) {
     try {
         if (!input.name) {
@@ -100,6 +126,15 @@ async function createBot(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Update mutable fields on an existing bot account.
+ *
+ * @param input.id — unique identifier of the bot to update
+ * @param input.display_name — new display name
+ * @param input.description — new description
+ * @param input.status — new status value
+ * @returns `{ status: 200, data: Bot }` the updated bot record, or 404 if not found
+ */
 async function updateBot(input) {
     try {
         const { id, ...fields } = input;
@@ -113,6 +148,12 @@ async function updateBot(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Delete a bot account by ID.
+ *
+ * @param input.id — unique identifier of the bot to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or 404 if not found
+ */
 async function deleteBot(input) {
     try {
         const deleted = await iam.deleteBot(input.id);
@@ -125,6 +166,12 @@ async function deleteBot(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all roles assigned to a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: { roles: Role[] } }` the bot's roles, or 404 if bot not found
+ */
 async function getBotRoles(input) {
     try {
         const bot = await iam.getBot(input.id);
@@ -138,6 +185,16 @@ async function getBotRoles(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Assign a role to a bot account.
+ *
+ * Validates that the role type is one of superadmin, admin, or member.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.role — role name to assign
+ * @param input.type — role type (superadmin, admin, or member)
+ * @returns `{ status: 201, data: Role }` the newly assigned role, or 404 if bot not found
+ */
 async function addBotRole(input) {
     try {
         if (!input.role || !input.type) {
@@ -157,6 +214,13 @@ async function addBotRole(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Remove a role from a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.role — role name to remove
+ * @returns `{ status: 200, data: { removed: true } }` on success, or 404 if role not found
+ */
 async function removeBotRole(input) {
     try {
         const removed = await iam.removeBotRole(input.id, input.role);
@@ -169,6 +233,12 @@ async function removeBotRole(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all API keys for a bot account.
+ *
+ * @param input.id — unique identifier of the bot
+ * @returns `{ status: 200, data: { keys: ApiKey[] } }` the bot's API keys, or 404 if bot not found
+ */
 async function listBotKeys(input) {
     try {
         const bot = await iam.getBot(input.id);
@@ -182,6 +252,17 @@ async function listBotKeys(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Create a new API key for a bot account.
+ *
+ * Returns 409 if an API key with the same name already exists for this bot.
+ *
+ * @param input.id — unique identifier of the bot
+ * @param input.name — human-readable name for the API key (required)
+ * @param input.scopes — optional list of permission scopes to restrict the key
+ * @param input.expires_at — optional ISO 8601 expiration timestamp
+ * @returns `{ status: 201, data: ApiKey }` the newly created API key (includes the secret)
+ */
 async function createBotKey(input) {
     try {
         if (!input.name) {
@@ -201,6 +282,12 @@ async function createBotKey(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Revoke an existing bot API key.
+ *
+ * @param input.keyId — unique identifier of the API key to revoke
+ * @returns `{ status: 200, data: { revoked: true } }` on success, or 404 if key not found
+ */
 async function revokeBotKey(input) {
     try {
         const revoked = await iam.revokeBotKey(input.keyId);

package/build/api/controlplane.d.ts

@@ -1,20 +1,68 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * List all registered application namespaces.
+ *
+ * @returns `{ status: 200, data: { apps } }` array of known app identifiers
+ */
 export declare function listApps(): Promise<LTApiResult>;
+/**
+ * Query active worker profiles for an application.
+ *
+ * Sends a roll-call request to the mesh and collects responses from
+ * all running workers within the optional delay window.
+ *
+ * @param input.appId — application namespace to query (defaults to 'durable')
+ * @param input.delay — milliseconds to wait for worker responses before returning
+ * @returns `{ status: 200, data: { profiles } }` array of worker profile objects
+ */
 export declare function rollCall(input: {
     appId?: string;
     delay?: number;
 }): Promise<LTApiResult>;
+/**
+ * Apply a throttle rate to workflow execution.
+ *
+ * Sets the throttle value for a specific topic or workflow within an app
+ * namespace. Also publishes a synthetic `mesh.throttle` event so the
+ * dashboard event stream reflects the change.
+ *
+ * @param input.appId — application namespace (defaults to 'durable')
+ * @param input.throttle — throttle value to apply (required, must be a number)
+ * @param input.topic — optional topic to scope the throttle to
+ * @param input.guid — optional workflow GUID to scope the throttle to
+ * @returns `{ status: 200, data: { success } }` boolean indicating the throttle was applied
+ */
 export declare function applyThrottle(input: {
     appId?: string;
     throttle: number;
     topic?: string;
     guid?: string;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve stream statistics for an application.
+ *
+ * Returns throughput and backlog metrics for Redis streams backing the
+ * given app namespace over the specified time window.
+ *
+ * @param input.app_id — application namespace (defaults to 'durable')
+ * @param input.duration — time window for stats aggregation, e.g. '1h', '30m' (defaults to '1h')
+ * @param input.stream — optional specific stream name to filter results
+ * @returns `{ status: 200, data: { ... } }` stream statistics object
+ */
 export declare function getStreamStats(input: {
     app_id?: string;
     duration?: string;
     stream?: string;
 }): Promise<LTApiResult>;
+/**
+ * Subscribe to mesh events for an application.
+ *
+ * Establishes a subscription to the event stream of the given app
+ * namespace so that mesh events are captured and forwarded.
+ *
+ * @param input.appId — application namespace to subscribe to (defaults to 'durable')
+ * @returns `{ status: 200, data: { subscribed, appId } }` confirmation with the subscribed app ID
+ */
 export declare function subscribeMesh(input: {
     appId?: string;
 }): Promise<LTApiResult>;

package/build/api/controlplane.js

@@ -40,6 +40,11 @@ exports.getStreamStats = getStreamStats;
 exports.subscribeMesh = subscribeMesh;
 const controlplane = __importStar(require("../services/controlplane"));
 const events_1 = require("../lib/events");
+/**
+ * List all registered application namespaces.
+ *
+ * @returns `{ status: 200, data: { apps } }` array of known app identifiers
+ */
 async function listApps() {
     try {
         const apps = await controlplane.listApps();
@@ -49,6 +54,16 @@ async function listApps() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Query active worker profiles for an application.
+ *
+ * Sends a roll-call request to the mesh and collects responses from
+ * all running workers within the optional delay window.
+ *
+ * @param input.appId — application namespace to query (defaults to 'durable')
+ * @param input.delay — milliseconds to wait for worker responses before returning
+ * @returns `{ status: 200, data: { profiles } }` array of worker profile objects
+ */
 async function rollCall(input) {
     try {
         const appId = input.appId || 'durable';
@@ -59,6 +74,19 @@ async function rollCall(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Apply a throttle rate to workflow execution.
+ *
+ * Sets the throttle value for a specific topic or workflow within an app
+ * namespace. Also publishes a synthetic `mesh.throttle` event so the
+ * dashboard event stream reflects the change.
+ *
+ * @param input.appId — application namespace (defaults to 'durable')
+ * @param input.throttle — throttle value to apply (required, must be a number)
+ * @param input.topic — optional topic to scope the throttle to
+ * @param input.guid — optional workflow GUID to scope the throttle to
+ * @returns `{ status: 200, data: { success } }` boolean indicating the throttle was applied
+ */
 async function applyThrottle(input) {
     try {
         const appId = input.appId || 'durable';
@@ -87,6 +115,17 @@ async function applyThrottle(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve stream statistics for an application.
+ *
+ * Returns throughput and backlog metrics for Redis streams backing the
+ * given app namespace over the specified time window.
+ *
+ * @param input.app_id — application namespace (defaults to 'durable')
+ * @param input.duration — time window for stats aggregation, e.g. '1h', '30m' (defaults to '1h')
+ * @param input.stream — optional specific stream name to filter results
+ * @returns `{ status: 200, data: { ... } }` stream statistics object
+ */
 async function getStreamStats(input) {
     try {
         const schema = input.app_id || 'durable';
@@ -98,6 +137,15 @@ async function getStreamStats(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Subscribe to mesh events for an application.
+ *
+ * Establishes a subscription to the event stream of the given app
+ * namespace so that mesh events are captured and forwarded.
+ *
+ * @param input.appId — application namespace to subscribe to (defaults to 'durable')
+ * @returns `{ status: 200, data: { subscribed, appId } }` confirmation with the subscribed app ID
+ */
 async function subscribeMesh(input) {
     try {
         const appId = input.appId || 'durable';

package/build/api/dba.d.ts

@@ -1,4 +1,23 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * Prune stale HotMesh data from Redis.
+ *
+ * Selectively removes completed jobs, stream entries, engine/worker
+ * streams, and search attributes. Delegates to the HotMesh DBA service.
+ *
+ * @param input.expire — Redis TTL expression for pruned keys
+ * @param input.jobs — prune completed job hashes
+ * @param input.streams — prune activity streams
+ * @param input.engineStreams — prune engine consumer streams
+ * @param input.engineStreamsExpire — TTL for engine stream entries
+ * @param input.workerStreams — prune worker consumer streams
+ * @param input.workerStreamsExpire — TTL for worker stream entries
+ * @param input.attributes — prune FT.SEARCH attributes
+ * @param input.entities — limit pruning to these entity types
+ * @param input.pruneTransient — include transient keys
+ * @param input.keepHmark — preserve hmark keys
+ * @returns `{ status: 200, data: <prune result summary> }`
+ */
 export declare function prune(input: {
     expire?: string;
     jobs?: boolean;
@@ -12,4 +31,12 @@ export declare function prune(input: {
     pruneTransient?: boolean;
     keepHmark?: boolean;
 }): Promise<LTApiResult>;
+/**
+ * Deploy (or redeploy) all HotMesh workflow schemas.
+ *
+ * Triggers a full schema deployment across all registered entities,
+ * updating the Redis execution graph. Safe to call repeatedly.
+ *
+ * @returns `{ status: 200, data: { ok: true } }`
+ */
 export declare function deploy(): Promise<LTApiResult>;

package/build/api/dba.js

@@ -36,6 +36,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.prune = prune;
 exports.deploy = deploy;
 const dbaService = __importStar(require("../services/dba"));
+/**
+ * Prune stale HotMesh data from Redis.
+ *
+ * Selectively removes completed jobs, stream entries, engine/worker
+ * streams, and search attributes. Delegates to the HotMesh DBA service.
+ *
+ * @param input.expire — Redis TTL expression for pruned keys
+ * @param input.jobs — prune completed job hashes
+ * @param input.streams — prune activity streams
+ * @param input.engineStreams — prune engine consumer streams
+ * @param input.engineStreamsExpire — TTL for engine stream entries
+ * @param input.workerStreams — prune worker consumer streams
+ * @param input.workerStreamsExpire — TTL for worker stream entries
+ * @param input.attributes — prune FT.SEARCH attributes
+ * @param input.entities — limit pruning to these entity types
+ * @param input.pruneTransient — include transient keys
+ * @param input.keepHmark — preserve hmark keys
+ * @returns `{ status: 200, data: <prune result summary> }`
+ */
 async function prune(input) {
     try {
         const result = await dbaService.prune({
@@ -57,6 +76,14 @@ async function prune(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Deploy (or redeploy) all HotMesh workflow schemas.
+ *
+ * Triggers a full schema deployment across all registered entities,
+ * updating the Redis execution graph. Safe to call repeatedly.
+ *
+ * @returns `{ status: 200, data: { ok: true } }`
+ */
 async function deploy() {
     try {
         await dbaService.deploy();