@locusai/locus-gateway 0.22.13

package/dist/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Core type definitions for the Locus Gateway.
+ *
+ * These interfaces define the contract between the gateway core
+ * and platform-specific adapters (Telegram, Discord, WhatsApp, etc.).
+ */
+import type { ChildProcess } from "node:child_process";
+/** Every platform implements this interface to bridge messages into the gateway. */
+export interface PlatformAdapter {
+    /** Platform identifier (e.g., "telegram", "discord", "whatsapp"). */
+    readonly platform: string;
+    /** Start listening for messages. */
+    start(): Promise<void>;
+    /** Stop the adapter gracefully. */
+    stop(): Promise<void>;
+    /** Send a message to a session. */
+    send(sessionId: string, message: OutboundMessage): Promise<void>;
+    /**
+     * Edit a previously sent message (if supported).
+     * Adapters that don't support editing should omit this method.
+     */
+    edit?(sessionId: string, messageId: string, message: OutboundMessage): Promise<void>;
+    /** Platform capabilities — informs the gateway how to format output. */
+    capabilities: PlatformCapabilities;
+}
+/** Declares what a platform supports so the gateway can adapt its output. */
+export interface PlatformCapabilities {
+    /** Whether sent messages can be edited (streaming via edit). */
+    supportsEditing: boolean;
+    /** Whether inline action buttons are supported. */
+    supportsInlineButtons: boolean;
+    /** Whether Markdown formatting is supported. */
+    supportsMarkdown: boolean;
+    /** Whether HTML formatting is supported. */
+    supportsHTML: boolean;
+    /** Whether file uploads are supported. */
+    supportsFileUpload: boolean;
+    /** Maximum message length (chars) before splitting. */
+    maxMessageLength: number;
+    /** Whether the platform can "stream" output by editing messages in place. */
+    supportsStreaming: boolean;
+}
+/** A message arriving from a platform into the gateway. */
+export interface InboundMessage {
+    /** Platform identifier. */
+    platform: string;
+    /** Platform-specific chat/channel ID (string for cross-platform compat). */
+    sessionId: string;
+    /** Platform-specific user ID. */
+    userId: string;
+    /** Message text content. */
+    text: string;
+    /** Optional file attachments. */
+    attachments?: Attachment[];
+    /** ID of the message being replied to (if any). */
+    replyTo?: string;
+    /** Platform-specific extra data. */
+    metadata?: Record<string, unknown>;
+}
+/** A message going from the gateway to a platform. */
+export interface OutboundMessage {
+    /** Message text content. */
+    text: string;
+    /** Desired format — the adapter will convert if the platform doesn't support it. */
+    format: "plain" | "markdown" | "html";
+    /** Platform-agnostic actions (buttons, links). */
+    actions?: Action[];
+    /** File attachments. */
+    attachments?: Attachment[];
+}
+/** A platform-agnostic action (button or link). */
+export interface Action {
+    /** Unique identifier for callback routing. */
+    id: string;
+    /** Display text for the action. */
+    label: string;
+    /** Action type. */
+    type: "button" | "link";
+    /** URL for link-type actions. */
+    url?: string;
+}
+/** A file attachment. */
+export interface Attachment {
+    /** Filename. */
+    name: string;
+    /** MIME type. */
+    mimeType: string;
+    /** File content as a Buffer, or a URL to download. */
+    content: Buffer | string;
+}
+/** A parsed slash command. */
+export interface ParsedCommand {
+    type: "command";
+    command: string;
+    args: string[];
+    raw: string;
+}
+/** Free-text input (not a command). */
+export interface FreeText {
+    type: "freetext";
+    text: string;
+}
+/** Context passed to command handlers. */
+export interface RouteContext {
+    /** The platform the message came from. */
+    platform: string;
+    /** Session (chat/channel) ID. */
+    sessionId: string;
+    /** User ID. */
+    userId: string;
+    /** Platform capabilities. */
+    capabilities: PlatformCapabilities;
+    /** Send a reply back through the gateway. */
+    reply(message: OutboundMessage): Promise<void>;
+    /** Edit a previously sent message (if supported). Returns false if unsupported. */
+    editReply?(messageId: string, message: OutboundMessage): Promise<boolean>;
+    /** Platform-specific metadata from the inbound message. */
+    metadata?: Record<string, unknown>;
+}
+/** Result from executing a command. */
+export interface CommandResult {
+    /** Output text. */
+    text: string;
+    /** Format of the output text. */
+    format: "plain" | "markdown" | "html";
+    /** Optional actions to include with the response. */
+    actions?: Action[];
+    /** Whether the output was streamed (for logging/telemetry). */
+    streaming?: boolean;
+}
+/** A tracked active command. */
+export interface ActiveCommand {
+    /** Unique tracking ID. */
+    id: string;
+    /** Command name. */
+    command: string;
+    /** Command arguments. */
+    args: string[];
+    /** Associated subprocess (if any). */
+    childProcess: ChildProcess | null;
+    /** When the command started. */
+    startedAt: Date;
+}
+/** Exclusivity group for concurrent command management. */
+export type ExclusivityGroup = "workspace" | "git";
+/** Returned when a command is blocked by an exclusive conflict. */
+export interface ConflictResult {
+    blocked: true;
+    runningCommand: ActiveCommand;
+    group: ExclusivityGroup;
+}
+/** Maps command names to CLI arguments. */
+export interface CommandDefinition {
+    /** The locus CLI arguments for this command. */
+    cliArgs: string[];
+    /** Whether this command produces streaming output. */
+    streaming: boolean;
+    /** If set, the command requires arguments. Value is the help message. */
+    requiresArgs?: string;
+}
+/** Events emitted by the gateway. */
+export type GatewayEvent = {
+    type: "message_received";
+    message: InboundMessage;
+} | {
+    type: "command_started";
+    sessionId: string;
+    command: string;
+    args: string[];
+} | {
+    type: "command_completed";
+    sessionId: string;
+    command: string;
+    exitCode: number;
+} | {
+    type: "error";
+    error: Error;
+    context?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@locusai/locus-gateway",
+  "version": "0.22.13",
+  "description": "Channel-agnostic message gateway for Locus platform adapters",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm && bun build ./src/index.ts --outfile ./dist/index.cjs --target node --format cjs && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "clean": "rm -rf dist node_modules"
+  },
+  "dependencies": {
+    "@locusai/sdk": "^0.22.13"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "locusai-package",
+    "locus",
+    "gateway"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}