@jini-ai/admin 0.3.9 → 0.4.0

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

@@ -13,23 +13,25 @@
  * factory over it — makes both work:
  *
  * ```ts
- * const transport = createHttpTransport({ baseUrl: '/api/admin/v1' });
+ * const transport = createHttpTransport({ baseUrl: '/api/admin/v1', fetch: ({ url }, init) => fetch(url, init) });
  *
- * const client = createAdminClient(transport, {
- *   identity: createIdentityRoutes,          // shipped by @jini-ai/admin
- *   media:    createMediaRoutes,             // shipped by @jini-ai/admin
+ * const client = createAdminClient({ transport, groups: {
+ *   identity: createHostIdentityRoutes,      // host implementation of AdminIdentityPort
+ *   media:    createHostMediaRoutes,         // host implementation of AdminMediaPort
  *   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
+ * await client.identity.listUsers({}); // host adapter over Jini's port contract
+ * await client.posts.list({});         // the host's own port
  * ```
  *
  * 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.
+ * This package ships port contracts and the assembler, not backend route factories;
+ * the host supplies each factory and may share it with other hosts without changing this seam.
  *
  * ## Why `AdminTransport` is an interface and not just a function
  *
@@ -51,25 +53,35 @@ 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`.
+     * @param init Standard `RequestInit` plus an optional success observer. 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>;
+    request<T>(requiredArgs: {
+        readonly path: string;
+    }, optionalArgs?: RequestInit & {
+        /** Called only on success with the response metadata, after parsing and before resolving.
+         *  Reading ETag here lets route adapters send If-Match without duplicating transport logic. */
+        readonly onOk?: (args: {
+            readonly response: Response;
+        }) => void;
+    }): 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
+ * Host implementations of this package's ports and a host's own route groups use
+ * the identical signature — that symmetry is what lets shared and host-owned groups sit in
  * the same client with no adapter between them.
  */
-export type AdminRouteGroupFactory<TPort> = (transport: AdminTransport) => TPort;
+export type AdminRouteGroupFactory<TPort> = (requiredArgs: {
+    readonly 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.
+ * groups are as type-safe as shared 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]>;

package/dist/core/transport/types.js

@@ -13,23 +13,25 @@
  * factory over it — makes both work:
  *
  * ```ts
- * const transport = createHttpTransport({ baseUrl: '/api/admin/v1' });
+ * const transport = createHttpTransport({ baseUrl: '/api/admin/v1', fetch: ({ url }, init) => fetch(url, init) });
  *
- * const client = createAdminClient(transport, {
- *   identity: createIdentityRoutes,          // shipped by @jini-ai/admin
- *   media:    createMediaRoutes,             // shipped by @jini-ai/admin
+ * const client = createAdminClient({ transport, groups: {
+ *   identity: createHostIdentityRoutes,      // host implementation of AdminIdentityPort
+ *   media:    createHostMediaRoutes,         // host implementation of AdminMediaPort
  *   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
+ * await client.identity.listUsers({}); // host adapter over Jini's port contract
+ * await client.posts.list({});         // the host's own port
  * ```
  *
  * 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.
+ * This package ships port contracts and the assembler, not backend route factories;
+ * the host supplies each factory and may share it with other hosts without changing this seam.
  *
  * ## Why `AdminTransport` is an interface and not just a function
  *

package/dist/media/adapters/http.d.ts

@@ -0,0 +1,27 @@
+import type { MediaApiPort } from '../ports.js';
+import type { MediaRequestOptions } from '../models.js';
+/** Authentication, workspace addressing, transport retries and error decoding belong to the host.
+ * Retryable errors remain intact so the library can recover automatically after an outage.
+ * The adapter never reaches for global fetch, tokens or a hardcoded workspace. */
+export interface MediaTransportPort {
+    request<T>(required: {
+        path: string;
+        method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        body?: unknown;
+    }, optional?: MediaRequestOptions): Promise<T>;
+    url(required: {
+        path: string;
+    }, optional?: Record<string, never>): string;
+}
+export declare function createHttpMediaApi({ transport, basePath }: {
+    transport: MediaTransportPort;
+    basePath: string;
+}, { replacePath, restorePath, }?: {
+    replacePath?: (required: {
+        id: string;
+    }, optional?: Record<string, never>) => string;
+    restorePath?: (required: {
+        id: string;
+    }, optional?: Record<string, never>) => string;
+}): MediaApiPort;
+//# sourceMappingURL=http.d.ts.map

package/dist/media/adapters/http.js

@@ -0,0 +1,44 @@
+import { queryMedia } from '../rules.js';
+export function createHttpMediaApi({ transport, basePath }, { replacePath, restorePath, } = {}) {
+    const base = basePath.replace(/\/$/, '');
+    const path = (id) => `${base}/${encodeURIComponent(id)}`;
+    async function asset(method, target, body, options) {
+        options.signal?.throwIfAborted();
+        const response = await transport.request({ path: target, method, ...(body === undefined ? {} : { body }) }, options);
+        return response.media;
+    }
+    return {
+        replaceSupported: !!replacePath,
+        restoreSupported: !!restorePath,
+        async list(query, options = {}) {
+            options.signal?.throwIfAborted();
+            const response = await transport.request({ path: base, method: 'GET' }, options);
+            return queryMedia({ media: response.media, query });
+        },
+        upload(input, { signal, ...metadata } = {}) {
+            return asset('POST', base, { ...input, ...metadata }, signal ? { signal } : {});
+        },
+        update({ id, patch }, options = {}) {
+            return asset('PATCH', path(id), patch, options);
+        },
+        ...(replacePath ? { replace({ id, upload }, options = {}) {
+                return asset('POST', replacePath({ id }), upload, options);
+            } } : {}),
+        trash({ id }, options = {}) {
+            return asset('POST', `${path(id)}/trash`, undefined, options);
+        },
+        ...(restorePath ? { restore({ id }, options = {}) {
+                return asset('POST', restorePath({ id }), undefined, options);
+            } } : {}),
+        delete({ id }, options = {}) {
+            options.signal?.throwIfAborted();
+            return transport.request({ path: path(id), method: 'DELETE' }, options);
+        },
+        originalUrl({ id, version }, _optional = {}) {
+            // Replacement preserves the id; the refreshed version must identify its new bytes.
+            const revision = version === undefined ? '' : `?v=${encodeURIComponent(version)}`;
+            return transport.url({ path: `${path(id)}/original${revision}` });
+        },
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/media/adapters/memory.d.ts

@@ -0,0 +1,11 @@
+import type { MediaApiPort, MediaProvidersPort } from '../ports.js';
+import type { MediaAsset, MediaProvider } from '../models.js';
+export declare function createMemoryMediaApi({ assets }: {
+    assets?: readonly MediaAsset[];
+}, { now }?: {
+    now?: () => string;
+}): MediaApiPort;
+export declare function createMemoryMediaProviders({ providers }: {
+    providers?: readonly MediaProvider[];
+}, _optional?: Record<string, never>): MediaProvidersPort;
+//# sourceMappingURL=memory.d.ts.map

package/dist/media/adapters/memory.js

@@ -0,0 +1,139 @@
+import { queryMedia } from '../rules.js';
+export function createMemoryMediaApi({ assets = [] }, { now = () => new Date().toISOString() } = {}) {
+    const items = new Map(assets.map((item) => [item.id, Object.freeze({ ...item })]));
+    let sequence = 0;
+    function check(options) {
+        options.signal?.throwIfAborted();
+    }
+    function get(id) {
+        const item = items.get(id);
+        if (!item)
+            throw new Error(`Media not found: ${id}`);
+        return item;
+    }
+    function put(item) {
+        const frozen = Object.freeze(item);
+        items.set(item.id, frozen);
+        return frozen;
+    }
+    function content(input) {
+        // The REAL server ignores the declared string and stores sniffContentType(bytes) instead.
+        // This fake has no bytes to sniff — its input is an opaque base64 string a test made up —
+        // so it echoes what the caller declared. Tests needing disagreement must seed assets directly.
+        return { byteSize: Math.max(0, Math.floor(input.dataBase64.length * 3 / 4) - (input.dataBase64.match(/=+$/)?.[0].length ?? 0)), contentType: input.contentType, sha256: `memory-content-${++sequence}` };
+    }
+    return {
+        replaceSupported: true,
+        restoreSupported: true,
+        async list(query, options = {}) {
+            check(options);
+            return Object.freeze(queryMedia({ media: [...items.values()], query }));
+        },
+        async upload(input, options = {}) {
+            check(options);
+            let id;
+            do {
+                id = `memory-${++sequence}`;
+            } while (items.has(id));
+            const timestamp = now();
+            return put({
+                id,
+                title: options.title ?? input.filename,
+                alt: options.alt ?? '',
+                caption: options.caption ?? '',
+                credit: options.credit ?? '',
+                slug: options.slug ?? id,
+                width: options.width ?? null,
+                height: options.height ?? null,
+                cssClass: options.cssClass ?? null,
+                htmlAttributes: options.htmlAttributes ?? null,
+                status: 'active',
+                publicUrl: null,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                version: 1,
+                ...content(input),
+            });
+        },
+        async update({ id, patch }, options = {}) {
+            check(options);
+            const previous = get(id);
+            const metadata = Object.fromEntries(Object.entries(patch).filter(([key, value]) => ['title', 'slug', 'alt', 'caption', 'credit', 'width', 'height', 'cssClass', 'htmlAttributes'].includes(key) && value !== undefined));
+            return put({ ...previous, ...metadata, version: previous.version + 1, updatedAt: now() });
+        },
+        async replace({ id, upload }, options = {}) {
+            check(options);
+            const previous = get(id);
+            if (previous.status !== 'active')
+                throw new Error('Cannot replace trashed media');
+            return put({
+                ...previous,
+                ...content(upload),
+                version: previous.version + 1,
+                updatedAt: now(),
+            });
+        },
+        async trash({ id }, options = {}) {
+            check(options);
+            const previous = get(id);
+            return put({
+                ...previous,
+                status: 'trashed',
+                publicUrl: null,
+                version: previous.version + 1,
+                updatedAt: now(),
+            });
+        },
+        async restore({ id }, options = {}) {
+            check(options);
+            const previous = get(id);
+            return put({ ...previous, status: 'active', version: previous.version + 1, updatedAt: now() });
+        },
+        async delete({ id }, options = {}) {
+            check(options);
+            if (get(id).status !== 'trashed')
+                throw new Error('Trash media before permanent deletion');
+            items.delete(id);
+            return { purged: true };
+        },
+        // Distinct memory:// scheme so a URL assertion fails if the consumer calls a real client.
+        originalUrl: ({ id }) => `memory://media-original/${encodeURIComponent(id)}`,
+    };
+}
+export function createMemoryMediaProviders({ providers = [] }, _optional = {}) {
+    const items = new Map(providers.map((item) => [item.id, Object.freeze({ ...item })]));
+    function write(id, configured) {
+        const previous = items.get(id);
+        if (!previous)
+            throw new Error('Unknown provider');
+        const next = Object.freeze({ ...previous, configured });
+        items.set(id, next);
+        return next;
+    }
+    return {
+        async list(_required, options = {}) {
+            options.signal?.throwIfAborted();
+            return Object.freeze([...items.values()]);
+        },
+        async saveSettings({ id, baseUrl, model }, options = {}) {
+            options.signal?.throwIfAborted();
+            const previous = items.get(id);
+            if (!previous)
+                throw new Error('Unknown provider');
+            const next = Object.freeze({ ...previous, baseUrl, model });
+            items.set(id, next);
+            return next;
+        },
+        async saveCredential({ id, credential }, options = {}) {
+            options.signal?.throwIfAborted();
+            if (!credential.trim())
+                throw new Error('Credential is required');
+            return write(id, true);
+        },
+        async removeCredential({ id }, options = {}) {
+            options.signal?.throwIfAborted();
+            return write(id, false);
+        },
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/media/conformance/media-api.conformance.d.ts

@@ -0,0 +1,7 @@
+import type { MediaApiPort } from '../ports.js';
+/** Destructive checklist: run only against an isolated backend with no production data.
+ * Returns named checks and throws at the first failed contract. No test-framework dependency. */
+export declare function runMediaApiConformance({ api }: {
+    api: MediaApiPort;
+}, _optional?: Record<string, never>): Promise<readonly string[]>;
+//# sourceMappingURL=media-api.conformance.d.ts.map

package/dist/media/conformance/media-api.conformance.js

@@ -0,0 +1,69 @@
+import { canReplaceMedia } from '../rules.js';
+/** Destructive checklist: run only against an isolated backend with no production data.
+ * Returns named checks and throws at the first failed contract. No test-framework dependency. */
+export async function runMediaApiConformance({ api }, _optional = {}) {
+    const checks = [];
+    function assert(condition, name) {
+        if (!condition)
+            throw new Error(`Media API conformance: ${name}`);
+        checks.push(name);
+    }
+    async function rejects(run, name) {
+        let rejected = false;
+        try {
+            await run();
+        }
+        catch {
+            rejected = true;
+        }
+        assert(rejected, name);
+    }
+    const input = {
+        filename: 'conformance.png',
+        contentType: 'image/png',
+        dataBase64: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aT1sAAAAASUVORK5CYII=',
+    };
+    const created = await api.upload(input, { alt: 'initial alt' });
+    assert(created.id.length > 0 && created.status === 'active', 'upload creates an active asset');
+    try {
+        const before = await api.list({});
+        assert(before.some((item) => item.id === created.id), 'list contains upload');
+        const updated = await api.update({ id: created.id, patch: { title: 'renamed' } });
+        assert(updated.title === 'renamed' && updated.alt === 'initial alt', 'partial metadata patch preserves untouched fields');
+        assert(created.title === 'conformance.png', 'prior snapshots do not mutate');
+        const images = await api.list({ filter: 'images' });
+        assert(images.every((item) => item.contentType?.startsWith('image/')), 'image filter');
+        assert(typeof api.originalUrl({ id: created.id }) === 'string', 'original URL is synchronous');
+        await rejects(() => api.delete({ id: created.id }), 'active asset cannot be purged');
+        if (canReplaceMedia({ api })) {
+            const replaced = await api.replace({
+                id: created.id,
+                upload: { ...input, filename: 'replacement.png' },
+            });
+            assert(replaced.id === created.id &&
+                replaced.alt === updated.alt &&
+                replaced.title === updated.title, 'replace retains identity and metadata');
+        }
+        else {
+            assert(api.replace === undefined || api.replaceSupported === false, 'replacement is optional and unavailable');
+        }
+        const abort = new AbortController();
+        abort.abort();
+        await rejects(() => api.list({}, { signal: abort.signal }), 'aborted list rejects');
+        await rejects(() => api.update({ id: created.id, patch: { title: 'must not save' } }, { signal: abort.signal }), 'aborted write rejects');
+        assert((await api.list({})).find((item) => item.id === created.id)?.title === 'renamed', 'aborted write has no effects');
+        const trashed = await api.trash({ id: created.id });
+        assert(trashed.status === 'trashed', 'trash is a distinct state');
+        assert((await api.delete({ id: created.id })).purged, 'trashed asset can be purged');
+        assert(!(await api.list({})).some((item) => item.id === created.id), 'purge removes asset');
+        await rejects(() => api.update({ id: created.id, patch: {} }), 'missing asset rejects');
+        return Object.freeze(checks);
+    }
+    finally {
+        if ((await api.list({})).some((item) => item.id === created.id)) {
+            await api.trash({ id: created.id });
+            await api.delete({ id: created.id });
+        }
+    }
+}
+//# sourceMappingURL=media-api.conformance.js.map

package/dist/media/controllers/edit-media.controller.d.ts

@@ -0,0 +1,24 @@
+import type { MediaApiPort } from '../ports.js';
+import type { MediaAsset, MediaMetadataPatch, UploadInput } from '../models.js';
+export declare function createEditMediaController({ api, item }: {
+    api: MediaApiPort;
+    item: MediaAsset;
+}, _optional?: Record<string, never>): {
+    getSnapshot: () => Readonly<{
+        draft: MediaMetadataPatch;
+        saving: boolean;
+        error: string | null;
+    }>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    dispose: () => void;
+    setDraft({ patch }: {
+        patch: MediaMetadataPatch;
+    }, _optional?: Record<string, never>): void;
+    save(_required?: Record<string, never>, _optional?: Record<string, never>): Promise<boolean>;
+    replace({ upload }: {
+        upload: UploadInput;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+};
+//# sourceMappingURL=edit-media.controller.d.ts.map

package/dist/media/controllers/edit-media.controller.js

@@ -0,0 +1,69 @@
+import { createControllerStore } from '../../core/module/controller-store.js';
+import { diffMediaMetadata, canReplaceMedia } from '../rules.js';
+export function createEditMediaController({ api, item }, _optional = {}) {
+    // Frozen at mount, exactly like draft's initializer — stays the value draft was seeded
+    // from even as the live list advances underneath it. Never diff against a drifting item.
+    let baseline = Object.freeze({ ...item });
+    const store = createControllerStore({
+        initial: {
+            draft: metadataDraft({ item }),
+            saving: false,
+            error: null,
+        },
+    });
+    async function perform(run) {
+        if (store.signal.aborted || store.getSnapshot().saving)
+            return false;
+        store.set({ patch: { saving: true, error: null } });
+        try {
+            const saved = await run();
+            if (store.signal.aborted)
+                return false;
+            baseline = saved;
+            store.set({
+                patch: {
+                    draft: metadataDraft({ item: baseline }),
+                },
+            });
+            return true;
+        }
+        catch (error) {
+            store.set({
+                patch: { error: error instanceof Error ? error.message : 'Failed to save media metadata' },
+            });
+            return false;
+        }
+        finally {
+            store.set({ patch: { saving: false } });
+        }
+    }
+    return {
+        getSnapshot: store.getSnapshot,
+        subscribe: store.subscribe,
+        dispose: store.dispose,
+        setDraft({ patch }, _optional = {}) {
+            if (!store.getSnapshot().saving)
+                store.set({ patch: { draft: { ...store.getSnapshot().draft, ...patch } } });
+        },
+        async save(_required = {}, _optional = {}) {
+            const patch = diffMediaMetadata({ item: baseline, draft: store.getSnapshot().draft });
+            if (Object.keys(patch).length === 0)
+                return true;
+            return perform(() => api.update({ id: item.id, patch }, { signal: store.signal }));
+        },
+        async replace({ upload }, _optional = {}) {
+            if (!canReplaceMedia({ api })) {
+                store.set({ patch: { error: 'File replacement is unavailable' } });
+                return false;
+            }
+            return perform(() => api.replace({ id: item.id, upload }, { signal: store.signal }));
+        },
+    };
+}
+/** Do not invent CMS fields for hosts which omit them: undefined is an untouched field. */
+function metadataDraft({ item }) {
+    return Object.fromEntries(Object.entries({ title: item.title, slug: item.slug, alt: item.alt,
+        caption: item.caption, credit: item.credit, width: item.width, height: item.height,
+        cssClass: item.cssClass, htmlAttributes: item.htmlAttributes }).filter(([, value]) => value !== undefined));
+}
+//# sourceMappingURL=edit-media.controller.js.map

package/dist/media/controllers/library.controller.d.ts

@@ -0,0 +1,47 @@
+import { countMediaTabs } from '../rules.js';
+import type { MediaApiPort } from '../ports.js';
+import type { MediaAsset, MediaQuery, UploadInput } from '../models.js';
+export interface LibraryState {
+    readonly items: readonly MediaAsset[] | null;
+    readonly query: MediaQuery;
+    readonly loading: boolean;
+    readonly busy: boolean;
+    readonly pendingIds: readonly string[];
+    readonly error: string | null;
+    readonly pendingPurge: MediaAsset | null;
+    readonly hasUntyped: boolean;
+    readonly counts: ReturnType<typeof countMediaTabs> | null;
+}
+export declare function createLibraryController({ api }: {
+    api: MediaApiPort;
+}, { query }?: {
+    query?: MediaQuery;
+}): {
+    getSnapshot: () => Readonly<LibraryState>;
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }) => () => void;
+    load: (_required?: Record<string, never>, _optional?: Record<string, never>) => Promise<void>;
+    setQuery({ query }: {
+        query: MediaQuery;
+    }, _optional?: Record<string, never>): Promise<void>;
+    upload({ input, alt }: {
+        input: UploadInput;
+        alt?: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    trash({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    restore({ id }: {
+        id: string;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    requestPurge({ item }: {
+        item: MediaAsset;
+    }, _optional?: Record<string, never>): void;
+    cancelPurge(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+    confirmPurge({ confirmed }: {
+        confirmed: boolean;
+    }, _optional?: Record<string, never>): Promise<boolean>;
+    dispose(_required?: Record<string, never>, _optional?: Record<string, never>): void;
+};
+//# sourceMappingURL=library.controller.d.ts.map