@craftainer/crud-sdk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# @craftainer/crud-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.
+> [!NOTE]
+> This repository is vibe coded with [Claude](https://claude.com/product/claude-code).
+
+Typed `fetch` client for craftainer CRUD APIs (the TypeScript twin of the
+Python `crud-sdk`): manifest-driven resources, a query builder, RFC 9457
+problem-details errors, an opt-in cache with SSE invalidation, and TanStack
+Query helpers. ESM only. Created from
+[`template-npm-package`](https://github.com/craftainer/template-npm-package);
+the shared conventions are in [`docs/TEMPLATE.md`](docs/TEMPLATE.md).
+
+## Entry points
+
+| Import                          | Source                  | Contents                                                                                                                                                         |
+| ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@craftainer/crud-sdk`          | `src/index.ts`          | The client core and the shared contracts in `src/interfaces.ts` (`CacheStore`, `Middleware`, `RequestContext`, `TokenProvider`, `CrudEvent`). Zero dependencies. |
+| `@craftainer/crud-sdk/cache`    | `src/cache/index.ts`    | Cache middleware, memory and IndexedDB stores, SSE invalidation.                                                                                                 |
+| `@craftainer/crud-sdk/tanstack` | `src/tanstack/index.ts` | `queryOptions` factories, key factory, invalidation bridge.                                                                                                      |
+| `crud-sdk-codegen` (bin)        | `src/codegen/cli.ts`    | Writes TypeScript types from a manifest.                                                                                                                         |
+
+The package has no `dependencies`. `idb` and `eventsource-parser` are dev
+dependencies that `tsdown` inlines (`noExternal`). `@tanstack/query-core`
+(for `./tanstack`) and `json-schema-to-typescript` (for the codegen bin) are
+optional peer dependencies.
+
+Add or remove an entry point in `package.json`'s `exports`/`bin` and
+`tsdown.config.ts`'s `entry` together.
+
+## Client
+
+```ts
+import { createClient } from "@craftainer/crud-sdk";
+
+const client = createClient({
+  baseUrl: "https://api.example.com",
+  tokenProvider: ({ refresh }) => getToken({ refresh }), // optional
+  // fetch, middleware, manifestUrl are optional too
+});
+const heroes = await client.resource("heroes"); // highest api_version, or ("heroes", "v1")
+const page = await heroes.list({
+  filters: { power_level__min: 3, name__icontains: "ada" },
+  sort: "-power_level",
+  limit: 50,
+});
+for await (const hero of heroes.iterAll({ filters: { is_locked: false } })) {
+  // pages with skip += limit until a short page
+}
+await heroes.update(1, { name: "Ada" }, { ifMatch: etag }); // 412 -> PreconditionFailed
+```
+
+- **Discovery.** The manifest loads on first use through
+  `/.well-known/api-catalog` (the `describedby` link with the manifest
+  profile), or from `manifestUrl`. Manifest types keep the wire member names
+  (`skip_param`, `max_age`, ...) and ignore unknown members.
+- **Operations** (each gated on the manifest's capabilities and `paths`,
+  else `CapabilityError`): `list`, `iterAll`, `get`, `create`, `update`,
+  `updateMany`, `delete`, `deleteMany`, `restore({ id } | { filters })`,
+  `clone`, `createDraft`, `publish`, `filters`, `stats`, `predict`,
+  `revisions`, `eventsUrl()`. Every call takes `{ signal }`. A call that is
+  invalid for the manifest (unknown field or operator, wrong value type, bad
+  sort or paging) rejects with `InvalidQueryError` before any request.
+- **Query strings** are byte for byte those of the Python SDK (a shared
+  table, `tests/fixtures/url-parity.json`, checks both): parameters in the
+  order `id`, filters sorted by (field, operator), sort, skip, limit,
+  `include_archived`, `include_unpublished`; everything but `A-Za-z0-9-._~`
+  percent-encoded; datetimes are `Date`s sent as UTC with milliseconds
+  trimmed; `date` fields take `YYYY-MM-DD` strings.
+- **Errors.** `ProblemError` (RFC 9457) with subclasses `BadRequest`,
+  `Unauthorized`, `Forbidden`, `NotFound`, `PreconditionFailed`,
+  `ValidationFailed` (`errors`), `Locked`, `RateLimited` (`retryAfter`),
+  `ServerError`; `ConnectionFailed` for transport failures (an abort passes
+  through unchanged). All extend `CrudError`.
+- **Auth.** The token provider is called per request; after a `401` it is
+  called once with `{ refresh: true }` and the request is retried only if
+  the token changed. The cache scope is `"anon"` or the first 32 hex of the
+  SHA-256 of the whole token (never decoded).
+- **Middleware.** `createClient({ middleware })` or `client.use(mw)` (added
+  innermost). Each request carries a `RequestContext` (`resource`, `op`,
+  `recordId`, `scope`, `apiVersion`, `signal`).
+- **Typed records.** `client.resource<Read, Create, Update>("heroes")` takes
+  the interfaces written by the codegen below (not checked at runtime).
+
+## Codegen
+
+```sh
+CRUD_SDK_TOKEN=... crud-sdk-codegen --manifest https://api.example.com --out src/crud-types.ts
+crud-sdk-codegen --manifest ./manifest.json --out src/crud-types.ts
+```
+
+Writes `<Name><Version>Read|Create|Update` (and `Draft`) interfaces per
+resource from the manifest's JSON Schemas. `--manifest` is a manifest URL, a
+server origin (discovers through the api-catalog) or a file; the optional
+peer `json-schema-to-typescript` must be installed.
+
+## Caching / TanStack
+
+`createCache({ store, policies })` (from `./cache`) returns two `Middleware`:
+`cache.middleware` and `cache.autoIfMatch`. Put both **innermost**, after
+whatever sets `Authorization`: the cache scope is `anon` without an
+Authorization header, else the first 32 hex characters of the SHA-256 of the
+whole credential, taken from the request as it is sent. `policies` maps
+manifest resource names to `cachePolicyFromManifest(resource)` (plain I1
+objects, snake_case members).
+
+- Every read revalidates (`If-None-Match`, `304` rebuilt from the store).
+  `max_age`/`stale_while_revalidate` freshness applies only while the
+  resource's SSE stream is connected, never with `cache.revalidate_only`.
+- Wire the stream with `invalidateOnEvents(cache, getEventHub({ fetch, url,
+events }), "heroes")`; `fetch` must be authenticated. Events invalidate and
+  never apply snapshots. `subscribeEvents` is the lower-level entry.
+- Stores: `MemoryStore` (LRU) and `IndexedDbStore` (store failures are a miss).
+  `clearMany(prefixes)` is optional on a custom `CacheStore`.
+- `cacheStatus(response)` says `hit`, `stale`, `revalidated` or `miss`;
+  `cache.close()` stops background refreshes.
+
+`./tanstack` has no runtime dependency on `@tanstack/query-core`: `crudKeys`,
+`listOptions`/`recordOptions`/`statsOptions`/`predictOptions`/
+`revisionsOptions`/`manifestOptions`, `infiniteListOptions`, the
+`create`/`update`/`deleteMutationOptions`, `invalidateResource`/
+`invalidateCollections`/`invalidateRecord` (each takes `{ client, resource }`)
+and `bridgeEvents(queryClient, hub, { client, resource })`, where `client` is
+the id string (`client.id`) and `resource` the same string the keys use. Use
+`tanstackCachePolicy` so the SDK cache only revalidates and TanStack's
+`staleTime` owns freshness. The factories take structural slices (`list(query, { signal })`, ...), which
+the client's options-object methods do not match for `list`, `stats`,
+`predict` and the manifest. `tanstackApi(client, resource)` (from
+`./tanstack`) binds one `ResourceClient` to all of them; a query is the
+client's `ListOptions` (`{ filters, sort, skip, limit, ... }`) without
+`signal`, which TanStack's `signal` fills in.
+
+**Query keys** are namespaced by client and caller scope, so clients or
+callers sharing one `QueryClient` never see each other's data:
+
+```
+["crud", client, resource, scope, kind, ...rest]   kind: list | record | stats | predict | revisions
+["crud", client, "_manifest", scope]
+```
+
+`client` is `CrudClient.id` (`createClient({ id })`, default `baseUrl`; keep it
+stable across reloads of a persisted cache). `scope` is `client.scope()`.
+`await client.namespace()` returns the `{ client, scope }` that every factory
+takes as its first argument (`listOptions(ns, resource, api, query)`,
+`createMutationOptions(queryClient, ns, resource, api)`). `resource` is the
+manifest name, or `name@apiVersion` for a pinned version (a different
+string is a different resource: pass the same one to the invalidate helpers
+and `bridgeEvents`; `_manifest` is reserved). The namespace is a snapshot: a
+token change (login, logout, refresh to another identity) changes the scope,
+so resolve it again then, for example in a provider keyed on the token.
+Clients that share a `baseUrl` but differ in anything else need distinct ids.
+
+Because `resource` precedes `scope`, "everything of resource X on client C" is
+one prefix (`crudKeys.resource(c, x)`, or `invalidateResource(queryClient, c,
+x)`), and `crudKeys.client(c)` clears a whole client. Narrowing by scope, kind
+or record id uses `crudKeys.filter({ client, resource?, scope?, kinds?, id? })`,
+which returns `{ queryKey }` or `{ predicate }` to spread into
+`invalidateQueries`/`removeQueries`. Mutations and `bridgeEvents` invalidate
+every scope of the client's resource, since a write changes what every caller sees.
+
+```ts
+import { createClient } from "@craftainer/crud-sdk";
+import {
+  createCache,
+  MemoryStore,
+  cachePolicyFromManifest,
+} from "@craftainer/crud-sdk/cache";
+import { listOptions, tanstackApi } from "@craftainer/crud-sdk/tanstack";
+
+const cache = createCache({
+  store: new MemoryStore(),
+  policies: { heroes: cachePolicyFromManifest(heroesManifestEntry) },
+});
+const client = createClient({
+  baseUrl,
+  middleware: [cache.middleware, cache.autoIfMatch],
+});
+const api = tanstackApi(client, await client.resource("heroes"));
+useQuery(listOptions(await client.namespace(), "heroes", api, { limit: 50 }));
+```
+
+Cache keys carry no server origin, so a store shared between servers needs a
+per-origin namespace: give each server its own `MemoryStore` or its own
+`IndexedDbStore({ name })` (the IndexedDB database name). The key format does
+not change.
+
+`policies` is keyed by `name@apiVersion` (built from that version's manifest
+entry) or by plain `name` for every version; the event stream and the
+freshness gate are per resource name, and the gate stays open while at least
+one subscription for that resource is connected. `filters` entries are never
+served fresh.
+
+The cache scope is the same on both sides: `client.scope()` equals
+`credentialScope` of the `Authorization` header the client sends (an empty
+token sends no header and is `anon`). `cache.autoIfMatch` reads `recordId`,
+the resource and `apiVersion` from the client's request context, so
+`update`/`delete` without `ifMatch` send the ETag cached for that caller.
+
+See
+[`docs/adrs/0002-cache-freshness-and-event-invalidation.md`](docs/adrs/0002-cache-freshness-and-event-invalidation.md).
+
+## Development
+
+Open the repository in the devcontainer, then run
+`prek run --all-files --hook-stage manual`.
+
+## License
+
+Licensed under the [GNU General Public License v3.0](LICENSE).

package/dist/auth-DwtNEKrw.mjs

@@ -0,0 +1,22 @@
+//#region src/auth.ts
+/** The scope of an anonymous caller. */
+const ANON = "anon";
+/**
+* Cache scope of a caller: `"anon"`, or the first 32 hex characters of the
+* SHA-256 of the whole bearer token. Nothing in the token is trusted or
+* decoded (a forged `sub` must not select another caller's entries), and the
+* raw token never leaves this function.
+*/
+async function cacheScope(token) {
+	if (token === null || token === void 0) return ANON;
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+	return Array.from(new Uint8Array(digest).subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** A provider that always returns `token` (a refresh changes nothing). */
+function staticToken(token) {
+	return () => token;
+}
+//#endregion
+export { cacheScope as n, staticToken as r, ANON as t };
+
+//# sourceMappingURL=auth-DwtNEKrw.mjs.map

package/dist/auth-DwtNEKrw.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-DwtNEKrw.mjs","names":[],"sources":["../src/auth.ts"],"sourcesContent":["import type { TokenProvider } from \"./interfaces.ts\";\n\n/** The scope of an anonymous caller. */\nexport const ANON = \"anon\";\n\n/**\n * Cache scope of a caller: `\"anon\"`, or the first 32 hex characters of the\n * SHA-256 of the whole bearer token. Nothing in the token is trusted or\n * decoded (a forged `sub` must not select another caller's entries), and the\n * raw token never leaves this function.\n */\nexport async function cacheScope(\n  token: string | null | undefined,\n): Promise<string> {\n  if (token === null || token === undefined) {\n    return ANON;\n  }\n  const digest = await crypto.subtle.digest(\n    \"SHA-256\",\n    new TextEncoder().encode(token),\n  );\n  return Array.from(new Uint8Array(digest).subarray(0, 16), (byte) =>\n    byte.toString(16).padStart(2, \"0\"),\n  ).join(\"\");\n}\n\n/** A provider that always returns `token` (a refresh changes nothing). */\nexport function staticToken(token: string | null): TokenProvider {\n  return () => token;\n}\n"],"mappings":";;AAGA,MAAa,OAAO;;;;;;;AAQpB,eAAsB,WACpB,OACiB;CACjB,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;CAET,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CACA,OAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,SACzD,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CACnC,CAAC,CAAC,KAAK,EAAE;AACX;;AAGA,SAAgB,YAAY,OAAqC;CAC/D,aAAa;AACf"}

package/dist/cache/index.d.mts

@@ -0,0 +1,166 @@
+import { a as Middleware, i as MaybePromise, n as CacheStore, r as CrudEvent, t as CacheEntry } from "../interfaces-s73cVfIF.mjs";
+import { a as SubscribeEventsOptions, c as CachePolicy, d as tanstackCachePolicy, i as EventsConfig, l as ManifestCacheHints, n as EventHub, o as getEventHub, r as EventHubOptions, s as subscribeEvents, t as EventHandlers, u as cachePolicyFromManifest } from "../events-DpSWzSN9.mjs";
+//#region src/cache/middleware.d.ts
+/**
+ * A store may clear several prefixes in one pass (one walk, one transaction);
+ * the cache uses it when present and falls back to `clear` per prefix.
+ */
+interface CacheStoreMany extends CacheStore {
+  clearMany?(prefixes: readonly string[]): MaybePromise<void>;
+}
+interface CacheOptions {
+  readonly store: CacheStoreMany;
+  /**
+   * Policy per manifest resource: `name@apiVersion` (built from that version's
+   * manifest entry) or, for every version, plain `name`. A resource without
+   * one is not cached. The event stream and the freshness gate are per name.
+   */
+  readonly policies: Readonly<Record<string, CachePolicy>>;
+  /** Cache the manifest document per caller scope. Default `true`. */
+  readonly cacheManifest?: boolean;
+  /** Epoch milliseconds; injectable for tests. */
+  readonly now?: () => number;
+}
+interface Cache {
+  /** Put it in the client's middleware chain. */
+  readonly middleware: Middleware;
+  /** Record whether the SSE stream of `resource` is connected (gates fresh hits). */
+  setEventsActive(resource: string, active: boolean): void;
+  eventsActive(resource: string): boolean;
+  /** Clear what an SSE event makes stale, in every API version. */
+  invalidateEvent(resource: string, action: string, recordId: number | undefined): Promise<void>;
+  /** Clear everything cached for `resource` except `filters` (after a reconnect). */
+  clearResource(resource: string): Promise<void>;
+  /** Clear keys under `prefix` (everything the store owns when omitted). */
+  clear(prefix?: string): Promise<void>;
+  /**
+   * Adds `If-Match` from the cached record ETag to `PATCH`/`DELETE ?id=` that
+   * have none. Put it innermost, next to `middleware`, so it sees the same
+   * Authorization (and so scope) the request is sent with.
+   */
+  readonly autoIfMatch: Middleware;
+  /** The stored ETag of a record of one API version, for `auto_if_match`. */
+  cachedEtag(resource: string, recordId: number, scope: string, apiVersion: string | null): Promise<string | undefined>;
+  /** Abort background revalidations and wait for them. */
+  close(): Promise<void>;
+}
+export declare function createCache(options: CacheOptions): Cache;
+//#endregion
+//#region src/cache/scope.d.ts
+/**
+ * `"anon"` when the request has no Authorization header; otherwise the first
+ * 32 hex characters of the SHA-256 of the whole credential, the same digest as
+ * the client's `cacheScope(token)` (a `Bearer ` prefix is dropped, any other value is hashed as it is). It is read from the
+ * request the cache sees, so it must be the innermost middleware that matters:
+ * whatever sets Authorization has to run before the cache. The raw credential
+ * never enters a key or a log, and the unverified `sub` claim is never used.
+ */
+export declare function credentialScope(headers: Headers): Promise<string>;
+//#endregion
+//#region src/cache/entry.d.ts
+/** How the cache answered a read: see `cacheStatus`. */
+type CacheStatus = "hit" | "stale" | "revalidated" | "miss";
+/**
+ * How the cache answered `response`: `hit` (fresh, no network), `stale`
+ * (inside the stale-while-revalidate window, refreshed in the background),
+ * `revalidated` (a `304` rebuilt from the stored entry) or `miss`.
+ * `undefined` when the cache did not handle the request.
+ */
+export declare function cacheStatus(response: Response): CacheStatus | undefined;
+//#endregion
+//#region src/cache/memory.d.ts
+interface MemoryStoreOptions {
+  /** Default 1024. */
+  readonly maxEntries?: number;
+  readonly defaultTtlMs?: number;
+  /** Epoch milliseconds; injectable for tests. */
+  readonly now?: () => number;
+}
+/** LRU store (default 1024 entries) that also honours each entry's ttl. */
+export declare class MemoryStore implements CacheStore {
+  private readonly data;
+  private readonly maxEntries;
+  private readonly defaultTtlMs;
+  private readonly now;
+  constructor(options?: MemoryStoreOptions);
+  /** Number of stored entries (expired ones included until touched). */
+  get size(): number;
+  get(key: string): CacheEntry | undefined;
+  set(key: string, entry: CacheEntry, ttlMs?: number): void;
+  delete(key: string): void;
+  /** Remove every key under any of `prefixes` in one walk. */
+  clearMany(prefixes: readonly string[]): void;
+  clear(prefix?: string): void;
+}
+//#endregion
+//#region src/cache/idb.d.ts
+interface IndexedDbStoreOptions {
+  /** Database name; default `craftainer-crud-cache`. */
+  readonly name?: string;
+  readonly defaultTtlMs?: number;
+  /** Epoch milliseconds; injectable for tests. */
+  readonly now?: () => number;
+}
+export declare class IndexedDbStore implements CacheStore {
+  private readonly name;
+  private readonly defaultTtlMs;
+  private readonly now;
+  private opening;
+  constructor(options?: IndexedDbStoreOptions);
+  private open;
+  /** Run `work` on the database; a failure drops the handle (so a later call retries) and yields `fallback`. */
+  private run;
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(prefix?: string): Promise<void>;
+  /** Clear several prefixes in one transaction (one bound range each). */
+  clearMany(prefixes: readonly string[]): Promise<void>;
+  /** Close the database handle; a later call reopens it. */
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/cache/keys.d.ts
+/** The ops that read and are cached (`manifest` has its own key). */
+type CacheKind = "list" | "record" | "stats" | "predict" | "revisions" | "filters";
+/**
+ * Sorts the query pairs the client sent and drops `id` (it is the subject).
+ * Values are kept verbatim: the client already emits canonical,
+ * percent-encoded text, so nothing is decoded or re-encoded here.
+ */
+export declare function canonicalQuery(query: string): string;
+interface KeyParts {
+  readonly resource: string;
+  readonly kind: CacheKind;
+  readonly recordId?: number | undefined;
+  readonly scope: string;
+  readonly query?: string;
+  /** `null` (no version) renders as `_`. */
+  readonly apiVersion: string | null;
+}
+/** The key of one cached response. */
+export declare function buildKey(parts: KeyParts): string;
+/** Key of the manifest document for one caller scope. */
+export declare function manifestKey(scope: string): string;
+/** Prefix of the `record` entries of one record (every version, scope, query). */
+export declare function recordPrefix(resource: string, recordId: number): string;
+/** Everything cached for `resource` except `filters` (a reconnect or an unknown change). */
+export declare function resourcePrefixes(resource: string): string[];
+/**
+ * Prefixes an SSE event clears, per the spec's table: `create` clears the
+ * collection kinds; `update`/`delete`/`restore` also clear the record and its
+ * revisions; an unknown action or a missing record id clears the resource.
+ */
+export declare function eventPrefixes(resource: string, action: string, recordId: number | undefined): string[];
+//#endregion
+//#region src/cache/wire.d.ts
+/**
+ * Subscribe `cache` to `hub` for the manifest resource `resource`. Events
+ * clear the spec's prefixes, a reconnect clears the resource, and fresh hits
+ * are allowed only while the stream is connected. Returns the unsubscribe
+ * (it also closes the freshness gate).
+ */
+export declare function invalidateOnEvents(cache: Cache, hub: EventHub, resource: string): () => void;
+//#endregion
+export { type Cache, type CacheEntry, type CacheKind, type CacheOptions, type CachePolicy, type CacheStatus, type CacheStore, type CacheStoreMany, type CrudEvent, type EventHandlers, type EventHub, type EventHubOptions, type EventsConfig, type IndexedDbStoreOptions, type KeyParts, type ManifestCacheHints, type MemoryStoreOptions, type SubscribeEventsOptions, cachePolicyFromManifest, getEventHub, subscribeEvents, tanstackCachePolicy };
+//# sourceMappingURL=index.d.mts.map