@nextclaw/extension-sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @nextclaw/extension-sdk
+
+Backend SDK for NextClaw extension server processes.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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 };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { NextClawExtension } from "./services/extension-client.service.js";
+export { NextClawExtension };

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

@@ -0,0 +1,38 @@
+import { eventKeys, getKeyId } 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;
+	};
+	onChange = (handler) => this.params.eventBus.subscribeAll((event) => {
+		if (event.type !== getKeyId(eventKeys.configUpdated)) return;
+		const payload = event.payload;
+		if (payload.path !== "channels" && payload.path !== `channels.${this.params.channelId}`) return;
+		this.get().then((config) => handler(config));
+	});
+};
+var ExtensionChannelService = class {
+	id;
+	config;
+	constructor(params) {
+		this.params = params;
+		this.id = params.channelId;
+		this.config = new ChannelConfig(params);
+	}
+	submitMessage = async (input) => {
+		await this.params.transport.postIngress(MESSAGE_SUBMIT_EVENT_TYPE, {
+			...input,
+			channelId: this.id
+		});
+	};
+	onNcpEvent = (handler) => this.params.eventBus.on(eventKeys.ncpEvent, (event) => {
+		handler(event);
+	});
+};
+//#endregion
+export { ExtensionChannelService };

package/dist/services/extension-client.service.d.ts

@@ -0,0 +1,18 @@
+import { ExtensionCapabilities, ExtensionChannels, ExtensionRequestHandler, NextClawExtensionOptions } from "../types/extension-sdk.types.js";
+import { EventBus } from "@nextclaw/shared";
+
+//#region src/services/extension-client.service.d.ts
+declare class NextClawExtension {
+  readonly eventBus: EventBus;
+  readonly channels: ExtensionChannels;
+  readonly capabilities: ExtensionCapabilities;
+  readonly extensionId: string;
+  private readonly transport;
+  private realtimeSubscription;
+  constructor(options?: NextClawExtensionOptions);
+  readonly close: () => void;
+  readonly onRequest: (handler: ExtensionRequestHandler) => (() => void);
+  private readonly toEventBusEnvelope;
+}
+//#endregion
+export { NextClawExtension };

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

@@ -0,0 +1,127 @@
+import { ExtensionChannelService } from "./extension-channel.service.js";
+import { ExtensionTransportService } from "./extension-transport.service.js";
+import { EventBus } from "@nextclaw/shared";
+//#region src/services/extension-client.service.ts
+var ExtensionChannelRegistry = class {
+	channels = /* @__PURE__ */ new Map();
+	constructor(params) {
+		this.params = params;
+	}
+	use = (channelId) => {
+		const normalizedChannelId = channelId.trim();
+		if (!normalizedChannelId) throw new Error("channelId is required.");
+		const existing = this.channels.get(normalizedChannelId);
+		if (existing) return existing;
+		const channel = new ExtensionChannelService({
+			channelId: normalizedChannelId,
+			eventBus: this.params.eventBus,
+			transport: this.params.transport
+		});
+		this.channels.set(normalizedChannelId, channel);
+		return channel;
+	};
+};
+function readRequest(payload) {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+	const record = payload;
+	if (typeof record.requestId !== "string" || typeof record.extensionId !== "string" || typeof record.kind !== "string") return null;
+	return {
+		requestId: record.requestId,
+		extensionId: record.extensionId,
+		kind: record.kind,
+		payload: record.payload && typeof record.payload === "object" && !Array.isArray(record.payload) ? record.payload : {}
+	};
+}
+function normalizeName(value, name) {
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${name} is required.`);
+	return normalized;
+}
+async function handleRequest(transport, request, handler) {
+	try {
+		const data = await handler(request);
+		await transport.respondToRequest({
+			requestId: request.requestId,
+			ok: true,
+			data
+		});
+	} catch (error) {
+		await transport.respondToRequest({
+			requestId: request.requestId,
+			ok: false,
+			error: { message: error instanceof Error ? error.message : String(error) }
+		});
+	}
+}
+var ExtensionCapabilityRegistry = class {
+	constructor(params) {
+		this.params = params;
+	}
+	provide = (namespace, capability) => {
+		const normalizedNamespace = normalizeName(namespace, "namespace");
+		const unsubscribeHandlers = this.readHandlers(capability).map(([name, handler]) => this.provideHandler(`${normalizedNamespace}.${name}`, handler));
+		if (unsubscribeHandlers.length === 0) throw new Error(`capability '${normalizedNamespace}' has no callable methods.`);
+		return () => {
+			for (const unsubscribe of unsubscribeHandlers) unsubscribe();
+		};
+	};
+	provideHandler = (kind, handler) => {
+		const normalizedKind = normalizeName(kind, "kind");
+		return this.params.eventBus.subscribeAll((event) => {
+			if (event.type !== "extension.request") return;
+			const request = readRequest(event.payload);
+			if (!request || request.extensionId !== this.params.extensionId || request.kind !== normalizedKind) return;
+			handleRequest(this.params.transport, request, async (matchedRequest) => await handler(matchedRequest.payload ?? {}, matchedRequest));
+		});
+	};
+	readHandlers = (capability) => Object.entries(capability).filter((entry) => typeof entry[1] === "function");
+};
+var NextClawExtension = class {
+	eventBus;
+	channels;
+	capabilities;
+	extensionId;
+	transport;
+	realtimeSubscription = null;
+	constructor(options = {}) {
+		this.transport = new ExtensionTransportService(options);
+		this.extensionId = this.transport.extensionId;
+		this.eventBus = new EventBus({
+			onFirstSubscriber: () => {
+				this.realtimeSubscription ??= this.transport.subscribe((event) => {
+					this.eventBus.emitEnvelope(this.toEventBusEnvelope(event));
+				});
+			},
+			onNoSubscribers: () => {
+				this.realtimeSubscription?.close();
+				this.realtimeSubscription = null;
+			}
+		});
+		this.channels = new ExtensionChannelRegistry({
+			eventBus: this.eventBus,
+			transport: this.transport
+		});
+		this.capabilities = new ExtensionCapabilityRegistry({
+			eventBus: this.eventBus,
+			extensionId: this.extensionId,
+			transport: this.transport
+		});
+	}
+	close = () => {
+		this.realtimeSubscription?.close();
+		this.realtimeSubscription = null;
+	};
+	onRequest = (handler) => this.eventBus.subscribeAll((event) => {
+		if (event.type !== "extension.request") return;
+		const request = readRequest(event.payload);
+		if (!request || request.extensionId !== this.extensionId) return;
+		handleRequest(this.transport, request, handler);
+	});
+	toEventBusEnvelope = (event) => ({
+		...event,
+		emittedAt: event.emittedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		source: event.source ?? "realtime"
+	});
+};
+//#endregion
+export { NextClawExtension };

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

@@ -0,0 +1,85 @@
+import { normalizeEndpoint, resolveWebSocketUrl } from "../utils/extension-url.utils.js";
+//#region src/services/extension-transport.service.ts
+function readRuntimeEnv() {
+	return typeof process === "undefined" ? {} : process.env;
+}
+function requireRuntimeValue(value, name) {
+	const trimmed = value?.trim();
+	if (!trimmed) throw new Error(`${name} is required.`);
+	return trimmed;
+}
+var ExtensionTransportService = class {
+	token;
+	extensionId;
+	endpoint;
+	fetchImpl;
+	webSocketFactory;
+	constructor(options = {}) {
+		const env = readRuntimeEnv();
+		this.endpoint = normalizeEndpoint(options.endpoint ?? requireRuntimeValue(env.NEXTCLAW_EXTENSION_ENDPOINT, "NEXTCLAW_EXTENSION_ENDPOINT"));
+		this.token = options.token ?? requireRuntimeValue(env.NEXTCLAW_EXTENSION_TOKEN, "NEXTCLAW_EXTENSION_TOKEN");
+		this.extensionId = options.extensionId ?? requireRuntimeValue(env.NEXTCLAW_EXTENSION_ID, "NEXTCLAW_EXTENSION_ID");
+		this.fetchImpl = options.fetch ?? globalThis.fetch;
+		this.webSocketFactory = options.webSocketFactory;
+		if (typeof this.fetchImpl !== "function") throw new Error("fetch is unavailable. Provide fetch when creating the extension.");
+	}
+	postIngress = async (type, payload) => {
+		const envelope = {
+			type,
+			extensionId: this.extensionId,
+			payload,
+			emittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			source: "extension-sdk"
+		};
+		const response = await this.fetchImpl(`${this.endpoint}/webhook`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${this.token}`
+			},
+			body: JSON.stringify(envelope)
+		});
+		const body = await response.json().catch(() => null);
+		if (!response.ok) throw new Error(this.readErrorMessage(body, `NextClaw ingress failed with ${response.status}`));
+		return this.readResponseData(body);
+	};
+	respondToRequest = async (response) => {
+		await this.postIngress("extension.response", response);
+	};
+	subscribe = (handler) => {
+		const socket = this.createSocket(resolveWebSocketUrl(this.endpoint, "/ws"));
+		socket.onmessage = (event) => {
+			const envelope = this.parseEnvelope(event.data);
+			if (envelope) handler(envelope);
+		};
+		return { close: () => socket.close() };
+	};
+	createSocket = (url) => {
+		if (this.webSocketFactory) return this.webSocketFactory(url);
+		if (typeof globalThis.WebSocket !== "function") throw new Error("WebSocket is unavailable. Provide webSocketFactory when creating the extension.");
+		return new globalThis.WebSocket(url);
+	};
+	parseEnvelope = (value) => {
+		if (typeof value !== "string") return null;
+		try {
+			const parsed = JSON.parse(value);
+			return parsed && typeof parsed === "object" && typeof parsed.type === "string" ? parsed : null;
+		} catch {
+			return null;
+		}
+	};
+	readErrorMessage = (body, fallback) => {
+		if (!body || typeof body !== "object") return fallback;
+		const error = body.error;
+		return typeof error?.message === "string" && error.message.trim() ? error.message : fallback;
+	};
+	readResponseData = (body) => {
+		if (body && typeof body === "object" && !Array.isArray(body)) {
+			const record = body;
+			if (record.ok === true && "data" in record) return record.data;
+		}
+		return body;
+	};
+};
+//#endregion
+export { ExtensionTransportService };

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

@@ -0,0 +1,111 @@
+import { Unsubscribe } from "@nextclaw/shared";
+import { NcpEndpointEvent } from "@nextclaw/ncp";
+
+//#region src/types/extension-sdk.types.d.ts
+type NextClawExtensionOptions = {
+  endpoint?: string;
+  token?: string;
+  extensionId?: string;
+  fetch?: typeof fetch;
+  webSocketFactory?: (url: string) => NextClawExtensionWebSocketLike;
+};
+type NextClawExtensionWebSocketLike = {
+  onopen: (() => void) | null;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: (() => void) | null;
+  close: () => void;
+};
+type ExtensionTransportEnvelope<TPayload = unknown> = {
+  type: string;
+  extensionId: string;
+  payload: TPayload;
+  emittedAt?: string;
+  source?: string;
+};
+type ExtensionRequest = {
+  requestId: string;
+  extensionId: string;
+  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;
+};
+type ExtensionChannelConfig = {
+  get: <TConfig = unknown>() => Promise<TConfig>;
+  onChange: <TConfig = unknown>(handler: (config: TConfig) => void | Promise<void>) => Unsubscribe;
+};
+type ExtensionChannel = {
+  id: string;
+  submitMessage: (input: Omit<ChannelSubmittedMessage, "channelId">) => Promise<void>;
+  onNcpEvent: (handler: (event: NcpEndpointEvent) => void | Promise<void>) => Unsubscribe;
+  config: ExtensionChannelConfig;
+};
+type ExtensionChannels = {
+  use: (channelId: string) => ExtensionChannel;
+};
+type ExtensionRequestHandler = (request: ExtensionRequest) => unknown | Promise<unknown>;
+type ExtensionCapabilityPayload = Record<string, unknown>;
+type ExtensionCapabilityHandler<TPayload extends ExtensionCapabilityPayload = ExtensionCapabilityPayload> = (payload: TPayload, request: ExtensionRequest) => unknown | Promise<unknown>;
+type ExtensionCapabilities = {
+  provide: (namespace: string, capability: object) => Unsubscribe;
+  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 };

package/dist/utils/extension-url.utils.js

@@ -0,0 +1,13 @@
+//#region src/utils/extension-url.utils.ts
+function normalizeEndpoint(endpoint) {
+	const trimmed = endpoint.trim();
+	if (!trimmed) throw new Error("NextClaw extension endpoint is required.");
+	return trimmed.replace(/\/+$/, "");
+}
+function resolveWebSocketUrl(endpoint, path) {
+	const url = new URL(path, `${normalizeEndpoint(endpoint)}/`);
+	url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url.toString();
+}
+//#endregion
+export { normalizeEndpoint, resolveWebSocketUrl };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nextclaw/extension-sdk",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Backend SDK for NextClaw extension server processes.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Peiiii/nextclaw.git"
+  },
+  "homepage": "https://github.com/Peiiii/nextclaw/tree/master/packages/nextclaw-extension-sdk",
+  "bugs": {
+    "url": "https://github.com/Peiiii/nextclaw/issues"
+  },
+  "keywords": [
+    "nextclaw",
+    "extension-sdk",
+    "channel",
+    "realtime"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp": "0.5.7",
+    "@nextclaw/shared": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension --unbundle",
+    "lint": "eslint src --max-warnings=0",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}