@deepdockai/cli 1.0.26 → 1.0.28

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.28
+
+- The device API's `Error.code` list no longer names `organization_required`, `forbidden`, `conflict` and `already_member`: only the dashboard tree (`/partner`) answers them, never `/v1`. The CLI still meets them on its own `/partner` calls and keeps their exit codes (`organization_required` 1, the other three 2), now from a list of its own. Nothing changes for a script that reads `--json` or the exit code.
+
+## 1.0.27
+
+- An update is called with `PATCH` again; a read and a create stay `POST`. All three take a flat JSON body and nothing in the URL. The method must be the action's own: any other answers `405 invalid_request` with `Allow` naming the one method (`POST` or `PATCH`), so a `POST` to an update is refused and does nothing. A query string on an action path is still `400 invalid_request`. A write still needs an `Idempotency-Key`; a read ignores it.
+- Each entry of the action index has a `method` (`POST` or `PATCH`) beside its `operation` (`read`, `create` or `update`).
+- The bundled clients' `write` takes the action's operation after the action name (`write(deviceId, system, action, 'create' | 'update', key, input)`) and sends `POST` for a create and `PATCH` for an update; `PendingWrite` carries it as `operation`. Reads are unchanged. Idempotency handling is unchanged.
+- The skill's references describe the contract.
+
 ## 1.0.26
 
 - Every action is called with `POST /v1/devices/{deviceId}/systems/{system}/actions/{action}` and its inputs in a flat JSON body, reads and updates included. There is no `GET` read and no `PATCH` update any more: any other method answers `405 invalid_request` with `Allow: POST`, and a query string on an action path answers `400 invalid_request` ("inputs go in the JSON body, not in the URL"), so no value reaches a URL, a request log or a proxy. A read takes `limit` (a JSON integer) and `cursor` (a string) in the same body; a write still needs an `Idempotency-Key`, a read ignores it. Values are typed as given: an integer input is a JSON number, and `"1001"` is refused where it is declared as one.

package/dist/deepdock.js

@@ -11241,6 +11241,7 @@ var actionRow = (action) => {
   const {
     name,
     operation: _operation,
+    method: _method,
     input: _input,
     output: _output,
     description,
@@ -11439,7 +11440,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.26";
+var VERSION = "1.0.28";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md

@@ -22,7 +22,8 @@ integration against a demo device. It is not for building or changing actions: D
    screen, and from then on it belongs to your organisation until you release it.
 3. A device reports the **systems** it runs; each system has **actions**, deterministic operations
    that Deepdock builds and verifies before offering them.
-4. Every action is a `POST` with a flat JSON body, never a value in the URL. A **read** (the
+4. Every action takes a flat JSON body, never a value in the URL: `POST` for a read or create,
+   `PATCH` for an update. A **read** (the
    action's `operation`) also takes `limit` and `cursor` in that body to page; a **write** (`create`
    or `update`) needs an `Idempotency-Key` as well.
 5. Every write needs an `Idempotency-Key`: a new key per intended write, the same key on every retry,

package/skill/references/calling-actions.md

@@ -3,12 +3,13 @@
 All paths are under `/v1/devices/{deviceId}/systems/{system}/actions/{action}`. `deviceId` is the
 UUID from pairing; `system` and `action` are the slugs from the action index.
 
-## Calling an action: POST
+## Calling an action: POST, or PATCH for an update
 
-Every action, whether it reads, creates or updates, is called with `POST` and a flat JSON object as
-the body. What the action does is its `operation` (`read`, `create` or `update`) in the action
-index and the OpenAPI document; the HTTP method never says. Any other method answers
-`405 invalid_request` with `Allow: POST`.
+Every action is called with a flat JSON object as the body. A read and a create are `POST`, an
+update is `PATCH`. What the action does is its `operation` (`read`, `create` or `update`), and its
+`method` (`POST` or `PATCH`), in the action index and the OpenAPI document. Any other method
+answers `405 invalid_request` with `Allow` naming the action's one method, so a `POST` to an update
+is refused, not run.
 
 Inputs are typed as the action's schema declares them and are never sent as text when they are not:
 an integer is a JSON number (`"patientId": 4711`, not `"4711"`; the text form is refused with
@@ -64,7 +65,7 @@ curl -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/createNote" \
 
 - A create answers `201` with `{ data: { <returned fields> } }`, typically the new record's id. A
   replay of the same key answers `200` with the same data and `Idempotent-Replayed: true`.
-- An update is a `POST` too and answers `200` whether it ran now or is a replay; the header tells
+- An update is a `PATCH` to the same path, with the same body rules, and answers `200` whether it ran now or is a replay; the header tells
   you which.
 - The returned id is the system's own id (for example `noteId`). Store it as the system gave it;
   do not predict or re-key it. Result field types come from each action's own output schema: do not
@@ -98,14 +99,14 @@ Never invent an id, copy one from another device, or hard-code one from a test r
   from the action's own output schema.
 - **Mark every test text `TEST-DEEPDOCK-<id>`** on the demo device only, and list what you created
   ([testing.md](testing.md)).
-- A call with a query string, or with any method but `POST`, is refused (`400` and `405`), so a
+- A call with a query string, or with a method other than the action's own, is refused (`400` and `405`), so a
   client library that puts parameters in the URL for you needs its body mode.
 
 ## Refusals specific to the call shape
 
 | Answer | Cause | Fix |
 |---|---|---|
-| `405 invalid_request`, `Allow: POST` | any method but `POST` on an action path | call it with `POST` |
+| `405 invalid_request`, `Allow: POST` or `Allow: PATCH` | a method other than the action's own (for example `POST` to an update, or `PATCH` to a read or create) | use the method `Allow` names: `POST` for a read or create, `PATCH` for an update |
 | `400 invalid_request` | a query string on an action path | move every value into the JSON body |
 | `400 invalid_request` | an input of the wrong type, such as `"4711"` where an integer is declared | send the type the schema declares |
 
@@ -138,7 +139,7 @@ attempts per key per rolling 60 seconds, whose `429` carries neither the header
 | Header | When | Meaning |
 |---|---|---|
 | `Idempotent-Replayed: true` | a write's `200` | the stored result of an earlier run; nothing written again |
-| `Allow` | `405 invalid_request` | always `POST`: every action is called with it |
+| `Allow` | `405 invalid_request` | the action's one method: `POST` for a read or create, `PATCH` for an update |
 | `WWW-Authenticate: Bearer` | `401` | the key was refused |
 | `Retry-After` | `429` | seconds to wait, when present |
 

package/skill/references/clients/deepdock.py

@@ -105,10 +105,15 @@ class Deepdock:
                 return
             cursor = page.next_cursor
 
-    def write(self, device_id: str, system: str, action: str, idempotency_key: str,
+    def write(self, device_id: str, system: str, action: str, operation: str, idempotency_key: str,
               body: Dict[str, InputValue]) -> WriteResult:
-        """Runs a write action (a create or an update) with POST; `body` values are typed as the action's schema declares."""
-        data, headers = self._send("POST", self._action_path(device_id, system, action), json=body,
+        """Runs a write action: POST for operation "create", PATCH for "update" (from the action index; any
+        other method answers 405 with `Allow` naming the right one). `body` values are typed as the
+        action's schema declares. Any other `operation` raises ValueError before anything is sent."""
+        if operation not in ("create", "update"):
+            raise ValueError(f"operation must be 'create' or 'update', got {operation!r}")
+        data, headers = self._send("PATCH" if operation == "update" else "POST",
+                                   self._action_path(device_id, system, action), json=body,
                                    headers={"Idempotency-Key": idempotency_key})
         return WriteResult(data=data, replayed=headers.get("Idempotent-Replayed") == "true")
 
@@ -150,6 +155,7 @@ class PendingWrite:
     device_id: str
     system: str
     action: str
+    operation: str  # create | update, from the action index
     input: Dict[str, InputValue]
     status: str = "pending"  # pending | sent | done | unknown | refused
     conflict_retries: int = 0
@@ -161,7 +167,7 @@ class PendingWrite:
 def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
     """One attempt; returns the row with its new status. The caller persists it."""
     try:
-        res = dd.write(row.device_id, row.system, row.action, row.key, row.input)
+        res = dd.write(row.device_id, row.system, row.action, row.operation, row.key, row.input)
         return replace(row, status="done", result=res.data)
     except DeepdockTransportError:
         return replace(row, status="sent")

package/skill/references/clients/deepdock.ts

@@ -57,6 +57,8 @@ export type Page<Item> = { items: Item[]; nextCursor: string | null }
 export type WriteResult<T> = { data: T; replayed: boolean }
 /** A flat JSON value as the action's schema declares it: a number is a number, never its text. */
 export type InputValue = string | number | boolean
+/** What a write action does, from `operation` in the action index: a create is POST, an update PATCH. */
+export type WriteOperation = 'create' | 'update'
 export type ActionInput = Record<string, InputValue>
 
 export type SystemStatus = 'running' | 'stopped' | 'missing' | 'unknown'
@@ -229,18 +231,21 @@ export class Deepdock {
   }
 
   /**
-   * Runs a write action (a create or an update) with POST. `input` values are typed as the action's
-   * schema declares. `idempotencyKey` is new per intended write and the same on every retry.
+   * Runs a write action: POST for a `create`, PATCH for an `update`. Take `operation` from the
+   * action index; any other method answers 405 with `Allow` naming the right one. `input` values
+   * are typed as the action's schema declares. `idempotencyKey` is new per intended write and the
+   * same on every retry.
    */
   async write<Result>(
     deviceId: string,
     system: string,
     action: string,
+    operation: WriteOperation,
     idempotencyKey: string,
     input: ActionInput,
   ): Promise<WriteResult<Result>> {
     const { data, headers } = await this.send<Result>(this.actionPath(deviceId, system, action), {
-      method: 'POST',
+      method: operation === 'update' ? 'PATCH' : 'POST',
       headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
       body: JSON.stringify(input),
     })
@@ -285,6 +290,7 @@ export type PendingWrite = {
   deviceId: string
   system: string
   action: string
+  operation: WriteOperation
   input: ActionInput
   status: PendingStatus
   conflictRetries: number
@@ -311,7 +317,7 @@ const RETRY_SAME_KEY = new Set([
 /** One attempt; returns the row with its new status. The caller persists it. */
 export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingWrite> => {
   try {
-    const { data } = await dd.write(row.deviceId, row.system, row.action, row.key, row.input)
+    const { data } = await dd.write(row.deviceId, row.system, row.action, row.operation, row.key, row.input)
     return { ...row, status: 'done', result: data }
   } catch (err) {
     if (err instanceof DeepdockTransportError) return { ...row, status: 'sent' }

package/skill/references/concepts.md

@@ -72,7 +72,8 @@ offering it; it then runs the same way every time. Actions are
 **assigned** to your organisation by Deepdock, so the set you can call is yours, not the whole
 catalogue.
 
-- Every action is called with `POST` and a flat JSON body; its `operation` says what it does.
+- Every action takes a flat JSON body; its `operation` says what it does: `POST` for a read or a
+  create, `PATCH` for an update.
 - A **read** also pages with `limit` and `cursor` in the body.
 - A **write** is a `create` (answers `201`) or an `update` (answers `200`), and needs an
   `Idempotency-Key` header.

package/skill/references/discovery.md

@@ -25,9 +25,9 @@ document into the repository and refresh it with the same command when you touch
 What to read off it:
 
 - **`paths`**: one operation per action at
-  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; every one is a `post`;
-  its `operation` says whether it reads, creates or updates. Any other method answers
-  `405 invalid_request` with `Allow: POST`.
+  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; each is a `post` (read, create) or a `patch` (update);
+  its `operation` says which. Any other method answers `405 invalid_request` with `Allow` naming
+  the right one.
 - **`summary` and `description`**: what the action does and what it changes in the system, what
   an omitted optional input becomes, action-specific refusals (`code` and when), and what the
   system only warns about and what the action does then. Read the description before mapping your
@@ -56,7 +56,7 @@ curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" \
   -H "Authorization: Bearer $DEEPDOCK_API_KEY"
 ```
 
-Answers `{ data: [ { name, operation, description, input, output } ] }`, filtered to your assigned
+Answers `{ data: [ { name, operation, method, description, input, output } ] }`, filtered to your assigned
 actions, with the same JSON Schemas the OpenAPI document carries. Use it at runtime to confirm an
 action exists before offering it in your UI, or to validate input client-side before sending.
 

package/skill/references/errors.md

@@ -17,16 +17,16 @@ with the **same** `Idempotency-Key`); **Show** says what the end user should see
 
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
-| `invalid_request` | 400 (405 for a method but `POST`) | malformed request: bad `limit` or `cursor` in a read's body; missing or malformed `Idempotency-Key`; a body that is not an object; an action input that is unknown, missing, too short or long, out of bounds or not an allowed value (`fields` names each); a malformed pairing code or device id; a query string on an action path (inputs go in the JSON body), an input of the wrong type, such as `"4711"` where an integer is declared, an action called with any method but `POST` (`405`, `Allow: POST`) | no; fix the code | nothing; a developer bug |
+| `invalid_request` | 400 (405 for a method other than the action's own) | malformed request: bad `limit` or `cursor` in a read's body; missing or malformed `Idempotency-Key`; a body that is not an object; an action input that is unknown, missing, too short or long, out of bounds or not an allowed value (`fields` names each); a malformed pairing code or device id; a query string on an action path (inputs go in the JSON body), an input of the wrong type, such as `"4711"` where an integer is declared, an action called with a method other than its own (`405`, `Allow` names the one: `POST` for a read or create, `PATCH` for an update) | no; fix the code | nothing; a developer bug |
 | `payload_too_large` | 413 | the request body is over 1 MiB | no; send less | nothing; a developer bug, or shorten the text |
 | `unauthenticated` | 401 | the key is missing, malformed, for the other environment, unknown, revoked or expired | no | "Deepdock API key refused; check it in the dashboard" to an operator |
 | `partner_not_approved` | 403 | your organisation is waiting for approval by Deepdock; no key of it works yet. Keys made before the approval start working once it is given | no, until Deepdock approves; then yes | "our Deepdock account is waiting for approval; contact Deepdock" |
 | `not_found` | 404 | no such route; an update whose id matches no record; a write naming a record that does not exist or belongs to another one | no | "record not found" when it is a record; otherwise a bug |
 | `rate_limited` | 429 | more than 600 calls, or more than 120 writes (counted in both), with this key in a minute; or more than 5 failed pairing claims in 60 s | yes, after `Retry-After: 60` (`retryAfterSeconds: 60` in the body); a write keeps its key. The pairing claim answer has neither: wait up to a minute | "try again in a minute" |
 
-Codes your `/v1` code never receives, listed so the enum is complete: `organization_required`
-(403), `forbidden` (403), `conflict` (409), `already_member` (409) and `client_outdated` (400) are
-dashboard-only.
+`client_outdated` (400) is in the enum but answered only to the Deepdock CLI (by its
+`X-Deepdock-Cli` version), so your own `/v1` code never receives it. The dashboard tree's own codes
+(`organization_required`, `forbidden`, `conflict`, `already_member`) are not in the `/v1` enum.
 
 ## Device, system and action resolution
 

package/skill/references/example-integration.md

@@ -23,7 +23,7 @@ import { Deepdock, DeepdockError, DeepdockTransportError, attempt, type PendingW
 const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // base from DEEPDOCK_BASE_URL, else production; 30 s timeout
 const page = await dd.read<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' }, { limit: 50 })
 for await (const p of dd.readAll<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' })) { /* every page */ }
-const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', key, input)
+const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', 'create', key, input)
 const systems = await dd.systems(deviceId)                      // live; can throw device_offline
 const device = await dd.pair('K7Q-4MX', 'Demo')                 // keep device.id
 ```
@@ -33,7 +33,7 @@ from deepdock import Deepdock, DeepdockError, DeepdockTransportError, PendingWri
 
 dd = Deepdock(os.environ["DEEPDOCK_API_KEY"])
 page = dd.read(device_id, "example-erp", "searchNotes", {"text": "TEST-DEEPDOCK-"}, limit=50)
-res = dd.write(device_id, "example-erp", "createNote", key, body)   # res.data, res.replayed
+res = dd.write(device_id, "example-erp", "createNote", "create", key, body)   # res.data, res.replayed
 ```
 
 Errors: `DeepdockError` has `status`, `code`, `requestId`, `systems`; switch on `code`
@@ -42,7 +42,7 @@ Errors: `DeepdockError` has `status`, `code`, `requestId`, `systems`; switch on
 
 ## Sending a write: persist first, then one attempt at a time
 
-Persist the pending write (key, device, action, input, status) **before** the first send,
+Persist the pending write (key, device, action, operation, input, status) **before** the first send,
 so a crash between send and answer cannot produce a second record under a new key. `attempt()`
 moves the row to `done`, `sent` (retry later, same key), `unknown` (read back before anything
 else) or `refused` (nothing was written; a changed input gets a new key). A job retries `sent`
@@ -51,7 +51,7 @@ rows with backoff: seconds, then minutes, for hours if the device stays offline.
 ```ts
 const row: PendingWrite = {
   key: `order-${order.id}-create-note`, // 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event
-  deviceId, system: 'example-erp', action: 'createNote',
+  deviceId, system: 'example-erp', action: 'createNote', operation: 'create',
   input, status: 'pending', conflictRetries: 0,
 }
 await store.save(row)                      // before the first send
@@ -74,7 +74,7 @@ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
 export const run = async (store: { save: (row: PendingWrite) => Promise<void> }) => {
   const marker = `TEST-DEEPDOCK-${randomUUID().replaceAll('-', '').slice(0, 6).toUpperCase()}`
   let row: PendingWrite = {
-    key: `demo-${marker}-create`, deviceId, system, action: 'createNote',
+    key: `demo-${marker}-create`, deviceId, system, action: 'createNote', operation: 'create',
     input: { text: marker, orderNumber: '1001' },
     status: 'pending', conflictRetries: 0,
   }
@@ -132,8 +132,8 @@ curl -sS -i -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/create
   -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-create" -H 'Content-Type: application/json' \
   -d '{"text":"TEST-DEEPDOCK-K3M9QA","orderNumber":"1001"}'
 
-# An update: also POST, same rules
-curl -sS -i -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/updateNote" \
+# An update: PATCH, same rules
+curl -sS -i -X PATCH "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/updateNote" \
   -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-update" -H 'Content-Type: application/json' \
   -d '{"noteId":1001,"text":"TEST-DEEPDOCK-K3M9QA edited"}'
 
@@ -143,7 +143,7 @@ curl -sS -X DELETE "$BASE/v1/devices/$DEVICE" -H "$AUTH"
 
 A port in another language keeps the clients' shape: one `send` that sets the bearer header,
 parses the envelope, throws a typed error with `code` on `{ error }` and a transport error on no
-answer or non-JSON; `read` as a POST with `limit` and `cursor` in the body; `write` with `Idempotency-Key` and the
+answer or non-JSON; `read` as a POST with `limit` and `cursor` in the body; `write` (POST for a create, PATCH for an update) with `Idempotency-Key` and the
 `Idempotent-Replayed` header; `attempt` over a persisted pending write.
 
 ## Mapping the user's intent to a call (checklist)
@@ -151,7 +151,7 @@ answer or non-JSON; `read` as a POST with `limit` and `cursor` in the body; `wri
 1. Which device? From your product's configuration for that customer site; never from the
    user's free text.
 2. Is the action active? `systems()` once per session; show paused features as paused.
-3. Which action and operation? From the stored index for that system.
+3. Which action and operation (create is POST, update is PATCH)? From the stored index for that system.
 4. Does the write need a reference (author user, open case, record id)? Read it first.
 5. Build the input in the types the schema declares; validate against the schema (`pattern`, `minLength`, `maxLength`,
    `enum`) before sending so the user sees the rule where they typed.

package/skill/references/idempotency.md

@@ -1,6 +1,6 @@
 # Idempotency for writes
 
-Every write (a `create` or `update` action, called with `POST`) carries an `Idempotency-Key` header. Without it the request is
+Every write (a `create` action, called with `POST`, or an `update`, called with `PATCH`) carries an `Idempotency-Key` header. Without it the request is
 refused with `400 invalid_request`. A read ignores the header.
 
 ## The key