capability-worker 0.1.0 → 0.1.1

package/README.md

@@ -229,7 +229,7 @@ Use `requireCapabilitySignature` when route handlers prefer exception flow:
 
 ```ts
 import { requireCapabilitySignature } from "capability-worker/auth";
-import { errorResponse, jsonResponse } from "capability-worker/http";
+import { errorResponse, okJson } from "capability-worker/http";
 
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
@@ -242,7 +242,7 @@ export default {
         .bind(accountId)
         .all();
 
-      return jsonResponse({ ok: true, data: rows.results });
+      return okJson(rows.results);
     } catch (error) {
       return errorResponse(error);
     }
@@ -254,7 +254,7 @@ Use `verifyCapabilitySignature` when route handlers prefer explicit result handl
 
 ```ts
 import { verifyCapabilitySignature } from "capability-worker/auth";
-import { errorJson, jsonResponse } from "capability-worker/http";
+import { errorJson, okJson } from "capability-worker/http";
 
 const auth = await verifyCapabilitySignature(request, env);
 
@@ -262,10 +262,7 @@ if (!auth.ok) {
   return errorJson(auth.code, auth.message, auth.status);
 }
 
-return jsonResponse({
-  ok: true,
-  accountId: auth.accountId
-});
+return okJson({ accountId: auth.accountId });
 ```
 
 Rules for signed routes:
@@ -382,6 +379,7 @@ import {
   errorJson,
   errorResponse,
   jsonResponse,
+  okJson,
   textResponse
 } from "capability-worker/http";
 
@@ -392,7 +390,16 @@ export async function readMeeting(request: Request, env: Env) {
     throw new HttpError(404, "meeting_not_found", "Meeting not found.");
   }
 
-  return jsonResponse({ ok: true, data: meeting });
+  return okJson(meeting);
+}
+```
+
+Success shape:
+
+```json
+{
+  "ok": true,
+  "data": {}
 }
 ```
 
@@ -412,6 +419,7 @@ Useful helpers:
 
 ```ts
 jsonResponse(value, init);
+okJson(data, init);
 textResponse(value, init);
 htmlResponse(value, init);
 redirectResponse(location, status);
@@ -915,6 +923,10 @@ CAPABILITY_PUBLIC_KEYS_URL = "https://host.example.com/capability/public-keys"
 
 ## New Capability Worker Recipe
 
+The npm package includes a small starter at `templates/new-capability-worker`.
+It uses `capability-build-assets`, `requireCapabilitySignature`, `okJson`,
+`errorJson`, and `textResponse` from this package.
+
 1. Create `cli/definition.json`.
 2. Create `cli/mapping.json`.
 3. Create `skills/<capability-name>/SKILL.md`.
@@ -932,7 +944,7 @@ Minimal route skeleton:
 
 ```ts
 import { requireCapabilitySignature } from "capability-worker/auth";
-import { errorResponse, jsonResponse, textResponse } from "capability-worker/http";
+import { errorJson, errorResponse, okJson, textResponse } from "capability-worker/http";
 
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
@@ -940,7 +952,7 @@ export default {
       const url = new URL(request.url);
 
       if (url.pathname === "/api/health") {
-        return jsonResponse({ ok: true });
+        return okJson({ status: "ok" });
       }
 
       if (url.pathname === "/api/meetings" && request.method === "GET") {
@@ -954,22 +966,13 @@ export default {
           .all();
 
         if (wantsJson) {
-          return jsonResponse({ ok: true, data: rows.results });
+          return okJson(rows.results);
         }
 
         return textResponse(formatMeetingsTable(rows.results));
       }
 
-      return jsonResponse(
-        {
-          ok: false,
-          error: {
-            code: "not_found",
-            message: "Not found."
-          }
-        },
-        404
-      );
+      return errorJson("not_found", "Not found.", 404);
     } catch (error) {
       return errorResponse(error);
     }

package/dist/runtime/http/index.d.ts

@@ -7,6 +7,7 @@ declare class HttpError extends Error {
     });
 }
 declare function jsonResponse(value: unknown, init?: ResponseInit | number): Response;
+declare function okJson(data: unknown, init?: ResponseInit | number): Response;
 declare function textResponse(value: string, init?: ResponseInit | number): Response;
 declare function htmlResponse(value: string, init?: ResponseInit | number): Response;
 declare function redirectResponse(location: string, status?: number): Response;
@@ -21,4 +22,4 @@ declare function booleanParam(value: unknown): boolean;
 declare function limitParam(value: unknown, defaultValue?: number, max?: number): number;
 declare function getRepeated(url: URL, key: string): string[];
 
-export { HttpError, booleanParam, errorJson, errorResponse, getRepeated, htmlResponse, isJsonRequested, jsonResponse, limitParam, parseJsonBody, readJsonObject, redirectResponse, stringArrayParam, stringParam, textResponse };
+export { HttpError, booleanParam, errorJson, errorResponse, getRepeated, htmlResponse, isJsonRequested, jsonResponse, limitParam, okJson, parseJsonBody, readJsonObject, redirectResponse, stringArrayParam, stringParam, textResponse };

package/dist/runtime/http/index.js

@@ -1 +1 @@
-class t extends Error{status;code;expose;constructor(t,e,n,r){super(n),this.name="HttpError",this.status=t,this.code=e,this.expose=r?.expose??t<500}}function e(t,e=200){const n=d(e);return new Response(JSON.stringify(t,null,2),{...n,headers:m(n.headers,"content-type","application/json; charset=utf-8")})}function n(t,e=200){return new Response(t.endsWith("\n")?t:`${t}\n`,{...d(e),headers:m(d(e).headers,"content-type","text/plain; charset=utf-8")})}function r(t,e=200){const n=d(e);return new Response(t,{...n,headers:m(n.headers,"content-type","text/html; charset=utf-8")})}function o(t,e=302){return new Response(null,{status:e,headers:{location:t,"cache-control":"no-store"}})}function s(t,n,r=400,o={}){return e({ok:!1,error:{code:t,message:n},...o},r)}function a(e){return e instanceof t?s(e.code,e.expose?e.message:"Internal error.",e.status):s("internal_error","Internal error.",500)}async function c(t){if(!t.body)return{};try{const e=await t.json();return!e||"object"!=typeof e||Array.isArray(e)?{}:e}catch{return{}}}async function u(e){const n=await e.json().catch(()=>null);if(!n||"object"!=typeof n||Array.isArray(n))throw new t(400,"invalid_json","Expected a JSON object.");return n}function i(t,e){const n=t.searchParams.get("json");return""===n||"1"===n||"true"===n||!0===e?.json}function f(t){if("string"!=typeof t)return;const e=t.trim();return e.length>0?e:void 0}function h(t){if(Array.isArray(t))return t.filter(t=>"string"==typeof t).map(t=>t.trim()).filter(Boolean);const e=f(t);return e?[e]:[]}function p(t){return!0===t||"true"===t||"1"===t||""===t}function l(t,e=20,n=100){const r="number"==typeof t?t:Number(t);return Number.isFinite(r)?Math.max(1,Math.min(n,Math.floor(r))):e}function y(t,e){return t.searchParams.getAll(e).map(t=>t.trim()).filter(Boolean)}function d(t){return"number"==typeof t?{status:t}:t}function m(t,e,n){const r=new Headers(t);return r.has(e)||r.set(e,n),r}export{t as HttpError,p as booleanParam,s as errorJson,a as errorResponse,y as getRepeated,r as htmlResponse,i as isJsonRequested,e as jsonResponse,l as limitParam,c as parseJsonBody,u as readJsonObject,o as redirectResponse,h as stringArrayParam,f as stringParam,n as textResponse};
+class t extends Error{status;code;expose;constructor(t,e,n,r){super(n),this.name="HttpError",this.status=t,this.code=e,this.expose=r?.expose??t<500}}function e(t,e=200){const n=m(e);return new Response(JSON.stringify(t,null,2),{...n,headers:x(n.headers,"content-type","application/json; charset=utf-8")})}function n(t,n=200){return e({ok:!0,data:t},n)}function r(t,e=200){return new Response(t.endsWith("\n")?t:`${t}\n`,{...m(e),headers:x(m(e).headers,"content-type","text/plain; charset=utf-8")})}function o(t,e=200){const n=m(e);return new Response(t,{...n,headers:x(n.headers,"content-type","text/html; charset=utf-8")})}function s(t,e=302){return new Response(null,{status:e,headers:{location:t,"cache-control":"no-store"}})}function a(t,n,r=400,o={}){return e({ok:!1,error:{code:t,message:n},...o},r)}function c(e){return e instanceof t?a(e.code,e.expose?e.message:"Internal error.",e.status):a("internal_error","Internal error.",500)}async function u(t){if(!t.body)return{};try{const e=await t.json();return!e||"object"!=typeof e||Array.isArray(e)?{}:e}catch{return{}}}async function i(e){const n=await e.json().catch(()=>null);if(!n||"object"!=typeof n||Array.isArray(n))throw new t(400,"invalid_json","Expected a JSON object.");return n}function f(t,e){const n=t.searchParams.get("json");return""===n||"1"===n||"true"===n||!0===e?.json}function h(t){if("string"!=typeof t)return;const e=t.trim();return e.length>0?e:void 0}function p(t){if(Array.isArray(t))return t.filter(t=>"string"==typeof t).map(t=>t.trim()).filter(Boolean);const e=h(t);return e?[e]:[]}function l(t){return!0===t||"true"===t||"1"===t||""===t}function y(t,e=20,n=100){const r="number"==typeof t?t:Number(t);return Number.isFinite(r)?Math.max(1,Math.min(n,Math.floor(r))):e}function d(t,e){return t.searchParams.getAll(e).map(t=>t.trim()).filter(Boolean)}function m(t){return"number"==typeof t?{status:t}:t}function x(t,e,n){const r=new Headers(t);return r.has(e)||r.set(e,n),r}export{t as HttpError,l as booleanParam,a as errorJson,c as errorResponse,d as getRepeated,o as htmlResponse,f as isJsonRequested,e as jsonResponse,y as limitParam,n as okJson,u as parseJsonBody,i as readJsonObject,s as redirectResponse,p as stringArrayParam,h as stringParam,r as textResponse};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "capability-worker",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared toolkit for Cloudflare Workers that expose CLI-like capabilities over HTTP.",
   "type": "module",
   "sideEffects": false,
   "files": [
     "dist",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/templates/new-capability-worker/README.md

@@ -0,0 +1,15 @@
+# New Capability Worker
+
+Small starter for a Cloudflare Worker capability that uses the shared `capability-worker` package.
+
+## Setup
+
+```sh
+pnpm install
+CAPABILITY_BASE_URL=https://starter.example.com/api pnpm -C worker run build:capability-assets
+pnpm -C worker run typecheck
+pnpm -C worker run dev
+```
+
+Replace `starter` names, command definitions, mapping routes, and domain behavior before deploying.
+

package/templates/new-capability-worker/cli/definition.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": "cli.definition.v1",
+  "cli": {
+    "name": "starter",
+    "summary": "Run starter capability commands.",
+    "description": "A minimal capability definition to replace with product-specific commands."
+  },
+  "commandGroups": [
+    {
+      "id": "starter",
+      "title": "Starter",
+      "description": "Starter commands."
+    }
+  ],
+  "commands": [
+    {
+      "id": "hello",
+      "group": "starter",
+      "command": "starter hello",
+      "summary": "Return a signed hello response.",
+      "description": "Verifies the capability signature and returns a small account-scoped response.",
+      "usage": "starter hello [--json]",
+      "risk": "read",
+      "requiresConfirmation": false,
+      "arguments": [],
+      "options": [
+        {
+          "name": "--json",
+          "key": "json",
+          "type": "boolean",
+          "description": "Return structured JSON instead of text."
+        }
+      ],
+      "examples": [
+        {
+          "description": "Return a text response.",
+          "command": "starter hello"
+        },
+        {
+          "description": "Return a JSON response.",
+          "command": "starter hello --json"
+        }
+      ],
+      "output": "Without --json, prints a short text response. With --json, returns a standard { ok, data } JSON response."
+    }
+  ]
+}
+

package/templates/new-capability-worker/cli/mapping.json

@@ -0,0 +1,8 @@
+{
+  "hello": {
+    "method": "GET",
+    "path": "/hello",
+    "query": ["json"]
+  }
+}
+

package/templates/new-capability-worker/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "new-capability-worker",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.9.0",
+  "scripts": {
+    "build:capability-assets": "pnpm -C worker run build:capability-assets",
+    "typecheck": "pnpm -C worker run typecheck",
+    "dev": "pnpm -C worker run dev",
+    "deploy": "pnpm -C worker run deploy"
+  }
+}
+

package/templates/new-capability-worker/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+packages:
+  - worker
+
+minimumReleaseAgeExclude:
+  - capability-worker@0.1.1
+

package/templates/new-capability-worker/skills/starter/SKILL.md

@@ -0,0 +1,9 @@
+# Starter
+
+Use the `starter` command to verify that the capability is installed and signed requests are working.
+
+## Commands
+
+- `starter hello`: returns a short text response.
+- `starter hello --json`: returns the same response as structured JSON.
+

package/templates/new-capability-worker/worker/capability/info.template.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "capability.info.v1",
+  "id": "starter",
+  "name": "starter",
+  "displayName": "Starter",
+  "summary": "Run starter capability commands.",
+  "description": "A minimal capability definition to replace with product-specific commands.",
+  "homepage": "${CAPABILITY_BASE_URL}",
+  "apiBaseUrl": "${CAPABILITY_BASE_URL}",
+  "endpoints": {
+    "definition": "definition",
+    "mapping": "mapping"
+  },
+  "skill": {
+    "name": "starter",
+    "entrypoint": {
+      "path": "SKILL.md",
+      "url": "skill/SKILL.md",
+      "contentType": "text/markdown"
+    },
+    "resources": []
+  },
+  "auth": {
+    "scheme": "capability-signature-v1",
+    "accountHeader": "x-capability-account-id",
+    "timestampHeader": "x-capability-timestamp",
+    "keyIdHeader": "x-capability-key-id",
+    "signatureHeader": "x-capability-signature"
+  },
+  "version": "${APP_ASSET_VERSION}",
+  "updatedAt": "2026-07-06T00:00:00Z",
+  "cache": {
+    "maxAgeSeconds": 86400
+  }
+}
+

package/templates/new-capability-worker/worker/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "starter-capability-worker",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build:capability-assets": "capability-build-assets --worker-root . --repo-root .. --validate",
+    "typecheck": "tsc --noEmit",
+    "dev": "wrangler dev",
+    "deploy": "pnpm run build:capability-assets && wrangler deploy"
+  },
+  "dependencies": {
+    "capability-worker": "^0.1.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260627.0",
+    "typescript": "^5.9.0",
+    "wrangler": "^4.51.0"
+  }
+}
+

package/templates/new-capability-worker/worker/src/worker.ts

@@ -0,0 +1,51 @@
+import { isCapabilityAssetPath } from "capability-worker";
+import { requireCapabilitySignature } from "capability-worker/auth";
+import {
+  errorJson,
+  errorResponse,
+  isJsonRequested,
+  okJson,
+  textResponse
+} from "capability-worker/http";
+
+export interface Env {
+  ASSETS: Fetcher;
+  CAPABILITY_PUBLIC_KEYS_JSON?: string;
+  CAPABILITY_PUBLIC_KEYS_URL?: string;
+  CAPABILITY_PUBLIC_KEYS_SERVICE?: Fetcher;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+
+      if (isCapabilityAssetPath(url.pathname, { basePath: "/api" })) {
+        return env.ASSETS.fetch(request);
+      }
+
+      if (url.pathname === "/api/health" && request.method === "GET") {
+        return okJson({ status: "ok" });
+      }
+
+      if (url.pathname === "/api/hello" && request.method === "GET") {
+        const { accountId } = await requireCapabilitySignature(request, env);
+        const data = {
+          accountId,
+          message: "Hello from the starter capability."
+        };
+
+        if (isJsonRequested(url)) {
+          return okJson(data);
+        }
+
+        return textResponse(`Hello ${accountId}.`);
+      }
+
+      return errorJson("not_found", "Not found.", 404);
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }
+};
+

package/templates/new-capability-worker/worker/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/**/*.ts"]
+}
+

package/templates/new-capability-worker/worker/wrangler.jsonc

@@ -0,0 +1,17 @@
+{
+  "name": "starter-capability-worker",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-07-06",
+  "assets": {
+    "directory": "./public",
+    "binding": "ASSETS",
+    "html_handling": "none",
+    "not_found_handling": "none"
+  },
+  "vars": {
+    "CAPABILITY_BASE_URL": "https://starter.example.com/api",
+    "APP_ASSET_VERSION": "0.1.1",
+    "CAPABILITY_PUBLIC_KEYS_URL": "https://example.com/capability/public-keys"
+  }
+}
+