@worker-protocol/client 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,126 @@
+# @worker-protocol/client
+
+Read a Worker, and take work from it. The consumer half of worker-protocol.
+
+**worker-protocol is an open specification for Workers that can be seen, operated and given work by
+people who did not build them.** HTTP and JSON Schema, no runtime. A *Worker* describes itself in a
+Descriptor served at `/.well-known/worker-protocol` — the one address this protocol fixes — and
+declares there which of its Capabilities it implements and at which addresses.
+
+`consume(url)` reads that document once, resolves every address the Worker declared, and answers an
+object with one member per Capability that Worker implements — and nothing for the ones it does not.
+A console, a Control Tower, a teams app or a Worker that answers another Worker's Tasks is built on
+this.
+
+It depends on `@worker-protocol/schemas` and on `fetch`, and on nothing else. **A consumer is not a
+server**, so nothing here asks you to install a web framework in order to make HTTP requests.
+
+## Install
+
+```
+npm i @worker-protocol/client zod
+```
+
+`zod` is a peer dependency (`^4.5.4`), shared with `@worker-protocol/schemas`.
+
+## Reading a Worker
+
+```ts
+import { consume } from "@worker-protocol/client";
+
+const worker = await consume("https://fleet.example.com", { credential: process.env.TOKEN });
+
+worker.descriptor; // the document itself, validated
+worker.edition; // the edition this Worker declares it speaks
+
+// Each of these is present only where the Worker declared the Capability.
+const health = await worker.health?.();
+const alerts = await worker.alerts?.();
+const activity = await worker.activity?.();
+
+const buckets = await worker.metrics?.read("vehicles.quiet", {
+  granularity: "day",
+  from: new Date("2026-09-01T00:00:00Z"),
+  by: ["region"],
+});
+```
+
+Paging, the cursor, the ordering, the retry that must not happen on a refusal the caller cannot fix,
+and the classification of an answer that cannot be read are all carried here. Nine of the rules this
+package implements oblige a *consumer* rather than a Worker, and a consumer that wrote this itself
+would be deriving every one of them again.
+
+## Taking work
+
+A Task is work a Worker needs somebody to do. Nobody is assigned one and nobody closes one: it
+exists while its condition holds and it is gone when that stops being true.
+
+```ts
+const open = await worker.tasks?.list();
+
+for (const task of open ?? []) {
+  // How to answer this type: the Action to post, and the JSON Schema of what it takes. Both are
+  // read out of the Descriptor you already hold — the Task itself says nothing about how to answer
+  // it, because that belongs to the Worker that raised it.
+  const answer = worker.tasks?.answers(task.type);
+  if (answer === undefined) continue;
+
+  const input = doTheWork(task.payload);
+  await worker.actions?.perform(answer.action, input, { idempotencyKey: crypto.randomUUID() });
+}
+```
+
+The schema comes back as it travels, so a console can render a form from it and an agent can build
+the document, neither having been told anything about this Worker in advance. Where a Task can end
+several ways, that schema is a discriminated union and each ending is a variant.
+
+`worker.nudges?.(type)` tells a Worker there is work of a type it answers. It buys latency and
+nothing else — a consumer reading on its own schedule is slower and never wrong — so it answers
+nothing and is safe to lose.
+
+## When a call does not succeed
+
+| Thrown | What happened |
+|---|---|
+| `Refused` | The Worker answered a refusal, and it carries the code. A `reject` is not repeated; a `retry` already was, with backoff, before you saw this. |
+| `Malformed` | The Worker answered something this protocol does not admit, naming the rule it broke. |
+| `Unserved` | The Worker declared an address that serves nothing there. |
+
+Retries and their backoff are `retries` and `backoffMs` on the options, and default to three
+attempts from 200ms. A credential is presented as `Authorization: Bearer <token>` and is never sent
+to an origin the Descriptor did not record as the Worker's own.
+
+## Before any work changes hands
+
+```ts
+import { canAnswer } from "@worker-protocol/client";
+
+const { verdict, why } = canAnswer(owner.descriptor, answerer.descriptor, taskType);
+```
+
+A Worker declares its *Skills*: the Task types it can answer, what it needs to be handed to answer
+one, and what it produces. `canAnswer` compares that against what the owner sends and what the
+owner's answering Action takes, in both directions, and answers `compatible`, `incompatible` or
+`unknown` with a reason. `unknown` is not `false`: an answerer that declares the Skill and states no
+requirement has claimed the capability and said nothing about what it needs, which the protocol
+allows, and reporting that as a refusal would be inventing an obligation.
+
+## Strict about what this protocol fixes, blind to what it does not
+
+Every document the protocol's schemas describe is validated, and a Worker that answers something
+else raises `Malformed` naming the rule. A Task's payload, an Action's input and result, an event's
+data are the Worker's own — this protocol has no data model — and nothing here looks inside them.
+
+## Related packages
+
+- `@worker-protocol/schemas` — the Zod objects that generate the normative JSON Schemas.
+- `@worker-protocol/hono` — the other half: `mount()`, for building a Worker on Hono.
+- `@worker-protocol/conformance` — point it at a Worker's base URL, get a report of what it complies
+  with.
+
+## License and name
+
+Apache-2.0, patent grant included — implement the protocol in any product, commercial or not,
+without asking anyone. The name is not part of that grant (Apache-2.0 §6): a claim that something
+*speaks worker-protocol* is one this project vouches for, and the conformance tool is how it is
+earned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worker-protocol/client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "workerProtocolEdition": "0.1",
   "description": "Read a Worker, and take work from it. The consumer half of worker-protocol",
   "license": "Apache-2.0",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/rowing-tech/worker-protocol.git",
     "directory": "packages/client"
   },
-  "homepage": "https://github.com/rowing-tech/worker-protocol#readme",
+  "homepage": "https://github.com/rowing-tech/worker-protocol/tree/main/packages/client#readme",
   "bugs": "https://github.com/rowing-tech/worker-protocol/issues",
   "publishConfig": {
     "access": "public"
@@ -29,14 +29,14 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@worker-protocol/schemas": "0.1.0"
+    "@worker-protocol/schemas": "0.1.2"
   },
   "peerDependencies": {
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/node": "26.5.1",
-    "@worker-protocol/hono": "0.1.0",
+    "@worker-protocol/hono": "0.1.2",
     "hono": "4.13.7",
     "typescript": "7.0.2",
     "vitest": "5.0.0",