@redonvn/open-claw-sdk 0.1.0

package/docs/DOCS.md

@@ -0,0 +1,342 @@
+---
+title: "OpenClaw SDK"
+summary: "Convert OpenAPI JSON documents into OpenClaw agent tools and generated plugin files"
+---
+
+# OpenClaw SDK
+
+`@redonvn/open-claw-sdk` is a small SDK for converting an OpenAPI `.json` document into:
+
+- OpenClaw-compatible tool definitions
+- A generated plugin module (`index.ts`)
+- A plugin manifest (`openclaw.plugin.json`)
+- A normalized tool catalog (`tool-catalog.json`)
+
+The package is designed for the common RedAI workflow:
+
+1. Receive an OpenAPI `.json` file from a backend team.
+2. Convert each operation into an OpenClaw tool.
+3. Generate a plugin that can be loaded by OpenClaw without hand-writing each tool.
+
+## Problem It Solves
+
+Writing OpenClaw tools manually is slow when an API already has an OpenAPI contract. This SDK removes the repetitive part:
+
+- Reads OpenAPI `paths`
+- Converts operations into JSON Schema tool parameters
+- Generates consistent tool names
+- Produces a ready-to-wire OpenClaw plugin skeleton
+
+## Package Scope
+
+This package currently targets **OpenAPI JSON** input and **HTTP tool generation**.
+
+Supported:
+
+- OpenAPI 3.x JSON documents
+- Path parameters
+- Query parameters
+- Request body JSON schema
+- Non-auth header parameters when `includeHeaders` is enabled
+- `$ref` resolution from `components.schemas`
+
+Not handled yet:
+
+- OpenAPI YAML input
+- Cookie parameters
+- Multipart/form-data request builders
+- Custom auth flows beyond simple bearer token or API key injection
+- Advanced response typing inside the generated runtime
+
+## Installation
+
+From the monorepo root:
+
+```bash
+npm --workspace @redonvn/open-claw-sdk install
+```
+
+Or publish/install it as a standalone package:
+
+```bash
+npm install @redonvn/open-claw-sdk
+```
+
+## CLI
+
+The package ships a CLI named `open-claw-sdk`.
+
+### Generate plugin files from an OpenAPI document
+
+```bash
+open-claw-sdk generate \
+  --input=./openapi.json \
+  --outDir=./generated/sepay-plugin \
+  --pluginId=sepay-api \
+  --pluginName="SePay API" \
+  --toolPrefix=sepay \
+  --defaultServerUrl=https://my-api.example.com \
+  --optional=true
+```
+
+### Required arguments
+
+- `--input`: path or URL to the OpenAPI `.json` document
+- `--outDir`: output directory for generated plugin files
+- `--pluginId`: OpenClaw plugin id
+
+### Optional arguments
+
+- `--pluginName`: display name for the plugin
+- `--toolPrefix`: prefix added to every generated tool name
+- `--defaultServerUrl`: overrides the first server URL in the OpenAPI document
+- `--includeHeaders=true`: include non-auth header params in the tool schema
+- `--optional=false`: register tools as required instead of opt-in
+
+## Generated Output
+
+The CLI writes three files:
+
+### `openclaw.plugin.json`
+
+Plugin manifest used by OpenClaw for discovery and config validation.
+
+Generated config fields:
+
+- `baseUrl`
+- `bearerToken`
+- `apiKey`
+- `apiKeyHeader`
+- `timeoutMs`
+- `defaultHeaders`
+
+### `index.ts`
+
+Generated OpenClaw plugin module. It imports `createOpenApiPlugin(...)` from this SDK and registers every converted tool automatically.
+
+### `tool-catalog.json`
+
+Normalized metadata snapshot of all tools. This is useful for review, debugging, or downstream automation.
+
+## Programmatic API
+
+### Load an OpenAPI document
+
+```ts
+import { loadOpenApiDocument } from "@redonvn/open-claw-sdk";
+
+const document = await loadOpenApiDocument("./openapi.json");
+```
+
+### Convert OpenAPI into OpenClaw tools
+
+```ts
+import { convertOpenApiToTools } from "@redonvn/open-claw-sdk";
+
+const catalog = convertOpenApiToTools(document, {
+  pluginId: "sepay-api",
+  pluginName: "SePay API",
+  toolPrefix: "sepay",
+  optional: true
+});
+```
+
+### Generate plugin files
+
+```ts
+import { generatePluginFromOpenApi } from "@redonvn/open-claw-sdk";
+
+const result = await generatePluginFromOpenApi({
+  input: "./openapi.json",
+  outDir: "./generated/sepay-plugin",
+  pluginId: "sepay-api",
+  pluginName: "SePay API",
+  toolPrefix: "sepay"
+});
+
+console.log(result.catalog.tools.length);
+console.log(result.files.indexPath);
+```
+
+### Build an OpenClaw plugin at runtime
+
+```ts
+import { createOpenApiPlugin } from "@redonvn/open-claw-sdk";
+
+const catalog = {
+  pluginId: "demo-api",
+  pluginName: "Demo API",
+  description: "Generated plugin",
+  serverUrl: "https://api.example.com",
+  optional: true,
+  tools: [
+    {
+      name: "demo_get_user",
+      description: "Get user by id",
+      method: "GET",
+      path: "/users/{id}",
+      operationId: "get_user",
+      tags: ["users"],
+      parameters: {
+        type: "object",
+        properties: {
+          path: {
+            type: "object",
+            properties: {
+              id: { type: "string" }
+            },
+            required: ["id"],
+            additionalProperties: false
+          }
+        },
+        required: ["path"],
+        additionalProperties: false
+      }
+    }
+  ]
+} as const;
+
+export default createOpenApiPlugin(catalog);
+```
+
+## Conversion Rules
+
+### Tool naming
+
+Each operation becomes one tool.
+
+Tool name source:
+
+1. `operationId` if present
+2. fallback from `method + path`
+
+Then the SDK:
+
+- normalizes to `snake_case`
+- optionally prepends `toolPrefix`
+
+Example:
+
+- `operationId: getCompanyDetail` -> `getcompanydetail`
+- with `toolPrefix: "mst"` -> `mst_getcompanydetail`
+
+If you want more readable names, keep `operationId` stable and explicit in the OpenAPI source.
+
+### Parameter shape
+
+Generated tool parameters are grouped by HTTP location:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "path": { "type": "object" },
+    "query": { "type": "object" },
+    "headers": { "type": "object" },
+    "body": { "type": "object" }
+  },
+  "additionalProperties": false
+}
+```
+
+Notes:
+
+- `path` is required when the route contains required path params.
+- `body` is required when `requestBody.required = true`.
+- Auth headers such as `authorization` and `x-api-key` are excluded from generated tool parameters.
+- Those auth values should come from plugin config instead.
+
+### Schema conversion
+
+The SDK converts OpenAPI schemas into plain JSON Schema suitable for `api.registerTool(...)`.
+
+Handled mappings:
+
+- `type`, `enum`, `default`, `description`
+- `properties`, `required`
+- `items`
+- `oneOf`, `anyOf`, `allOf`
+- `nullable`
+- `$ref` from `components.schemas`
+
+## Runtime Behavior
+
+`createOpenApiPlugin(...)` generates tool executors with a simple HTTP runtime:
+
+- Resolves `baseUrl` from `plugins.entries.<pluginId>.config.baseUrl`
+- Falls back to the generated `serverUrl` from OpenAPI when available
+- Injects bearer token or API key from plugin config
+- Serializes query parameters with `URLSearchParams`
+- Sends JSON body with `fetch`
+- Returns either JSON or text response as OpenClaw text content
+
+## OpenClaw Config Example
+
+```json5
+{
+  plugins: {
+    entries: {
+      "sepay-api": {
+        enabled: true,
+        config: {
+          baseUrl: "https://api.example.com",
+          bearerToken: "YOUR_TOKEN",
+          timeoutMs: 15000,
+          defaultHeaders: {
+            "x-tenant-id": "redon"
+          }
+        }
+      }
+    }
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        tools: {
+          allow: ["sepay-api"]
+        }
+      }
+    ]
+  }
+}
+```
+
+If the generated tools stay optional, they must be allowlisted by tool name or by plugin id.
+
+## Recommended Workflow
+
+1. Keep the OpenAPI document clean, especially `operationId`, `summary`, and schema descriptions.
+2. Generate the plugin into a dedicated folder.
+3. Review `tool-catalog.json` before enabling the plugin.
+4. Adjust tool naming with `toolPrefix` if the API is large or likely to conflict with other plugins.
+5. Configure `baseUrl` and auth in `plugins.entries.<id>.config`.
+
+## File Layout
+
+```text
+packages/open-claw-sdk/
+  src/
+    cli.ts
+    generator.ts
+    openapi.ts
+    runtime.ts
+    types.ts
+    utils.ts
+  docs/
+    DOCS.md
+```
+
+## Development Notes
+
+- The package uses only Node 18+ built-ins.
+- Generated plugins are intentionally simple and easy to audit.
+- This SDK is positioned as a bridge from backend OpenAPI contracts to OpenClaw tools, not as a full OpenAPI client generator.
+
+## Next Improvements
+
+- YAML input support
+- Better `operationId` to tool-name normalization
+- Multipart/form-data generation
+- Per-operation auth strategies
+- More structured error/result formatting for agent consumption