@constellaapp/openclaw 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# @openclaw/constella-openclaw
+
+OpenClaw plugin that connects to Constella external APIs and exposes two tools:
+
+- `constella_search_notes`
+- `constella_insert_note`
+
+## Install
+
+### From npm (official)
+
+```bash
+openclaw plugins install @openclaw/constella-openclaw
+```
+
+### Local dev install
+
+```bash
+openclaw plugins install -l /Users/tejas1/Documents/Constella\ Codebases/third_party/constella-openclaw
+```
+
+## Configure
+
+Set plugin config in your OpenClaw config file:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "constella-openclaw": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "https://fastfind.app",
+          "apiKey": "csk_your_key_here"
+        }
+      }
+    }
+  }
+}
+```
+
+## Enable the tools
+
+Optional plugin tools must be allowlisted:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "constella_search_notes",
+            "constella_insert_note"
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## API endpoints used
+
+- `POST /constella-external-api/retrieve-info`
+- `POST /constella-external-api/insert-note`
+
+Auth header sent by this plugin:
+
+- `x_access_key: csk_...`

package/index.ts

@@ -0,0 +1,119 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+import { createConstellaClient } from "./src/client.js";
+
+type PluginConfig = {
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+function toTextResult(payload: unknown) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+function readStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const out = value.filter((item): item is string => typeof item === "string");
+  return out.length > 0 ? out : undefined;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  const raw = (api.pluginConfig ?? {}) as PluginConfig;
+  const baseUrl =
+    typeof raw.baseUrl === "string" && raw.baseUrl.trim()
+      ? raw.baseUrl.trim()
+      : "https://fastfind.app";
+  const apiKey = typeof raw.apiKey === "string" ? raw.apiKey.trim() : "";
+
+  if (!apiKey) {
+    api.logger.warn(
+      "[constella-openclaw] Missing apiKey in plugin config. Tools will not be registered.",
+    );
+    return;
+  }
+
+  const client = createConstellaClient({
+    baseUrl,
+    apiKey,
+    logger: api.logger,
+  });
+
+  const searchTool: AnyAgentTool = {
+    name: "constella_search_notes",
+    description: "Search Constella notes with optional filters and date range.",
+    parameters: Type.Object(
+      {
+        query: Type.Optional(Type.String()),
+        queries: Type.Optional(Type.Array(Type.String())),
+        categories: Type.Optional(Type.Array(Type.String())),
+        tags: Type.Optional(Type.Array(Type.String())),
+        from_date_time: Type.Optional(Type.String()),
+        to_end_date_time: Type.Optional(Type.String()),
+        top_k: Type.Optional(Type.Number()),
+        similarity_setting: Type.Optional(Type.Number()),
+        fixedIntegrationNames: Type.Optional(Type.Array(Type.String())),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const result = await client.searchNotes({
+        query: typeof params.query === "string" ? params.query : undefined,
+        queries: readStringArray(params.queries),
+        categories: readStringArray(params.categories),
+        tags: readStringArray(params.tags),
+        from_date_time:
+          typeof params.from_date_time === "string"
+            ? params.from_date_time
+            : undefined,
+        to_end_date_time:
+          typeof params.to_end_date_time === "string"
+            ? params.to_end_date_time
+            : undefined,
+        top_k: typeof params.top_k === "number" ? params.top_k : undefined,
+        similarity_setting:
+          typeof params.similarity_setting === "number"
+            ? params.similarity_setting
+            : undefined,
+        fixedIntegrationNames: readStringArray(params.fixedIntegrationNames),
+      });
+      return toTextResult(result);
+    },
+  };
+
+  const insertTool: AnyAgentTool = {
+    name: "constella_insert_note",
+    description: "Insert a note into Constella.",
+    parameters: Type.Object(
+      {
+        title: Type.String(),
+        content: Type.Optional(Type.String()),
+      },
+      { additionalProperties: false },
+    ),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const title = typeof params.title === "string" ? params.title.trim() : "";
+      if (!title) {
+        throw new Error("title is required");
+      }
+
+      const result = await client.insertNote({
+        title,
+        content: typeof params.content === "string" ? params.content : "",
+      });
+      return toTextResult(result);
+    },
+  };
+
+  api.registerTool(searchTool, { optional: true });
+  api.registerTool(insertTool, { optional: true });
+}

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "constella-openclaw",
+  "name": "Constella",
+  "description": "Constella external API plugin (search + insert notes).",
+  "uiHints": {
+    "baseUrl": {
+      "label": "Constella Base URL",
+      "placeholder": "https://fastfind.app"
+    },
+    "apiKey": {
+      "label": "Constella API Key",
+      "sensitive": true,
+      "placeholder": "csk_..."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string"
+      },
+      "apiKey": {
+        "type": "string"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@constellaapp/openclaw",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for Constella search and note insertion.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@constellaapp/openclaw",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/client.ts

@@ -0,0 +1,81 @@
+export type ConstellaLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+export type ConstellaClientOptions = {
+  baseUrl: string;
+  apiKey: string;
+  logger?: ConstellaLogger;
+};
+
+type RetrieveInfoRequest = {
+  query?: string;
+  queries?: string[];
+  categories?: string[];
+  tags?: string[];
+  from_date_time?: string;
+  to_end_date_time?: string;
+  top_k?: number;
+  similarity_setting?: number;
+  fixedIntegrationNames?: string[];
+};
+
+type InsertNoteRequest = {
+  title: string;
+  content?: string;
+};
+
+function normalizeBaseUrl(input: string): string {
+  return input.replace(/\/+$/, "");
+}
+
+export function createConstellaClient(options: ConstellaClientOptions) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const apiKey = options.apiKey;
+  const logger = options.logger;
+
+  async function postJson<TResponse>(
+    path: string,
+    body: Record<string, unknown>,
+  ): Promise<TResponse> {
+    const url = `${baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        x_access_key: apiKey,
+      },
+      body: JSON.stringify(body),
+    });
+
+    const text = await response.text();
+    let parsed: unknown;
+    try {
+      parsed = text ? JSON.parse(text) : {};
+    } catch {
+      parsed = { raw: text };
+    }
+
+    if (!response.ok) {
+      const detail =
+        (parsed as { detail?: string })?.detail ||
+        (parsed as { error?: string })?.error ||
+        `Constella request failed (${response.status})`;
+      logger?.error?.(detail);
+      throw new Error(detail);
+    }
+
+    return parsed as TResponse;
+  }
+
+  return {
+    async searchNotes(payload: RetrieveInfoRequest): Promise<unknown> {
+      return await postJson("/constella-external-api/retrieve-info", payload);
+    },
+    async insertNote(payload: InsertNoteRequest): Promise<unknown> {
+      return await postJson("/constella-external-api/insert-note", payload);
+    },
+  };
+}