@cube-nl/dmp-sdk 0.0.0-stage → 1.0.0-rc.4

package/README.md

@@ -1,3 +1,721 @@
-# Temporary Holding Version
+# @cube-nl/dmp-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Nederlands.** De TypeScript-SDK voor het DMP: één client waarmee een app de REST-API van
+`cube/api` aanroept, in de browser of in Node 20+. Zonder runtime-dependencies: alleen `fetch`,
+`URL` en Web Crypto. Hij spreekt precies de wire-format van `cube/api` op `5.0.x` —
+`page[size]`/`page[number]`, `filter[veld][operator]`, `If-Match` met `X-Dmp-Record-Version`,
+`Idempotency-Key` — en gooit elke weigering als een `DmpError` met de stabiele `code` en de
+`reason` van de API. Inloggen gaat met OAuth 2.1 + PKCE (S256) tegen `cube/oauth-server`, of met
+een persoonlijk token voor een PoC. Het token blijft standaard alleen in het geheugen.
+
+Dit pakket vervangt `dmp.js` en `oauth.js` uit de hackathon-starter van `cube/resources`
+(`docs/hackathon/starter/public/`): dezelfde logica, getypt en getest. Het staat openbaar op npm:
+`npm install @cube-nl/dmp-sdk@next` (zolang het een release candidate is), of als losse
+`cube-sdk.js` via jsDelivr of unpkg.
+
+Besluit OP-05: **één client, resources als eigenschap** —
+`createClient(...).resources('projects').list()`, geen ingang per soort.
+
+---
+
+The rest of this document is in English.
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Authentication](#authentication)
+- [Reading](#reading)
+- [Writing](#writing)
+- [Custom operations](#custom-operations)
+- [Errors](#errors)
+- [Voor AI-tools](#voor-ai-tools)
+- [Route B: apps without a build step](#route-b-apps-without-a-build-step)
+- [What this SDK deliberately does not do](#what-this-sdk-deliberately-does-not-do)
+- [Development](#development)
+- [Integration tests](#integration-tests)
+
+## Install
+
+Published on the public npm registry as [`@cube-nl/dmp-sdk`](https://www.npmjs.com/package/@cube-nl/dmp-sdk):
+
+```bash
+npm install @cube-nl/dmp-sdk@next   # while 1.0.0 is a release candidate
+npm install @cube-nl/dmp-sdk        # once a stable version is out
+```
+
+Release candidates go to the `next` dist-tag, stable versions to `latest`. The package is an ES
+module with its own `.d.ts`; there is no CommonJS build.
+
+For an app without a build step, the single-file browser build is on the npm CDNs. Pin an exact
+version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@cube-nl/dmp-sdk@1.0.0-rc.4/dist/cube-sdk.js"></script>
+<!-- or -->
+<script src="https://unpkg.com/@cube-nl/dmp-sdk@1.0.0-rc.4/dist/cube-sdk.js"></script>
+```
+
+Fallback, for an unreleased commit: `npm install
+git+ssh://git@gitlab.cube.nl/cube/packages/laravel/filament/dmp/sdk-js.git#5.0.x` (needs access to
+our GitLab; `prepare` builds `dist/`).
+
+## Quick start
+
+These ten lines ran as they are (24-09-2026, Node 24, installed from `npm pack`) against the
+hackathon demo DMP on `127.0.0.1:8000`, with a personal token in `DMP_TOKEN`:
+
+```js
+import { createClient } from '@cube-nl/dmp-sdk';
+
+const dmp = createClient({ baseUrl: 'http://127.0.0.1:8000/apps/api/v1', auth: process.env.DMP_TOKEN });
+
+const { resources } = await dmp.capabilities();                  // always first
+console.log(resources.map((resource) => resource.name));         // [ 'tasks', 'projects' ]
+
+const projects = await dmp.resources('projects').list({
+    fields: ['id', 'name', 'budget'], filter: { status: 'actief' }, sort: '-budget', page: { size: 3 },
+});
+console.log(projects.data, projects.meta.page);                  // rows, { size, number, total, pages }
+```
+
+```text
+[ 'tasks', 'projects' ]
+[ { id: 2, name: 'App', budget: 30000 }, { id: 1, name: 'Website', budget: 12000 }, … ] { size: 3, number: 1, total: 8, pages: 3 }
+```
+
+In a browser app the token comes from the OAuth session instead (see
+[Authentication](#authentication)), and `baseUrl` is the "Base URL" on the panel's API → Connect
+screen. Besides `data` and `meta.page`, show `meta.omitted` (relations you asked for and may not
+see) as missing, not as empty.
+
+`baseUrl` includes the API prefix (`apps/api/v1` unless the host changed `cube-apps.faces.rest.prefix`). A relative
+one (`/apps/api/v1`) works in a browser behind a dev-server proxy.
+
+### `createClient(options)`
+
+| Option | Meaning |
+|---|---|
+| `baseUrl` | Required. The API base URL, prefix included |
+| `auth` | A token string, a function returning one (read on every call), `bearer(...)`, or an OAuth session from `createOAuth()`. Omitted: no `Authorization` header |
+| `fetch` | Your own `fetch` (a proxy wrapper, a test double). Default: the global one |
+| `headers` | Sent on every request. `X-Dmp-Act-As` goes here — on a server, never in a browser |
+| `cache` | The fetch cache mode. Default `'no-cache'` in a browser (revalidate with the ETag instead of serving a stale list after a write), unset in Node |
+| `onResponse` | `({ method, url, status, ms }) => void` for every call. Never receives the token |
+
+It returns `{ capabilities(), resources(name), request(method, path, options) }`.
+
+## Authentication
+
+Every request carries `Authorization: Bearer <token>`. The API refuses a browser session cookie.
+
+### OAuth 2.1 + PKCE (the right way for an app)
+
+```ts
+import { createClient, createOAuth } from '@cube-nl/dmp-sdk';
+
+const oauth = createOAuth({
+    issuer: 'https://dmp.example.nl',             // discovery: {issuer}/.well-known/oauth-authorization-server
+    clientId: import.meta.env.VITE_DMP_CLIENT_ID,
+    redirectUri: 'http://localhost:5173/callback',// exactly as registered: scheme, host, port, path
+    scopes: ['api:read', 'api:write'],            // api:write does not include api:read
+});
+
+const dmp = createClient({ baseUrl: 'https://dmp.example.nl/apps/api/v1', auth: oauth });
+
+// On every page load: null when this is not the callback.
+await oauth.handleCallback();
+
+if ((await oauth.getTokens()) === null) {
+    await oauth.signIn();                         // navigates away to the DMP's consent screen
+}
+```
+
+What it does, following `cube/oauth-server` and the starter's `oauth.js`:
+
+- **Discovery** (RFC 8414), once, cached; a failed discovery is not cached. The endpoints are read
+  from there, never hardcoded. Pass `metadata` to skip it.
+- **S256 or nothing.** A server that does not list `S256` in `code_challenge_methods_supported`
+  is refused before the browser leaves.
+- **Only the `redirectUri` is a callback.** On any other page `handleCallback()`
+  answers `null` and touches nothing, so an app route with a `?code=` or `?error=` of its own keeps
+  working and a pending sign-in survives it.
+- **The verifier and state** go to `sessionStorage` (or `pendingStore`), are used once and removed
+  the moment a matching callback is handled. A callback whose `state` was not sent from here is
+  refused without a token request, and an `?error=` is checked against the state too before it is
+  reported; neither cancels the pending sign-in. In a browser, `handleCallback()` also removes
+  `code` and `state` from the address bar.
+- **The code exchange and refresh** are form-encoded `POST`s to `token_endpoint`.
+- **`metadata` overrides, it does not have to replace.** Pass the whole document (with
+  `authorization_endpoint` and `token_endpoint`) to skip discovery, or only the members you want
+  changed on top of what discovery returns.
+- **Tokens stay in memory** unless you pass a `tokenStore`. Reloading the page means signing in
+  again (usually without a prompt, since the person is still logged in at the DMP).
+- **Refresh** happens 30 seconds before expiry (`refreshLeewaySeconds`), and once on a `401`,
+  after which the request is retried once. Concurrent callers share one refresh. A refused refresh
+  token is forgotten.
+
+| Session method | |
+|---|---|
+| `discover()` | The authorization server metadata |
+| `authorizationUrl({ state?, extraParams? })` | Build the URL yourself (Node, or a custom redirect) |
+| `signIn({ extraParams? })` | Browser: go to that URL |
+| `handleCallback(url?)` | Exchange the code; `null` when `url` is not the `redirectUri` with a `code` or `error` |
+| `refresh()` | Force a refresh |
+| `getTokens()` / `setTokens(tokens)` | Read or seed the store |
+| `signOut()` | Forget the tokens (this does not revoke them at the DMP; the person does that under *Verbonden apps*) |
+
+`registerClient(metadata, { clientName, redirectUris })` does RFC 7591 self-registration when the
+DMP turned it on (`registration_endpoint` is in discovery), and returns a public `client_id`.
+
+A **confidential** client (`clientSecret`) is for a server only. Anything in a browser bundle is
+public; a browser app is a public client and PKCE is its proof.
+
+#### In a browser on another origin: CORS
+
+`cube/api` answers CORS on its own prefix when the host turns it on (`DMP_API_CORS`,
+`DMP_API_CORS_ORIGINS`), and exposes every header this SDK reads. The OAuth endpoints do not:
+`/.well-known/oauth-authorization-server` and `/oauth/token` send no CORS headers (checked against
+`cube/oauth-server` 5.0.0-rc.1). A page on `localhost:5173` can therefore not discover or exchange a
+code directly; the browser refuses it with a `TypeError`. Let the dev server forward those two
+paths to the DMP (the hackathon starter does exactly that) and point the SDK at its own origin:
+
+```ts
+const oauth = createOAuth({
+    issuer: location.origin,                      // discovery through the proxy
+    metadata: { token_endpoint: '/oauth/token' }, // the exchange and refresh through the proxy too
+    clientId, redirectUri, scopes: ['api:read'],
+});
+```
+
+The `authorization_endpoint` stays the DMP's own: that one is a navigation, not a `fetch`.
+
+Token limits the API applies to an OAuth token: it reaches **no custom operation**, not even with
+`*`; `X-Dmp-Act-As` is ignored; the scope never opens more than the person may.
+
+### A personal token or an API-client token
+
+```ts
+import { bearer, createClient } from '@cube-nl/dmp-sdk';
+
+createClient({ baseUrl, auth: process.env.DMP_TOKEN });          // a string
+createClient({ baseUrl, auth: () => tokenFromSomewhere() });      // read on every call
+createClient({ baseUrl, auth: bearer(() => vault.get('dmp')) });  // the same, explicitly
+```
+
+A personal token (`$user->createToken('poc', ['projects.list'])->plainTextToken`) in a browser app
+ends up in the bundle: PoC only. An API-client token that holds `_api.act_as` must never reach a
+browser at all.
+
+Your own strategy is any object with `getAccessToken()` and, optionally, `onUnauthorized()`
+(resolve `true` to have the request retried once).
+
+## Reading
+
+`dmp.resources<T>(name)` returns a client for one resource. The name must match
+`[a-z][a-z0-9_]*`, as the API's does. Pass your own record type as `T` if you have one; the default
+is `Record<string, unknown>`.
+
+### `list(query?)` — `GET /{resource}`
+
+| Query | Wire | Notes |
+|---|---|---|
+| `fields: ['id', 'name']` | `fields[projects]=id,name` | Default: the resource's `summary`. An object writes one entry per resource, but `cube/api` reads only the queried resource's: an included relation always comes with its own summary |
+| `filter: { active: true }` | `filter[active]=1` | Plain equality; booleans as `1`/`0` |
+| `filter: { hours: '>=8' }` | `filter[hours]=>=8` | The six prefixes `=`, `<>`, `>`, `>=`, `<`, `<=` |
+| `filter: { hours: { gte: 8, lte: 10 } }` | `filter[hours][gte]=8&filter[hours][lte]=10` | Named operators: `eq neq gt gte lt lte in like ilike is between` |
+| `filter: { status: { in: ['a', 'b'] } }` | `filter[status][in]=a,b` | `in` and `between` take an array |
+| `filter: { left_at: { is: 'not_null' } }` | `filter[left_at][is]=not_null` | `is` takes `'null'`, `'not_null'` or `null` |
+| `sort: ['-name', 'id']` | `sort=-name,id` | `-` for descending |
+| `page: { size: 25, number: 2 }` | `page[size]=25&page[number]=2` | Default 50, max 200. Above the max is a 422, never a clamp |
+| `include: 'customer'` | `include=customer` | One level deep, scoped by the target's rules |
+| `withCount: 'tasks'` | `with_count=tasks` | Adds `tasks_aantal` to each row; sortable |
+| `has: { tasks: true }` / `{ tasks: 2 }` / `{ tasks: { min, max } }` | `has[tasks]=1` / `has[tasks][min]=2` / … | Rows whose relation holds at least/at most |
+| `params: { 'x': '1' }` | `x=1` | Raw, appended last, for anything newer than this SDK |
+
+Filters combine with AND; there is no OR, `in` stands in for it. Two mistakes are thrown as a
+`TypeError` before any request: a bare array (`filter: { status: ['a', 'b'] }` — the API refuses
+`filter[status][]=` because it names no operator), and an array under an operator that takes one
+value.
+
+The answer is a `ListResponse<T>`:
+
+| Field | |
+|---|---|
+| `data` | The rows |
+| `meta.page` | `{ size, number, total, pages }` — `total` is the whole filtered set, not this page |
+| `meta.omitted` | Requested relations that came back with no data: show them as missing, not empty |
+| `meta.pruned` | Relations delivered but not guaranteed complete: "not everything visible", not a total |
+| `meta.forbidden_fields` | Fields withheld from an otherwise normal 200 |
+| `etag` | Weak representation validator (`If-None-Match`), **never** for `If-Match` |
+| `rateLimit` | `{ limit, remaining, reset }` from the `X-RateLimit-*` headers |
+| `status`, `headers` | As received |
+
+### `pages(query?)` and `all(query?)`
+
+Async generators that walk `meta.page` with the same query, one request per page, stopping at the
+last page (or an empty one). Pagination on the API is mandatory and has no "fetch everything"; these
+make it explicit that you are asking for many requests. Mind the rate limit.
+
+```ts
+for await (const project of dmp.resources('projects').all({ page: { size: 200 } })) { … }
+```
+
+### `get(id, query?)` — `GET /{resource}/{id}`
+
+Accepts only `fields`, `include` and `withCount`. The answer's `recordVersion` is the strong
+validator for a later `update`/`delete`. A row outside your scope is a `404 not_found`, exactly
+like one that does not exist.
+
+An empty id, `.` or `..` is refused before a request is made: the URL parser would resolve the
+last two as path steps and send the request to another endpoint. The same holds for operation names.
+
+### `aggregate({ fn, group?, filter?, has? })` — `GET /{resource}/_aggregate`
+
+```ts
+const { data, meta } = await dmp.resources('employees').aggregate({
+    fn: ['count', 'sum(hours)'],
+    group: ['department_id', 'started_on.month'],
+    filter: { active: true },
+});
+data[0]['sum(hours)'];   // keyed by exactly the strings you sent
+meta.groups;             // meta.page is null: aggregates do not paginate
+```
+
+Functions: `count` (bare, or on a field), `sum`, `avg`, `min`, `max`, per field as
+`_capabilities.resources[].aggregatable` allows. Truncations: `.day`, `.week` (ISO), `.month`,
+`.quarter`, `.year`. A field you may not read is a `403 field_forbidden` here, not withheld.
+
+### `capabilities()` — `GET /_capabilities`
+
+Returns `Capabilities`: `contract`, the `resources` this token and this user may reach (fields
+with type/nullable/readonly, actions, operations, summary, filterable, sortable, groupable,
+aggregatable, relations, countable), plus `operators`, `operator_symbols`, `aggregations` and
+`pagination`. A resource you hold no ability for is simply absent. Build UIs and queries from this,
+not from assumptions.
+
+## Writing
+
+```ts
+import { newIdempotencyKey } from '@cube-nl/dmp-sdk';
+
+const projects = dmp.resources('projects');
+
+const key = newIdempotencyKey();                               // one per logical create
+const created = await projects.create({ name: 'X' }, { idempotencyKey: key });
+created.status;         // 201
+created.location;       // https://dmp.example.nl/apps/api/v1/projects/7
+created.recordVersion;  // for the next conditional write
+created.replayed;       // true when this is the stored answer to an earlier attempt with this key
+
+const updated = await projects.update(7, { name: 'Y' }, { ifMatch: created.recordVersion });
+await projects.delete(7, { ifMatch: updated.recordVersion });  // 204 → data: null
+```
+
+| Method | Wire | Options |
+|---|---|---|
+| `create(body, opts?)` | `POST /{resource}` → 201 | `idempotencyKey`, `fields` |
+| `update(id, body, opts?)` | `PATCH /{resource}/{id}` → 200, partial | `ifMatch`, `fields` |
+| `delete(id, opts?)` | `DELETE /{resource}/{id}` → 204 | `ifMatch` |
+
+- **`ifMatch` is `recordVersion` (`X-Dmp-Record-Version`), never the `etag`.** A weak tag (`W/"…"`)
+  is thrown as a `TypeError` before sending: the API would refuse it with a 409 anyway. `'*'` means
+  "must still exist". A stale version is a `409 conflict`, and the error carries the current
+  `recordVersion` so you can re-read or retry.
+- **`idempotencyKey`**: retrying with the same key and the same body replays the first 201
+  (`replayed: true`) instead of writing twice. The same key with a different body is a
+  `422 validation_failed`. `fields` is part of what "the same request" means — repeat it. A
+  replay's `recordVersion` is the version at creation time; re-read before using it in `ifMatch`.
+- The SDK never retries a write by itself, except once after a `401` when the auth strategy got a
+  new token (a 401 wrote nothing).
+- `DELETE` is off on the server unless the host set `allow_delete`, whatever the schema says.
+
+## Custom operations
+
+```ts
+// POST /articles/42/publish
+const result = await dmp.resources('articles').operation(42, 'publish',
+    { publish_at: '2026-10-01T09:00:00Z' },
+    { idempotencyKey: newIdempotencyKey(), ifMatch: version });
+
+// POST /articles/_operations/import
+const job = await dmp.resources('articles').collectionOperation('import', { url }, { idempotencyKey: key });
+job.accepted;   // true on 202: queued, not done
+```
+
+| Status | `data` | `accepted` |
+|---|---|---|
+| 200 | the `output` resource's record | false |
+| 202 | `null` | true — queued, not done |
+| 204 | `null` | false — done, nothing to return |
+
+An operation `_capabilities` marks `idempotent: false` **requires** `idempotencyKey` (422 without
+it). A wildcard `*` token does not reach operations; the token needs `{resource}.{operation}` by
+name, and an OAuth token reaches none. Names starting with `_` are reserved and thrown as a
+`TypeError`.
+
+## Errors
+
+Every non-2xx answer throws a `DmpError`:
+
+```ts
+import { isDmpError } from '@cube-nl/dmp-sdk';
+
+try {
+    await dmp.resources('projects').list({ sort: 'nope' });
+} catch (error) {
+    if (isDmpError(error) && error.code === 'query_invalid' && error.reason === 'not_sortable') {
+        error.errors?.sort;   // ['Allowed values: …']
+    }
+}
+```
+
+| Field | |
+|---|---|
+| `status` | HTTP status |
+| `code` | The stable code (below), an OAuth `error` from the token endpoint, or `null` when the body was not a problem (a proxy's 502 page). **Decide on this** |
+| `reason` | The finer classification under `code` (`not_sortable`, `not_filterable`, `limit_too_high`, …), or `null` for "none finer" |
+| `type`, `title`, `detail` | RFC 9457 members. `detail` is for people; it is also `message` |
+| `errors` | Per field or parameter, e.g. `errors.sort`, `errors['Idempotency-Key']` |
+| `recordVersion` | On a 409 `conflict`: the record's current version |
+| `retryAfter` | Seconds, on a 429 `rate_limited` |
+| `allow` | On a 405 `unsupported_action`: the actions the resource does offer (`list`, `get`, …; `cube/api` names actions here, not HTTP methods). `null` in a browser on another origin: `Allow` is not a CORS-exposed header |
+| `headers`, `body`, `isProblem` | The raw material |
+
+The codes, exactly as `cube/api` emits them:
+
+| Status | `code` | Repair |
+|---|---|---|
+| 401 | `token_invalid` | Sign in again / present a valid token (the SDK already tried one refresh) |
+| 403 | `resource_forbidden` | The person's own rights say no — ask an administrator |
+| 403 | `client_scope_exceeded` | The token's abilities or scopes say no — reissue or ask consent for more |
+| 403 | `field_forbidden` | `_aggregate` on a field you may not read |
+| 403 | `client_inactive`, `client_without_user` | The `ApiClient` is off or unlinked |
+| 403 | `act_as_forbidden`, `act_as_unknown` | Act-as not allowed for this token, or unknown subject |
+| 404 | `not_found` | Does not exist, or is outside your scope — the API does not say which, on purpose |
+| 405 | `unsupported_action` | The resource does not do this; see `allow` |
+| 409 | `conflict` | Stale `ifMatch`: re-read (or use `error.recordVersion`) and retry |
+| 422 | `query_invalid` | A name the resource does not have; `errors` lists what it does have |
+| 422 | `validation_failed` | A value is wrong; `errors` per field. Also: an idempotency key reused with another body |
+| 422 | `cardinality_exceeded` | `page[size]` over the max, or too many groups |
+| 429 | `rate_limited` | Wait `retryAfter` seconds |
+
+A network failure (DNS, offline, CORS refused by the browser) is not a `DmpError`: it is the
+`TypeError` `fetch` itself throws, untouched, so it cannot be mistaken for an answer from the API.
+
+## Voor AI-tools
+
+**Nederlands.** Bouwt een AI-tool (Claude Code, Cursor, …) een app tegen een DMP, dan begint hij bij
+de MCP-server van dat DMP (`cube/apps`, `POST {dmp}/apps/mcp`) met de tool **`dmp.instructions`**. Die zegt
+hoe een app bij dit DMP inlogt (`authenticatie.oauth`, met het discovery-adres), wat de basis-URL
+van de API is (`de_api.basis_url`), welke regels en foutcodes er gelden, en wat de AI-tool zelf
+níét doet: de API aanroepen, of om rijen of een token vragen. Daarna `dmp.capabilities` en
+`dmp.describe` voor de vorm van de gegevens, en dan code schrijven die deze SDK gebruikt.
+
+The DMP's MCP server (`cube/mcp`) does not hand an AI agent any rows. It gives the **shape** —
+`dmp.capabilities`, `dmp.describe` per resource — and `dmp.instructions`: how an app built against
+this DMP signs in and calls the REST API. The agent's job is to **write code that uses this SDK**,
+running in the user's browser with the user's token; not to call the API itself.
+
+If you are an AI coding agent reading this:
+
+1. Call `dmp.instructions` first. Take `de_api.basis_url` as `baseUrl`, and
+   `authenticatie.oauth.discovery`'s origin as `issuer` when `authenticatie.oauth.beschikbaar` is
+   true. Otherwise use a personal token from an env variable (`VITE_DMP_TOKEN`), never inlined.
+   In a browser on another origin, discovery and the token endpoint go through the dev server's
+   proxy: see [CORS](#in-a-browser-on-another-origin-cors).
+2. Use `dmp.describe` for field names, types and filters. Use only what it (and, at runtime,
+   `dmp.capabilities()`) lists: an invented field or filter is a `422 query_invalid`, not a guess
+   the API will humour.
+3. Write:
+   ```ts
+   const oauth = createOAuth({ issuer, clientId, redirectUri, scopes: ['api:read'] });
+   const dmp = createClient({ baseUrl, auth: oauth });
+   await oauth.handleCallback();
+   const caps = await dmp.capabilities();
+   ```
+   and build the app's queries with `dmp.resources(name).list/get/aggregate(...)`.
+4. Handle `DmpError` by `code` using the table above. Show `meta.omitted`, `meta.pruned` and
+   `meta.forbidden_fields` to the user as "not visible to you", never as empty.
+5. Do not run the app's requests yourself, do not ask the user to paste rows or their token into
+   the conversation, and do not put a token in code or in the repo. The data does not go to the AI
+   vendor; that is the point of the design (ADR 0005).
+6. Ask only for the scopes the app needs: `api:read`, and `api:write` for writes (it does not
+   include `api:read`). `mcp:use` is for the MCP connection and opens nothing here.
+
+## Route B: apps without a build step
+
+**Nederlands.** Route B is de route voor niet-ontwikkelaars (cube/apps#38): Claude bouwt in
+Claude.ai of Claude Desktop een app van gewone HTML en JavaScript-modules, zonder `npm install` en
+zonder build. Zo'n app laadt `cube-sdk.js` met een script-tag en praat alleen via `CubeApp`. Zolang
+het DMP de app niet heeft gepubliceerd draait hij in de **previewstand**: nep-data in de browser,
+geen enkel verzoek naar een DMP. Na goedkeuring en publicatie schrijft het DMP
+`cube-app.config.json` naast de app, en dezelfde code draait **live**: de eindgebruiker logt in met
+OAuth (PKCE) en de app leest en schrijft echte gegevens, begrensd tot wat de app in zijn manifest
+vraagt en wat die persoon mag.
+
+### The page
+
+```html
+<!doctype html>
+<html lang="nl">
+<head>
+    <meta charset="utf-8">
+    <title>Uren invullen</title>
+    <script src="./cube-sdk.js"></script>
+    <script type="module" src="./app.js"></script>
+</head>
+<body>
+    <main id="app"></main>
+</body>
+</html>
+```
+
+```js
+// app.js — the same file in the preview and live
+const app = await CubeApp.connect();
+
+if (app.user() === null) {
+    document.querySelector('#app').innerHTML = '<button id="login">Inloggen</button>';
+    document.querySelector('#login').onclick = () => app.signIn();
+} else {
+    const { data, meta } = await app.resource('urenregel').list({
+        filter: { datum: { gte: '2026-09-28' } }, sort: '-datum', page: { size: 20 },
+    });
+    // render data; meta.page.total is the number of rows in the whole filtered set
+}
+```
+
+`cube-sdk.js` is a single classic script (an IIFE, no imports) that sets `window.CubeApp`. Do not
+send it with the app: the DMP adds the version it pins to every `dist/` it assembles. During the
+preview the page loads it from the same folder, wherever the preview runs.
+
+### The manifest: `cube-app.json`
+
+Required in the app's root. It declares what the app uses; the reviewer approves exactly that, and
+live the app's OAuth client is capped to it.
+
+```json
+{
+  "name": "Uren invullen",
+  "description": "Medewerkers vullen hun uren in voor de week.",
+  "uses": { "urenregel": ["list", "get", "create", "update"], "project": ["list"] },
+  "sdk": "1"
+}
+```
+
+`uses` keys are REST resource names from `_capabilities`, the values actions. `"sdk"` is
+`CubeApp.sdk` of the build the app was written against (`"1"`).
+
+### Preview and live
+
+`CubeApp.connect()` fetches `./cube-app.config.json` relative to the page.
+
+| | Preview | Live |
+|---|---|---|
+| When | `cube-app.config.json` is absent: a 404, a network failure, or a page that is not a JSON object (a dev server answering every path with `index.html`) | The file is there. Any other error status (a 500) rejects `connect()`, and a file missing a member rejects it with a `TypeError` naming it: a broken publish never turns into a quiet preview |
+| Data | Mock data: the `mock` option, else what `CubeApp.mock(data)` registered, else `./cube-mock.json`, else none (every resource is then a 404) | The DMP's REST face through `createClient`, as the signed-in person |
+| Network | Only the page's own folder: `cube-app.config.json`, `cube-mock.json`, `cube-app.json`. **Never a DMP** | Discovery, the authorize redirect, the token endpoint and the REST face |
+| User | A stand-in, `{ id: 'preview', name: 'Voorbeeldgebruiker', scopes: [] }`, signed in from the start | `null` until signed in, then `{ id, name: null, scopes }` from the access token |
+| Writes | Create, update and delete change the data in memory until the page reloads; the mock data passed in is never changed | Real writes |
+
+`cube-app.config.json` is written by the DMP when the Hub publishes an approved release, and only
+then. The maker and the AI never send it (the DMP refuses a submitted file with that name), so a
+preview cannot reach real data.
+
+```json
+{
+  "dmpUrl": "https://dmp.example.nl",
+  "clientId": "9f6c…",
+  "redirectUri": "https://apps.example.nl/uren-invullen/",
+  "scopes": ["api:read", "api:write"]
+}
+```
+
+| Member | |
+|---|---|
+| `dmpUrl` | Required. The DMP's origin; the OAuth issuer unless `issuer` is set |
+| `clientId` | Required. The app's public OAuth client |
+| `redirectUri` | Required. Absolute, or relative to the page; must equal the registered one exactly |
+| `scopes` | Required. A string or a list |
+| `apiUrl` | The REST base URL. Default `{dmpUrl}/apps/api/v1` |
+| `issuer` | Default `dmpUrl` |
+| `metadata` | Passed to `createOAuth`: endpoints on top of (or, complete, instead of) discovery; for a token endpoint behind a proxy, see [CORS](#in-a-browser-on-another-origin-cors) |
+
+#### The preview answers as the REST face does
+
+`app.resource(name)` returns the same `ResourceClient` as `createClient().resources(name)`, and in
+the preview it answers with the same envelope (`data`, `meta.page`, `recordVersion`, a header
+`X-Dmp-Preview: true`) and the same refusals as `DmpError`, so error handling written in the
+preview is the code that runs live. The query goes through `buildQuery` and is read back the way
+the REST face reads it:
+
+- `filter` with every operator (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `like`, `ilike`,
+  `is`, `between`) and the prefix form (`'>=4'`), values typed after the field; `like` is a
+  case-insensitive substring match where `%` is a wildcard and `_` a literal, as in the engine.
+  A field outside the schema's `filters` is `422 query_invalid` / `not_filterable`.
+- `sort` (several, `-` for descending; an unknown field is `not_sortable`), `page[size]` (default
+  50, above 200 `422 cardinality_exceeded`, never clamped) and `page[number]`.
+- `fields`; without it a row carries the schema's `summary_fields`, as on the REST face.
+- `get` of an id that is not there is `404 not_found`; an unknown resource `404 not_found`.
+- `create` and `update`: a key that is not writable (`id`, the schema's `readonly`) is
+  `422 query_invalid` per field; a value of the wrong declared type `422 validation_failed` with
+  Laravel's sentence per field; an empty body `422 validation_failed`. `ifMatch` with a stale
+  `recordVersion` is `409 conflict`; `idempotencyKey` replays the first answer.
+- `aggregate` with `count`, `count(f)`, `sum(f)`, `avg(f)`, `min(f)`, `max(f)`, grouped on fields
+  and on `.day`, `.week` (ISO, `2026-W23`), `.month`, `.quarter` (`2026-Q2`) and `.year`; a date-time is
+  bucketed by the date as written. A call needs `aggregate` in the manifest's `uses` (`list` alone no longer
+  suffices). Grouping is limited to the schema's `groupable` fields and a function to what `aggregatable` allows
+  (absent: every field, every function; a bare `count` is always allowed). Groups come ascending by their values,
+  nulls first; a `sum` of nothing is `null`; a whole-set aggregate over no rows answers one row. At most 5
+  dimensions and 1000 groups; a repeated entry is refused.
+- A field with `choices` in the schema: a value outside `values` (else the field's own `enum`) is
+  `422 validation_failed` ("The selected status is invalid."), and a choice that is not `writable` is read-only.
+- With a `cube-app.json` next to the page (or the `manifest` option), a call outside its `uses` is
+  `403 client_scope_exceeded`, as the live client is capped to it.
+- Signed out (`signOut()`), every call is `401 token_invalid`.
+
+What the preview cannot do: mock data names no relations, so an `include` or `withCount` comes back
+in `meta.omitted` (show it as "not visible", as live) and `has` is not applied; custom operations
+are `404 not_found`; `location` and `etag` are null.
+
+### Mock data
+
+The shape is `cube.mock_data`'s output as is: per REST resource the `dmp.describe` payload and the
+synthetic rows.
+
+```json
+{
+  "urenregel": {
+    "schema": {
+      "name": "urenregel",
+      "filters": ["project_id", "datum"],
+      "readonly": ["id"],
+      "summary_fields": ["id", "project_id", "datum", "uren"],
+      "fields": {
+        "id": { "type": "integer" },
+        "project_id": { "type": "integer" },
+        "datum": { "type": "string", "format": "date" },
+        "uren": { "type": "number" },
+        "omschrijving": { "type": ["string", "null"] }
+      }
+    },
+    "rows": [{ "id": 1, "project_id": 1, "datum": "2026-09-28", "uren": 8, "omschrijving": "Ontwerp" }]
+  }
+}
+```
+
+Ship it as `cube-mock.json` next to `index.html`, or register it in a script before the app's
+module runs: `CubeApp.mock({ ... })`. A resource without a `schema` takes its fields from its rows.
+
+The schema may also carry three keys that `cube.mock_data` writes: `groupable` (fields an aggregate may group on),
+`aggregatable` (per field, the functions allowed) and `choices` (per field, `{ "values": [...], "writable": true }`).
+Without them the preview is permissive: every field, every function; only a field's own `enum` is checked on writes.
+
+### `CubeApp` API
+
+| | |
+|---|---|
+| `CubeApp.connect(options?)` | `Promise<CubeAppSession>`. Options: `mock`, `manifest` (an object, or `false` to check nothing), `pageUrl` (default the page's URL), `fetch`, `tokenStorage` (`'session'`, the default, or `'memory'`), `autoSignIn` (default `false`) |
+| `CubeApp.mock(data)` | Registers preview data for the next `connect()`; `null` forgets it |
+| `CubeApp.version` | This SDK's version, e.g. `'1.0.0-rc.4'` |
+| `CubeApp.sdk` | The manifest `"sdk"` this build serves, `'1'` |
+| `session.mode` | `'preview'` or `'live'` |
+| `session.user()` | `{ id, name, scopes }` or `null` |
+| `session.signIn()` | Live: navigates to the DMP's sign-in. Preview: signs the stand-in in |
+| `session.signOut()` | Forgets the tokens in this browser (not a revocation). Preview: signs the stand-in out |
+| `session.resource(name)` | A `ResourceClient`: `list`, `pages`, `all`, `get`, `aggregate`, `create`, `update`, `delete`, `operation`, `collectionOperation` |
+| `session.signInError` | The error the last sign-in came back with (a refused consent: `code` `access_denied`), else `null`; `connect()` does not reject for it |
+
+Live, `connect()` handles the OAuth callback itself (on the `redirectUri`), so the redirect URI can
+be the app's own `index.html`. The tokens go to `sessionStorage` by default, unlike `createOAuth`'s
+memory default: a no-build app reloads often, and a redirect round trip on every reload is worse for
+its users than a token that lives as long as the tab. `tokenStorage: 'memory'` opts out. `user()` reads
+the id and scopes from the access token for display; the DMP checks the token on every request.
+
+`CubeApp` is also exported from the ES module (`import { CubeApp } from '@cube-nl/dmp-sdk'`) for an
+app with a build (route A).
+
+### For the host: serving `cube-sdk.js`
+
+| | |
+|---|---|
+| File | `dist/cube-sdk.js` in the package, `@cube-nl/dmp-sdk/cube-sdk.js` as an export; on jsDelivr/unpkg as `@cube-nl/dmp-sdk@<version>/dist/cube-sdk.js`; the CI's `pack` job also keeps it as an artifact |
+| Size | 31.4 KiB minified, 11.3 KiB gzipped (1.0.0-rc.4) |
+| Version | The banner's first line, `/*! @cube-nl/dmp-sdk 1.0.0-rc.4 cube-sdk.js … */`, and `CubeApp.version` |
+
+Pin it by copying the built file of a known version into the host, rather than fetching it at
+runtime: `npm pack @cube-nl/dmp-sdk@<version>` downloads the tarball, `package/dist/cube-sdk.js` is
+the file. Nothing from a CDN, nothing at request time.
+
+## What this SDK deliberately does not do
+
+- **No per-resource generated types.** `_capabilities` is per token and at runtime, and OpenAPI
+  generation does not exist yet (api#6). Pass your own `T` to `resources<T>()`.
+- **No cursor pagination.** The API's wire has `page[size]`/`page[number]` only; the engine's cursor
+  is not exposed.
+- **No automatic retries**, of reads or writes, apart from the single retry after a refreshed 401.
+  A 429 is thrown with `retryAfter`; what to do is the app's call.
+- **No token persistence** by default. Pass a `tokenStore` if you decide otherwise, knowingly.
+  `CubeApp` is the one deliberate exception (`sessionStorage`, see [Route B](#route-b-apps-without-a-build-step)).
+- **No token revocation call**: `cube/oauth-server` publishes no revocation endpoint. `signOut()`
+  forgets locally; the person revokes the connection in the DMP under *Verbonden apps*.
+- **No `_history`**: the API has not built it. `request()` reaches any path once it exists.
+
+## Development
+
+```bash
+npm ci
+npm run lint    # tsc --noEmit, strict
+npm test        # tsc + cube-sdk.js build, then node:test against a mock fetch — no network
+npm pack
+```
+
+`test/fixtures/api-wire.json` holds responses as `cube/api`'s own tests pin them (each case names
+its source test). When the API's wire format changes, update the fixture; `test/contract.test.js`
+then says what the SDK still reads wrong.
+
+TypeScript and esbuild (which bundles `dist/cube-sdk.js`, see `scripts/build-browser.mjs`) are the only
+dev dependencies; there are no runtime dependencies, and there should not be.
+
+### Releasing
+
+Bump `version` in `package.json` and `src/version.ts` (a test holds them equal), add the CHANGELOG
+entry, merge, then push a tag that equals the version (e.g. `1.0.0-rc.4`). The tag pipeline's
+`publish` job checks that, builds, and runs `npm publish`: a version with a `-` goes to the `next`
+dist-tag, any other to `latest`. It needs the masked, protected CI variable `NPM_TOKEN` (an npm
+granular access token with write access to the `cube-nl` org).
+
+## Integration tests
+
+`test/integration.test.js` runs the SDK against a real DMP. `npm test` includes it, and it skips
+itself unless `DMP_SDK_IT_URL` and `DMP_SDK_IT_TOKEN` are set, so the CI (which has no DMP) only
+runs the mock-fetch tests. It is written against the hackathon demo app (`projects`, `tasks`) and
+**writes**: every run leaves a few `SDK-IT …` projects behind (`php artisan demo:reset` clears them).
+
+```bash
+php artisan serve --host=127.0.0.1 --port=8000       # in the demo app
+DMP_SDK_IT_URL=http://127.0.0.1:8000 DMP_SDK_IT_TOKEN=… npm run test:integration
+```
+
+| Variable | |
+|---|---|
+| `DMP_SDK_IT_URL` | The DMP's origin, also the OAuth issuer. Required |
+| `DMP_SDK_IT_TOKEN` | A token with list, get, aggregate, create and update on the resource (the demo's `api_client`). Required |
+| `DMP_SDK_IT_BASE_URL` | Default `{DMP_SDK_IT_URL}/apps/api/v1` |
+| `DMP_SDK_IT_RESOURCE` | Default `projects` |
+| `DMP_SDK_IT_CREATE` | JSON merged into every created record next to a unique `name`. Default `{"status":"actief","budget":1}` |
+| `DMP_SDK_IT_READ_TOKEN` | A token with `api:read` only: a `POST` must be `403 client_scope_exceeded` |
+| `DMP_SDK_IT_PERSONAL_TOKEN` | A personal token (`$user->createToken(...)`) |
+| `DMP_SDK_IT_CLIENT_ID` | A public OAuth client: discovery and the authorization URL |
+| `DMP_SDK_IT_REDIRECT_URI` | Its redirect URI. Default `http://localhost:5173/callback` |
+| `DMP_SDK_IT_AUTHORIZE_CMD` | A shell command that signs in and allows the consent for the URL in `DMP_SDK_IT_AUTHORIZE_URL`, and prints the code. With it, the code exchange, the scope refusal on the OAuth token, the refresh and the refusal of a spent code and a rotated refresh token run as well |
+
+For the demo, the authorize command is its own Playwright script, reading everything from the
+environment so no password ends up in a process list:
+
+```bash
+export DMP_SDK_IT_AUTHORIZE_CMD='PLAYWRIGHT_DIR=… node scripts/authorize-code.mjs \
+  "$DMP_SDK_IT_AUTHORIZE_URL" "$DMP_SDK_IT_EMAIL" "$DMP_SDK_IT_PASSWORD" "$DMP_SDK_IT_REDIRECT_URI"'
+```
+
+Filament slows down a login after a few attempts a minute; run the OAuth test a few times in a
+row and it waits for that (or `demo:reset`, which also clears the counter).