@honua/app-platform 0.1.7-beta.0 → 0.1.10-beta.0

package/studio/lifecycle-client.js

@@ -17,30 +17,38 @@
  * `./lifecycle-errors.js` for the RFC 7807 problem-detail taxonomy and the
  * `generation-conflict` discriminant.
  *
- * ## Enumeration gap
+ * ## Publication proposals
  *
- * 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:
+ * {@link HonuaStudioPublicationRequestsClient} submits an already-saved
+ * immutable version for publication, reads the resulting proposal, and walks
+ * it to a final state with a bounded, cancellable
+ * {@link HonuaStudioPublicationRequestsClient.poll}. Only `Active` yields a
+ * final publication URL; `Rejected` and `Failed` are terminal without one,
+ * and a status this release does not recognize is treated as neither.
+ * Approval is deliberately **not** part of this surface — see that class's
+ * doc comment.
  *
- * - `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.
+ * ## Enumeration
+ *
+ * `contentItems.list()` (`GET /content-items`) and `drafts.list()`
+ * (`GET /package-drafts`) are the content-browser entry points added by
+ * `honua-server#3003`: filters (`family`, `workspaceId`, `ownerId`, `search`, plus
+ * `state` for content items), opaque keyset-cursor pagination ordered by
+ * `updatedAt` then row id descending, and — for content items — a joined
+ * Content Publication Registry lifecycle badge per row, so a lifecycle badge
+ * costs no extra request. Both resource groups also expose a bounded
+ * `listAll()` async generator and a `collect()` convenience that walk the
+ * cursor for you; neither can loop forever (see
+ * {@link HONUA_STUDIO_LIST_MAX_PAGES}).
+ *
+ * Cursors are **opaque**. Pass a `nextCursor` back verbatim; never build,
+ * parse, or persist-and-mutate one.
  *
  * @module
  */
-import { isHonuaError } from "../core/errors.js";
+import { HonuaTimeoutError, isHonuaError } from "../core/errors.js";
 import { HonuaStudioError, classifyStudioProblemStatus } from "./lifecycle-errors.js";
+import { isStudioPublicationActive, isStudioPublicationTerminal, normalizeStudioPublicationStatus, studioPublicationUrl, } from "./publication-status.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}. */
@@ -57,6 +65,7 @@ export class HonuaStudioLifecycleClient {
     #basePath;
     packageFamilies;
     drafts;
+    contentItems;
     contentVersions;
     publicationRequests;
     rollbackRequests;
@@ -65,6 +74,7 @@ export class HonuaStudioLifecycleClient {
         this.#basePath = normalizeBasePath(options.basePath ?? HONUA_STUDIO_LIFECYCLE_BASE_PATH);
         this.packageFamilies = new HonuaStudioPackageFamiliesClient(this);
         this.drafts = new HonuaStudioDraftsClient(this);
+        this.contentItems = new HonuaStudioContentItemsClient(this);
         this.contentVersions = new HonuaStudioContentVersionsClient(this);
         this.publicationRequests = new HonuaStudioPublicationRequestsClient(this);
         this.rollbackRequests = new HonuaStudioRollbackRequestsClient(this);
@@ -72,7 +82,7 @@ export class HonuaStudioLifecycleClient {
     get basePath() {
         return this.#basePath;
     }
-    /** Escape hatch for endpoints without a dedicated method yet (see the module doc's "Enumeration gap"). */
+    /** Escape hatch for any endpoint that does not have a dedicated method on this client yet. */
     raw(request) {
         return this.request(request.method ?? "GET", request.path, request.body, {
             signal: request.signal,
@@ -122,6 +132,35 @@ export class HonuaStudioDraftsClient {
     create(request, options = {}) {
         return this.#lifecycle.request("POST", "/package-drafts", request, options);
     }
+    /**
+     * `GET /package-drafts` — one page of mutable drafts matching `filters`
+     * (`family`, `workspaceId`, `ownerId`, `search`), ordered by `updatedAt` then
+     * `draftId` descending.
+     *
+     * Rows are full {@link StudioPackageDraft} objects. Pass the response's
+     * `nextCursor` back as `filters.cursor` for the next page; its absence (or
+     * `null`) means this was the last one. Prefer {@link listAll} or
+     * {@link collect} over hand-rolling that loop.
+     */
+    // `async` so the client-side `limit` guard in `withStudioListQuery` surfaces
+    // as a rejected promise, exactly like every server-side failure on this
+    // client, rather than as a synchronous throw callers would have to catch
+    // separately.
+    async list(filters = {}, options = {}) {
+        return await this.#lifecycle.request("GET", withStudioListQuery("/package-drafts", filters), undefined, options);
+    }
+    /**
+     * Walk `GET /package-drafts` to completion, yielding each page verbatim.
+     * Bounded by `options.maxPages` — see {@link HonuaStudioContentItemsClient.listAll}
+     * for the shared pagination rules.
+     */
+    listAll(filters = {}, options = {}) {
+        return paginateStudioList((pageFilters, pageOptions) => this.list(pageFilters, pageOptions), filters, options);
+    }
+    /** Accumulate every draft page into one {@link StudioListCollection}. */
+    collect(filters = {}, options = {}) {
+        return collectStudioList(this.listAll(filters, options));
+    }
     /** `GET /package-drafts/{draftId}` — retrieve a mutable draft. */
     get(draftId, options = {}) {
         return this.#lifecycle.request("GET", `/package-drafts/${encodeURIComponent(draftId)}`, undefined, options);
@@ -157,6 +196,178 @@ export class HonuaStudioDraftsClient {
         return this.#lifecycle.request("POST", `/package-drafts/${encodeURIComponent(draftId)}/content-versions`, undefined, options);
     }
 }
+/** Page size `GET /content-items` and `GET /package-drafts` use when `limit` is omitted. */
+export const HONUA_STUDIO_LIST_DEFAULT_LIMIT = 25;
+/**
+ * Largest `limit` the Studio list endpoints accept. The server clamps anything
+ * larger down to this value rather than erroring, which would silently hand a
+ * caller fewer rows than they asked for, so this client rejects an oversized
+ * `limit` up front instead.
+ */
+export const HONUA_STUDIO_LIST_MAX_LIMIT = 1_000;
+/**
+ * Default hard bound on how many pages {@link HonuaStudioContentItemsClient.listAll}
+ * / {@link HonuaStudioDraftsClient.listAll} will fetch. There is no
+ * "walk forever" mode, and no option that produces one.
+ */
+export const HONUA_STUDIO_LIST_MAX_PAGES = 1_000;
+/**
+ * True when a page is the last one — the server sends `nextCursor: null` on
+ * the final page, and its source-generated JSON context omits `null`
+ * properties, so "absent" and "null" mean the same thing. An empty-string
+ * cursor is treated as exhausted too rather than replayed as a filter value.
+ */
+export function isStudioListExhausted(page) {
+    return typeof page.nextCursor !== "string" || page.nextCursor.length === 0;
+}
+/** `/content-items` — enumerate Studio content items with joined publication badges. */
+export class HonuaStudioContentItemsClient {
+    #lifecycle;
+    constructor(lifecycle) {
+        this.#lifecycle = lifecycle;
+    }
+    /**
+     * `GET /content-items` — one page of content items matching `filters`
+     * (`family`, `workspaceId`, `ownerId`, `state`, `search`), ordered by `updatedAt`
+     * then `itemId` descending so pages stay stable while other rows are
+     * concurrently created or updated.
+     *
+     * Each row is a summary projection — no envelope — carrying the derived
+     * `state` (`draft`/`current`/`published`) and, when the Content Publication
+     * Registry has a publication whose `sourceContentId` is this `itemId`, a
+     * joined `publication` badge with the route's *own* lifecycle. That join is
+     * batched server-side, so a badge costs no extra request.
+     *
+     * A non-admin caller under `Studio:EndUserAuthorization:Enabled` always gets
+     * their own content regardless of the `owner` filter they pass, and a caller
+     * whose id cannot be resolved at all is refused with `403` rather than shown
+     * an unscoped list. An unknown `family` or `state` value is `400`.
+     */
+    // `async` so the client-side `limit` guard in `withStudioListQuery` surfaces
+    // as a rejected promise, exactly like every server-side failure on this
+    // client, rather than as a synchronous throw callers would have to catch
+    // separately.
+    async list(filters = {}, options = {}) {
+        return await this.#lifecycle.request("GET", withStudioListQuery("/content-items", filters), undefined, options);
+    }
+    /**
+     * Walk `GET /content-items` to completion, yielding each page verbatim.
+     *
+     * - **Bounded by construction.** At most `options.maxPages` pages
+     *   ({@link HONUA_STUDIO_LIST_MAX_PAGES} by default) are fetched. Reaching
+     *   the cap ends the walk; the last yielded page still carries the
+     *   `nextCursor` to resume from.
+     * - **Cursors stay opaque.** Each request replays the previous page's
+     *   `nextCursor` verbatim; `filters.cursor` seeds the walk, so a walk can be
+     *   resumed exactly where a previous one stopped.
+     * - **Cancellable.** `options.signal` aborts the in-flight page request and
+     *   ends the iteration.
+     * - **A stuck server is not an infinite loop.** A page that repeats the
+     *   cursor it was fetched with throws {@link HonuaStudioError} rather than
+     *   paging forever.
+     * - **Standard error handling.** Every non-2xx surfaces as
+     *   {@link HonuaStudioError} with its RFC 7807 problem details.
+     */
+    listAll(filters = {}, options = {}) {
+        return paginateStudioList((pageFilters, pageOptions) => this.list(pageFilters, pageOptions), filters, options);
+    }
+    /** Accumulate every content-item page into one {@link StudioListCollection}. */
+    collect(filters = {}, options = {}) {
+        return collectStudioList(this.listAll(filters, options));
+    }
+}
+/**
+ * The shared bounded cursor walk behind every `listAll`. Generic over the row
+ * type so content items and drafts get identical pagination semantics from one
+ * implementation.
+ */
+async function* paginateStudioList(fetchPage, filters, options) {
+    const maxPages = normalizePageBound(options.maxPages);
+    const requestOptions = { signal: options.signal, headers: options.headers };
+    let cursor = filters.cursor;
+    for (let page = 0; page < maxPages; page += 1) {
+        throwIfAborted(options.signal);
+        const current = await fetchPage(cursor === undefined ? filters : { ...filters, cursor }, requestOptions);
+        yield current;
+        if (isStudioListExhausted(current))
+            return;
+        const next = current.nextCursor;
+        // A server that hands back the cursor it was just given would otherwise
+        // spin until `maxPages`, re-fetching the same page every time.
+        if (next === cursor) {
+            throw new HonuaStudioError("internal", 500, `Studio list pagination stalled: the server returned the same cursor it was queried with (${next}).`);
+        }
+        cursor = next;
+    }
+}
+/** Drain a bounded page walk into one {@link StudioListCollection}. */
+async function collectStudioList(pages) {
+    const items = [];
+    let pageCount = 0;
+    let total = 0;
+    let last;
+    for await (const page of pages) {
+        pageCount += 1;
+        total = page.total;
+        last = page;
+        items.push(...page.items);
+    }
+    // The generator stops either because the server said "no more" or because
+    // the page cap fired; only the second leaves a usable resume cursor behind.
+    const truncated = last !== undefined && !isStudioListExhausted(last);
+    return {
+        items,
+        pages: pageCount,
+        total,
+        nextCursor: truncated ? (last?.nextCursor ?? undefined) : undefined,
+        truncated,
+    };
+}
+function normalizePageBound(value) {
+    if (value === undefined)
+        return HONUA_STUDIO_LIST_MAX_PAGES;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`maxPages must be an integer >= 1, received ${String(value)}.`);
+    }
+    return value;
+}
+/**
+ * Serialize the shared Studio list filters onto `path`.
+ *
+ * Blank strings are dropped rather than sent as an empty filter the server
+ * would trim to `null` anyway.
+ */
+function withStudioListQuery(path, filters) {
+    const params = new URLSearchParams();
+    if (filters.family?.trim())
+        params.set("family", filters.family);
+    if (filters.state?.trim())
+        params.set("state", filters.state);
+    if (filters.workspaceId?.trim())
+        params.set("workspaceId", filters.workspaceId);
+    if (filters.ownerId?.trim())
+        params.set("ownerId", filters.ownerId);
+    if (filters.search?.trim())
+        params.set("search", filters.search);
+    if (filters.cursor)
+        params.set("cursor", filters.cursor);
+    if (filters.limit !== undefined)
+        params.set("limit", String(normalizeListLimit(filters.limit)));
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+/**
+ * Reject a `limit` the server would not honor as asked. Below `1` it would be
+ * replaced with the default and above {@link HONUA_STUDIO_LIST_MAX_LIMIT} it
+ * would be silently clamped — both hand back a page size the caller did not
+ * request, which is worse than a thrown programming error.
+ */
+function normalizeListLimit(limit) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > HONUA_STUDIO_LIST_MAX_LIMIT) {
+        throw new TypeError(`limit must be an integer between 1 and ${HONUA_STUDIO_LIST_MAX_LIMIT}, received ${String(limit)}.`);
+    }
+    return limit;
+}
 /** `/content-items/{itemId}/versions*` and `/version-comparisons` — immutable content versions. */
 export class HonuaStudioContentVersionsClient {
     #lifecycle;
@@ -187,7 +398,58 @@ export class HonuaStudioContentVersionsClient {
         return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}/reopen`, request, options);
     }
 }
-/** `/content-items/{itemId}/versions/{versionId}/publish-requests`. */
+/** Default delay between {@link HonuaStudioPublicationRequestsClient.poll} attempts. */
+export const HONUA_STUDIO_PUBLICATION_POLL_INTERVAL_MS = 1_000;
+/** Default attempt bound for {@link HonuaStudioPublicationRequestsClient.poll}. */
+export const HONUA_STUDIO_PUBLICATION_POLL_MAX_ATTEMPTS = 30;
+/**
+ * Body keys a publication *submission* may never carry. Approval is a
+ * separate principal acting through the canonical Admin API/CLI, so the SDK
+ * refuses to serialize a submission that tries to assert its own decision,
+ * override policy, or seed a terminal status — see
+ * {@link HonuaStudioPublicationRequestsClient} for why this is enforced
+ * client-side as well as server-side.
+ *
+ * Matching is on the exact key (case-insensitively); an additive server field
+ * that merely *mentions* approval (`approvalPolicyId`, say) is unaffected.
+ */
+const REJECTED_SUBMISSION_KEYS = new Set([
+    "status",
+    "state",
+    "approve",
+    "approved",
+    "approval",
+    "approvedat",
+    "approvedby",
+    "autoapprove",
+    "selfapprove",
+    "skipapproval",
+    "bypassapproval",
+    "bypasspolicy",
+    "policyoverride",
+    "overridepolicy",
+    "force",
+]);
+/**
+ * `/content-items/{itemId}/versions/{versionId}/publish-requests` — submit an
+ * already-saved immutable version for publication and walk the resulting
+ * proposal to a final state.
+ *
+ * ## Approval is a different principal
+ *
+ * This client can **create**, **get** and **poll** a publication proposal. It
+ * deliberately exposes no approve, authorize, force, or policy-override
+ * capability, and {@link create} refuses to serialize a submission body that
+ * tries to smuggle one (see {@link REJECTED_SUBMISSION_KEYS}). A proposer
+ * therefore cannot approve their own publication, or bypass policy, through
+ * any method on this class — approval happens through the canonical Admin
+ * API/CLI acting as a separate principal, and the server enforces the same
+ * rule with a `403` (`code: "forbidden"`) if a proposer tries anyway.
+ *
+ * {@link HonuaStudioLifecycleClient.raw} is a generic HTTP escape hatch with
+ * no Studio approval semantics of its own; it reaches whatever the server
+ * exposes and is subject to exactly the same server-side authorization.
+ */
 export class HonuaStudioPublicationRequestsClient {
     #lifecycle;
     constructor(lifecycle) {
@@ -195,12 +457,269 @@ export class HonuaStudioPublicationRequestsClient {
     }
     /**
      * `POST /content-items/{itemId}/versions/{versionId}/publish-requests` —
-     * persist a publication request and move the published pointer when
-     * validation permits.
+     * submit an already-saved immutable version for publication.
+     *
+     * The submission carries only the identity of what is being published
+     * (`itemId`, `versionId`, the optional `contentHash` pin), the requested
+     * route/visibility `intent`, and an optional `idempotencyKey` so a replayed
+     * submit resolves to the same proposal. It never carries a decision:
+     * an approval, policy-override, or `status` key in `request` throws a
+     * {@link HonuaStudioError} with `code: "validation"` **before** anything is
+     * sent.
+     *
+     * The response carries the joined `operationInstanceId`, `proposalId`,
+     * `proposalUri`, `auditId` and `correlationId` identifiers verbatim.
+     */
+    // `async` so the client-side approval guard below surfaces as a rejected
+    // promise, exactly like every server-side failure on this client, rather
+    // than as a synchronous throw callers would have to catch separately.
+    async create(itemId, versionId, request = {}, options = {}) {
+        assertNoApprovalFields(request);
+        return this.#lifecycle.request("POST", `${this.#path(itemId, versionId)}/publish-requests`, serializeStudioPublicationRequestInput(request), options);
+    }
+    /**
+     * `GET /content-items/{itemId}/versions/{versionId}/publish-requests/{requestId}`
+     * — read one publication proposal's current status and joined identifiers.
+     *
+     * A proposal that does not exist, or is not reachable from this
+     * `itemId`/`versionId` pair, throws `code: "not-found"`; one outside the
+     * caller's owner/tenant scope throws `code: "forbidden"`.
+     */
+    get(itemId, versionId, requestId, options = {}) {
+        return this.#lifecycle.request("GET", `${this.#path(itemId, versionId)}/publish-requests/${encodeURIComponent(requestId)}`, undefined, options);
+    }
+    /**
+     * Poll one publication proposal until it reaches a terminal state or a
+     * bound is reached, whichever comes first.
+     *
+     * - **Bounded by construction.** Every poll stops after at most
+     *   `maxAttempts` `GET`s (and `timeoutMs`, when given). There is no
+     *   unbounded mode.
+     * - **A final publication URL only at `Active`.** `Rejected` and `Failed`
+     *   end the poll with `terminal: true`, `active: false` and no URL.
+     * - **An unrecognized status is never final.** A state this release does
+     *   not know keeps the poll waiting until a bound is hit, and comes back as
+     *   `state: undefined, terminal: false, active: false`.
+     * - **Cancellable.** `options.signal` aborts the in-flight request and the
+     *   wait between attempts; the returned promise rejects with the signal's
+     *   abort reason — including when the abort lands mid-request, where the
+     *   underlying `HonuaClient` would otherwise normalize the rejection to a
+     *   generic SDK abort error.
+     * - **`timeoutMs` is a real wall-clock bound.** It aborts an in-flight `GET`
+     *   as well as being checked between attempts, and the inter-attempt wait is
+     *   clamped to the time left, so a hung response cannot leave the poll
+     *   pending past the deadline even when the underlying `HonuaClient` has no
+     *   `timeoutMs` of its own. A deadline reached with at least one observation
+     *   returns `exhausted: "timeout"`; a deadline that expires before the very
+     *   first response arrives has nothing to report and throws
+     *   {@link HonuaTimeoutError}.
+     * - **Standard error handling.** Every non-2xx surfaces as
+     *   {@link HonuaStudioError} with its RFC 7807 problem details, exactly as
+     *   for every other method on this client.
+     */
+    async poll(itemId, versionId, requestId, options = {}) {
+        const maxAttempts = normalizePollBound(options.maxAttempts, HONUA_STUDIO_PUBLICATION_POLL_MAX_ATTEMPTS);
+        const intervalMs = normalizeInterval(options.intervalMs);
+        const timeoutMs = options.timeoutMs === undefined ? undefined : normalizeInterval(options.timeoutMs);
+        // The wall-clock bound owns its own abort signal rather than being a
+        // between-attempts `Date.now()` check alone: `HonuaClient` carries no
+        // request timeout unless the consumer configured one, so a `GET` that is
+        // accepted and never answered would otherwise hold the poll open forever
+        // in spite of a finite `timeoutMs`.
+        const deadline = createPollDeadline(timeoutMs, options.signal);
+        const requestOptions = { signal: deadline.signal, headers: options.headers };
+        let observed;
+        try {
+            // Bounded by construction: the loop counter is the only thing that drives
+            // it, `maxAttempts` is validated to be a finite integer >= 1, and every
+            // path out of the body either returns or advances the counter.
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+                throwIfAborted(options.signal);
+                let request;
+                try {
+                    request = await this.get(itemId, versionId, requestId, requestOptions);
+                }
+                catch (error) {
+                    // The caller's cancellation is reported with the caller's own
+                    // `reason`. `HonuaClient.pipelineFetch` normalizes an in-flight fetch
+                    // abort into a generic SDK abort error, which would otherwise lose it.
+                    throwIfAborted(options.signal);
+                    if (deadline.expired())
+                        return this.#timedOut(observed, attempt - 1, timeoutMs);
+                    throw error;
+                }
+                const state = normalizeStudioPublicationStatus(request.status);
+                observed = { request, state };
+                options.onStatus?.(request, state);
+                if (isStudioPublicationTerminal(request.status)) {
+                    return toPollOutcome(request, state, attempt, undefined);
+                }
+                if (attempt >= maxAttempts) {
+                    return toPollOutcome(request, state, attempt, "max-attempts");
+                }
+                const remainingMs = deadline.remainingMs();
+                if (remainingMs !== undefined && remainingMs <= 0) {
+                    return toPollOutcome(request, state, attempt, "timeout");
+                }
+                // Never sleep past the deadline: a `intervalMs` larger than the time
+                // left would overshoot the documented bound by a whole interval.
+                const waitMs = remainingMs === undefined ? intervalMs : Math.min(intervalMs, remainingMs);
+                // When the wait is the whole remaining time, waking from it *is* the
+                // deadline being reached, and the loop must stop without consulting the
+                // clock again. Re-deriving `expiresAt - Date.now()` here made that a
+                // race: a timer may fire a tick before `Date.now()` passes its target,
+                // so the remainder read back as 1 rather than 0, the `<= 0` guard did
+                // not fire, and the loop issued one more GET *after* the documented
+                // bound -- the exact overshoot this clamp exists to prevent.
+                const waitsOutDeadline = remainingMs !== undefined && waitMs >= remainingMs;
+                await delay(waitMs, options.signal);
+                if (waitsOutDeadline) {
+                    return toPollOutcome(request, state, attempt, "timeout");
+                }
+                const leftAfterWait = deadline.remainingMs();
+                if (leftAfterWait !== undefined && leftAfterWait <= 0) {
+                    return toPollOutcome(request, state, attempt, "timeout");
+                }
+            }
+        }
+        finally {
+            deadline.dispose();
+        }
+        // Unreachable while `maxAttempts >= 1`; kept so the bound is enforced by
+        // the type system rather than by a comment.
+        throw new TypeError(`maxAttempts must be an integer >= 1, received ${String(maxAttempts)}.`);
+    }
+    /**
+     * The wall-clock bound fired. With at least one observation the poll reports
+     * it the documented way (`exhausted: "timeout"`); with none there is no
+     * proposal to report, so the deadline surfaces as the SDK's own
+     * {@link HonuaTimeoutError} rather than an invented empty outcome.
      */
-    create(itemId, versionId, request = {}, options = {}) {
-        return this.#lifecycle.request("POST", `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}/publish-requests`, request, options);
+    #timedOut(observed, attempts, timeoutMs) {
+        if (!observed)
+            throw new HonuaTimeoutError(timeoutMs ?? 0);
+        return toPollOutcome(observed.request, observed.state, attempts, "timeout");
+    }
+    #path(itemId, versionId) {
+        return `/content-items/${encodeURIComponent(itemId)}/versions/${encodeURIComponent(versionId)}`;
+    }
+}
+function createPollDeadline(timeoutMs, callerSignal) {
+    if (timeoutMs === undefined) {
+        return {
+            signal: callerSignal,
+            expired: () => false,
+            remainingMs: () => undefined,
+            dispose: () => undefined,
+        };
     }
+    const controller = new AbortController();
+    const expiresAt = Date.now() + timeoutMs;
+    let expired = false;
+    const timer = setTimeout(() => {
+        expired = true;
+        controller.abort();
+    }, timeoutMs);
+    const onCallerAbort = () => {
+        controller.abort(callerSignal ? abortReason(callerSignal) : undefined);
+    };
+    if (callerSignal?.aborted)
+        onCallerAbort();
+    else
+        callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    return {
+        signal: controller.signal,
+        expired: () => expired,
+        remainingMs: () => expiresAt - Date.now(),
+        dispose: () => {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener("abort", onCallerAbort);
+        },
+    };
+}
+function toPollOutcome(request, state, attempts, exhausted) {
+    return {
+        request,
+        state,
+        terminal: isStudioPublicationTerminal(request.status),
+        active: isStudioPublicationActive(request.status),
+        publicationUrl: studioPublicationUrl(request),
+        attempts,
+        exhausted,
+    };
+}
+/**
+ * Throw a client-side `validation` {@link HonuaStudioError} — nothing is sent
+ * — when a submission body carries an approval or policy-override key.
+ */
+function assertNoApprovalFields(request) {
+    const offending = Object.keys(request).filter((key) => REJECTED_SUBMISSION_KEYS.has(key.toLowerCase()));
+    if (offending.length === 0)
+        return;
+    const rule = [
+        "the proposer cannot approve their own publication or override policy.",
+        "Approval is a separate principal acting through the Admin API/CLI.",
+    ].join(" ");
+    throw new HonuaStudioError("validation", 400, `A publication submission must not carry ${offending.join(", ")}: ${rule}`);
+}
+/**
+ * Keep the pre-contract acknowledgement spelling source-compatible while
+ * sending only the canonical property understood by the Studio API. An
+ * explicitly supplied canonical value always wins.
+ */
+function serializeStudioPublicationRequestInput(request) {
+    if (!Object.hasOwn(request, "warningAcknowledgment"))
+        return request;
+    const { warningAcknowledgment, ...canonicalRequest } = request;
+    if (warningAcknowledgment === undefined || Object.hasOwn(request, "warningAcknowledgement")) {
+        return canonicalRequest;
+    }
+    return { ...canonicalRequest, warningAcknowledgement: warningAcknowledgment };
+}
+function normalizePollBound(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`maxAttempts must be an integer >= 1, received ${String(value)}.`);
+    }
+    return value;
+}
+function normalizeInterval(value) {
+    if (value === undefined)
+        return HONUA_STUDIO_PUBLICATION_POLL_INTERVAL_MS;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new TypeError(`Poll interval and timeout must be finite and >= 0, received ${String(value)}.`);
+    }
+    return value;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortReason(signal);
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+/** `setTimeout` that settles early — by rejecting with the abort reason — when `signal` aborts. */
+function delay(ms, signal) {
+    if (ms <= 0) {
+        throwIfAborted(signal);
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }
 /** `/content-items/{itemId}/rollback-requests`. */
 export class HonuaStudioRollbackRequestsClient {

package/studio/lifecycle-errors.d.ts

@@ -3,7 +3,8 @@
  *
  * 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
+ * (`400`/`401`/`403`/`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
@@ -30,6 +31,11 @@
  * status code of the failed response:
  *
  * - `validation` — `400`, request or envelope failed validation.
+ * - `unauthorized` — `401`, the request carried no usable principal.
+ * - `forbidden` — `403`, the principal is authenticated but is not permitted
+ *   to perform the operation — the owner/tenant scope ceiling, and the
+ *   separate-approver rule that stops a proposer from approving their own
+ *   publication (see {@link HonuaStudioPublicationRequestsClient}).
  * - `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).
@@ -41,7 +47,7 @@
  *
  * @experimental
  */
-export type HonuaStudioProblemKind = "validation" | "not-found" | "generation-conflict" | "internal" | "unknown";
+export type HonuaStudioProblemKind = "validation" | "unauthorized" | "forbidden" | "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

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

@@ -1 +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"}
+{"version":3,"file":"lifecycle-errors.d.ts","sourceRoot":"","sources":["../../../src/studio/lifecycle-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,sBAAsB,GAC9B,YAAY,GACZ,cAAc,GACd,WAAW,GACX,WAAW,GACX,qBAAqB,GACrB,UAAU,GACV,SAAS,CAAC;AAEd;;;;;;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,CAiBtF"}