@kvasar/openclaw-storyblok-plugin 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# OpenClaw Storyblok Plugin
+
+This plugin integrates OpenClaw with Storyblok CMS, exposing tools to manage stories, components, and space information.
+
+## Features
+
+- Retrieve story by ID or UUID
+- List stories with filters (folder, status, etc.)
+- Create new stories
+- Update existing stories
+- Publish/unpublish stories
+- Get component definitions (schema)
+- Get space details
+
+## Configuration
+
+When adding this plugin to an OpenClaw agent, provide the following configuration:
+
+| Parameter | Description |
+|-----------|-------------|
+| `baseUrl` | Storyblok API base URL (default: `https://api.storyblok.com`) |
+| `spaceId` | Your Storyblok space ID (numeric) |
+| `managementToken` | Management API token for write operations |
+| `previewToken` | (Optional) Preview/Delivery token for read-only access |
+
+Tokens can be generated in your Storyblok dashboard under **Settings > API**.
+
+## Tools
+
+All tools are namespaced with `storyblok_`. See tool descriptions in the agent for detailed parameters.
+
+### Story operations
+- `storyblok_get_story` – Retrieve a story by ID or UUID
+- `storyblok_list_stories` – List stories with optional filters
+- `storyblok_create_story` – Create a new story draft
+- `storyblok_update_story` – Update a story (draft or published)
+- `storyblok_publish_story` – Publish a story (optionally with version note)
+- `storyblok_unpublish_story` – Unpublish a story
+
+### Components & Space
+- `storyblok_get_components` – List component definitions (schema)
+- `storyblok_get_space` – Retrieve space information
+
+## Development
+
+This plugin is written in TypeScript. Build and test:
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+## Notes
+
+- Management token is required for write operations and can also be used for reads if preview token is omitted.
+- Use preview token for read-only scenarios to limit exposure.
+- The plugin supports both Management API (v1) and Delivery API (v2) as appropriate.

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+  "id": "openclaw-storyblok",
+  "kind": "tool",
+  "name": "Storyblok Integration",
+  "version": "0.1.0",
+  "description": "Provides tools to interact with Storyblok CMS via Management API and Delivery API. Supports stories, components, and space management.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "description": "Storyblok API base URL (e.g., https://api.storyblok.com or your custom domain). Usually https://api.storyblok.com for Management API."
+      },
+      "spaceId": {
+        "type": "string",
+        "description": "Storyblok space ID (numeric)."
+      },
+      "managementToken": {
+        "type": "string",
+        "description": "Storyblok Management API token (for write operations)."
+      },
+      "previewToken": {
+        "type": "string",
+        "description": "Storyblok Preview/Delivery token (for read-only operations). Optional if only using management token for reads."
+      }
+    },
+    "required": ["baseUrl", "spaceId", "managementToken"]
+  },
+  "uiHints": {
+    "baseUrl": {
+      "label": "API Base URL",
+      "placeholder": "https://api.storyblok.com"
+    },
+    "spaceId": {
+      "label": "Space ID",
+      "placeholder": "12345"
+    },
+    "managementToken": {
+      "label": "Management Token",
+      "placeholder": "your_management_token",
+      "sensitive": true
+    },
+    "previewToken": {
+      "label": "Preview Token",
+      "placeholder": "your_preview_token",
+      "sensitive": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kvasar/openclaw-storyblok-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin — interact with Storyblok CMS via Management API and Delivery API",
+  "type": "module",
+  "main": "./index.ts",
+  "files": [
+    "index.ts",
+    "src/",
+    "openclaw.plugin.json",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "tsc --noEmit && vitest run"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "tools": [
+      "storyblok_get_space",
+      "storyblok_get_story",
+      "storyblok_list_stories",
+      "storyblok_create_story",
+      "storyblok_update_story",
+      "storyblok_publish_story",
+      "storyblok_unpublish_story",
+      "storyblok_get_components"
+    ]
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.32.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": ["openclaw", "plugin", "storyblok", "cms"],
+  "license": "MIT"
+}

package/src/__tests__/README.md

@@ -0,0 +1,115 @@
+# Storyblok Plugin (thin client) — OpenClaw
+
+Thin‑client OpenClaw plugin that calls an external REST service to generate Storyblok pages via AI.
+
+## Quick Start
+
+### 1. Clone the plugin repository
+
+```bash
+git clone git@bitbucket.org:scaledagilequa/openclaw-storyblok-plugin.git
+cd openclaw-storyblok-plugin
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Build the plugin
+
+```bash
+npm run build
+```
+
+### 4. Configure OpenClaw
+
+Add the plugin to your OpenClaw configuration (`~/.openclaw/config.yaml` or equivalent):
+
+```yaml
+plugins:
+  - id: storyblok
+    config:
+      serviceUrl: "http://localhost:8000"   # base URL of your Storyblok AI service
+      apiKey: "optional-key"                # optional API key for the service
+```
+
+### 5. Restart OpenClaw
+
+Restart OpenClaw (or reload plugins) to activate the new plugin.
+
+## Plugin Configuration
+
+| Key | Type | Required | Default | Description |
+|-----|------|----------|---------|-------------|
+| `serviceUrl` | string | Yes | `http://localhost:8000` | Base URL of the Storyblok AI service (must be reachable from OpenClaw). |
+| `apiKey` | string | No | – | Optional API key if the service requires authentication. |
+
+## Tool
+
+### `storyblok_generate_page`
+
+Generates a Storyblok page by sending a prompt to the external AI service.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | string | Description of the page you want to generate. |
+
+**Example usage (in OpenClaw chat):**
+
+```
+@assistant storyblok_generate_page prompt="Landing page for an AI consulting company"
+```
+
+**Response:**
+
+Returns the JSON response from the external service (typically containing the created story details).
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+## Architecture
+
+```
+openclaw-storyblok-plugin/
+├── src/
+│   └── index.ts           # Plugin entry point (registers the tool)
+├── openclaw.plugin.json   # Plugin manifest
+├── package.json           # Dependencies and scripts
+└── tsconfig.json         # TypeScript configuration
+```
+
+The plugin uses `node-fetch` to call the external REST service. It is designed to be a thin client—all business logic resides in the separate Storyblok AI service.
+
+## Related Projects
+
+- **Storyblok AI Service**: Python FastAPI service that does the actual LLM generation and Storyblok integration. Available at `git@bitbucket.org:scaledagilequa/openclaw-storyblok.git`.
+
+## License
+
+MIT

package/src/__tests__/openclaw.plugin.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://openclaw.ai/schema/openclaw.plugin.v1.json",
+  "id": "storyblok",
+  "name": "Storyblok",
+  "description": "Thin‑client plugin for Storyblok AI page generation (calls external REST service)",
+  "version": "0.1.0",
+  "config": {
+    "serviceUrl": {
+      "type": "string",
+      "description": "Base URL of the Storyblok AI service (e.g., http://localhost:8000)",
+      "required": true,
+      "default": "http://localhost:8000"
+    },
+    "apiKey": {
+      "type": "string",
+      "description": "Optional API key for the service (if required)",
+      "secret": true,
+      "required": false
+    }
+  },
+  "tools": [
+    {
+      "name": "storyblok_generate_page",
+      "description": "Generate a Storyblok page via AI using the external service",
+      "parameters": {
+        "prompt": { "type": "string", "description": "Description of the page you want to generate" }
+      }
+    }
+  ]
+}