@jini-ai/admin 0.1.0

package/dist/core/routing/rules.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Pure route matching, driven by the panel registry rather than a hard-coded branch list.
+ *
+ * ## What changed from the ported original
+ *
+ * The reference implementation's `parseRoute` is a ~30-line if-chain with one branch per
+ * detail route — `/posts/:id`, `/menus/new`, `/widgets/regions/:key`,
+ * `/collections/:key/:entryId`, and so on. It works, and its fall-through-to-dashboard behaviour
+ * is deliberate. But it means a panel cannot own a URL without an edit to the router, which is
+ * fatal for a package whose whole point is that hosts and AI-generated code add panels.
+ *
+ * Here the panel declares its patterns and the matcher is generic. Behaviour that is preserved
+ * exactly, because each was a considered decision in the original:
+ *
+ * - **Unrecognized paths fall through** (`panelId: null`) rather than rendering a placeholder,
+ *   so a typo behaves like a bad URL rather than an empty screen.
+ * - **A bare single segment only matches a registered panel.** Testing against the registry
+ *   rather than accepting any single segment is what keeps `/typo` from rendering an empty shell.
+ * - **Trailing slashes are insignificant** — segments are split and empties dropped, so
+ *   `/settings/` and `/settings` are the same screen.
+ * - **Query is parsed but never part of matching.** The reference implementation's widget-editor
+ *   route reads `?type=` for its initial state; that is panel state, not routing.
+ */
+import type { AdminPanel } from '../manifest/types.js';
+import type { AdminRoute } from './types.js';
+/** Default mount point. Overridable per call — a product that mounts its admin elsewhere passes
+ *  its own base rather than patching this package. */
+export declare const DEFAULT_ADMIN_BASE = "/admin";
+/** `"/admin/settings/"` -> `"/admin/settings"`; leaves a lone `"/"` alone. */
+export declare function stripTrailingSlash(pathname: string): string;
+/** Route path -> URL. `/settings` -> `/admin/settings`; `/` -> `/admin/`. */
+export declare function adminHref(routePath: string, base?: string): string;
+/**
+ * URL pathname -> route path, base stripped. Always starts with `/`.
+ *
+ * A bare `/admin` (no trailing slash) and `/admin/` both mean the dashboard, so the base is
+ * removed by prefix rather than by assuming a trailing separator.
+ *
+ * Unlike the reference implementation's version this takes `pathname` as a required argument instead of defaulting to
+ * `window.location.pathname` — that default is what made the original untestable without a DOM,
+ * and it belongs in the browser layer, not here.
+ */
+export declare function currentRoutePath(pathname: string, base?: string): string;
+/**
+ * Matches a route path against the registered panels.
+ *
+ * Callers should pass the **resolved** panel set (see `resolvePanels`), not the raw one — routing
+ * to a panel whose capability is not wired would render a section the host deliberately withheld.
+ *
+ * @complexity O(p * r * s) — p panels, r patterns per panel, s segments per pattern. Bounded by
+ * the manifest, and the common case exits on the first segment comparison.
+ */
+export declare function matchRoute<T>(routePath: string, panels: readonly AdminPanel<T>[]): AdminRoute;
+//# sourceMappingURL=rules.d.ts.map

package/dist/core/routing/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/core/routing/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;sDACsD;AACtD,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,MAA2B,GAAG,MAAM,CAGtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAA2B,GAAG,MAAM,CAM5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,CA0B7F"}

package/dist/core/routing/rules.js

@@ -0,0 +1,113 @@
+/**
+ * @file Pure route matching, driven by the panel registry rather than a hard-coded branch list.
+ *
+ * ## What changed from the ported original
+ *
+ * The reference implementation's `parseRoute` is a ~30-line if-chain with one branch per
+ * detail route — `/posts/:id`, `/menus/new`, `/widgets/regions/:key`,
+ * `/collections/:key/:entryId`, and so on. It works, and its fall-through-to-dashboard behaviour
+ * is deliberate. But it means a panel cannot own a URL without an edit to the router, which is
+ * fatal for a package whose whole point is that hosts and AI-generated code add panels.
+ *
+ * Here the panel declares its patterns and the matcher is generic. Behaviour that is preserved
+ * exactly, because each was a considered decision in the original:
+ *
+ * - **Unrecognized paths fall through** (`panelId: null`) rather than rendering a placeholder,
+ *   so a typo behaves like a bad URL rather than an empty screen.
+ * - **A bare single segment only matches a registered panel.** Testing against the registry
+ *   rather than accepting any single segment is what keeps `/typo` from rendering an empty shell.
+ * - **Trailing slashes are insignificant** — segments are split and empties dropped, so
+ *   `/settings/` and `/settings` are the same screen.
+ * - **Query is parsed but never part of matching.** The reference implementation's widget-editor
+ *   route reads `?type=` for its initial state; that is panel state, not routing.
+ */
+/** Default mount point. Overridable per call — a product that mounts its admin elsewhere passes
+ *  its own base rather than patching this package. */
+export const DEFAULT_ADMIN_BASE = '/admin';
+/** `"/admin/settings/"` -> `"/admin/settings"`; leaves a lone `"/"` alone. */
+export function stripTrailingSlash(pathname) {
+    return pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname;
+}
+/** Route path -> URL. `/settings` -> `/admin/settings`; `/` -> `/admin/`. */
+export function adminHref(routePath, base = DEFAULT_ADMIN_BASE) {
+    const normalized = routePath.startsWith('/') ? routePath : `/${routePath}`;
+    return `${base}${normalized}`;
+}
+/**
+ * URL pathname -> route path, base stripped. Always starts with `/`.
+ *
+ * A bare `/admin` (no trailing slash) and `/admin/` both mean the dashboard, so the base is
+ * removed by prefix rather than by assuming a trailing separator.
+ *
+ * Unlike the reference implementation's version this takes `pathname` as a required argument instead of defaulting to
+ * `window.location.pathname` — that default is what made the original untestable without a DOM,
+ * and it belongs in the browser layer, not here.
+ */
+export function currentRoutePath(pathname, base = DEFAULT_ADMIN_BASE) {
+    if (pathname === base)
+        return '/';
+    if (pathname.startsWith(`${base}/`))
+        return pathname.slice(base.length) || '/';
+    // Reached only if the app is mounted somewhere unexpected; treat the whole path as the route
+    // rather than silently returning the dashboard, so the mismatch is visible in the URL.
+    return pathname || '/';
+}
+/**
+ * Matches a route path against the registered panels.
+ *
+ * Callers should pass the **resolved** panel set (see `resolvePanels`), not the raw one — routing
+ * to a panel whose capability is not wired would render a section the host deliberately withheld.
+ *
+ * @complexity O(p * r * s) — p panels, r patterns per panel, s segments per pattern. Bounded by
+ * the manifest, and the common case exits on the first segment comparison.
+ */
+export function matchRoute(routePath, panels) {
+    const [rawPath, rawQuery] = routePath.split('?');
+    const segments = (rawPath ?? '').split('/').filter(Boolean);
+    const query = new URLSearchParams(rawQuery ?? '');
+    const miss = (panelId) => ({ panelId, view: null, params: {}, query });
+    // Root is the dashboard by convention, and `dashboard` need not be registered for `/` to
+    // resolve — the shell's fallback handles an empty registry.
+    if (segments.length === 0)
+        return miss('dashboard');
+    const panel = panels.find((p) => p.id === segments[0]);
+    if (!panel)
+        return miss(null);
+    const rest = segments.slice(1);
+    // Bare panel segment: the index view.
+    if (rest.length === 0)
+        return miss(panel.id);
+    for (const route of panel.routes ?? []) {
+        const params = matchPattern(route.pattern, rest);
+        if (params)
+            return { panelId: panel.id, view: route.view, params, query };
+    }
+    // A registered panel with unmatched trailing segments. Falls through rather than rendering the
+    // panel's index view, so `/posts/abc/typo` is a bad URL rather than silently showing the list.
+    return miss(null);
+}
+/**
+ * Matches one pattern against already-split segments.
+ *
+ * @returns captured params, or `null` when the pattern does not match. An empty object is a
+ * successful match with no captures — which is why this returns `null` rather than `{}` for a
+ * miss, and why callers must check for `null` explicitly rather than truthiness of the size.
+ */
+function matchPattern(pattern, segments) {
+    const patternSegments = pattern.split('/').filter(Boolean);
+    if (patternSegments.length !== segments.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternSegments.length; i += 1) {
+        const patternSegment = patternSegments[i] ?? '';
+        const segment = segments[i] ?? '';
+        if (patternSegment.startsWith(':')) {
+            params[patternSegment.slice(1)] = segment;
+            continue;
+        }
+        if (patternSegment !== segment)
+            return null;
+    }
+    return params;
+}
+//# sourceMappingURL=rules.js.map

package/dist/core/routing/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/core/routing/rules.ts"],"names":[],"mappings":"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"}

package/dist/core/routing/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Route model types.
+ *
+ * ## Route paths vs URLs — the distinction this module exists to keep straight
+ *
+ * Carried over from the reference implementation's `lib/router.ts`, where collapsing these two is documented as the exact
+ * mistake that produced `/admin/#/section/settings` URLs:
+ *
+ * - a **route path** is base-agnostic and is what the matcher consumes: `/`, `/settings`,
+ *   `/posts/abc`
+ * - a **URL** is what goes in an `href` or the address bar: `/admin/`, `/admin/settings`
+ *
+ * `adminHref` converts the first into the second; `currentRoutePath` recovers the first from a
+ * pathname. Nothing else should be doing string surgery on a location.
+ */
+/** A resolved route. */
+export interface AdminRoute {
+    /**
+     * The matched panel's id, or `null` when nothing matched.
+     *
+     * `null` is not an error state the shell must handle specially — the documented behaviour, kept
+     * from the reference implementation, is that an unrecognized path falls through to the dashboard rather than rendering
+     * an empty placeholder for a typo.
+     */
+    readonly panelId: string | null;
+    /**
+     * Which of the panel's views to render. `null` means the panel's own index view (`/users`), as
+     * opposed to one of its detail routes (`/users/abc`).
+     */
+    readonly view: string | null;
+    /** Captured `:name` segments from the matched pattern. Empty for an index route. */
+    readonly params: Readonly<Record<string, string>>;
+    /** Parsed query string. Always present, possibly empty. */
+    readonly query: URLSearchParams;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/routing/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElD,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC"}

package/dist/core/routing/types.js

@@ -0,0 +1,17 @@
+/**
+ * @file Route model types.
+ *
+ * ## Route paths vs URLs — the distinction this module exists to keep straight
+ *
+ * Carried over from the reference implementation's `lib/router.ts`, where collapsing these two is documented as the exact
+ * mistake that produced `/admin/#/section/settings` URLs:
+ *
+ * - a **route path** is base-agnostic and is what the matcher consumes: `/`, `/settings`,
+ *   `/posts/abc`
+ * - a **URL** is what goes in an `href` or the address bar: `/admin/`, `/admin/settings`
+ *
+ * `adminHref` converts the first into the second; `currentRoutePath` recovers the first from a
+ * pathname. Nothing else should be doing string surgery on a location.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/routing/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/core/transport/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file The error contract every admin route group throws, host-supplied or Jini-shipped.
+ *
+ * Ported from the reference implementation's `lib/api.ts` (`ApiError`, `describeApiError`), which is the
+ * only implementation of this shape that has been through real operator use. Two decisions from
+ * that file are carried across deliberately, because both were arrived at by an audit and both
+ * look like oversights if you only read the code:
+ *
+ * 1. **`body` is kept raw.** A caller sometimes needs a route-specific field beyond
+ *    `code`/`message` (a 409's `currentVersion`, a validation route's field list). Exposing the
+ *    parsed body means that never requires an `AdminApiError` subclass per route.
+ *
+ * 2. **There is deliberately NO shared `code` -> message table.** The same `code` means
+ *    genuinely different things in different domains — in the reference implementation,
+ *    `RESOURCE_CONFLICT` is "still
+ *    referenced elsewhere" on Roles, "that slug is already taken" on Workspace, and "that
+ *    username is already in use" on Users. Three correct operator-facing sentences for one code.
+ *    A shared table could only pick one, which is a regression dressed as consolidation. So
+ *    `describeApiError` is only the *base case*: it decides what to show when the server sent no
+ *    message, or when the thrown value is not an `AdminApiError` at all (network failure, a
+ *    thrown non-Error). Panels layer their own per-code copy on top and fall through to this.
+ */
+/** A failed admin API call that reached the server and came back non-2xx. */
+export declare class AdminApiError extends Error {
+    readonly status: number;
+    /**
+     * Canonical error `code` from the response body when the server sent one. Not enumerated here
+     * on purpose — the vocabulary belongs to the host's API, and a union type in this package would
+     * have to be widened by a Jini release every time a product added a code.
+     */
+    readonly code?: string | undefined;
+    /** Raw parsed JSON error body, when present. See decision 1 in the file header. */
+    readonly body?: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, code?: string, body?: Record<string, unknown>);
+}
+/**
+ * Base-case translation from a thrown request error to operator-facing copy.
+ *
+ * This is the "opt-out by default" fallback, not a complete message catalog — see decision 2 in
+ * the file header. A panel with real per-code handling checks its own codes first and falls
+ * through here for the rest:
+ *
+ * ```ts
+ * function describe(e: unknown, fallback: string): string {
+ *   if (e instanceof AdminApiError && e.code === 'PANEL_SPECIFIC_CODE') return '...';
+ *   return describeApiError(e, fallback);
+ * }
+ * ```
+ *
+ * @complexity O(1) — two `instanceof` checks, no iteration.
+ */
+export declare function describeApiError(e: unknown, fallback: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/transport/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/transport/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,6EAA6E;AAC7E,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAExC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAO3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrE"}

package/dist/core/transport/errors.js

@@ -0,0 +1,63 @@
+/**
+ * @file The error contract every admin route group throws, host-supplied or Jini-shipped.
+ *
+ * Ported from the reference implementation's `lib/api.ts` (`ApiError`, `describeApiError`), which is the
+ * only implementation of this shape that has been through real operator use. Two decisions from
+ * that file are carried across deliberately, because both were arrived at by an audit and both
+ * look like oversights if you only read the code:
+ *
+ * 1. **`body` is kept raw.** A caller sometimes needs a route-specific field beyond
+ *    `code`/`message` (a 409's `currentVersion`, a validation route's field list). Exposing the
+ *    parsed body means that never requires an `AdminApiError` subclass per route.
+ *
+ * 2. **There is deliberately NO shared `code` -> message table.** The same `code` means
+ *    genuinely different things in different domains — in the reference implementation,
+ *    `RESOURCE_CONFLICT` is "still
+ *    referenced elsewhere" on Roles, "that slug is already taken" on Workspace, and "that
+ *    username is already in use" on Users. Three correct operator-facing sentences for one code.
+ *    A shared table could only pick one, which is a regression dressed as consolidation. So
+ *    `describeApiError` is only the *base case*: it decides what to show when the server sent no
+ *    message, or when the thrown value is not an `AdminApiError` at all (network failure, a
+ *    thrown non-Error). Panels layer their own per-code copy on top and fall through to this.
+ */
+/** A failed admin API call that reached the server and came back non-2xx. */
+export class AdminApiError extends Error {
+    status;
+    /**
+     * Canonical error `code` from the response body when the server sent one. Not enumerated here
+     * on purpose — the vocabulary belongs to the host's API, and a union type in this package would
+     * have to be widened by a Jini release every time a product added a code.
+     */
+    code;
+    /** Raw parsed JSON error body, when present. See decision 1 in the file header. */
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.name = 'AdminApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+/**
+ * Base-case translation from a thrown request error to operator-facing copy.
+ *
+ * This is the "opt-out by default" fallback, not a complete message catalog — see decision 2 in
+ * the file header. A panel with real per-code handling checks its own codes first and falls
+ * through here for the rest:
+ *
+ * ```ts
+ * function describe(e: unknown, fallback: string): string {
+ *   if (e instanceof AdminApiError && e.code === 'PANEL_SPECIFIC_CODE') return '...';
+ *   return describeApiError(e, fallback);
+ * }
+ * ```
+ *
+ * @complexity O(1) — two `instanceof` checks, no iteration.
+ */
+export function describeApiError(e, fallback) {
+    if (e instanceof AdminApiError)
+        return e.message || fallback;
+    return e instanceof Error ? e.message : fallback;
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/transport/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/transport/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,6EAA6E;AAC7E,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,MAAM,CAAS;IAExB;;;;OAIG;IACM,IAAI,CAAsB;IAEnC,mFAAmF;IAC1E,IAAI,CAAuC;IAEpD,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa,EAAE,IAA8B;QACxF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAU,EAAE,QAAgB;IAC3D,IAAI,CAAC,YAAY,aAAa;QAAE,OAAO,CAAC,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC7D,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnD,CAAC"}

package/dist/core/transport/http.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file The default HTTP `AdminTransport`, and the client assembler.
+ *
+ * Ported from the reference implementation's `lib/api.ts` `request()`, with the two
+ * hard-coded values it closed over — the base URL and the same-origin cookie policy — lifted into
+ * options. Nothing else about the request/response handling changed; the error-body parsing in
+ * particular is deliberately identical, including the `.catch(() => ({}))` on a body that is not
+ * JSON.
+ */
+import type { AdminClient, AdminRouteGroupFactory, AdminTransport } from './types.js';
+/**
+ * The subset of `fetch` this transport actually uses.
+ *
+ * Deliberately narrower than `typeof globalThis.fetch`: the transport only ever passes a string
+ * URL, never a `URL` or a `Request`. Declaring that narrows what a test double has to implement
+ * (the global signature forces a stub to handle three input shapes it will never receive), and
+ * the real `globalThis.fetch` is still assignable here because a function accepting a wider input
+ * satisfies one accepting a narrower one.
+ */
+export type AdminFetch = (input: string, init?: RequestInit) => Promise<Response>;
+export interface HttpTransportOptions {
+    /**
+     * Prefix for every path (`/api/admin/v1`). No trailing slash — paths always start with `/`.
+     *
+     * Unlike the reference implementation's module-level `const BASE`, this is per-transport so one
+     * process can talk to more than one admin API. A fleet orchestrator managing many site instances
+     * in one process is exactly the case where a single shared base is the thing that would have to
+     * be unpicked first.
+     */
+    readonly baseUrl: string;
+    /**
+     * Injected `fetch`, defaulting to the global. Present so a test can supply a stub without
+     * `vi.stubGlobal`, which is what forced the reference implementation's own hook tests to assert
+     * URLs and HTTP methods when what they meant to describe was behaviour.
+     */
+    readonly fetch?: AdminFetch;
+    /**
+     * Merged into every request. `Content-Type: application/json` is applied unless overridden;
+     * a per-call `headers` still wins over both.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Defaults to `same-origin`, matching the cookie-session admin the reference implementation
+     * ships. A token-authenticated
+     * host sets `omit` and supplies an `Authorization` header instead.
+     */
+    readonly credentials?: RequestCredentials;
+}
+/**
+ * The standard `fetch`-backed transport.
+ *
+ * Success bodies are parsed as JSON. A non-2xx response throws `AdminApiError` carrying the
+ * server's `error` string, HTTP status, canonical `code` when present, and the raw parsed body.
+ */
+export declare function createHttpTransport(options: HttpTransportOptions): AdminTransport;
+/**
+ * Assembles route groups into one client.
+ *
+ * Jini-shipped and host-owned groups are indistinguishable here on purpose — both are just
+ * `(transport) => port`. See `types.ts`'s header for the worked example.
+ */
+export declare function createAdminClient<TGroups extends Record<string, AdminRouteGroupFactory<unknown>>>(transport: AdminTransport, groups: TGroups): AdminClient<TGroups>;
+//# sourceMappingURL=http.d.ts.map

package/dist/core/transport/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/core/transport/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElF,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEpD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAkCjF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,EAC/F,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,OAAO,GACd,WAAW,CAAC,OAAO,CAAC,CAYtB"}

package/dist/core/transport/http.js

@@ -0,0 +1,63 @@
+/**
+ * @file The default HTTP `AdminTransport`, and the client assembler.
+ *
+ * Ported from the reference implementation's `lib/api.ts` `request()`, with the two
+ * hard-coded values it closed over — the base URL and the same-origin cookie policy — lifted into
+ * options. Nothing else about the request/response handling changed; the error-body parsing in
+ * particular is deliberately identical, including the `.catch(() => ({}))` on a body that is not
+ * JSON.
+ */
+import { AdminApiError } from './errors.js';
+/**
+ * The standard `fetch`-backed transport.
+ *
+ * Success bodies are parsed as JSON. A non-2xx response throws `AdminApiError` carrying the
+ * server's `error` string, HTTP status, canonical `code` when present, and the raw parsed body.
+ */
+export function createHttpTransport(options) {
+    const { baseUrl, headers: baseHeaders, credentials = 'same-origin' } = options;
+    const doFetch = options.fetch ?? globalThis.fetch;
+    return {
+        async request(path, init = {}) {
+            const res = await doFetch(`${baseUrl}${path}`, {
+                credentials,
+                ...init,
+                // Spread last so a per-call header overrides both the JSON default and the transport's
+                // own. The reference implementation's original spread `...init` last, which meant a call passing `headers` lost
+                // the `Content-Type` default rather than merging with it.
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...baseHeaders,
+                    ...init.headers,
+                },
+            });
+            // A 204 or an empty body is not a JSON parse failure worth surfacing — it is a successful
+            // mutation with nothing to return. Same `.catch(() => ({}))` as the original.
+            const body = (await res.json().catch(() => ({})));
+            if (!res.ok) {
+                throw new AdminApiError(String(body?.error ?? `request failed (${res.status})`), res.status, typeof body?.code === 'string' ? body.code : undefined, body);
+            }
+            return body;
+        },
+    };
+}
+/**
+ * Assembles route groups into one client.
+ *
+ * Jini-shipped and host-owned groups are indistinguishable here on purpose — both are just
+ * `(transport) => port`. See `types.ts`'s header for the worked example.
+ */
+export function createAdminClient(transport, groups) {
+    const built = { transport };
+    for (const [name, factory] of Object.entries(groups)) {
+        // `transport` is a reserved key: shadowing it would silently replace the escape hatch every
+        // host relies on for un-wrapped routes. Loud failure beats a client whose `.transport` is a
+        // route group.
+        if (name === 'transport') {
+            throw new Error('createAdminClient: "transport" is a reserved route-group name');
+        }
+        built[name] = factory(transport);
+    }
+    return built;
+}
+//# sourceMappingURL=http.js.map

package/dist/core/transport/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/core/transport/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8C5C;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC/E,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAElD,OAAO;QACL,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,OAAoB,EAAE;YACnD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,EAAE;gBAC7C,WAAW;gBACX,GAAG,IAAI;gBACP,uFAAuF;gBACvF,gHAAgH;gBAChH,0DAA0D;gBAC1D,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,GAAG,WAAW;oBACd,GAAI,IAAI,CAAC,OAA8C;iBACxD;aACF,CAAC,CAAC;YAEH,0FAA0F;YAC1F,8EAA8E;YAC9E,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAA4B,CAAC;YAE7E,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,MAAM,IAAI,aAAa,CACrB,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,mBAAmB,GAAG,CAAC,MAAM,GAAG,CAAC,EACvD,GAAG,CAAC,MAAM,EACV,OAAO,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EACtD,IAAI,CACL,CAAC;YACJ,CAAC;YACD,OAAO,IAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAyB,EACzB,MAAe;IAEf,MAAM,KAAK,GAA4B,EAAE,SAAS,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,4FAA4F;QAC5F,4FAA4F;QAC5F,eAAe;QACf,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,KAA6B,CAAC;AACvC,CAAC"}

package/dist/core/transport/index.d.ts

@@ -0,0 +1,5 @@
+export { AdminApiError, describeApiError } from './errors.js';
+export { createAdminClient, createHttpTransport } from './http.js';
+export type { AdminFetch, HttpTransportOptions } from './http.js';
+export type { AdminClient, AdminRouteGroupFactory, AdminTransport } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/transport/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/transport/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EAAE,WAAW,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/transport/index.js

@@ -0,0 +1,3 @@
+export { AdminApiError, describeApiError } from './errors.js';
+export { createAdminClient, createHttpTransport } from './http.js';
+//# sourceMappingURL=index.js.map

package/dist/core/transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/transport/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/core/transport/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file The transport seam — the single primitive every admin route group is built on.
+ *
+ * ## Why this exists
+ *
+ * The reference implementation's `lib/api.ts` is 1,548 lines and 134 methods in one flat object literal,
+ * every one of them closing over a module-private `request()` and a module-private
+ * `BASE = "/api/admin/v1"`. That shape has two costs: the whole object is one unit (you cannot
+ * take the 67 generic methods without the 67 CMS-domain ones), and there is no way for a host to
+ * add a route group without editing the file.
+ *
+ * Inverting it — `request` becomes an injected `AdminTransport`, and each route group becomes a
+ * factory over it — makes both work:
+ *
+ * ```ts
+ * const transport = createHttpTransport({ baseUrl: '/api/admin/v1' });
+ *
+ * const client = createAdminClient(transport, {
+ *   identity: createIdentityRoutes,          // shipped by @jini-ai/admin
+ *   media:    createMediaRoutes,             // shipped by @jini-ai/admin
+ *   posts:    createHostPostRoutes,          // the host's own, same signature
+ *   widgets:  createHostWidgetRoutes,        // the host's own
+ * });
+ *
+ * await client.identity.listUsers();   // Jini's
+ * await client.posts.list();           // the host's
+ * ```
+ *
+ * Both halves share one auth policy, one error class, one place to add retries or tracing. A host
+ * adding a route is a factory plus one line in the map — it never edits a Jini file, and it never
+ * grows a second `fetch` wrapper with its own subtly different error handling, which is exactly
+ * how `api.ts` reached 1,548 lines.
+ *
+ * ## Why `AdminTransport` is an interface and not just a function
+ *
+ * A bare `request<T>(path, init)` function would have been enough for HTTP. It is an interface so
+ * a host can supply a non-HTTP implementation without any route group knowing: a fleet orchestrator
+ * drives many site instances in-process and can hand over a direct-dispatch transport that never opens a
+ * socket, and tests can supply a fake that returns fixtures. Both are the same seam, which is the
+ * point.
+ */
+/**
+ * How an admin route group talks to its backend.
+ *
+ * Implementations must throw `AdminApiError` on a non-success response so panels can rely on one
+ * error shape regardless of which transport is wired. A transport that throws its own error type
+ * silently breaks every panel's `instanceof` check.
+ */
+export interface AdminTransport {
+    /**
+     * @param path Route-group-relative path, always starting with `/` (`/users`, `/media/abc`).
+     *   The base is the transport's concern — a route group that embeds a base is not portable to
+     *   a host that mounts the admin API somewhere else.
+     * @param init Standard `RequestInit`. A transport that is not HTTP-backed may ignore fields it
+     *   cannot honour, but must respect `method` and `body`.
+     * @throws {AdminApiError} on any non-success response.
+     */
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+}
+/**
+ * A route group: turns a transport into a typed set of operations.
+ *
+ * Every port implementation in this package is one of these, and a host's own route groups use
+ * the identical signature — that symmetry is what lets Jini-shipped and host-owned groups sit in
+ * the same client with no adapter between them.
+ */
+export type AdminRouteGroupFactory<TPort> = (transport: AdminTransport) => TPort;
+/**
+ * The assembled client: one object carrying every wired route group.
+ *
+ * `TGroups` is inferred from the factory map handed to `createAdminClient`, so a host's own
+ * groups are as type-safe as the shipped ones with no declaration merging or module augmentation.
+ */
+export type AdminClient<TGroups extends Record<string, AdminRouteGroupFactory<unknown>>> = {
+    readonly [K in keyof TGroups]: ReturnType<TGroups[K]>;
+} & {
+    /** The transport every group was built over — exposed so a host can make one-off calls to a
+     *  route it has not (or will never) wrap in a group, without reaching for a bare `fetch`. */
+    readonly transport: AdminTransport;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/transport/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/transport/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,cAAc,KAAK,KAAK,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,IAAI;IACzF,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD,GAAG;IACF;iGAC6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;CACpC,CAAC"}