@stapel/categories-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @stapel/categories-react

package/MODULE.md

@@ -0,0 +1,194 @@
+# @stapel/categories-react — module guide
+
+Pairs with **stapel-categories 0.6.0** (`>=0.6 <0.7`), 23 paths under
+`/categories/api/v1/`. Contract sources: the module's own
+`docs/{schema,errors,flows}.json`, pinned in `contract-pins.json` and
+regenerated under `pnpm gen:check`.
+
+## Layers
+
+```
+src/api/          categoriesApi.ts   the five public reads; the one home of path strings
+                  types.ts           wire aliases, and the one hand-mirrored field
+                  generated/         openapi-typescript, drift-gated
+src/catalog/      pks.ts             treenode's comma-joined pk columns
+                  tree.ts            flat rows → tree, slug → node, breadcrumbs
+                  sync.ts            the delta protocol as pure transitions
+                  labels.ts          key-or-literal, per row
+src/model/        runtime · context · queryKeys · catalogStore · catalogSync · queries
+src/headless/     CategoriesProvider · CategoryTree · CategoryBreadcrumbs
+                  CategoryCarousel · CategoryPicker · CategoryFeatures
+src/default/      the antd skin, `./default` subpath
+src/i18n/         keys · ru · es · errorsMap + generated/
+src/nav/          manifest.ts
+```
+
+`catalog/` is pure: no React, no fetch, no storage. That is what lets the tree
+assembly and the whole delta protocol be tested without a DOM, and what lets an
+SSR render call them directly.
+
+There is **no `flows/` layer**: `stapel-categories` annotates no `@flow_step`
+and its `docs/flows.json` is `[]`, so the pair is not wired into `gen:flows`
+(spec §8.1 — a flows layer only where a multi-step flow exists).
+
+## The three server facts this package exists to absorb
+
+### 1. There is no tree endpoint
+
+Three shapes could serve a catalogue, and the right one for a storefront is the
+paginated list: `GET /categories/` with `RevisionPagination`, envelope
+`{pagination, revisions, results}`, rows ordered by `revision`. Each row
+carries `tn_parent`, `tn_priority`, `tn_ancestors_pks`, `tn_children_pks`.
+
+The ancestry columns are django-treenode `TextField`s holding **comma-joined
+pks** (`treenode/utils.py`: `PKS_SEPARATOR = ","`), typed `string` in the
+schema, `""` for a root. `parseTreenodePks` exists because the storefront spec
+described them as arrays; a `JSON.parse` there fails, and a naive
+`Number(column)` yields `NaN`, which fails every `===` against a real id and
+therefore reads as "the parent is missing".
+
+`buildCategoryTree` filters two flags the endpoint does not:
+
+- `deleted` — the list's `include_deleted` defaults to **true**, and the delta
+  protocol needs it that way.
+- `active` — filtered server-side only by `/carousel/`. It is the storefront's
+  visibility switch, so the public tree drops inactive rows by default and
+  keeping them is an explicit option.
+
+An unreachable row (a parent cycle in authored data) is promoted to a root
+rather than dropped: a broken branch must be visible, not absent.
+
+### 2. There is no slug lookup
+
+`lookup_field` is never overridden and the list has no slug filter. `/c/:slug`
+resolves against the synced tree. `Category.slug` is `unique=True` on the
+model, so a collision cannot come from the database — it can only come from a
+stale row in the client's own snapshot, and first-in-display-order wins
+deterministically.
+
+### 3. Names are translation keys
+
+Covered in the README and in `catalog/labels.ts` at length. The short version:
+`translate()` runs the `DISPLAY_TRANSLATOR` seam, its default is the identity
+function, and **no serializer calls it** — the only two call sites are
+`Category.__str__` and the admin's memoized feature label. `translatable`
+(category) and `translate` (feature) say per row whether a string is a key.
+
+`featureOptionsAreKeys` carries the third case, which is the one that bites
+both ways: option labels are keys only under `translate: "all"` and only while
+`config.translatable_options` is not false. Translating an opted-out option
+shows the raw key; not translating an opted-in one shows the raw key too.
+
+## The delta protocol, and the two rules the docs omit
+
+The module's viewset docstring gives four steps: full GET, store
+`revisions.global_max`, `?min_revision=`, drop `deleted: true`. Implemented
+literally, that protocol has two holes.
+
+**`deleted_ids` beats scanning rows.** `revisions.deleted_ids` is computed as
+`filter(deleted=True, revision__gt=min_revision)` — unpaginated, over the whole
+table, and reflecting the CURRENT flag (so a category deleted and then restored
+is simply absent from it). The `deleted: true` rows, by contrast, are
+paginated: a walk that stops early misses one. Both channels are applied;
+`deleted_ids` is the complete one. On a full sync it is `[]` by construction —
+the server only computes it when `min_revision` was sent — which is why
+dropping `deleted: true` rows still matters.
+
+**A multi-page walk must pin its window.** `paginate_queryset` filters at
+request time and orders by `revision`; `global_max` is `Max(revision)` over the
+table at response time. A write landing between two pages shifts every later
+boundary. `max_revision` exists for exactly this and the documented flow never
+mentions it: `nextPageRequest` pins the window to the first page's
+`global_max`, and `applyCategoryPage`'s `cursorLimit` stops the cursor
+recording anything past it. Whatever was written during the walk is picked up
+by the next delta.
+
+Beyond that, two loop guards:
+
+- a **page budget** (`MAX_SYNC_PAGES`, 1000 — a million categories at the
+  server's max page size), because a server-reported `has_next` bug is an
+  infinite request loop against production, not a slow render; and
+- **publish-on-completion**: a truncated walk rewinds its cursor to the stored
+  one, so the worst case is one repeated full walk rather than a permanently
+  incomplete tree.
+
+The FULL/DELTA distinction is expressed as *what the accumulator starts from*
+(`EMPTY_SNAPSHOT` vs the stored snapshot), not as a flag on the merge. A flag
+invites both silent failures: a delta treated as full empties the catalogue, a
+full treated as delta resurrects rows deleted while the client was away.
+
+## Why the catalogue is app-scoped, not user-scoped
+
+`createRepository` is the only sanctioned client-side persistence primitive,
+and `scope` is not a size decision here. A user-scoped repository is encrypted
+with the per-session key and wiped at logout with no opt-out — both wrong for a
+category tree, which is public content identical for every visitor and for a
+visitor with no session at all. App scope also means the store never asks for a
+`SessionManager`, so it works on a page with no auth wired.
+
+Every read and write is wrapped: a private window, cleared site data or a
+snapshot written by an older shape all degrade to "no snapshot". A cold sync
+costs one request; a cache that throws costs the page.
+
+## The bridge to @stapel/attributes-react
+
+`GET /categories/{id}/features/` is where the two packages meet.
+`CategoryFeature` **is** attributes-react's `FeatureDef` — not a parallel type
+— so `bag.features` feeds `<FeatureFields>`, `unsupportedTypeGate`,
+`mirrorValidate` and `formatFeatureValue` unmodified. `test/features.test.tsx`
+asserts that end to end: the rows this pair fetches go through
+`unsupportedTypes` and it names the one type no builtin editor covers.
+
+This pair adds exactly three decisions on top and no more: whether the name is
+a key, whether the options are keys, and which rows are `show_as_badge` /
+`show_at_title` projections. Value semantics — defaults, validation, formatting
+— stay with the package that owns them.
+
+## Notes on the contract, recorded rather than worked around
+
+1. **`FeatureConfig`'s discriminator is malformed, and the generated types are
+   wrong because of it.** The schema declares
+   `discriminator: {propertyName: "type", mapping: {"null": ConvertibleUnitConfig}}`
+   — one bogus entry instead of the ten type slugs. openapi-typescript
+   therefore (a) strips the discriminator from every use site, emitting
+   `Omit<FeatureConfig, "type">`, and (b) re-adds a synthetic one per member,
+   so the generated `IntConfig` declares `type: "IntConfig"` where the wire
+   sends `"int"`. Feature configs are consequently typed through
+   attributes-react's hand-mirrored `FeatureConfig` (itself pinned against the
+   engine's generated golden corpus). **Upstream ask**: emit the ten slugs in
+   `discriminator.mapping`, and both halves disappear.
+2. **`FeatureCompact` carries no `revision`**, so the `/features/` collection's
+   `RevisionPagination` envelope always reports `revisions.min/max: null`. Not
+   on this pair's surface (a storefront reads features through a category), but
+   it makes the parallel feature tree un-syncable by the same protocol.
+3. **`POST {id}/validate-dto/` reads like a public helper and is not one.** The
+   viewset is `ReadOnlyOrStaff`, which allows safe methods to anyone and
+   everything else to staff — so this answers 403 to a visitor. It is absent
+   from `CategoriesApi` for that reason, not by oversight.
+4. **`include_deleted` is honoured** (`RevisionViewSetMixin.get_queryset`),
+   despite being documented on the paginator, which ignores it. Its default is
+   `true`.
+5. **No `translations/` directory.** 20 of the 62 registry codes can never come
+   from an upstream catalogue. They split by owner: the 42 cross-cutting
+   `stapel_core` codes are generated from core's catalogue, the 8
+   `stapel_categories` codes are authored in this pair's `./i18n/{ru,es}`, and
+   the 12 `stapel_attributes` codes stay with `@stapel/attributes-react`, which
+   already translates them. `test/i18n.test.ts` asserts over the UNION of the
+   two bundles a host registers, so nobody can "fix" a red test by copying
+   another package's twelve keys in and giving one refusal two sentences.
+
+## Tests
+
+119 in 9 files (115 in `test`, 4 in `test:pack`).
+
+| File | What it holds down |
+|---|---|
+| `tree.test.ts` | flat rows → tree; priority order and its tie-break; both filters; orphan promotion; parent cycles; slug resolution incl. collisions; breadcrumbs cross-checked against the server's own `tn_ancestors_pks` |
+| `sync.test.ts` | cold vs warm request; the `max_revision` pin; `deleted_ids` applied with no tombstone row present; cursor monotonicity and the window cap; snapshot parsing rejecting junk; the page budget and its cursor rewind |
+| `labels.test.ts` | key vs literal for categories, features and option labels; a missing translation showing the key |
+| `catalog.test.tsx` | loading / ready-empty / failed as three different sentences; "unknown slug" only after the catalogue loaded; the second mount asking for a delta |
+| `features.test.tsx` | the attributes-react bridge, including `unsupportedTypes` over the un-reshaped payload |
+| `skin.test.tsx` | the four `matchList` arms on screen; both blocked reasons named; searching without a request; ru copy |
+| `i18n.test.ts` | every registry code resolving in en/ru/es over the union of the two bundles; ownership of the twenty un-catalogued keys; interpolation slots preserved |
+| `pair.test.ts` | query-key namespace; the API surface being exactly the five public reads; nav ids, surfaces, routes and components |
+| `prodBundlePurity.test.ts` | no demo/showcase code in the tarball |

package/README.md

@@ -0,0 +1,191 @@
+# @stapel/categories-react
+
+The frontend pair for **stapel-categories**: the catalogue tree a storefront
+navigates by, kept fresh with the module's own revision-delta protocol instead
+of being refetched on every page.
+
+The backend has **no tree endpoint** and **no slug lookup**, and it serves
+category names as **translation keys**. This package is where each of those
+three facts is handled once, in the open, rather than rediscovered by every
+host.
+
+Business + state in the main entry, zero visual opinion; the antd skin lives
+behind `./default`. Built on `@stapel/core` (typed client + `StapelApiError`
+envelope, `LoadState`, `createRepository`, i18n engine, TanStack Query) and
+`@stapel/attributes-react` (the feature schema's value types).
+
+## Install
+
+```
+pnpm add @stapel/categories-react @stapel/core @stapel/attributes-react @tanstack/react-query react
+# for the default skin:
+pnpm add antd @stapel/tokens-antd
+```
+
+## A catalogue, in six lines
+
+**No session, no workspace id, no auth client** — every endpoint this pair
+calls is a safe method under `ReadOnlyOrStaff`, so the catalogue renders for a
+visitor who will never sign in:
+
+```tsx
+import { createCategoriesRuntime, CategoriesProvider } from "@stapel/categories-react";
+import { CatalogPage } from "@stapel/categories-react/default";
+
+const runtime = createCategoriesRuntime({ baseUrl: "/categories/api/v1/" });
+
+export function CatalogRoute() {
+  return (
+    <CategoriesProvider runtime={runtime}>
+      <CatalogPage />
+    </CategoriesProvider>
+  );
+}
+```
+
+## The client builds the tree, because the server has none
+
+`GET /categories/` returns **flat rows ordered by `revision`** — a sync feed,
+not a menu. Ancestry rides along in django-treenode's columns, which are
+**comma-joined primary-key strings**, not arrays:
+
+```jsonc
+{ "id": 4, "slug": "used-phones", "name": "category.used_phones",
+  "tn_parent": 2, "tn_ancestors_pks": "1,2", "tn_children_pks": "" }
+```
+
+`buildCategoryTree(rows)` assembles the hierarchy, orders siblings by
+`tn_priority` descending (ties by id, so a catalogue that never set priority
+does not reshuffle between renders), and drops two kinds of row the endpoint
+happily serves: soft-deleted ones, and **inactive** ones — `active` is filtered
+server-side only by `/carousel/`.
+
+A row whose parent is missing becomes a root rather than disappearing. Dropping
+it would delete a live branch of the catalogue from the menu and give nobody a
+reason.
+
+## The catalogue is synced by delta, not refetched
+
+The module documents the protocol on its own viewset: full GET → store
+`revisions.global_max` → later `?min_revision=<stored>` → drop what comes back
+`deleted: true`. This package implements it into an **app-scoped repository**
+(`createRepository(..., { scope: "app" })` — the one sanctioned persistence
+primitive), so a second page costs one small delta request instead of the whole
+catalogue.
+
+Two rules the documentation does not state are implemented anyway:
+
+- **`revisions.deleted_ids` is the complete tombstone channel.** The
+  `deleted: true` rows are paginated, so one can sit on a page a short walk
+  never reached; `deleted_ids` is computed unpaginated over the whole table.
+  Both are applied; the list is the one that is complete.
+- **A multi-page walk pins `max_revision`.** Pages are ordered by revision and
+  filtered at request time, so a write landing between page 1 and page 2 shifts
+  every later boundary and the walk skips a row. The window is pinned to the
+  `global_max` the first page reported, and the cursor never records reading
+  past it.
+
+A walk stopped by its page budget reports `truncated` and **rewinds its
+cursor**: the rows are still shown, but the next sync redoes the walk rather
+than sitting a delta on top of a catalogue that was never fully read.
+
+## `/c/:slug` is resolved on the client
+
+`CategoryViewSet` never overrides `lookup_field` and the list endpoint has no
+slug filter, so `GET /categories/<slug>/` is a 404 and `?slug=` is ignored. The
+storefront's `/c/:slug` resolves against the synced tree —
+`resolveCategorySlug(index, slug)` — which is a second, independent reason the
+tree is cached.
+
+A slug is not "unknown" until the catalogue has actually loaded. Rendering
+"there is no category here" during a sync shows a 404 for a page that exists.
+
+## Names are translation KEYS
+
+This is the fact most likely to be got wrong, so the package states it in the
+types instead of in a comment.
+
+`stapel-categories` stores keys and never owns a catalogue. Its
+`DISPLAY_TRANSLATOR` seam is called from `Category.__str__` and the admin's
+label cache — **no serializer calls it**. So a category arrives as
+`{"name": "category.electronics"}` even on a deployment with a real translator
+configured, there is no `?lang=`, and `GET /translation-keys/` is a
+service-only extraction feed for translators, not a resolver.
+
+Which strings are keys is declared per row, and the pair reads the flag rather
+than guessing:
+
+```tsx
+categoryLabel(category)   // { kind: "key" | "literal", value }  ← `translatable`
+featureLabel(feature)     // `translate: "none"` makes the name a literal
+featureOptionsAreKeys(f)  // `translate: "all"` AND config.translatable_options
+renderCategoryLabel(label, t)
+```
+
+The resolution goes through the **host's** i18n engine, and this package ships
+no category names: a catalogue is a deployment's content, not a library's
+chrome. When a key does not resolve, the key is shown — deliberately. A visible
+`category.electronics` gets fixed; a prettified "Electronics" invented by the
+library ships for a year in the wrong language.
+
+## The feature schema, and where attributes-react takes over
+
+`GET /categories/{id}/features/` resolves inheritance and order server-side and
+returns the polymorphic attributes config **verbatim** — not through
+`get_config_with_defaults()`, so an absent key means "the type's default", and
+`@stapel/attributes-react` owns those defaults. `<CategoryFeatures>` hands the
+rows over unmodified:
+
+```tsx
+<CategoryFeatures categoryId={id}>
+  {(bag) => (
+    <FeatureFields features={bag.features} values={values} onChange={set} />
+  )}
+</CategoryFeatures>
+```
+
+The same `bag.features` is what `@stapel/search-react`'s facet panel takes as
+`categoryFeatures` to caption facet values.
+
+## Surface
+
+| Export | What it is |
+|---|---|
+| `createCategoriesRuntime` / `CategoriesProvider` | wiring |
+| `useCategoryCatalog` | the delta-synced tree, one hook, mounted once |
+| `useCategoryChildren` / `useCategoryCarousel` / `useCategoryFeatures` / `useCategoriesRevision` | the four direct reads |
+| `buildCategoryTree` / `resolveCategorySlug` / `categoryBreadcrumbs` / `parseTreenodePks` | pure tree assembly |
+| `applyCategoryPage` / `firstPageRequest` / `nextPageRequest` / `syncCatalog` | the delta protocol, testable without React |
+| `categoryLabel` / `featureLabel` / `renderCategoryLabel` | the translation-key answer |
+| `<CategoryTree>` `<CategoryBreadcrumbs>` `<CategoryCarousel>` `<CategoryPicker>` `<CategoryFeatures>` | headless bags |
+| `/default`: `CatalogPage` `CategoryPage` `CategoryTreePane` `CategoryBreadcrumbsBar` `CategoryCarouselStrip` `CategoryPickerField` `CategoryFeatureList` | the antd skin |
+
+Nav entries: `categories.catalog` → `/c`, `categories.category` → `/c/:slug`,
+both `surface: "public"`. `/` is **not** claimed — the storefront's landing is
+categories *plus* search, and a composed route belongs to the container that
+composes it.
+
+`<CategoryPage>` takes `renderListings` for the same reason: the results half of
+`/c/:slug` belongs to another pair, handed in rather than imported across the
+L2 layer.
+
+## Not in this version
+
+The catalogue **admin** — create/update/delete, `bulk_add`, `bulk-commands`,
+`undelete`, `convert-type` and the four feature-editor operations — is not on
+this pair's surface. Every one of them is `IsStaffUser`, and the storefront
+wave leaves them to Django admin. `POST {id}/validate-dto/` is absent for the
+same reason: DRF treats it as a write, so it answers 403 to exactly the
+visitors who would want it; the compose form uses attributes-react's
+client-side mirror plus the server's verdict on publish. `GET
+/translation-keys/` is `IsServiceRequest`. `GET /data.json` is a second sync
+protocol and one tested protocol beats two half-tested ones.
+
+Nothing is hidden: `manifest.json` lists the whole contract.
+
+## More
+
+- [`MODULE.md`](./MODULE.md) — the module guide: layers, and every contract
+  note recorded rather than worked around.
+- [`llms.txt`](./llms.txt) — the generated surface slice for a coding harness.
+- [`manifest.json`](./manifest.json) — the machine-readable self-description.

package/dist/api/categoriesApi.d.ts

@@ -0,0 +1,121 @@
+import type { StapelClient } from "@stapel/core";
+import type { Category, CategoryFeature, CategoryListParams, CategoryPage, MaxRevision } from "./types.js";
+/**
+ * The pair's typed operation surface — one method per stapel-categories
+ * endpoint a storefront may call, bound to the injected {@link StapelClient}
+ * (the per-module override seam of frontend-standard §7.2). Paths are relative
+ * to the runtime's `baseUrl` (`/categories/api/v1/`).
+ *
+ * ── Five reads, and the eighteen operations that are NOT here ──────────────
+ *
+ * The contract has 23 paths. Every one of them is on `ReadOnlyOrStaff`, which
+ * means SAFE methods are open to anonymous callers and everything else needs
+ * `is_staff` — so the split below is not a taste call, it is the permission
+ * boundary drawn on the surface:
+ *
+ *  - **Public reads, and this pair's whole surface**: the category list (the
+ *    delta-sync source), `children`, `carousel`, `{id}/features`, and
+ *    `revision`.
+ *  - **Staff writes**: create / update / delete, `bulk_add`,
+ *    `bulk-commands`, `undelete`, `convert-type`, and the four
+ *    `feature-editor*` operations. These are the catalogue admin, which the
+ *    storefront wave leaves to Django admin (spec §4.3) — a pair that exposed
+ *    them would invite a public screen to call something only staff may.
+ *  - **`POST {id}/validate-dto/` is a WRITE in DRF's eyes**, so despite
+ *    reading like a public helper it answers 403 to a visitor. The listing
+ *    compose flow validates against the same rules with
+ *    `@stapel/attributes-react`'s client-side mirror plus the server's verdict
+ *    on publish; asking this endpoint would fail for exactly the people who
+ *    need it.
+ *  - **`GET {id}/validate-configs/`** is a catalogue-health read for an
+ *    operator, not a storefront read.
+ *  - **`GET translation-keys/`** is `IsServiceRequest` (service-to-service):
+ *    it is the extraction feed for translators, and it returns KEYS with
+ *    admin refs — never resolved labels. See `catalog/labels.ts`.
+ *  - **`GET data.json/`** requires a `?revision=` cache-buster and hands back
+ *    the whole table in one response. It is a legitimate alternative to the
+ *    paged walk, but it is a *second* sync protocol, and the module documents
+ *    the paged one. One protocol, tested, beats two, half-tested.
+ *  - The parallel `/features/` collection (list, retrieve, create, …) is the
+ *    feature tree in its own right — an admin axis. A storefront reads
+ *    features THROUGH a category, which is the only place inheritance and
+ *    order are resolved.
+ *
+ * Nothing is hidden: `manifest.json` lists the whole contract.
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2 (task `core-typed-ops`); until then they are hand-authored here (the ONE
+ * legal home of path strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface CategoriesApi {
+    readonly client: StapelClient;
+    /**
+     * One page of the revision-paginated category list — the source the whole
+     * tree is assembled from, and the only endpoint that reports deletions.
+     *
+     * Rows are ordered by `revision`, NOT by tree position: this is a sync feed,
+     * not a menu. `revisions.global_max` is the cursor to store;
+     * `revisions.deleted_ids` is the authoritative tombstone list for a delta
+     * (see `catalog/sync.ts` for why it beats scanning `deleted: true` rows).
+     */
+    list(params?: CategoryListParams, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<CategoryPage>;
+    /**
+     * Non-deleted direct children of one category, `tn_priority` descending.
+     *
+     * Redundant with the synced tree by construction, and deliberately kept: a
+     * host that wants one branch without paying for the catalogue (an SSR
+     * category page, a lazily-expanded admin-ish picker) has an endpoint for it,
+     * and it is the one place the server does the `deleted` filtering.
+     */
+    children(id: number, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly Category[]>;
+    /**
+     * The carousel strip: `active` AND `carousel_enabled`, `tn_priority`
+     * descending, cached server-side and sent with
+     * `Cache-Control: public, max-age` — so this one is safe to call on every
+     * landing render.
+     */
+    carousel(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly Category[]>;
+    /**
+     * A category's resolved feature schema: its own features plus every ancestor's,
+     * deduplicated by SLUG (an `inherit` override is a new row sharing the
+     * parent's slug, and the version nearest this category wins), ordered by the
+     * category's own `CategoryFeature.order` first.
+     *
+     * This is what the listing compose form draws with
+     * `@stapel/attributes-react` and what labels a search facet. `config`
+     * arrives verbatim — defaults are the reader's job, and attributes-react
+     * owns them.
+     */
+    features(id: number, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly CategoryFeature[]>;
+    /**
+     * The table's current maximum revision, without transferring any rows.
+     *
+     * The cheap freshness probe: a stored snapshot whose cursor already equals
+     * this needs no delta request at all.
+     */
+    revision(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<MaxRevision>;
+}
+/**
+ * The wire query object for one list request.
+ *
+ * Exported because the query KEY is built from it, so the key and the request
+ * are the same value by construction.
+ *
+ * `include_deleted` is sent ONLY when the caller asked for a value, and the
+ * server's own default is `true`. Sending it always would be harmless; leaving
+ * it out when unasked keeps the cache key of a plain read from depending on
+ * this pair's opinion about a server default.
+ */
+export declare function categoryListParams(params?: CategoryListParams): Record<string, string | number | boolean | undefined>;
+export declare function createCategoriesApi(client: StapelClient): CategoriesApi;
+//# sourceMappingURL=categoriesApi.d.ts.map

package/dist/api/categoriesApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categoriesApi.d.ts","sourceRoot":"","sources":["../../src/api/categoriesApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;;;;;;;OAQG;IACH,IAAI,CACF,MAAM,CAAC,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;OAOG;IACH,QAAQ,CACN,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;KAC/B,GAAG,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;IAEjC;;;;;;;;;;OAUG;IACH,QAAQ,CACN,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;KAC/B,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,GAAE,kBAAuB,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAUvD;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CA8BvE"}

package/dist/api/categoriesApi.js

@@ -0,0 +1,48 @@
+/**
+ * The wire query object for one list request.
+ *
+ * Exported because the query KEY is built from it, so the key and the request
+ * are the same value by construction.
+ *
+ * `include_deleted` is sent ONLY when the caller asked for a value, and the
+ * server's own default is `true`. Sending it always would be harmless; leaving
+ * it out when unasked keeps the cache key of a plain read from depending on
+ * this pair's opinion about a server default.
+ */
+export function categoryListParams(params = {}) {
+    const query = {};
+    if (params.minRevision !== undefined)
+        query["min_revision"] = params.minRevision;
+    if (params.maxRevision !== undefined)
+        query["max_revision"] = params.maxRevision;
+    if (params.includeDeleted !== undefined) {
+        query["include_deleted"] = params.includeDeleted;
+    }
+    if (params.page !== undefined)
+        query["page"] = params.page;
+    if (params.pageSize !== undefined)
+        query["page_size"] = params.pageSize;
+    return query;
+}
+export function createCategoriesApi(client) {
+    return {
+        client,
+        list: (params, options) => client.get("/categories/", {
+            query: categoryListParams(params),
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        }),
+        children: (id, options) => client.get(`/categories/${String(id)}/children/`, {
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        }),
+        carousel: (options) => client.get("/categories/carousel/", {
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        }),
+        features: (id, options) => client.get(`/categories/${String(id)}/features/`, {
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        }),
+        revision: (options) => client.get("/categories/revision/", {
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        }),
+    };
+}
+//# sourceMappingURL=categoriesApi.js.map

package/dist/api/categoriesApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categoriesApi.js","sourceRoot":"","sources":["../../src/api/categoriesApi.ts"],"names":[],"mappings":"AA2HA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAA6B,EAAE;IAE/B,MAAM,KAAK,GAA0D,EAAE,CAAC;IACxE,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC;IACjF,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS;QAAE,KAAK,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC;IACjF,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACxC,KAAK,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC;IACnD,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IAC3D,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS;QAAE,KAAK,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;IACxE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAoB;IACtD,OAAO;QACL,MAAM;QAEN,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CACxB,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE;YACzB,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC;YACjC,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;QAEJ,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,CACxB,MAAM,CAAC,GAAG,CAAC,eAAe,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE;YAChD,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;QAEJ,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CACpB,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE;YAClC,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;QAEJ,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,CACxB,MAAM,CAAC,GAAG,CAAC,eAAe,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE;YAChD,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;QAEJ,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CACpB,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE;YAClC,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;KACL,CAAC;AACJ,CAAC"}