@honua/react 0.1.2-beta.0 → 0.1.7-beta.0

package/studio/lifecycle-client.js

@@ -0,0 +1,299 @@
+/**
+ * Typed client for the Studio package lifecycle API
+ * (`/api/v{version}/studio` in `honua-server`): package-family capability
+ * discovery, draft CRUD with optimistic-generation checking, validate,
+ * preview-plan, immutable content versions, version comparisons, publication
+ * requests, reopen, and rollback requests.
+ *
+ * Mirrors {@link HonuaControlPlaneClient}'s ergonomics
+ * (`src/control-plane/client.ts`): construct with the SDK's standard
+ * {@link HonuaClient} (transport, auth, retry, and timeout are inherited from
+ * it), reach resource groups off the client instance
+ * (`.drafts`, `.contentVersions`, `.publicationRequests`, `.rollbackRequests`,
+ * `.packageFamilies`), and use `.raw()` for any endpoint that does not yet
+ * have a dedicated method.
+ *
+ * Every method throws {@link HonuaStudioError} on a non-2xx response — see
+ * `./lifecycle-errors.js` for the RFC 7807 problem-detail taxonomy and the
+ * `generation-conflict` discriminant.
+ *
+ * ## Enumeration gap
+ *
+ * The lifecycle API doc is explicit that **there is no endpoint to enumerate
+ * drafts or content items** — only single-resource reads
+ * (`GET /package-drafts/{draftId}`, `GET /content-items/{itemId}/versions`,
+ * `GET /content-items/{itemId}/versions/{versionId}`) and the
+ * family-discovery list (`GET /package-families`, which already returns every
+ * family in one response and does need no list method of its own).
+ * `honua-server#3003` tracks adding a draft/content-item enumeration
+ * endpoint. Until it ships:
+ *
+ * - `contentVersions.list(itemId)` already covers version enumeration *for a
+ *   known item* — the gap is discovering `itemId`/`draftId` values in the
+ *   first place, not paging a known collection.
+ * - `.raw()` reaches any endpoint honua-server adds before this client grows
+ *   a dedicated method for it, without a breaking-change window.
+ * - When the enumeration endpoint ships, it is additive: a new
+ *   `drafts.list(options)` (or a new resource group) can be added without
+ *   touching any existing method signature.
+ *
+ * @module
+ */
+import { isHonuaError } from "../core/errors.js";
+import { HonuaStudioError, classifyStudioProblemStatus } from "./lifecycle-errors.js";
+/** Default base path for the Studio package lifecycle API. */
+export const HONUA_STUDIO_LIFECYCLE_BASE_PATH = "/api/v1/studio";
+/** Construct a {@link HonuaStudioLifecycleClient} from an existing {@link HonuaClient}. */
+export function createHonuaStudioLifecycleClient(options) {
+    return new HonuaStudioLifecycleClient(options);
+}
+/**
+ * Typed client for every endpoint in the Studio package lifecycle API.
+ *
+ * @experimental Not yet covered by the SDK's semver contract.
+ */
+export class HonuaStudioLifecycleClient {
+    #client;
+    #basePath;
+    packageFamilies;
+    drafts;
+    contentVersions;
+    publicationRequests;
+    rollbackRequests;
+    constructor(options) {
+        this.#client = options.client;
+        this.#basePath = normalizeBasePath(options.basePath ?? HONUA_STUDIO_LIFECYCLE_BASE_PATH);
+        this.packageFamilies = new HonuaStudioPackageFamiliesClient(this);
+        this.drafts = new HonuaStudioDraftsClient(this);
+        this.contentVersions = new HonuaStudioContentVersionsClient(this);
+        this.publicationRequests = new HonuaStudioPublicationRequestsClient(this);
+        this.rollbackRequests = new HonuaStudioRollbackRequestsClient(this);
+    }
+    get basePath() {
+        return this.#basePath;
+    }
+    /** Escape hatch for endpoints without a dedicated method yet (see the module doc's "Enumeration gap"). */
+    raw(request) {
+        return this.request(request.method ?? "GET", request.path, request.body, {
+            signal: request.signal,
+            headers: request.headers,
+        });
+    }
+    /** @internal */
+    async request(method, path, body, options = {}) {
+        try {
+            const response = await this.#client.pipelineFetch(method, this.resolvePath(path), { headers: jsonHeaders(options.headers), body: body === undefined ? null : JSON.stringify(body) }, options.signal);
+            if (response.status === 204)
+                return undefined;
+            return unwrapApiResponse(await readJson(response));
+        }
+        catch (error) {
+            throw toStudioError(error);
+        }
+    }
+    /** @internal */
+    resolvePath(path) {
+        if (path.startsWith("http://") || path.startsWith("https://"))
+            return path;
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        if (normalized === this.#basePath || normalized.startsWith(`${this.#basePath}/`))
+            return normalized;
+        return `${this.#basePath}${normalized}`;
+    }
+}
+/** `GET /package-families` — discover every package family's capabilities. */
+export class HonuaStudioPackageFamiliesClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /** Discover every package family, schema version, format, support level, and limitations. */
+    list(options = {}) {
+        return this.#lifecycle.request("GET", "/package-families", undefined, options);
+    }
+}
+/** `/package-drafts*` — mutable draft CRUD, validation, preview, and save-as-version. */
+export class HonuaStudioDraftsClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /** `POST /package-drafts` — create a mutable package draft. */
+    create(request, options = {}) {
+        return this.#lifecycle.request("POST", "/package-drafts", request, options);
+    }
+    /** `GET /package-drafts/{draftId}` — retrieve a mutable draft. */
+    get(draftId, options = {}) {
+        return this.#lifecycle.request("GET", `/package-drafts/${encodeURIComponent(draftId)}`, undefined, options);
+    }
+    /**
+     * `PUT /package-drafts/{draftId}` — replace a mutable draft with optional
+     * optimistic `generation` checking. A stale `generation` throws
+     * {@link HonuaStudioError} with `code: "generation-conflict"`.
+     */
+    replace(draftId, request, options = {}) {
+        return this.#lifecycle.request("PUT", `/package-drafts/${encodeURIComponent(draftId)}`, request, options);
+    }
+    /** `DELETE /package-drafts/{draftId}` — delete a draft. */
+    async delete(draftId, options = {}) {
+        await this.#lifecycle.request("DELETE", `/package-drafts/${encodeURIComponent(draftId)}`, undefined, options);
+    }
+    /** `POST /package-drafts/{draftId}/validate` — re-run validation, persisting the summary on the draft. */
+    validate(draftId, options = {}) {
+        return this.#lifecycle.request("POST", `/package-drafts/${encodeURIComponent(draftId)}/validate`, undefined, options);
+    }
+    /**
+     * `POST /package-drafts/{draftId}/preview-plan` — return a stable preview
+     * plan. `gp`/`etl`/`workflow` drafts advertise job-backed previews.
+     */
+    previewPlan(draftId, options = {}) {
+        return this.#lifecycle.request("POST", `/package-drafts/${encodeURIComponent(draftId)}/preview-plan`, undefined, options);
+    }
+    /**
+     * `POST /package-drafts/{draftId}/content-versions` — save a draft as an
+     * immutable content version and move the item's current pointer.
+     */
+    createContentVersion(draftId, options = {}) {
+        return this.#lifecycle.request("POST", `/package-drafts/${encodeURIComponent(draftId)}/content-versions`, undefined, options);
+    }
+}
+/** `/content-items/{itemId}/versions*` and `/version-comparisons` — immutable content versions. */
+export class HonuaStudioContentVersionsClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /** `GET /content-items/{itemId}/versions` — list immutable versions ordered by `versionNumber`. */
+    list(itemId, options = {}) {
+        return this.#lifecycle.request("GET", `/content-items/${encodeURIComponent(itemId)}/versions`, undefined, options);
+    }
+    /** `GET /content-items/{itemId}/versions/{versionId}` — retrieve one immutable version. */
+    get(itemId, versionId, options = {}) {
+        return this.#lifecycle.request("GET", `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}`, undefined, options);
+    }
+    /**
+     * `POST /content-items/{itemId}/version-comparisons` — compare two
+     * immutable versions by content hash, dependencies, validation, and
+     * provenance.
+     */
+    compare(itemId, request, options = {}) {
+        return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/version-comparisons`, request, options);
+    }
+    /**
+     * `POST /content-items/{itemId}/versions/{versionId}/reopen` — copy an
+     * immutable version into a new mutable draft with `baseVersionId` set.
+     */
+    reopen(itemId, versionId, request = {}, options = {}) {
+        return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}/reopen`, request, options);
+    }
+}
+/** `/content-items/{itemId}/versions/{versionId}/publish-requests`. */
+export class HonuaStudioPublicationRequestsClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /**
+     * `POST /content-items/{itemId}/versions/{versionId}/publish-requests` —
+     * persist a publication request and move the published pointer when
+     * validation permits.
+     */
+    create(itemId, versionId, request = {}, options = {}) {
+        return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}/publish-requests`, request, options);
+    }
+}
+/** `/content-items/{itemId}/rollback-requests`. */
+export class HonuaStudioRollbackRequestsClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /**
+     * `POST /content-items/{itemId}/rollback-requests` — persist a rollback
+     * request and move the current, published, or both pointers to an earlier
+     * immutable version.
+     */
+    create(itemId, request, options = {}) {
+        return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/rollback-requests`, request, options);
+    }
+}
+function normalizeBasePath(path) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    let end = normalized.length;
+    while (end > 1 && normalized[end - 1] === "/")
+        end -= 1;
+    return normalized.slice(0, end);
+}
+function jsonHeaders(headers) {
+    return { Accept: "application/json", "Content-Type": "application/json", ...headersToRecord(headers) };
+}
+function headersToRecord(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return { ...headers };
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+/** Unwrap `ApiResponse<T>` (`{ success, data, timestamp }`) into `T`, tolerating an already-unwrapped body. */
+function unwrapApiResponse(body) {
+    if (isRecord(body) && "data" in body && "success" in body) {
+        return body.data;
+    }
+    return body;
+}
+/**
+ * True when `error` has the exact shape a `HonuaHttpError` carries —
+ * deliberately **not** `error instanceof HonuaHttpError`.
+ *
+ * This module ships as part of the generated `@honua/app-platform/studio`
+ * split package (see `src/studio/index.ts`'s module doc and
+ * `scripts/prepare-split-packages.mjs`, which copies `core/` — including
+ * `core/errors.js` — into every split package rather than importing it from
+ * the `@honua/sdk` peer). A caller that wires this client to a `HonuaClient`
+ * constructed from that peer's own copy of `@honua/sdk-js` therefore has
+ * *two* separate `HonuaHttpError` classes in play — one per package copy of
+ * the identical source file. `error instanceof HonuaHttpError` silently
+ * returns `false` across that boundary even though `error` is exactly a
+ * `HonuaHttpError`, a classic dual-package hazard.
+ *
+ * Detection instead follows the SDK's own established cross-realm error
+ * guard, {@link isHonuaError} (`isHonuaSdkError`, `src/core/error-envelope.js`
+ * — "Cross-realm type guard backed by the public tag and registered code"):
+ * match on the frozen `sdkCode` tag every `HonuaHttpError` carries
+ * (`"core.http.transient"` / `"core.http.rejected"` — byte-identical string
+ * constants in every copy of the module, unlike the class's identity) plus a
+ * direct, non-`instanceof` read of the HTTP-specific `statusCode` own
+ * property. `HonuaStudioError` is built from these primitive values alone, so
+ * its construction never depends on receiving a specific class instance
+ * either.
+ */
+function isHonuaHttpErrorLike(error) {
+    if (!isHonuaError(error))
+        return false;
+    if (error.sdkCode !== "core.http.transient" && error.sdkCode !== "core.http.rejected")
+        return false;
+    return typeof error.statusCode === "number";
+}
+/** Convert a thrown `HonuaHttpError`-shaped rejection into a typed {@link HonuaStudioError}; pass through anything else. */
+function toStudioError(error) {
+    if (!isHonuaHttpErrorLike(error))
+        return error;
+    const problem = toProblemDetails(error.body);
+    const code = classifyStudioProblemStatus(error.statusCode);
+    const message = problem?.detail ?? problem?.title ?? error.message;
+    return new HonuaStudioError(code, error.statusCode, message, problem, { cause: error });
+}
+function toProblemDetails(body) {
+    return isRecord(body) ? body : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/studio/lifecycle-errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Error taxonomy for {@link HonuaStudioLifecycleClient}.
+ *
+ * Every non-2xx response from the Studio package lifecycle API
+ * (`/api/v{version}/studio`) is either a handler-generated client error
+ * (`400`/`404`/`409`) or a caught internal failure (`500`), and both use
+ * RFC 7807 problem details with `type: "https://honua.io/problems/studio"`
+ * (see `docs/internal/admin-api/studio-package-lifecycle.md` in
+ * `honua-server`). {@link HonuaStudioError} normalizes both into one typed
+ * shape so callers branch on `.code` instead of parsing HTTP status numbers
+ * or problem-detail strings.
+ *
+ * `generation-conflict` is a distinct discriminant (not folded into a
+ * generic `"conflict"` bucket) because it is the one Studio failure mode the
+ * SDK expects callers to *recover from automatically* — reload the draft and
+ * retry — rather than surface to a user. Use
+ * {@link isHonuaStudioGenerationConflict} to branch on it without comparing
+ * `.code` strings directly.
+ *
+ * This module intentionally does not join the central `HonuaSdkError`
+ * registry (`src/core/error-code-registry.ts`): `studio` is an
+ * `@experimental`, not-yet-semver-covered domain, matching the existing
+ * `HonuaCollaborationError` (`src/collaboration/errors.ts`) precedent for
+ * experimental-domain errors pending a scoped migration.
+ *
+ * @module
+ */
+/**
+ * Discriminant classifying a {@link HonuaStudioError}. Derived from the HTTP
+ * status code of the failed response:
+ *
+ * - `validation` — `400`, request or envelope failed validation.
+ * - `not-found` — `404`, the draft/version/content item does not exist (or,
+ *   per the API doc, is not reachable from the given `itemId`/`versionId`
+ *   pair — cross-item ids are treated as not found).
+ * - `generation-conflict` — `409`, the draft's server-managed `generation`
+ *   changed since the caller last read it (`PUT /package-drafts/{draftId}`
+ *   optimistic-concurrency check). Reload the draft and retry.
+ * - `internal` — `500`, a caught internal failure.
+ * - `unknown` — any other status the doc does not enumerate.
+ *
+ * @experimental
+ */
+export type HonuaStudioProblemKind = "validation" | "not-found" | "generation-conflict" | "internal" | "unknown";
+/**
+ * RFC 7807 problem-details body returned by the Studio package lifecycle API.
+ * `type` is `"https://honua.io/problems/studio"` on every documented error
+ * response; `code` and `errors` are optional server-supplied extensions.
+ *
+ * @experimental
+ */
+export interface HonuaStudioProblemDetails {
+    readonly type?: string;
+    readonly title?: string;
+    readonly status?: number;
+    readonly detail?: string;
+    readonly instance?: string;
+    readonly code?: string;
+    readonly errors?: Record<string, readonly string[]>;
+    readonly [extra: string]: unknown;
+}
+/** Canonical RFC 7807 `type` URI the Studio lifecycle API uses for every problem response. */
+export declare const HONUA_STUDIO_PROBLEM_TYPE: "https://honua.io/problems/studio";
+/**
+ * Thrown by every {@link HonuaStudioLifecycleClient} method when the server
+ * returns a non-2xx response. Carries the raw HTTP `statusCode`, the
+ * classified `.code` discriminant (see {@link HonuaStudioProblemKind}), and
+ * the parsed RFC 7807 `.problem` body when the response was problem+json.
+ *
+ * @experimental
+ */
+export declare class HonuaStudioError extends Error {
+    readonly code: HonuaStudioProblemKind;
+    readonly statusCode: number;
+    readonly problem: HonuaStudioProblemDetails | undefined;
+    constructor(code: HonuaStudioProblemKind, statusCode: number, message: string, problem?: HonuaStudioProblemDetails, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Type guard for {@link HonuaStudioError}. */
+export declare function isHonuaStudioError(error: unknown): error is HonuaStudioError;
+/**
+ * True only for the `409` optimistic-concurrency discriminant — the draft's
+ * `generation` changed since the caller last read it. Callers should reload
+ * the draft (`drafts.get`) and retry the `PUT` with the fresh `generation`
+ * rather than surface this as a hard failure.
+ */
+export declare function isHonuaStudioGenerationConflict(error: unknown): error is HonuaStudioError;
+/** @internal Classify an HTTP status code into a {@link HonuaStudioProblemKind}. */
+export declare function classifyStudioProblemStatus(statusCode: number): HonuaStudioProblemKind;
+//# sourceMappingURL=lifecycle-errors.d.ts.map

package/studio/lifecycle-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-errors.d.ts","sourceRoot":"","sources":["../../../src/studio/lifecycle-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,WAAW,GAAG,qBAAqB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjH;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IACpD,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,8FAA8F;AAC9F,eAAO,MAAM,yBAAyB,EAAG,kCAA2C,CAAC;AAErF;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,IAAI,EAAE,sBAAsB,CAAC;IAC7C,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,yBAAyB,GAAG,SAAS,CAAC;gBAG7D,IAAI,EAAE,sBAAsB,EAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,yBAAyB,EACnC,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQ7C;AAED,+CAA+C;AAC/C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAEzF;AAED,oFAAoF;AACpF,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,CAatF"}

package/studio/lifecycle-errors.js

@@ -0,0 +1,77 @@
+/**
+ * Error taxonomy for {@link HonuaStudioLifecycleClient}.
+ *
+ * Every non-2xx response from the Studio package lifecycle API
+ * (`/api/v{version}/studio`) is either a handler-generated client error
+ * (`400`/`404`/`409`) or a caught internal failure (`500`), and both use
+ * RFC 7807 problem details with `type: "https://honua.io/problems/studio"`
+ * (see `docs/internal/admin-api/studio-package-lifecycle.md` in
+ * `honua-server`). {@link HonuaStudioError} normalizes both into one typed
+ * shape so callers branch on `.code` instead of parsing HTTP status numbers
+ * or problem-detail strings.
+ *
+ * `generation-conflict` is a distinct discriminant (not folded into a
+ * generic `"conflict"` bucket) because it is the one Studio failure mode the
+ * SDK expects callers to *recover from automatically* — reload the draft and
+ * retry — rather than surface to a user. Use
+ * {@link isHonuaStudioGenerationConflict} to branch on it without comparing
+ * `.code` strings directly.
+ *
+ * This module intentionally does not join the central `HonuaSdkError`
+ * registry (`src/core/error-code-registry.ts`): `studio` is an
+ * `@experimental`, not-yet-semver-covered domain, matching the existing
+ * `HonuaCollaborationError` (`src/collaboration/errors.ts`) precedent for
+ * experimental-domain errors pending a scoped migration.
+ *
+ * @module
+ */
+/** Canonical RFC 7807 `type` URI the Studio lifecycle API uses for every problem response. */
+export const HONUA_STUDIO_PROBLEM_TYPE = "https://honua.io/problems/studio";
+/**
+ * Thrown by every {@link HonuaStudioLifecycleClient} method when the server
+ * returns a non-2xx response. Carries the raw HTTP `statusCode`, the
+ * classified `.code` discriminant (see {@link HonuaStudioProblemKind}), and
+ * the parsed RFC 7807 `.problem` body when the response was problem+json.
+ *
+ * @experimental
+ */
+export class HonuaStudioError extends Error {
+    code;
+    statusCode;
+    problem;
+    constructor(code, statusCode, message, problem, options = {}) {
+        super(message, "cause" in options ? { cause: options.cause } : undefined);
+        this.name = "HonuaStudioError";
+        this.code = code;
+        this.statusCode = statusCode;
+        this.problem = problem;
+    }
+}
+/** Type guard for {@link HonuaStudioError}. */
+export function isHonuaStudioError(error) {
+    return error instanceof HonuaStudioError;
+}
+/**
+ * True only for the `409` optimistic-concurrency discriminant — the draft's
+ * `generation` changed since the caller last read it. Callers should reload
+ * the draft (`drafts.get`) and retry the `PUT` with the fresh `generation`
+ * rather than surface this as a hard failure.
+ */
+export function isHonuaStudioGenerationConflict(error) {
+    return isHonuaStudioError(error) && error.code === "generation-conflict";
+}
+/** @internal Classify an HTTP status code into a {@link HonuaStudioProblemKind}. */
+export function classifyStudioProblemStatus(statusCode) {
+    switch (statusCode) {
+        case 400:
+            return "validation";
+        case 404:
+            return "not-found";
+        case 409:
+            return "generation-conflict";
+        case 500:
+            return "internal";
+        default:
+            return "unknown";
+    }
+}