@wokuapp/ai-toolkit 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -11,11 +11,11 @@
       "name": "woku",
       "source": "./",
       "description": "Design a listening program for your customer journey, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": { "name": "woku" },
       "license": "MIT",
       "homepage": "https://woku.app",
-      "keywords": ["woku", "mcp", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback"]
+      "keywords": ["woku", "mcp", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback", "sdk"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "name": "woku",
   "description": "Voice-of-customer for Claude Code. Design a listening program for your customer journey, run the fast VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server. Bundles the woku method so the agent acts as a CX consultant.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": { "name": "woku" },
   "homepage": "https://woku.app",
   "license": "MIT",
-  "keywords": ["woku", "mcp", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback"]
+  "keywords": ["woku", "mcp", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback", "sdk"]
 }

package/.codex-plugin/plugin.json

@@ -1,12 +1,12 @@
 {
   "name": "woku",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Voice-of-customer for OpenAI Codex. Design a listening program, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
   "author": { "name": "woku" },
   "homepage": "https://docs.woku.app/mcp/agent-guide",
   "repository": "https://github.com/wokuApp/woku-ai-toolkit",
   "license": "MIT",
-  "keywords": ["woku", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback"],
+  "keywords": ["woku", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback", "sdk"],
   "skills": "./skills/",
   "mcpServers": {
     "woku": {

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+Add two developer skills so the agent can build server-side woku integrations in code, not only operate the account through the MCP server:
+
+- `woku-sdk-javascript`: use the official `@wokuapp/sdk` (Node.js) to manage trackers, VoC tools, sends, tickets and action plans.
+- `woku-sdk-python`: use the official `woku` package (sync and async over httpx) with the same surface.
+
+Both skills are auto-discovered from `skills/`; no manifest changes are needed to load them.
+
 ## 0.1.0
 
 Initial release. Bundles woku's MCP server connection (`https://api.woku.app/mcp`) and the woku skill (the woku method plus the `woku_guide` / `design_voc_program` entry points). Plugin manifests for Claude Code (`.claude-plugin/`), Codex (`.codex-plugin/`), OpenClaw (`openclaw.plugin.json`) and Pi (`package.json`). OpenCode, claude.ai and ChatGPT connect to the MCP server through their own configuration.

package/README.md

@@ -8,6 +8,7 @@ It bundles:
 
 - The **woku MCP server** connection (`https://api.woku.app/mcp`), so the agent gets the full catalog (143 tools) with woku's OAuth. No API keys to copy.
 - The **woku skill**, which primes the agent with the method and tells it to call `woku_guide` first.
+- The **woku SDK skills** for JavaScript (`@wokuapp/sdk`) and Python (`woku`), so the agent can build server-side woku integrations in code (create tools, send surveys, read responses, drive tickets and action plans) over the public `/v1` API.
 
 ## Install
 
@@ -61,9 +62,11 @@ OpenCode runs OAuth automatically on the first authenticated call. To start the
 Install the plugin (this ships the woku skill):
 
 ```
-openclaw plugins install git:github.com/wokuApp/woku-ai-toolkit
+openclaw plugins install npm:@wokuapp/ai-toolkit
 ```
 
+You can also install from the git repository with `openclaw plugins install git:github.com/wokuApp/woku-ai-toolkit`.
+
 OpenClaw's plugin manifest declares local MCP servers only, so add woku's remote MCP server (`https://api.woku.app/mcp`) through your OpenClaw MCP configuration.
 
 ### Pi

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "woku-ai-toolkit",
   "name": "woku AI Toolkit",
   "description": "Voice-of-customer for your agent. Design a listening program, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wokuapp/ai-toolkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "woku AI Toolkit: connect your agent to woku's voice-of-customer platform. Design VoC programs and turn customer feedback into support tickets and action plans, through woku's MCP server.",
   "author": "woku",
   "license": "MIT",
@@ -19,6 +19,7 @@
     "ces",
     "surveys",
     "feedback",
+    "sdk",
     "plugin",
     "pi-package"
   ],

package/skills/woku-sdk-javascript/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: woku-sdk-javascript
+description: "Build a server-side woku integration in JavaScript or TypeScript with the official @wokuapp/sdk. Use when the user wants to manage their woku account from a Node.js backend: create trackers and VoC tools (NPS, CSAT, CES), send surveys by email or WhatsApp, read responses and delivery, curate support tickets, or drive action plans in code. This is server-only (secret key); for capturing feedback in a mobile app use @wokuapp/react-native instead."
+---
+
+# woku SDK for JavaScript and TypeScript
+
+`@wokuapp/sdk` is the official **server-side** client for the woku management API
+(`/v1`). Use it when the user wants woku operations in their Node.js backend
+instead of raw HTTP. It is typed, retries transient failures, makes creates
+idempotent, and auto-paginates lists.
+
+**Server-only.** The company secret key grants full management access. Keep it on
+the backend, never in a browser, mobile app or other untrusted client. For
+capturing feedback from a mobile app, use `@wokuapp/react-native` (a public
+capture key) instead.
+
+## Install and initialize
+
+```bash
+npm install @wokuapp/sdk
+```
+
+Requires Node.js 18+. Create one client and reuse it. The key comes from
+`WOKU_API_KEY` when you omit `apiKey`; the user gets it from the company
+Information section at admin.woku.app.
+
+```ts
+import { Woku } from '@wokuapp/sdk';
+
+const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });
+```
+
+## Core operations
+
+Creates are idempotent (auto `Idempotency-Key`); actions (send, test, reply) are
+never auto-retried.
+
+```ts
+// Tracker definitions and values (wire your CRM/ERP ids to feedback tools).
+const tracker = await woku.trackers.create({ name: 'Store #1', system: 'retail' });
+await woku.trackers.assignToWoku('woku_123', { name: 'Store #1', value: 'TX-42' });
+
+// VoC tools: npsTools / csatTools / cesTools (create/list/get/update/delete).
+const tool = await woku.npsTools.create({
+  name: 'Post-purchase',
+  npsMessage: 'How likely are you to recommend us?',
+});
+
+// Send a survey. IMPORTANT: `channel` is required and `recipients` is an array
+// of bare strings (emails for email, phone numbers for whatsapp), NOT objects.
+await woku.nps.sendInvitations({
+  channel: 'email',
+  npsToolId: tool._id,
+  recipients: ['ana@example.com'],
+});
+
+// Read responses and delivery/response-rate.
+for await (const r of await woku.nps.listResponses()) console.log(r);
+const delivery = await woku.dispatches.stats({ channel: 'email' });
+
+// Support tickets (AI-generated): list, filter, curate.
+for await (const t of await woku.tickets.list({ severity: 'high' })) console.log(t.title);
+
+// Action plans: approve and send to Jira/Monday/ClickUp/Notion or manage in woku.
+await woku.actionPlans.approve('plan_123');
+await woku.actionPlans.send('plan_123', {
+  provider: 'jira',
+  target: { projectId: '10032', issueTypeId: '10001' },
+});
+```
+
+Namespaces: `trackers`, `npsTools` / `csatTools` / `cesTools`, `nps` / `csat` /
+`ces`, `wokus`, `forms`, `flows`, `actionPlans`, `actionPlanGroups`, `tickets`,
+`ticketDestinations`, `dispatches`, `reports`, `company`, `quarantines`.
+
+## Pagination, errors, retries
+
+- List methods return a `Page`: iterate items with `for await (const x of page)`,
+  or walk pages with `page.hasNextPage()` and `page.getNextPage()`.
+- Every failure is a `WokuError`. HTTP errors are typed subclasses
+  (`NotFoundError`, `RateLimitError`, `AuthenticationError`, ...) carrying
+  `status`, the parsed body and the server `requestId`. Transport failures are
+  `WokuConnectionError` / `WokuTimeoutError`.
+- GETs and idempotent writes retry automatically with backoff, honoring the
+  `Retry-After` header.
+
+## Rotating the key
+
+`woku.company.rotateKey()` returns a new secret key and immediately invalidates
+the old one; store the returned key. `woku.company.revokeKey()` disables the key.
+
+## When to reach for the reference
+
+For the full method list, request/response shapes and per-call options, point the
+user to the SDK page at https://docs.woku.app/development/sdk-javascript and the
+API reference at https://docs.woku.app/development/api. There is an equivalent
+Python SDK (`woku`) documented at /development/sdk-python.

package/skills/woku-sdk-python/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: woku-sdk-python
+description: "Build a server-side woku integration in Python with the official woku package. Use when the user wants to manage their woku account from a Python backend: create trackers and VoC tools (NPS, CSAT, CES), send surveys by email or WhatsApp, read responses and delivery, curate support tickets, or drive action plans in code. Sync and async clients over httpx. This is server-only (secret key); for capturing feedback in a mobile app use @wokuapp/react-native instead."
+---
+
+# woku SDK for Python
+
+The `woku` package is the official **server-side** client for the woku
+management API (`/v1`), over `httpx`. Use it when the user wants woku operations
+in their Python backend instead of raw HTTP. It offers a synchronous client
+(`Woku`) and an asynchronous twin (`AsyncWoku`), typed request models, automatic
+retries, idempotent creates and auto-pagination. It is the counterpart of the
+JavaScript SDK (`@wokuapp/sdk`), with the same surface.
+
+**Server-only.** The company secret key grants full management access. Keep it on
+the backend, never in a client you do not control. For capturing feedback from a
+mobile app, use `@wokuapp/react-native` instead.
+
+## Install and initialize
+
+```bash
+pip install woku
+```
+
+Requires Python 3.9+. Create one client and reuse it. The key comes from
+`WOKU_API_KEY` when you omit `api_key`; the user gets it from the company
+Information section at admin.woku.app. Request bodies accept a plain dict (as
+below) or a generated Pydantic model from `woku._generated.models`.
+
+```python
+from woku import Woku
+
+woku = Woku(api_key="sk_...")  # or set WOKU_API_KEY and call Woku()
+```
+
+## Core operations
+
+Creates are idempotent (auto `Idempotency-Key`); actions (send, test, reply) are
+never auto-retried.
+
+```python
+# Tracker definitions and values (wire your CRM/ERP ids to feedback tools).
+tracker = woku.trackers.create({"name": "Store #1", "system": "retail"})
+woku.trackers.assign_to_woku("woku_123", {"name": "Store #1", "value": "TX-42"})
+
+# VoC tools: nps_tools / csat_tools / ces_tools (create/list/get/update/delete).
+tool = woku.nps_tools.create(
+    {"name": "Post-purchase", "npsMessage": "How likely are you to recommend us?"}
+)
+
+# Send a survey. IMPORTANT: `channel` is required and `recipients` is a list of
+# bare strings (emails for email, phone numbers for whatsapp), NOT objects.
+woku.nps.send_invitations(
+    {"channel": "email", "npsToolId": tool["_id"], "recipients": ["ana@example.com"]}
+)
+
+# Read responses and delivery/response-rate.
+for r in woku.nps.list_responses():
+    print(r)
+delivery = woku.dispatches.stats({"channel": "email"})
+
+# Support tickets (AI-generated): list, filter, curate.
+for t in woku.tickets.list({"severity": "high"}):
+    print(t["title"])
+
+# Action plans: approve and send to Jira/Monday/ClickUp/Notion or manage in woku.
+woku.action_plans.approve("plan_123")
+woku.action_plans.send(
+    "plan_123",
+    {"provider": "jira", "target": {"projectId": "10032", "issueTypeId": "10001"}},
+)
+```
+
+Namespaces: `trackers`, `nps_tools` / `csat_tools` / `ces_tools`, `nps` / `csat`
+/ `ces`, `wokus`, `forms`, `flows`, `action_plans`, `action_plan_groups`,
+`tickets`, `ticket_destinations`, `dispatches`, `reports`, `company`,
+`quarantines`.
+
+## Async
+
+Use `AsyncWoku` for awaitable methods and `async for` iteration; use it as a
+context manager to close the connection pool.
+
+```python
+import asyncio
+from woku import AsyncWoku
+
+
+async def main() -> None:
+    async with AsyncWoku(api_key="sk_...") as woku:
+        async for ticket in await woku.tickets.list({"severity": "high"}):
+            print(ticket["title"])
+
+
+asyncio.run(main())
+```
+
+## Pagination, errors, retries
+
+- Sync list methods return an iterable page: iterate items with `for x in page`,
+  or walk pages with `page.has_next_page()` and `page.get_next_page()`. The async
+  client iterates with `async for`.
+- Every failure is a `WokuError`. HTTP errors are typed subclasses
+  (`NotFoundError`, `RateLimitError`, `AuthenticationError`, ...) carrying
+  `status`, the parsed body and the server `request_id`. Transport failures are
+  `WokuConnectionError` / `WokuTimeoutError`.
+- GETs and idempotent writes retry automatically with backoff, honoring the
+  `Retry-After` header. Per-call overrides go in the `options` argument.
+
+## Rotating the key
+
+`woku.company.rotate_key()` returns a new secret key and immediately invalidates
+the old one; store `result["secretKey"]`. `woku.company.revoke_key()` disables
+the key.
+
+## When to reach for the reference
+
+For the full method list, request/response shapes and per-call options, point the
+user to the SDK page at https://docs.woku.app/development/sdk-python and the API
+reference at https://docs.woku.app/development/api. There is an equivalent
+JavaScript SDK (`@wokuapp/sdk`) documented at /development/sdk-javascript.