@codecks/fetch 1.0.1 → 2.0.1

package/README.md

@@ -13,7 +13,7 @@ npm install @codecks/fetch
 ```ts
 import {buildFetchers} from "@codecks/fetch";
 
-const {fetchFromRoot, fetchInstance, fetchInstances, fetchFromInstance} = buildFetchers({
+const {fetchFromRoot, fetchInstance, fetchInstances, fetchFromInstance, dispatch} = buildFetchers({
   token: "cdxat_…",
 });
 ```
@@ -61,7 +61,7 @@ before then.
 
 ### `fetchFromRoot` — query top-level relations
 
-Use this to query entry points like `account`, `loggedInUser`, or `releases`.
+Use this to query the entry points `account`, `loggedInUser` and `releases`.
 
 ```ts
 const result = await fetchFromRoot({
@@ -105,9 +105,8 @@ const account = result.account;
 // account has { ~model: "account", ~key: "1" }
 
 const details = await fetchFromInstance(account, {
-  fields: ["seats", "activeProjectCount"],
   relations: {
-    roles: {fields: ["role"]},
+    projects: {fields: ["name"]},
   },
 });
 ```
@@ -121,22 +120,19 @@ const result = await fetchFromRoot({
   account: {
     fields: ["name"],
     relations: {
-      // belongsTo — returns a single object (or null if optional)
-      disabledBy: {fields: ["name"]},
-
       // hasMany — returns an array
-      roles: {
-        fields: ["role"],
+      cards: {
+        fields: ["title"],
         relations: {
-          user: {fields: ["name", "fullName"]},
+          // belongsTo — returns a single object (or null if optional)
+          assignee: {fields: ["name", "fullName"]},
         },
       },
     },
   },
 });
 
-// result.account.disabledBy?.name
-// result.account.roles[0].user.name
+// result.account.cards[0].assignee?.name
 ```
 
 ## hasMany variants
@@ -147,32 +143,32 @@ hasMany relations support several query modes. Non-default variants require an `
 
 ```ts
 relations: {
-  roles: {
-    fields: ["role"],
-    orderBy: "-accountId",
+  cards: {
+    fields: ["title"],
+    orderBy: "-createdAt",
     limit: 10,
     offset: 0,
   },
 }
-// result.roles: Array<{role: string, ...}>
+// result.cards: Array<{title: string, ...}>
 ```
 
 ### Count
 
 ```ts
 relations: {
-  roles: {type: "count", as: "roleCount"},
+  cards: {type: "count", as: "cardCount"},
 }
-// result.roleCount: number
+// result.cardCount: number
 ```
 
 ### Exists
 
 ```ts
 relations: {
-  releases: {type: "exists", as: "hasReleases"},
+  cards: {type: "exists", as: "hasCards"},
 }
-// result.hasReleases: boolean
+// result.hasCards: boolean
 ```
 
 ### First
@@ -181,14 +177,14 @@ Returns a single result or `null`. Requires `orderBy`.
 
 ```ts
 relations: {
-  roles: {
+  cards: {
     type: "first",
-    as: "firstRole",
-    orderBy: "-accountId",
-    fields: ["role"],
+    as: "newestCard",
+    orderBy: "-createdAt",
+    fields: ["title"],
   },
 }
-// result.firstRole: {role: string, ...} | null
+// result.newestCard: {title: string, ...} | null
 ```
 
 ### Multiple queries on the same relation
@@ -197,13 +193,13 @@ Pass an array of aliased queries to query the same relation in different ways:
 
 ```ts
 relations: {
-  roles: [
-    {as: "adminRoles", fields: ["role"], filter: {role: "admin"}},
-    {as: "roleCount", type: "count"},
+  cards: [
+    {as: "startedCards", fields: ["title"], filter: {status: "started"}},
+    {as: "cardCount", type: "count"},
   ],
 }
-// result.adminRoles: Array<...>
-// result.roleCount: number
+// result.startedCards: Array<...>
+// result.cardCount: number
 ```
 
 ## Filtering
@@ -231,7 +227,7 @@ filter: {
 
 ```ts
 filter: {
-  createdAt: {op: "gt", value: "2025-01-01"},
+  createdAt: {op: "gt", value: new Date("2025-01-01")},
   effort: {op: "lte", value: 5},
 }
 ```
@@ -328,14 +324,62 @@ const card = await fetchInstance("card", "card-123", {
 
 All response types are fully inferred from your query — TypeScript knows exactly which fields and relations are present.
 
+## Writing data
+
+Every change is an action of the API, called with `dispatch(name, params)`. The name is the one
+the [API Reference](https://manual.codecks.io/api-reference/#actions) lists, and the params and the
+response are typed from it.
+
+```ts
+const {id, accountSeq} = await dispatch("cards/create", {content: "Fix login\nDetails…", deckId});
+await dispatch("cards/update", {id, status: "done", assigneeId: null});
+```
+
+- **Optional and nullable params**: left out, a value stays as it is; `null` clears it.
+- **Enums in params are closed**: `status: "snoozing"` is a type error, since the API only accepts
+  the listed values. Enums the API answers stay open, see [Field types](#field-types).
+- **Response**: an action without one resolves to `undefined`.
+- **Errors**: a refused action throws a `CodecksApiError` with the reason as its message, e.g.
+  `[403] requires card:write` for a read-only token. A missing scope has the `code`
+  `missing_scope` and the scope in `body.requiredScope`.
+
+Each action's JSDoc holds its description and the token scopes it needs. `ActionMap`,
+`ActionName`, `ActionParams<N>` and `ActionResponse<N>` are exported for wrapping `dispatch`.
+
+`dispatch` doesn't change what the `fetch*` functions return: they always ask the API again.
+
+## Stability
+
+The models and fields in this package are the ones the [API Reference](https://manual.codecks.io/api-reference/) documents. The API answers more than that, but anything undocumented is internal and can change without notice, so this package leaves it out.
+
+- **stable** — changes only after a deprecation and 6 months' notice, see [Stability](https://manual.codecks.io/api/#stability).
+- **preview** — may change in any release, listed in the [API changelog](https://manual.codecks.io/api-changelog/). The types mark these `@experimental`.
+- **deprecated** — the types mark these `@deprecated`, with the removal date and what to use instead, so editors strike them through.
+
+## Field types
+
+Field types come from the API Reference's schemas.
+
+- **Enums are open unions**: `card.status` is `"not_started" | "started" | "snoozing" | "done" | (string & {})`. The values autocomplete, but the API may add new ones, so a `switch` over one isn't exhaustive. Keep a `default` branch.
+- **Ids are nominal**: `CardId`, `UserId`, … can't be mixed up, also inside arrays and maps (`card.mentionedUsers: UserId[]`, `milestone.userCapacities: {[userId: UserId]: number}`).
+- **Dates**: a top-level timestamp is a `Date`, a day is `{year, month, day}`, except a day that is part of a key (`milestoneProgress.date`), which stays a string. Inside a json value (e.g. an entry of an array field) they stay ISO strings.
+
+The reference's named types and every id type are exported, so you can use them in your own code:
+
+```ts
+import type {CardId, Checkbox, Priority, UserId} from "@codecks/fetch";
+```
+
 ## Schema reference for LLMs
 
-This package ships with generated markdown files describing every API model, its fields, and relations. These are designed for LLM-based tools (Claude Code, Cursor, Copilot, etc.) that need to discover the API schema without relying on TypeScript autocomplete.
+This package ships with generated markdown files describing every documented API model, its fields, and relations, with the same stability markers. These are designed for LLM-based tools (Claude Code, Cursor, Copilot, etc.) that need to discover the API schema without relying on TypeScript autocomplete.
 
 ```
 node_modules/@codecks/fetch/schema/
   overview.md          # Root entry points + index of all models
   query-syntax.md      # Query DSL reference with examples
+  types.md             # Named types (Priority, Checkbox, ...) the model files link to
+  actions.md           # Every action with its params, response and required scopes
   models/
     card.md            # Fields + relations for the card model
     account.md         # Fields + relations for the account model
@@ -356,5 +400,9 @@ const {fetchFromRoot} = buildFetchersFromLoader({
     // your custom loading logic
     return recordOfResults;
   },
+  dispatch: async (name, params) => {
+    // POST params to `dispatch/${name}`, return the answer's `payload`
+    return payload;
+  },
 });
 ```

package/dist/_exploration/api-requester.d.ts

@@ -1,7 +1,6 @@
-import "../query-type-BqQ9oX_U.js";
-import "../index-k-KPWV9R.js";
-import { FetchOptions } from "../loader-utils-hvdC-xsQ.js";
-import { BaseRequester, MissingDataRequest } from "../loader-types-fd5tV0FD.js";
+import "../query-type-CwrwqxUP.js";
+import { FetchOptions } from "../loader-utils-DdrmVo0F.js";
+import { BaseRequester, MissingDataRequest } from "../loader-types-CIO8hJAv.js";
 
 //#region src/_exploration/api-requester.d.ts
 declare class ApiRequester implements BaseRequester {

package/dist/_exploration/api-requester.js

@@ -1,5 +1,5 @@
-import { bearerTransport, configuredFetch, ensureMapValue } from "../collection-utils-KmtGUuXm.js";
-import { serializeModel } from "../query-helpers-iX1fiqLv.js";
+import { bearerTransport, configuredFetch, ensureMapValue } from "../collection-utils-y85xawyq.js";
+import { serializeModel } from "../query-helpers-DndWBcMF.js";
 
 //#region src/_exploration/utils/concurrency-limiter.ts
 var ConcurrencyLimiter = class {