@nextclaw/extension-sdk 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 import { ChannelConfigGetRequest, ChannelConfigGetResponse, ChannelFileContent, ChannelImageContent, ChannelMessageContent, ChannelSubmittedAttachment, ChannelSubmittedMessage, ChannelTextContent, ExtensionCapabilities, ExtensionCapabilityHandler, ExtensionCapabilityPayload, ExtensionChannel, ExtensionChannelConfig, ExtensionChannels, ExtensionRequest, ExtensionRequestHandler, ExtensionRequestResponse, ExtensionTransportEnvelope, NextClawExtensionOptions, NextClawExtensionWebSocketLike } from "./types/extension-sdk.types.js";
 import { NextClawExtension } from "./services/extension-client.service.js";
-export { type ChannelConfigGetRequest, type ChannelConfigGetResponse, type ChannelFileContent, type ChannelImageContent, type ChannelMessageContent, type ChannelSubmittedAttachment, type ChannelSubmittedMessage, type ChannelTextContent, type ExtensionCapabilities, type ExtensionCapabilityHandler, type ExtensionCapabilityPayload, type ExtensionChannel, type ExtensionChannelConfig, type ExtensionChannels, type ExtensionRequest, type ExtensionRequestHandler, type ExtensionRequestResponse, type ExtensionTransportEnvelope, NextClawExtension, type NextClawExtensionOptions, type NextClawExtensionWebSocketLike };
+import { BusChannelCreateContext, BusChannelExtensionDefinition, BusChannelInboundMessage, BusChannelMessageBus, BusChannelRuntime, ChannelExtensionContext, ChannelExtensionDefinition, ChannelSubmittedMessageInput, ExtensionChannelAdapter, ExtensionChannelController, startBusChannelExtension, startChannelExtension, warnNcpEventError } from "./services/extension-channel-controller.service.js";
+export { type BusChannelCreateContext, type BusChannelExtensionDefinition, type BusChannelInboundMessage, type BusChannelMessageBus, type BusChannelRuntime, type ChannelConfigGetRequest, type ChannelConfigGetResponse, type ChannelExtensionContext, type ChannelExtensionDefinition, type ChannelFileContent, type ChannelImageContent, type ChannelMessageContent, type ChannelSubmittedAttachment, type ChannelSubmittedMessage, type ChannelSubmittedMessageInput, type ChannelTextContent, type ExtensionCapabilities, type ExtensionCapabilityHandler, type ExtensionCapabilityPayload, type ExtensionChannel, type ExtensionChannelAdapter, type ExtensionChannelConfig, ExtensionChannelController, type ExtensionChannels, type ExtensionRequest, type ExtensionRequestHandler, type ExtensionRequestResponse, type ExtensionTransportEnvelope, NextClawExtension, type NextClawExtensionOptions, type NextClawExtensionWebSocketLike, startBusChannelExtension, startChannelExtension, warnNcpEventError };

package/dist/index.js

@@ -1,2 +1,3 @@
 import { NextClawExtension } from "./services/extension-client.service.js";
-export { NextClawExtension };
+import { ExtensionChannelController, startBusChannelExtension, startChannelExtension, warnNcpEventError } from "./services/extension-channel-controller.service.js";
+export { ExtensionChannelController, NextClawExtension, startBusChannelExtension, startChannelExtension, warnNcpEventError };

package/dist/services/extension-channel-controller.service.d.ts

@@ -0,0 +1,97 @@
+import { ChannelSubmittedAttachment, ChannelSubmittedMessage, ExtensionChannel, NextClawExtensionOptions } from "../types/extension-sdk.types.js";
+import { NcpEndpointEvent } from "@nextclaw/ncp";
+
+//#region src/services/extension-channel-controller.service.d.ts
+type ExtensionChannelAdapter<TConfig, TInbound> = {
+  configure: (config: TConfig) => Promise<void>;
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  onMessage: (handler: (message: TInbound) => void | Promise<void>) => () => void;
+  sendNcpEvent: (event: NcpEndpointEvent) => Promise<void>;
+  sendOutboundText: (params: {
+    to: string;
+    text: string;
+    accountId?: string | null;
+    replyTo?: string | null;
+    media?: string[];
+    metadata?: Record<string, unknown>;
+  }) => Promise<void>;
+};
+type ChannelSubmittedMessageInput = Omit<ChannelSubmittedMessage, "channelId">;
+type BusChannelInboundMessage = {
+  channel: string;
+  senderId: string;
+  chatId: string;
+  content: string;
+  attachments?: ChannelSubmittedAttachment[];
+  metadata?: Record<string, unknown>;
+};
+type BusChannelMessageBus = {
+  publishInbound: (message: BusChannelInboundMessage) => Promise<void>;
+};
+type BusChannelRuntime = {
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  send: (message: {
+    channel: string;
+    chatId: string;
+    content: string;
+    replyTo?: string | null;
+    media: string[];
+    metadata: Record<string, unknown>;
+  }) => Promise<void>;
+};
+type BusChannelCreateContext<TConfig, TBus = BusChannelMessageBus> = {
+  config: TConfig;
+  bus: TBus;
+};
+type BusChannelExtensionDefinition<TConfig, TBus = BusChannelMessageBus> = {
+  channelId: string;
+  createChannel: (context: BusChannelCreateContext<TConfig, TBus>) => BusChannelRuntime;
+  mapInbound?: ExtensionChannelInboundMapper<BusChannelInboundMessage>;
+  onChannelStartError?: (error: unknown) => void | Promise<void>;
+};
+type ExtensionChannelInboundMapper<TInbound> = (message: TInbound) => ChannelSubmittedMessageInput | Promise<ChannelSubmittedMessageInput>;
+type ExtensionChannelControllerOptions<TConfig, TInbound> = {
+  channel: ExtensionChannel;
+  adapter: ExtensionChannelAdapter<TConfig, TInbound>;
+  mapInbound: ExtensionChannelInboundMapper<TInbound>;
+  onNcpEventError?: (error: unknown, event: NcpEndpointEvent) => void | Promise<void>;
+};
+type ChannelExtensionContext = {
+  channel: ExtensionChannel;
+};
+type ChannelExtensionDefinition<TConfig, TInbound> = {
+  channelId: string;
+  createAdapter: () => ExtensionChannelAdapter<TConfig, TInbound>;
+  mapInbound: ExtensionChannelInboundMapper<TInbound>;
+  createAuthCapability?: (context: ChannelExtensionContext) => object;
+  onNcpEventError?: (error: unknown, event: NcpEndpointEvent) => void | Promise<void>;
+};
+declare class ExtensionChannelController<TConfig, TInbound> {
+  private readonly options;
+  private readonly cleanups;
+  private started;
+  constructor(options: ExtensionChannelControllerOptions<TConfig, TInbound>);
+  start: () => Promise<void>;
+  stop: () => Promise<void>;
+  sendOutboundText: (params: {
+    to: string;
+    text: string;
+    accountId?: string | null;
+    replyTo?: string | null;
+    media?: string[];
+    metadata?: Record<string, unknown>;
+  }) => Promise<{
+    accepted: true;
+  }>;
+  private applyConfig;
+  private submitMessage;
+  private sendNcpEvent;
+  private drainCleanups;
+}
+declare function startChannelExtension<TConfig, TInbound>(definition: ChannelExtensionDefinition<TConfig, TInbound>, options?: NextClawExtensionOptions): Promise<void>;
+declare function startBusChannelExtension<TConfig, TBus = BusChannelMessageBus>(definition: BusChannelExtensionDefinition<TConfig, TBus>, options?: NextClawExtensionOptions): Promise<void>;
+declare function warnNcpEventError(channelId: string): (error: unknown) => void;
+//#endregion
+export { BusChannelCreateContext, BusChannelExtensionDefinition, BusChannelInboundMessage, BusChannelMessageBus, BusChannelRuntime, ChannelExtensionContext, ChannelExtensionDefinition, ChannelSubmittedMessageInput, ExtensionChannelAdapter, ExtensionChannelController, startBusChannelExtension, startChannelExtension, warnNcpEventError };

package/dist/services/extension-channel-controller.service.js

@@ -0,0 +1,212 @@
+import { NextClawExtension } from "./extension-client.service.js";
+import { NcpEventType } from "@nextclaw/ncp";
+//#region src/services/extension-channel-controller.service.ts
+function readRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+const AGENT_ROUTE_KINDS = new Set([
+	"direct",
+	"group",
+	"channel",
+	"thread"
+]);
+function parseSessionDeliveryRoute(sessionId) {
+	const parts = sessionId.trim().split(":");
+	if (parts[0] !== "agent" || parts.length < 5) return {};
+	const hasAccount = !AGENT_ROUTE_KINDS.has(parts[3]);
+	const kind = parts[hasAccount ? 4 : 3];
+	if (!AGENT_ROUTE_KINDS.has(kind ?? "")) return {};
+	return {
+		channel: parts[2],
+		...hasAccount ? { accountId: parts[3] } : {},
+		chatId: parts.slice(hasAccount ? 5 : 4).join(":")
+	};
+}
+function readString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function renderMessageText(parts) {
+	return parts.map((part) => (part.type === "text" || part.type === "rich-text") && part.text ? part.text : "").filter(Boolean).join("\n\n");
+}
+function defaultChannelEnabled(config) {
+	return !(config && typeof config === "object" && !Array.isArray(config) && config.enabled === false);
+}
+var ExtensionChannelController = class {
+	cleanups = [];
+	started = false;
+	constructor(options) {
+		this.options = options;
+	}
+	start = async () => {
+		if (this.started) return;
+		this.started = true;
+		this.cleanups.push(this.options.adapter.onMessage(this.submitMessage));
+		this.cleanups.push(this.options.channel.onNcpEvent(this.sendNcpEvent));
+		this.cleanups.push(this.options.channel.config.onChange(async () => {
+			await this.applyConfig();
+		}));
+		await this.applyConfig();
+	};
+	stop = async () => {
+		if (!this.started) return;
+		this.started = false;
+		this.drainCleanups();
+		await this.options.adapter.stop();
+	};
+	sendOutboundText = async (params) => {
+		await this.options.adapter.sendOutboundText(params);
+		return { accepted: true };
+	};
+	applyConfig = async () => {
+		const config = await this.options.channel.config.get();
+		await this.options.adapter.configure(config);
+		if (defaultChannelEnabled(config) === false) {
+			await this.options.adapter.stop();
+			return;
+		}
+		await this.options.adapter.start();
+	};
+	submitMessage = async (message) => {
+		await this.options.channel.submitMessage(await this.options.mapInbound(message));
+	};
+	sendNcpEvent = async (event) => {
+		try {
+			await this.options.adapter.sendNcpEvent(event);
+		} catch (error) {
+			await this.options.onNcpEventError?.(error, event);
+		}
+	};
+	drainCleanups = () => {
+		for (const cleanup of this.cleanups.splice(0).reverse()) cleanup();
+	};
+};
+var BusChannelAdapter = class {
+	channel = null;
+	messageHandler = null;
+	constructor(definition) {
+		this.definition = definition;
+	}
+	configure = async (config) => {
+		await this.stop();
+		this.channel = this.definition.createChannel({
+			config,
+			bus: { publishInbound: async (message) => {
+				await this.messageHandler?.(message);
+			} }
+		});
+	};
+	start = async () => {
+		const channel = this.channel;
+		if (!channel) return;
+		channel.start().catch(async (error) => {
+			await this.definition.onChannelStartError?.(error);
+		});
+	};
+	stop = async () => {
+		const channel = this.channel;
+		this.channel = null;
+		await channel?.stop();
+	};
+	onMessage = (handler) => {
+		this.messageHandler = handler;
+		return () => {
+			if (this.messageHandler === handler) this.messageHandler = null;
+		};
+	};
+	sendNcpEvent = async (event) => {
+		if (event.type !== NcpEventType.MessageCompleted) return;
+		const metadata = readRecord(event.payload.message.metadata);
+		const sessionRoute = parseSessionDeliveryRoute(event.payload.message.sessionId);
+		if ((readString(metadata.channel) ?? readString(metadata.channelId) ?? sessionRoute.channel) !== this.definition.channelId) return;
+		const chatId = readString(metadata.chatId) ?? readString(metadata.chat_id) ?? sessionRoute.chatId;
+		const content = renderMessageText(event.payload.message.parts).trim();
+		if (!chatId || !content) return;
+		const replyTo = readString(metadata.message_id);
+		await this.channel?.send({
+			channel: this.definition.channelId,
+			chatId,
+			content,
+			...replyTo ? { replyTo } : {},
+			media: [],
+			metadata: {
+				...metadata,
+				...sessionRoute.accountId && !metadata.accountId ? { accountId: sessionRoute.accountId } : {}
+			}
+		});
+	};
+	sendOutboundText = async (params) => {
+		const { accountId, media, metadata, replyTo, text, to } = params;
+		await this.channel?.send({
+			channel: this.definition.channelId,
+			chatId: to,
+			content: text,
+			...replyTo !== void 0 ? { replyTo } : {},
+			media: media ?? [],
+			metadata: {
+				...metadata ?? {},
+				...accountId ? { accountId } : {}
+			}
+		});
+	};
+};
+async function startChannelExtension(definition, options = {}) {
+	const extension = new NextClawExtension(options);
+	const channel = extension.channels.use(definition.channelId);
+	const controller = new ExtensionChannelController({
+		channel,
+		adapter: definition.createAdapter(),
+		mapInbound: definition.mapInbound,
+		onNcpEventError: definition.onNcpEventError
+	});
+	if (definition.createAuthCapability) extension.capabilities.provide("channel.auth", definition.createAuthCapability({ channel }));
+	extension.capabilities.provideHandler("channel.outbound.sendText", async (payload) => await controller.sendOutboundText({
+		to: readRequiredPayloadString(payload.to, "to"),
+		text: readRequiredPayloadString(payload.text, "text"),
+		accountId: readOptionalPayloadString(payload.accountId),
+		replyTo: readOptionalPayloadString(payload.replyTo),
+		media: readStringArray(payload.media),
+		metadata: readOptionalRecord(payload.metadata)
+	}));
+	await controller.start();
+}
+async function startBusChannelExtension(definition, options = {}) {
+	await startChannelExtension({
+		channelId: definition.channelId,
+		createAdapter: () => new BusChannelAdapter(definition),
+		mapInbound: definition.mapInbound ?? toSubmittedTextMessage
+	}, options);
+}
+function warnNcpEventError(channelId) {
+	return (error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`[${channelId}] failed to send NCP event: ${message}`);
+	};
+}
+function readRequiredPayloadString(value, name) {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`);
+	return value.trim();
+}
+function readOptionalPayloadString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function readStringArray(value) {
+	if (!Array.isArray(value)) return;
+	return value.filter((item) => typeof item === "string");
+}
+function readOptionalRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function toSubmittedTextMessage(message) {
+	return {
+		conversationId: message.chatId,
+		senderId: message.senderId,
+		content: {
+			type: "text",
+			text: message.content
+		},
+		...message.attachments ? { attachments: message.attachments } : {},
+		...message.metadata ? { metadata: message.metadata } : {}
+	};
+}
+//#endregion
+export { ExtensionChannelController, startBusChannelExtension, startChannelExtension, warnNcpEventError };

package/dist/services/extension-channel.service.js

@@ -1,13 +1,11 @@
-import { eventKeys, getKeyId } from "@nextclaw/shared";
+import { eventKeys, getKeyId, ingressKeys } from "@nextclaw/shared";
 //#region src/services/extension-channel.service.ts
-const CONFIG_GET_EVENT_TYPE = "extension.channel.config.get";
-const MESSAGE_SUBMIT_EVENT_TYPE = "extension.channel.message.submit";
 var ChannelConfig = class {
 	constructor(params) {
 		this.params = params;
 	}
 	get = async () => {
-		return (await this.params.transport.postIngress(CONFIG_GET_EVENT_TYPE, { channelId: this.params.channelId })).config;
+		return (await this.params.transport.postIngress(getKeyId(ingressKeys.extension.channelConfigGet), { channelId: this.params.channelId })).config;
 	};
 	onChange = (handler) => this.params.eventBus.subscribeAll((event) => {
 		if (event.type !== getKeyId(eventKeys.configUpdated)) return;
@@ -25,7 +23,7 @@ var ExtensionChannelService = class {
 		this.config = new ChannelConfig(params);
 	}
 	submitMessage = async (input) => {
-		await this.params.transport.postIngress(MESSAGE_SUBMIT_EVENT_TYPE, {
+		await this.params.transport.postIngress(getKeyId(ingressKeys.extension.channelMessageSubmit), {
 			...input,
 			channelId: this.id
 		});

package/dist/services/extension-transport.service.js

@@ -1,4 +1,5 @@
 import { normalizeEndpoint, resolveWebSocketUrl } from "../utils/extension-url.utils.js";
+import { getKeyId, ingressKeys } from "@nextclaw/shared";
 //#region src/services/extension-transport.service.ts
 function readRuntimeEnv() {
 	return typeof process === "undefined" ? {} : process.env;
@@ -44,7 +45,7 @@ var ExtensionTransportService = class {
 		return this.readResponseData(body);
 	};
 	respondToRequest = async (response) => {
-		await this.postIngress("extension.response", response);
+		await this.postIngress(getKeyId(ingressKeys.extension.response), response);
 	};
 	subscribe = (handler) => {
 		const socket = this.createSocket(resolveWebSocketUrl(this.endpoint, "/ws"));

package/dist/types/extension-sdk.types.d.ts

@@ -1,4 +1,4 @@
-import { Unsubscribe } from "@nextclaw/shared";
+import { ExtensionChannelConfigGetIngressPayload as ChannelConfigGetRequest, ExtensionChannelFileContent as ChannelFileContent, ExtensionChannelImageContent as ChannelImageContent, ExtensionChannelMessageContent as ChannelMessageContent, ExtensionChannelMessageSubmitIngressPayload, ExtensionChannelMessageSubmitIngressPayload as ChannelSubmittedMessage, ExtensionChannelSubmittedAttachment as ChannelSubmittedAttachment, ExtensionChannelTextContent as ChannelTextContent, ExtensionResponseIngressPayload as ExtensionRequestResponse, Unsubscribe } from "@nextclaw/shared";
 import { NcpEndpointEvent } from "@nextclaw/ncp";
 
 //#region src/types/extension-sdk.types.d.ts
@@ -31,59 +31,6 @@ type ExtensionRequest = {
   kind: string;
   payload?: Record<string, unknown>;
 };
-type ExtensionRequestResponse = {
-  requestId: string;
-  ok: true;
-  data?: unknown;
-} | {
-  requestId: string;
-  ok: false;
-  error: {
-    message: string;
-  };
-};
-type ChannelTextContent = {
-  type: "text";
-  text: string;
-};
-type ChannelImageContent = {
-  type: "image";
-  url?: string;
-  assetUri?: string;
-  mimeType?: string;
-  name?: string;
-};
-type ChannelFileContent = {
-  type: "file";
-  url?: string;
-  assetUri?: string;
-  mimeType?: string;
-  name?: string;
-};
-type ChannelMessageContent = ChannelTextContent | ChannelImageContent | ChannelFileContent;
-type ChannelSubmittedAttachment = {
-  id?: string;
-  name?: string;
-  path?: string;
-  url?: string;
-  assetUri?: string;
-  mimeType?: string;
-  size?: number;
-  source?: string;
-  status?: "ready" | "remote-only";
-  errorCode?: "too_large" | "download_failed" | "http_error" | "invalid_payload";
-};
-type ChannelSubmittedMessage = {
-  channelId: string;
-  conversationId: string;
-  senderId: string;
-  content: ChannelMessageContent;
-  attachments?: ChannelSubmittedAttachment[];
-  metadata?: Record<string, unknown>;
-};
-type ChannelConfigGetRequest = {
-  channelId: string;
-};
 type ChannelConfigGetResponse<TConfig = unknown> = {
   config: TConfig;
 };
@@ -93,7 +40,7 @@ type ExtensionChannelConfig = {
 };
 type ExtensionChannel = {
   id: string;
-  submitMessage: (input: Omit<ChannelSubmittedMessage, "channelId">) => Promise<void>;
+  submitMessage: (input: Omit<ExtensionChannelMessageSubmitIngressPayload, "channelId">) => Promise<void>;
   onNcpEvent: (handler: (event: NcpEndpointEvent) => void | Promise<void>) => Unsubscribe;
   config: ExtensionChannelConfig;
 };
@@ -108,4 +55,4 @@ type ExtensionCapabilities = {
   provideHandler: (kind: string, handler: ExtensionCapabilityHandler) => Unsubscribe;
 };
 //#endregion
-export { ChannelConfigGetRequest, ChannelConfigGetResponse, ChannelFileContent, ChannelImageContent, ChannelMessageContent, ChannelSubmittedAttachment, ChannelSubmittedMessage, ChannelTextContent, ExtensionCapabilities, ExtensionCapabilityHandler, ExtensionCapabilityPayload, ExtensionChannel, ExtensionChannelConfig, ExtensionChannels, ExtensionRequest, ExtensionRequestHandler, ExtensionRequestResponse, ExtensionTransportEnvelope, NextClawExtensionOptions, NextClawExtensionWebSocketLike };
+export { type ChannelConfigGetRequest, ChannelConfigGetResponse, type ChannelFileContent, type ChannelImageContent, type ChannelMessageContent, type ChannelSubmittedAttachment, type ChannelSubmittedMessage, type ChannelTextContent, ExtensionCapabilities, ExtensionCapabilityHandler, ExtensionCapabilityPayload, ExtensionChannel, ExtensionChannelConfig, ExtensionChannels, ExtensionRequest, ExtensionRequestHandler, type ExtensionRequestResponse, ExtensionTransportEnvelope, NextClawExtensionOptions, NextClawExtensionWebSocketLike };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/extension-sdk",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "description": "Backend SDK for NextClaw extension server processes.",
   "type": "module",
@@ -35,8 +35,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@nextclaw/shared": "0.1.6",
-    "@nextclaw/ncp": "0.5.12"
+    "@nextclaw/ncp": "0.5.13",
+    "@nextclaw/shared": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",