@messenger-box/platform-server 10.0.3-alpha.240 → 10.0.3-alpha.241

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@messenger-box/platform-server",
-    "version": "10.0.3-alpha.240",
+    "version": "10.0.3-alpha.241",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -70,7 +70,7 @@
             ]
         }
     },
-    "gitHead": "a05986428ed51c02e72eb2682fed7c40bc0558f9",
+    "gitHead": "54b4b576d7ae2c330a4acf7847c9758d8f9067d5",
     "typescript": {
         "definition": "lib/index.d.ts"
     }

package/lib/gateway/channel-registry.d.ts

@@ -1,10 +0,0 @@
-import type { IExternalChannelProvider, IExternalChannelRegistry, IChannelProviderConfig } from './types';
-export declare class ExternalChannelRegistry implements IExternalChannelRegistry {
-    private providers;
-    register(provider: IExternalChannelProvider): void;
-    unregister(providerType: string): void;
-    get(providerType: string): IExternalChannelProvider | undefined;
-    listTypes(): string[];
-    listProviders(): IChannelProviderConfig[];
-    has(providerType: string): boolean;
-}

package/lib/gateway/gateway-service.d.ts

@@ -1,23 +0,0 @@
-import type { CdmLogger } from '@cdm-logger/core';
-import type { IGatewayService, IExternalChannelRegistry, IMessageRouterService, IInboundMessage, IOutboundMessage, ISendResult, IGatewayChannelStatus } from './types';
-type InboundHandler = (message: IInboundMessage) => void;
-export declare class GatewayService implements IGatewayService {
-    private logger;
-    private registry;
-    private router;
-    private inboundHandlers;
-    private initialized;
-    constructor(registry: IExternalChannelRegistry, router: IMessageRouterService, logger?: CdmLogger.ILogger);
-    initialize(): Promise<void>;
-    shutdown(): Promise<void>;
-    getRegistry(): IExternalChannelRegistry;
-    connectChannel(channelType: string, accountId: string, options: Record<string, unknown>): Promise<void>;
-    disconnectChannel(channelType: string, accountId: string): Promise<void>;
-    sendMessage(message: IOutboundMessage): Promise<ISendResult>;
-    getStatus(): IGatewayChannelStatus[];
-    getChannelStatus(channelType: string): IGatewayChannelStatus[];
-    onInboundMessage(handler: InboundHandler): void;
-    /** Forward inbound message to all registered handlers and the router */
-    private handleInbound;
-}
-export {};

package/lib/gateway/index.d.ts

@@ -1,4 +0,0 @@
-export * from './types';
-export { ExternalChannelRegistry } from './channel-registry';
-export { MessageRouterService } from './message-router';
-export { GatewayService } from './gateway-service';

package/lib/gateway/message-router.d.ts

@@ -1,20 +0,0 @@
-import type { CdmLogger } from '@cdm-logger/core';
-import type { IInboundMessage, IOutboundMessage, ISendResult, IMessageRouterService, IExternalChannelRegistry } from './types';
-export declare class MessageRouterService implements IMessageRouterService {
-    private logger;
-    private registry;
-    constructor(registry: IExternalChannelRegistry, logger?: CdmLogger.ILogger);
-    /**
-     * Route an inbound message from an external channel provider to the platform.
-     *
-     * This is where external messages get translated into platform Posts.
-     * In Go: similar to picoclaw's `pkg/channels/handler.go` HandleInbound.
-     */
-    routeInbound(message: IInboundMessage): Promise<void>;
-    /**
-     * Route an outbound message from the platform to the correct external channel provider.
-     *
-     * Looks up the provider by channelType in the registry and delegates the send.
-     */
-    routeOutbound(message: IOutboundMessage): Promise<ISendResult>;
-}

package/lib/gateway/types.d.ts

@@ -1,280 +0,0 @@
-/**
- * Gateway Types — External messaging channel provider interfaces.
- *
- * Designed Go-portable: no Inversify decorators, no Mongoose, no Moleculer.
- * Every interface maps 1:1 to a Go interface. Uses plain constructors,
- * explicit error returns, and typed queues (via EventEmitter or NATS topics).
- *
- * Architecture mapping:
- *   openclaw  → ChannelProvider / ChannelAccountManager → this file
- *   picoclaw  → pkg/channels/channel.go                → this file
- *   clockbook → BOT_TYPES.IChannelRegistry              → this file
- *
- * Channel extensions register providers via `contributes.channels` in their
- * package.json and call `channels.registerProvider()` during activation.
- */
-import type { IChannelCapabilities, IChannelDock, IChannelAccountSnapshot, IChannelStatusIssue } from '../channels/types';
-/** Provider lifecycle state */
-export type ProviderState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
-/** Direction of a message relative to the gateway */
-export type MessageDirection = 'inbound' | 'outbound';
-/** Media attachment type */
-export type MediaType = 'image' | 'audio' | 'video' | 'document' | 'sticker' | 'location' | 'contact';
-export interface IMediaAttachment {
-    type: MediaType;
-    url?: string;
-    /** Raw bytes (base64 in JSON, []byte in Go) */
-    data?: string;
-    mimeType?: string;
-    filename?: string;
-    caption?: string;
-    /** Duration in seconds (audio/video) */
-    durationSec?: number;
-    /** Thumbnail URL or base64 */
-    thumbnail?: string;
-}
-/** An inbound message from an external channel into the gateway */
-export interface IInboundMessage {
-    /** Unique message ID from the external platform */
-    externalId: string;
-    /** Channel provider identifier (e.g. 'whatsapp', 'telegram') */
-    channelType: string;
-    /** Account ID within the channel provider */
-    accountId: string;
-    /** Sender identifier on the external platform */
-    senderId: string;
-    /** Sender display name */
-    senderName?: string;
-    /** Chat/conversation identifier on the external platform */
-    chatId: string;
-    /** Chat type */
-    chatType?: 'direct' | 'group' | 'channel';
-    /** Text content */
-    text?: string;
-    /** Media attachments */
-    media?: IMediaAttachment[];
-    /** Whether this is a reply to another message */
-    replyToExternalId?: string;
-    /** Unix timestamp in ms */
-    timestamp: number;
-    /** Raw payload from the external platform (for debugging/passthrough) */
-    raw?: Record<string, unknown>;
-}
-/** An outbound message from the gateway to an external channel */
-export interface IOutboundMessage {
-    /** Channel provider identifier */
-    channelType: string;
-    /** Account ID within the channel provider */
-    accountId: string;
-    /** Target chat/conversation identifier */
-    chatId: string;
-    /** Text content */
-    text?: string;
-    /** Media attachments */
-    media?: IMediaAttachment[];
-    /** Reply to a specific external message ID */
-    replyToExternalId?: string;
-    /** Arbitrary metadata */
-    metadata?: Record<string, unknown>;
-}
-/** Result of sending an outbound message */
-export interface ISendResult {
-    success: boolean;
-    /** External message ID assigned by the platform */
-    externalId?: string;
-    /** Error message if failed */
-    error?: string;
-    /** Timestamp of delivery (Unix ms) */
-    timestamp?: number;
-}
-/** Who is responsible for persisting chat messages to the DB. */
-export type PersistenceMode = 'backend' | 'frontend';
-/** Configuration schema for a channel provider (declared in contributes.channels) */
-export interface IChannelProviderConfig {
-    /** Unique provider type identifier (e.g. 'whatsapp', 'telegram') */
-    type: string;
-    /** Human-readable label */
-    label: string;
-    /** Provider description */
-    description?: string;
-    /** Icon name or URL */
-    icon?: string;
-    /** Provider capabilities */
-    capabilities: IChannelCapabilities;
-    /** Dock (outbound constraints, streaming, threading config) */
-    dock?: Partial<IChannelDock>;
-    /** JSON Schema for provider-specific configuration (API keys, tokens, etc.) */
-    configSchema?: Record<string, unknown>;
-    /**
-     * Who persists chat messages.
-     * - `'backend'`  — the gateway streaming pipeline saves messages; UI should skip auto-save.
-     * - `'frontend'` — the UI saves messages via sendMessagesMutation (default).
-     */
-    persistenceMode?: PersistenceMode;
-}
-/**
- * IExternalChannelProvider — the interface that channel extensions implement.
- *
- * Each extension contributes one provider. The gateway discovers providers
- * via `contributes.channels` in the extension manifest and calls
- * `channels.registerProvider(provider)` during extension activation.
- *
- * Go mapping:
- *   type ChannelProvider interface {
- *       Type() string
- *       Connect(ctx context.Context, accountId string, config map[string]any) error
- *       Disconnect(ctx context.Context, accountId string) error
- *       Send(ctx context.Context, msg OutboundMessage) (SendResult, error)
- *       State(accountId string) ProviderState
- *       OnMessage(handler func(InboundMessage))
- *   }
- */
-export interface IExternalChannelProvider {
-    /** Provider type identifier (e.g. 'whatsapp') */
-    readonly type: string;
-    /** Provider configuration */
-    readonly config: IChannelProviderConfig;
-    /**
-     * Connect an account to the external platform.
-     * @param accountId - Unique account identifier
-     * @param options - Provider-specific connection options (API keys, session data, etc.)
-     * @param signal - AbortSignal for cancellation (Go: context.Context)
-     */
-    connect(accountId: string, options: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
-    /**
-     * Disconnect an account from the external platform.
-     * @param accountId - Account to disconnect
-     */
-    disconnect(accountId: string): Promise<void>;
-    /**
-     * Send a message to the external platform.
-     * @param message - Outbound message to send
-     * @returns Send result with external ID on success
-     */
-    send(message: IOutboundMessage): Promise<ISendResult>;
-    /**
-     * Get the current connection state for an account.
-     * @param accountId - Account identifier
-     */
-    getState(accountId: string): ProviderState;
-    /**
-     * Get a snapshot of account status (connection info, last message times, etc.)
-     * @param accountId - Account identifier
-     */
-    getAccountSnapshot(accountId: string): IChannelAccountSnapshot | undefined;
-    /**
-     * Get any status issues (config problems, auth failures, etc.)
-     * @param accountId - Account identifier
-     */
-    getStatusIssues(accountId: string): IChannelStatusIssue[];
-    /**
-     * Register a handler for inbound messages.
-     * The gateway calls this once during provider registration.
-     * @param handler - Callback invoked for each inbound message
-     */
-    onMessage(handler: (message: IInboundMessage) => void): void;
-    /**
-     * Register a handler for provider state changes.
-     * @param handler - Callback invoked when connection state changes
-     */
-    onStateChange?(handler: (accountId: string, state: ProviderState) => void): void;
-    /**
-     * Dispose all resources. Called when the extension is deactivated.
-     */
-    dispose(): Promise<void>;
-}
-/**
- * IExternalChannelRegistry — tracks all registered external channel providers.
- *
- * Providers register themselves via extension activation; the gateway looks
- * them up by type when routing messages.
- *
- * Go mapping:
- *   type ChannelRegistry struct { providers map[string]ChannelProvider }
- */
-export interface IExternalChannelRegistry {
-    /** Register a channel provider (called during extension activation) */
-    register(provider: IExternalChannelProvider): void;
-    /** Unregister a channel provider (called during extension deactivation) */
-    unregister(providerType: string): void;
-    /** Get a provider by type */
-    get(providerType: string): IExternalChannelProvider | undefined;
-    /** List all registered provider types */
-    listTypes(): string[];
-    /** List all providers with their configs */
-    listProviders(): IChannelProviderConfig[];
-    /** Check if a provider type is registered */
-    has(providerType: string): boolean;
-}
-/** Gateway status for a single provider/account pair */
-export interface IGatewayChannelStatus {
-    channelType: string;
-    accountId: string;
-    state: ProviderState;
-    label: string;
-    snapshot?: IChannelAccountSnapshot;
-    issues: IChannelStatusIssue[];
-    /** Who persists chat messages — 'backend' or 'frontend' (default). */
-    persistenceMode?: PersistenceMode;
-}
-/**
- * IGatewayService — the top-level gateway orchestrator.
- *
- * Owns the channel registry, routes inbound messages to the platform,
- * and dispatches outbound messages to the correct provider.
- *
- * Go mapping:
- *   type GatewayService struct {
- *       registry  *ChannelRegistry
- *       router    *MessageRouter
- *       eventBus  *nats.Conn
- *   }
- */
-export interface IGatewayService {
-    /** Initialize the gateway (called once at startup) */
-    initialize(): Promise<void>;
-    /** Shut down the gateway gracefully */
-    shutdown(): Promise<void>;
-    /** Get the channel registry */
-    getRegistry(): IExternalChannelRegistry;
-    /** Connect an account on a specific channel */
-    connectChannel(channelType: string, accountId: string, options: Record<string, unknown>): Promise<void>;
-    /** Disconnect an account on a specific channel */
-    disconnectChannel(channelType: string, accountId: string): Promise<void>;
-    /** Send an outbound message via the appropriate provider */
-    sendMessage(message: IOutboundMessage): Promise<ISendResult>;
-    /** Get status for all connected channels/accounts */
-    getStatus(): IGatewayChannelStatus[];
-    /** Get status for a specific channel type */
-    getChannelStatus(channelType: string): IGatewayChannelStatus[];
-    /**
-     * Register a handler for inbound messages (gateway → platform).
-     * The resolver/microservice uses this to feed messages into the platform.
-     */
-    onInboundMessage(handler: (message: IInboundMessage) => void): void;
-}
-/**
- * IMessageRouterService — routes inbound messages to the messenger platform.
- *
- * Sits between external channel providers and the platform's channel/post
- * services. Translates IInboundMessage into platform Post creation.
- *
- * Go mapping:
- *   type MessageRouter struct { channelSvc ChannelService; postSvc PostService }
- */
-export interface IMessageRouterService {
-    /** Route an inbound message to the platform */
-    routeInbound(message: IInboundMessage): Promise<void>;
-    /** Route an outbound message from the platform to the external channel */
-    routeOutbound(message: IOutboundMessage): Promise<ISendResult>;
-}
-/** Topic for gateway inbound messages */
-export declare const GATEWAY_INBOUND_TOPIC = "GATEWAY_INBOUND";
-/** Topic for gateway outbound messages */
-export declare const GATEWAY_OUTBOUND_TOPIC = "GATEWAY_OUTBOUND";
-/** Topic for gateway channel status changes */
-export declare const GATEWAY_STATUS_TOPIC = "GATEWAY_STATUS";
-/** Build a scoped topic for a specific channel type */
-export declare function gatewayInboundTopic(channelType: string): string;
-export declare function gatewayOutboundTopic(channelType: string): string;
-export declare function gatewayStatusTopic(channelType: string): string;