@shepai/cli 1.181.0 → 1.182.0-pr512.369be8e

package/apis/json-schema/MessagingCommand.yaml

@@ -0,0 +1,28 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingCommand.yaml
+type: object
+properties:
+  type:
+    $ref: MessagingFrameType.yaml
+    description: "Type of frame: command, chat_message, or chat_control"
+  command:
+    $ref: MessagingCommandType.yaml
+    description: The slash command name (new, approve, reject, stop, resume, status)
+  featureId:
+    type: string
+    description: Target feature ID (short numeric or full UUID)
+  args:
+    type: string
+    description: Free-text arguments (feature description, rejection feedback, chat text)
+  chatId:
+    type: string
+    description: Chat ID for routing responses back to the correct conversation
+  platform:
+    $ref: MessagingPlatform.yaml
+    description: Platform for routing responses back (telegram or whatsapp)
+required:
+  - type
+  - command
+  - chatId
+  - platform
+description: A parsed command received from a messaging platform via the Gateway tunnel

package/apis/json-schema/MessagingCommandType.yaml

@@ -0,0 +1,17 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingCommandType.yaml
+type: string
+enum:
+  - new
+  - approve
+  - reject
+  - stop
+  - resume
+  - status
+  - mute
+  - unmute
+  - list
+  - chat
+  - end
+  - help
+description: Slash commands supported via messaging remote control

package/apis/json-schema/MessagingConfig.yaml

@@ -0,0 +1,40 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingConfig.yaml
+type: object
+properties:
+  enabled:
+    type: boolean
+    default: false
+    description: Whether messaging remote control is enabled
+  gatewayUrl:
+    type: string
+    description: URL of the Commands.com Gateway instance
+  deviceId:
+    type: string
+    description: Device ID used when registering integration routes and opening the tunnel
+  gatewayClientId:
+    type: string
+    description: OAuth client ID for fetching gateway access tokens (demo mode uses public client)
+  telegram:
+    $ref: MessagingPlatformConfig.yaml
+    description: Telegram platform configuration
+  whatsapp:
+    $ref: MessagingPlatformConfig.yaml
+    description: WhatsApp platform configuration
+  debounceMs:
+    type: integer
+    minimum: -2147483648
+    maximum: 2147483647
+    default: 5000
+    description: "Debounce window in milliseconds for notification delivery (default: 5000)"
+  chatBufferMs:
+    type: integer
+    minimum: -2147483648
+    maximum: 2147483647
+    default: 3000
+    description: "Buffer interval in milliseconds for chat relay output batching (default: 3000)"
+required:
+  - enabled
+  - debounceMs
+  - chatBufferMs
+description: Messaging remote control configuration

package/apis/json-schema/MessagingFrameType.yaml

@@ -0,0 +1,8 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingFrameType.yaml
+type: string
+enum:
+  - command
+  - chat_message
+  - chat_control
+description: Types of messages exchanged through the messaging tunnel

package/apis/json-schema/MessagingNotification.yaml

@@ -0,0 +1,22 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingNotification.yaml
+type: object
+properties:
+  event:
+    type: string
+    description: "Event type: feature lifecycle, CI status, gate waiting, command response, chat response"
+  featureId:
+    type: string
+    description: ID of the feature this notification relates to
+  title:
+    type: string
+    description: Human-readable feature name or title
+  message:
+    type: string
+    description: Human-readable notification body (sanitized, no code or secrets)
+required:
+  - event
+  - featureId
+  - title
+  - message
+description: A notification or response sent from Shep to a messaging platform via the Gateway tunnel

package/apis/json-schema/MessagingPlatform.yaml

@@ -0,0 +1,7 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingPlatform.yaml
+type: string
+enum:
+  - telegram
+  - whatsapp
+description: Supported external messaging platforms

package/apis/json-schema/MessagingPlatformConfig.yaml

@@ -0,0 +1,38 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: MessagingPlatformConfig.yaml
+type: object
+properties:
+  enabled:
+    type: boolean
+    default: false
+    description: Whether this platform connection is active
+  chatId:
+    type: string
+    description: Platform-specific chat ID for message routing (set during pairing)
+  paired:
+    type: boolean
+    default: false
+    description: Whether the chat has been verified via pairing code
+  pendingPairingCode:
+    type: string
+    description: One-time code shown to the user during pairing, cleared once confirmed
+  pendingPairingExpiresAt:
+    type: string
+    format: date-time
+    description: Expiry timestamp for the pending pairing code (ISO-8601)
+  routeId:
+    type: string
+    description: Gateway integration route ID allocated during pairing
+  routeToken:
+    type: string
+    description: Gateway integration route token (path-auth) allocated during pairing
+  publicUrl:
+    type: string
+    description: Public webhook URL that the messaging platform should POST updates to
+  botToken:
+    type: string
+    description: "Bot API token used by the daemon to send outbound messages (Telegram: 123456:ABC...)"
+required:
+  - enabled
+  - paired
+description: Configuration for a single messaging platform connection

package/apis/json-schema/Settings.yaml

@@ -36,6 +36,9 @@ properties:
   fabLayout:
     $ref: FabLayoutConfig.yaml
     description: FAB layout configuration (optional, defaults applied at runtime)
+  messaging:
+    $ref: MessagingConfig.yaml
+    description: Messaging remote control configuration (optional, defaults applied at runtime)
 required:
   - models
   - user

package/dist/packages/core/src/application/ports/output/services/gateway-client.interface.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Gateway Client Interface
+ *
+ * Output port for the Commands.com Gateway HTTP API. Implementations handle
+ * authentication (OAuth demo/OIDC) and integration-route provisioning so the
+ * MessagingService can receive inbound webhooks from Telegram/WhatsApp.
+ *
+ * Reference: https://github.com/Commands-com/gateway/blob/main/docs/openapi.yaml
+ */
+export interface GatewayOAuthToken {
+    accessToken: string;
+    tokenType: string;
+    /** Absolute expiry time in ms since epoch. */
+    expiresAt: number;
+    refreshToken?: string;
+}
+export interface GatewayIntegrationRoute {
+    routeId: string;
+    routeToken: string;
+    publicUrl: string;
+    deviceId: string;
+    interfaceType: string;
+}
+export interface CreateIntegrationRouteInput {
+    deviceId: string;
+    interfaceType: string;
+    /** Optional client-provided token override. Gateway issues one if omitted. */
+    routeToken?: string;
+    tokenMaxAgeDays?: number;
+    maxBodyBytes?: number;
+    deadlineMs?: number;
+}
+export interface FetchTokenInput {
+    gatewayUrl: string;
+    clientId: string;
+    /** For demo auth the client secret is optional. */
+    clientSecret?: string;
+    scope?: string;
+}
+/**
+ * Port for interacting with the Commands.com Gateway HTTP API.
+ *
+ * Implementations MUST NOT leak HTTP specifics (status codes, headers) to
+ * the application layer — return domain objects or throw domain errors.
+ */
+export interface IGatewayClient {
+    /**
+     * Fetch (or refresh) an OAuth access token for the configured client.
+     * Uses the client_credentials grant in demo mode.
+     */
+    fetchAccessToken(input: FetchTokenInput): Promise<GatewayOAuthToken>;
+    /**
+     * Register a new integration route on the gateway. The returned `publicUrl`
+     * is what the messaging platform (Telegram webhook, etc.) should POST to.
+     */
+    createIntegrationRoute(gatewayUrl: string, accessToken: string, input: CreateIntegrationRouteInput): Promise<GatewayIntegrationRoute>;
+}
+//# sourceMappingURL=gateway-client.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/gateway-client.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-client.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/gateway-client.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAErE;;;OAGG;IACH,sBAAsB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACrC"}

package/dist/packages/core/src/application/ports/output/services/gateway-client.interface.js

@@ -0,0 +1,10 @@
+/**
+ * Gateway Client Interface
+ *
+ * Output port for the Commands.com Gateway HTTP API. Implementations handle
+ * authentication (OAuth demo/OIDC) and integration-route provisioning so the
+ * MessagingService can receive inbound webhooks from Telegram/WhatsApp.
+ *
+ * Reference: https://github.com/Commands-com/gateway/blob/main/docs/openapi.yaml
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/message-sender.interface.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Message Sender Interface
+ *
+ * Output port for delivering outbound messaging notifications to an end user
+ * (Telegram chat, WhatsApp conversation, etc.). Implementations make direct
+ * HTTPS calls to the respective platform APIs — the tunnel is for inbound
+ * webhook relay only, not for pushing notifications.
+ */
+import type { MessagingNotification } from '../../../../domain/generated/output.js';
+export interface IMessageSender {
+    /**
+     * Deliver a notification to the configured end user. Implementations
+     * should handle platform routing (telegram vs whatsapp) internally based
+     * on current settings, and silently no-op if no platform is paired.
+     */
+    send(notification: MessagingNotification): Promise<void>;
+}
+//# sourceMappingURL=message-sender.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/message-sender.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-sender.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/message-sender.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAEpF,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,CAAC,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D"}

package/dist/packages/core/src/application/ports/output/services/message-sender.interface.js

@@ -0,0 +1,9 @@
+/**
+ * Message Sender Interface
+ *
+ * Output port for delivering outbound messaging notifications to an end user
+ * (Telegram chat, WhatsApp conversation, etc.). Implementations make direct
+ * HTTPS calls to the respective platform APIs — the tunnel is for inbound
+ * webhook relay only, not for pushing notifications.
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/messaging-service.interface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Messaging Service Interface
+ *
+ * Output port for the external messaging remote control subsystem.
+ * Enables controlling Shep via Telegram/WhatsApp through the
+ * Commands.com Gateway tunnel.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementation (MessagingService)
+ */
+import type { MessagingNotification } from '../../../../domain/generated/output.js';
+/**
+ * Port interface for the messaging remote control service.
+ *
+ * Implementations must:
+ * - Connect to the Gateway via WebSocket tunnel
+ * - Handle inbound commands (parsed by Gateway) and map them to use cases
+ * - Push outbound notifications through the tunnel for delivery to messaging apps
+ * - Support interactive chat relay between messaging apps and agent sessions
+ */
+export interface IMessagingService {
+    /** Start listening for inbound commands from the Gateway tunnel */
+    start(): Promise<void>;
+    /** Stop the messaging service and disconnect from the tunnel */
+    stop(): Promise<void>;
+    /** Send a notification to the user's messaging app via the Gateway */
+    sendNotification(notification: MessagingNotification): Promise<void>;
+    /** Check if messaging is configured and connected */
+    isConnected(): boolean;
+    /** Check if messaging is configured (credentials present, even if not connected) */
+    isConfigured(): boolean;
+}
+//# sourceMappingURL=messaging-service.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/messaging-service.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-service.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/messaging-service.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,gEAAgE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB,sEAAsE;IACtE,gBAAgB,CAAC,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE,qDAAqD;IACrD,WAAW,IAAI,OAAO,CAAC;IAEvB,oFAAoF;IACpF,YAAY,IAAI,OAAO,CAAC;CACzB"}

package/dist/packages/core/src/application/ports/output/services/messaging-service.interface.js

@@ -0,0 +1,12 @@
+/**
+ * Messaging Service Interface
+ *
+ * Output port for the external messaging remote control subsystem.
+ * Enables controlling Shep via Telegram/WhatsApp through the
+ * Commands.com Gateway tunnel.
+ *
+ * Following Clean Architecture:
+ * - Application layer depends on this interface
+ * - Infrastructure layer provides concrete implementation (MessagingService)
+ */
+export {};

package/dist/packages/core/src/application/ports/output/services/telegram-client.interface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Telegram Bot API Client Interface
+ *
+ * Output port for making outbound calls to api.telegram.org. Used by the
+ * messaging service to reply to users after processing a webhook, and to
+ * push debounced notifications from the daemon.
+ */
+export interface SendTelegramMessageInput {
+    /** Bot token (e.g. `123456:ABCDEF-...`). */
+    botToken: string;
+    chatId: string;
+    text: string;
+    /** Optional parse mode (`Markdown`, `MarkdownV2`, `HTML`). */
+    parseMode?: 'Markdown' | 'MarkdownV2' | 'HTML';
+}
+export interface ITelegramClient {
+    sendMessage(input: SendTelegramMessageInput): Promise<void>;
+}
+//# sourceMappingURL=telegram-client.interface.d.ts.map

package/dist/packages/core/src/application/ports/output/services/telegram-client.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-client.interface.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/core/src/application/ports/output/services/telegram-client.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,SAAS,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D"}

package/dist/packages/core/src/application/ports/output/services/telegram-client.interface.js

@@ -0,0 +1,8 @@
+/**
+ * Telegram Bot API Client Interface
+ *
+ * Output port for making outbound calls to api.telegram.org. Used by the
+ * messaging service to reply to users after processing a webhook, and to
+ * push debounced notifications from the daemon.
+ */
+export {};

package/dist/packages/core/src/application/use-cases/messaging/begin-pairing.use-case.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Begin Messaging Pairing Use Case
+ *
+ * Initiates a pairing handshake for a messaging platform (Telegram/WhatsApp):
+ *
+ *   1. Validates the Gateway URL.
+ *   2. Fetches an OAuth access token from the Gateway (demo mode uses the
+ *      public client; OIDC mode would inject a real client secret).
+ *   3. Creates an integration route on the Gateway for the target platform.
+ *      The returned `publicUrl` is what the user must point their Telegram
+ *      webhook (or WhatsApp callback) at.
+ *   4. Generates a one-time 6-digit pairing code and persists it along with
+ *      the newly-allocated route details on settings.
+ *   5. Returns a session DTO for the presentation layer to render.
+ *
+ * The pairing is finalized when either:
+ *   - The daemon's tunnel receives a `/pair <code>` message via a
+ *     `tunnel.request` frame and calls ConfirmMessagingPairingUseCase (future
+ *     auto-confirm path), or
+ *   - The user clicks "Confirm pairing" in the UI / CLI after seeing the
+ *     code echoed by their bot (current manual path).
+ */
+import { MessagingPlatform } from '../../../domain/generated/output.js';
+import type { ISettingsRepository } from '../../ports/output/repositories/settings.repository.interface.js';
+import type { IGatewayClient } from '../../ports/output/services/gateway-client.interface.js';
+export interface BeginMessagingPairingInput {
+    platform: MessagingPlatform;
+    gatewayUrl: string;
+}
+export interface MessagingPairingSession {
+    platform: MessagingPlatform;
+    code: string;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    gatewayUrl: string;
+    /** Public webhook URL the platform should POST updates to. */
+    publicUrl: string;
+    routeId: string;
+}
+export declare class BeginMessagingPairingUseCase {
+    private readonly settingsRepository;
+    private readonly gatewayClient;
+    constructor(settingsRepository: ISettingsRepository, gatewayClient: IGatewayClient);
+    execute(input: BeginMessagingPairingInput): Promise<MessagingPairingSession>;
+}
+//# sourceMappingURL=begin-pairing.use-case.d.ts.map

package/dist/packages/core/src/application/use-cases/messaging/begin-pairing.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"begin-pairing.use-case.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/messaging/begin-pairing.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAC5G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AAK9F,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAwBD,qBACa,4BAA4B;IAGrC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAEnC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAFb,kBAAkB,EAAE,mBAAmB,EAEvC,aAAa,EAAE,cAAc;IAG1C,OAAO,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAkFnF"}

package/dist/packages/core/src/application/use-cases/messaging/begin-pairing.use-case.js

@@ -0,0 +1,148 @@
+/**
+ * Begin Messaging Pairing Use Case
+ *
+ * Initiates a pairing handshake for a messaging platform (Telegram/WhatsApp):
+ *
+ *   1. Validates the Gateway URL.
+ *   2. Fetches an OAuth access token from the Gateway (demo mode uses the
+ *      public client; OIDC mode would inject a real client secret).
+ *   3. Creates an integration route on the Gateway for the target platform.
+ *      The returned `publicUrl` is what the user must point their Telegram
+ *      webhook (or WhatsApp callback) at.
+ *   4. Generates a one-time 6-digit pairing code and persists it along with
+ *      the newly-allocated route details on settings.
+ *   5. Returns a session DTO for the presentation layer to render.
+ *
+ * The pairing is finalized when either:
+ *   - The daemon's tunnel receives a `/pair <code>` message via a
+ *     `tunnel.request` frame and calls ConfirmMessagingPairingUseCase (future
+ *     auto-confirm path), or
+ *   - The user clicks "Confirm pairing" in the UI / CLI after seeing the
+ *     code echoed by their bot (current manual path).
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'tsyringe';
+import { randomInt, randomUUID } from 'node:crypto';
+import { MessagingPlatform } from '../../../domain/generated/output.js';
+const PAIRING_CODE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_GATEWAY_CLIENT_ID = 'commands-desktop-public';
+function assertValidGatewayUrl(url) {
+    if (!url?.trim()) {
+        throw new Error('Gateway URL is required to begin pairing.');
+    }
+    try {
+        const parsed = new URL(url);
+        if (!parsed.protocol) {
+            throw new Error('invalid');
+        }
+    }
+    catch {
+        throw new Error('Gateway URL must be a valid URL (e.g., https://gateway.example.com).');
+    }
+}
+function generatePairingCode() {
+    return randomInt(0, 1_000_000).toString().padStart(6, '0');
+}
+function platformKey(platform) {
+    return platform === MessagingPlatform.Telegram ? 'telegram' : 'whatsapp';
+}
+let BeginMessagingPairingUseCase = class BeginMessagingPairingUseCase {
+    settingsRepository;
+    gatewayClient;
+    constructor(settingsRepository, gatewayClient) {
+        this.settingsRepository = settingsRepository;
+        this.gatewayClient = gatewayClient;
+    }
+    async execute(input) {
+        assertValidGatewayUrl(input.gatewayUrl);
+        const settings = await this.settingsRepository.load();
+        if (!settings) {
+            throw new Error('Settings not found. Please run initialization first.');
+        }
+        const existing = settings.messaging ?? {
+            enabled: false,
+            debounceMs: 5000,
+            chatBufferMs: 3000,
+        };
+        // Device ID is stable across platforms and across pairings. Generate
+        // lazily on first pairing so the gateway can scope all routes + the
+        // tunnel connection to the same device owner.
+        const deviceId = existing.deviceId ?? `shep-${randomUUID()}`;
+        const clientId = existing.gatewayClientId ?? DEFAULT_GATEWAY_CLIENT_ID;
+        const key = platformKey(input.platform);
+        // 1. Fetch OAuth access token from the gateway.
+        let accessToken;
+        try {
+            const token = await this.gatewayClient.fetchAccessToken({
+                gatewayUrl: input.gatewayUrl,
+                clientId,
+            });
+            accessToken = token.accessToken;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Gateway authentication failed: ${msg}`);
+        }
+        // 2. Create an integration route for this platform.
+        let route;
+        try {
+            route = await this.gatewayClient.createIntegrationRoute(input.gatewayUrl, accessToken, {
+                deviceId,
+                interfaceType: key,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Gateway route registration failed: ${msg}`);
+        }
+        // 3. Generate pairing code + persist everything.
+        const code = generatePairingCode();
+        const expiresAt = new Date(Date.now() + PAIRING_CODE_TTL_MS).toISOString();
+        const existingPlatform = existing[key] ?? { enabled: false, paired: false };
+        settings.messaging = {
+            ...existing,
+            enabled: true,
+            gatewayUrl: input.gatewayUrl,
+            deviceId,
+            gatewayClientId: clientId,
+            [key]: {
+                ...existingPlatform,
+                enabled: true,
+                paired: false,
+                pendingPairingCode: code,
+                pendingPairingExpiresAt: expiresAt,
+                routeId: route.routeId,
+                routeToken: route.routeToken,
+                publicUrl: route.publicUrl,
+            },
+        };
+        settings.updatedAt = new Date();
+        await this.settingsRepository.update(settings);
+        return {
+            platform: input.platform,
+            code,
+            expiresAt,
+            gatewayUrl: input.gatewayUrl,
+            publicUrl: route.publicUrl,
+            routeId: route.routeId,
+        };
+    }
+};
+BeginMessagingPairingUseCase = __decorate([
+    injectable(),
+    __param(0, inject('ISettingsRepository')),
+    __param(1, inject('IGatewayClient')),
+    __metadata("design:paramtypes", [Object, Object])
+], BeginMessagingPairingUseCase);
+export { BeginMessagingPairingUseCase };

package/dist/packages/core/src/application/use-cases/messaging/confirm-pairing.use-case.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Confirm Messaging Pairing Use Case
+ *
+ * Finalizes a pairing handshake started by BeginMessagingPairingUseCase.
+ * Marks the platform as paired, stores the chatId, and clears the pending
+ * pairing code.
+ */
+import { MessagingPlatform, type Settings } from '../../../domain/generated/output.js';
+import type { ISettingsRepository } from '../../ports/output/repositories/settings.repository.interface.js';
+export interface ConfirmMessagingPairingInput {
+    platform: MessagingPlatform;
+    chatId: string;
+}
+export declare class ConfirmMessagingPairingUseCase {
+    private readonly settingsRepository;
+    constructor(settingsRepository: ISettingsRepository);
+    execute(input: ConfirmMessagingPairingInput): Promise<Settings>;
+}
+//# sourceMappingURL=confirm-pairing.use-case.d.ts.map

package/dist/packages/core/src/application/use-cases/messaging/confirm-pairing.use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-pairing.use-case.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/application/use-cases/messaging/confirm-pairing.use-case.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AAE5G,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBACa,8BAA8B;IAGvC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAAlB,kBAAkB,EAAE,mBAAmB;IAGpD,OAAO,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,QAAQ,CAAC;CAqCtE"}