@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/public-api/infrastructure/public-entry-writes.service.d.ts

@@ -0,0 +1,188 @@
+import type { AnyContentType } from '../../types/content-type';
+import { EntryWriterService } from '../../entries/infrastructure/persistence/entry-writer.service';
+import { PublishEntryUseCase } from '../../entries/application/use-cases/publish-entry.use-case';
+import { UnpublishEntryUseCase } from '../../entries/application/use-cases/unpublish-entry.use-case';
+import { BulkPublishEntriesUseCase } from '../../entries/application/use-cases/bulk-publish-entries.use-case';
+import { BulkUnpublishEntriesUseCase } from '../../entries/application/use-cases/bulk-unpublish-entries.use-case';
+import type { BulkActionResult, BulkPublishResult } from '../../entries/types/bulk-publish';
+import type { PublicSaveEntryDto } from '../http/dto/public-save-entry.dto';
+import type { PublicBulkSaveItemDto } from '../http/dto/public-bulk.dto';
+import { type PublicBulkSaveResult } from '../types/public-bulk';
+import type { PublicEntry } from '../types/public-entry';
+import { PublicEntriesQuery, type EntryLocator } from './public-entries.query';
+/**
+ * The write side of the public content API.
+ *
+ * **A thin edge over the admin's write pipeline, deliberately** — the opposite
+ * call from the read side, and for the opposite reason. The read stated its own
+ * WHERE because `EntriesService`'s knobs select rows a token must never see, so
+ * reaching through it would have made the visibility rule an argument about what
+ * was *not* passed. A write has no such hazard and a great deal more to get
+ * right: `EntryWriterService` already owns field validation, relation-delta
+ * application, media-target checks, revision numbering serialized by a per-entry
+ * advisory lock, the transactional outbox, and the i18n extension's sibling sync
+ * (which demotes rewritten published translations and re-validates them). A
+ * second implementation of any of that is how you get duplicate version numbers
+ * and translations that quietly drift. So this class adds exactly three things
+ * the writer does not know about — the locator, the grant gate (in the
+ * controller), and the public wire shape — and delegates the rest.
+ *
+ * **Responses are re-read through the public projection** rather than mapped
+ * from the writer's `EntryRecord`. It costs one SELECT per write and buys the
+ * guarantee that what a write returns is byte-identical in shape to what a read
+ * returns — including the reference fields the public `values` omits, which a
+ * hand-written mapper would have to remember to strip every time the field
+ * vocabulary grows.
+ *
+ * **No `OriginGuard`.** The admin's write controllers carry it because they are
+ * cookie-authenticated and therefore CSRF-able. A bearer token is not sent
+ * ambiently by a browser, so there is nothing to forge here — and requiring an
+ * `Origin` header would break every non-browser client, which is all of them.
+ */
+export declare class PublicEntryWritesService {
+    private readonly writer;
+    private readonly entries;
+    private readonly publishEntry;
+    private readonly unpublishEntry;
+    private readonly bulkPublishEntries;
+    private readonly bulkUnpublishEntries;
+    constructor(writer: EntryWriterService, entries: PublicEntriesQuery, publishEntry: PublishEntryUseCase, unpublishEntry: UnpublishEntryUseCase, bulkPublishEntries: BulkPublishEntriesUseCase, bulkUnpublishEntries: BulkUnpublishEntriesUseCase);
+    /**
+     * Create an entry. It lands as a **draft** on publishable types — the same
+     * as the editor's "new record", and the reason publish is its own call: a
+     * create that went live immediately would have no reviewable state.
+     *
+     * With `localeGroupId` the row joins an existing translation group instead
+     * of starting one, which is how a new locale of an existing record is
+     * written.
+     */
+    create(type: AnyContentType, body: PublicSaveEntryDto, workspaceId: string, grantedTypes: ReadonlySet<string>): Promise<PublicEntry>;
+    /**
+     * Update an entry's values and apply its relation deltas. On a publishable
+     * type this moves a published row back to `draft` while its published
+     * version stays live — the admin's **Modified** state — so an edit never
+     * silently changes what the world is reading.
+     *
+     * **A genuine partial update**, and this is a deliberate divergence from the
+     * admin's `PATCH`, which replaces the whole values bag because the editor
+     * always submits the full document. An API client does not: it sends the two
+     * fields it changed. Under replace semantics that silently nulls everything
+     * else — and since `required` only bites at publish time, the damage is
+     * invisible until a later publish fails on fields the caller never touched.
+     * A method named PATCH that destroys unsent data is a data-loss footgun, so
+     * the stored values are merged under the submitted ones here.
+     *
+     * Merge is **by key presence**, so nulling a field explicitly still works:
+     * `{"excerpt": null}` clears it, while omitting `excerpt` leaves it alone.
+     *
+     * `locale` here is the **addressing** locale — the query string's, which
+     * picks the row out of a translation group. It is deliberately not
+     * `body.locale`: that field is create-only (it stamps a new row's locale),
+     * and reading it here would let a body that omits it silently retarget a
+     * group write at the default-locale row. Which is exactly what it did, until
+     * a live check caught a German update rewriting the English article.
+     */
+    update(type: AnyContentType, locator: EntryLocator, body: PublicSaveEntryDto, workspaceId: string, grantedTypes: ReadonlySet<string>, locale?: string): Promise<PublicEntry>;
+    /**
+     * Save many entries of one type in a single request — the batch form of
+     * {@link create} and {@link update}, and the reason it is one method rather
+     * than two: an import is a list of records, some of which the caller already
+     * has and some of which it does not, and splitting that into two calls would
+     * make the client sort them first.
+     *
+     * **Each item is dispatched to the very same `create` / `update` above.**
+     * Nothing about what a write means is restated here — validation, relation
+     * deltas, media checks, revision numbering, the outbox, i18n's sibling sync
+     * all come from the one pipeline, so "saved in bulk" and "saved one at a
+     * time" cannot mean different things.
+     *
+     * **Partial success, item by item.** The items are written one transaction
+     * at a time (`EntryWriterService` opens its own per write, taking the
+     * workspace's shared content lock), so there is no batch to roll back even
+     * in principle — and rejecting forty-nine good entries because the fiftieth
+     * names a relation that does not exist would defeat the point of the
+     * endpoint. Every item therefore gets a verdict, failures carry the status
+     * and message their single-entry call would have produced, and the caller
+     * retries the ones it can fix. This is the same contract the bulk-publish
+     * commit already reports through its `skipped` list.
+     *
+     * **Written in order, one after another** rather than concurrently. Every
+     * write takes the workspace's shared content lock and (on a localized type)
+     * an advisory lock over the translation group, so a batch touching siblings
+     * would spend a fan-out contending with itself; sequential also makes the
+     * per-item results deterministic, which a caller diffing two runs relies on.
+     */
+    bulkSave(type: AnyContentType, items: readonly PublicBulkSaveItemDto[], workspaceId: string, grantedTypes: ReadonlySet<string>): Promise<PublicBulkSaveResult>;
+    /**
+     * The values bag an update submits: the stored values with the caller's
+     * merged over them (see {@link update}), minus any single relation the
+     * caller is setting through `relations`.
+     *
+     * That subtraction is what makes the two channels coexist. `toRecord`
+     * re-supplies every column-backed field including single-relation FKs, so
+     * without it a `relations: { author: { set } }` would always arrive
+     * alongside a stored `values.author` and be rejected as "sent in both
+     * places" — a collision this method created rather than the caller.
+     */
+    private mergedValues;
+    /**
+     * Publish many entries at once.
+     *
+     * **Delegates to `BulkPublishEntriesUseCase` — the admin's own** — rather
+     * than looping over {@link publish}. That use-case selects the candidate
+     * rows `FOR UPDATE` and re-validates them inside **one** transaction, which
+     * is the only thing that closes the window between "this draft validates"
+     * and "publish it"; a loop of single publishes would reopen it once per id.
+     * It also reports the ids it skipped and why (already published, blocked by
+     * validation, not found in this workspace), so a partial batch is legible
+     * rather than a flat count.
+     *
+     * The grant gate has already run in the caller, and the use-case is
+     * workspace-scoped, so an id from another workspace is reported as
+     * `not-found` — the same answer an id that never existed gets.
+     */
+    bulkPublish(type: AnyContentType, ids: string[], workspaceId: string): Promise<BulkPublishResult>;
+    /**
+     * Take many entries off the air, reverting each to a draft.
+     *
+     * `{ count }` rather than a per-id verdict, because unpublishing has no
+     * gate to fail: an id that is not a live published row of this workspace is
+     * simply not one of the rows that changed. The count is the number that
+     * actually transitioned, and one `entry.unpublished` event is emitted per
+     * transition — never per submitted id.
+     */
+    bulkUnpublish(type: AnyContentType, ids: string[], workspaceId: string): Promise<BulkActionResult>;
+    /**
+     * Remove many entries — soft-deleting on a `paranoid` type (recoverable
+     * from the admin's trash) and hard-deleting otherwise, exactly as
+     * {@link remove} does for one.
+     *
+     * Rows, not records: on a localized type this deletes the listed locales
+     * and leaves their siblings live.
+     */
+    bulkRemove(type: AnyContentType, ids: string[], workspaceId: string): Promise<BulkActionResult>;
+    /** Take an entry live. 422 when the stored draft no longer validates. */
+    publish(type: AnyContentType, locator: EntryLocator, workspaceId: string, grantedTypes: ReadonlySet<string>, locale?: string): Promise<PublicEntry>;
+    /** Take an entry back off the air, reverting it to a draft. */
+    unpublish(type: AnyContentType, locator: EntryLocator, workspaceId: string, grantedTypes: ReadonlySet<string>, locale?: string): Promise<PublicEntry>;
+    /**
+     * Remove an entry — soft delete on a `paranoid` type (recoverable from the
+     * admin's trash), a hard delete otherwise. Either way it leaves the public
+     * API immediately.
+     *
+     * Only **this** row: a translation is deleted on its own, so removing the
+     * German article leaves the English one live. Deleting a whole group means
+     * deleting each locale.
+     */
+    remove(type: AnyContentType, locator: EntryLocator, workspaceId: string, locale?: string): Promise<void>;
+    /**
+     * Re-read a just-written row through the public projection.
+     *
+     * `status: 'any'` because the row is usually a draft — the published-only
+     * default would 404 the thing that was just created. The locale is carried
+     * through so a sibling translation resolves to itself rather than to the
+     * default-locale row of its group.
+     */
+    private readBack;
+}
+//# sourceMappingURL=public-entry-writes.service.d.ts.map

package/dist/lib/public-api/infrastructure/public-entry-writes.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-entry-writes.service.d.ts","sourceRoot":"","sources":["../../../../src/lib/public-api/infrastructure/public-entry-writes.service.ts"],"names":[],"mappings":"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"}

package/dist/lib/public-api/infrastructure/public-entry-writes.service.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicEntryWritesService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const entry_row_1 = require("../../entries/infrastructure/persistence/entry-row");
+const entry_writer_service_1 = require("../../entries/infrastructure/persistence/entry-writer.service");
+const publish_entry_use_case_1 = require("../../entries/application/use-cases/publish-entry.use-case");
+const unpublish_entry_use_case_1 = require("../../entries/application/use-cases/unpublish-entry.use-case");
+const bulk_publish_entries_use_case_1 = require("../../entries/application/use-cases/bulk-publish-entries.use-case");
+const bulk_unpublish_entries_use_case_1 = require("../../entries/application/use-cases/bulk-unpublish-entries.use-case");
+const public_bulk_1 = require("../types/public-bulk");
+const bulk_save_op_1 = require("./bulk-save-op");
+const public_entries_query_1 = require("./public-entries.query");
+/**
+ * The write side of the public content API.
+ *
+ * **A thin edge over the admin's write pipeline, deliberately** — the opposite
+ * call from the read side, and for the opposite reason. The read stated its own
+ * WHERE because `EntriesService`'s knobs select rows a token must never see, so
+ * reaching through it would have made the visibility rule an argument about what
+ * was *not* passed. A write has no such hazard and a great deal more to get
+ * right: `EntryWriterService` already owns field validation, relation-delta
+ * application, media-target checks, revision numbering serialized by a per-entry
+ * advisory lock, the transactional outbox, and the i18n extension's sibling sync
+ * (which demotes rewritten published translations and re-validates them). A
+ * second implementation of any of that is how you get duplicate version numbers
+ * and translations that quietly drift. So this class adds exactly three things
+ * the writer does not know about — the locator, the grant gate (in the
+ * controller), and the public wire shape — and delegates the rest.
+ *
+ * **Responses are re-read through the public projection** rather than mapped
+ * from the writer's `EntryRecord`. It costs one SELECT per write and buys the
+ * guarantee that what a write returns is byte-identical in shape to what a read
+ * returns — including the reference fields the public `values` omits, which a
+ * hand-written mapper would have to remember to strip every time the field
+ * vocabulary grows.
+ *
+ * **No `OriginGuard`.** The admin's write controllers carry it because they are
+ * cookie-authenticated and therefore CSRF-able. A bearer token is not sent
+ * ambiently by a browser, so there is nothing to forge here — and requiring an
+ * `Origin` header would break every non-browser client, which is all of them.
+ */
+let PublicEntryWritesService = class PublicEntryWritesService {
+    writer;
+    entries;
+    publishEntry;
+    unpublishEntry;
+    bulkPublishEntries;
+    bulkUnpublishEntries;
+    constructor(writer, entries, publishEntry, unpublishEntry, bulkPublishEntries, bulkUnpublishEntries) {
+        this.writer = writer;
+        this.entries = entries;
+        this.publishEntry = publishEntry;
+        this.unpublishEntry = unpublishEntry;
+        this.bulkPublishEntries = bulkPublishEntries;
+        this.bulkUnpublishEntries = bulkUnpublishEntries;
+    }
+    /**
+     * Create an entry. It lands as a **draft** on publishable types — the same
+     * as the editor's "new record", and the reason publish is its own call: a
+     * create that went live immediately would have no reviewable state.
+     *
+     * With `localeGroupId` the row joins an existing translation group instead
+     * of starting one, which is how a new locale of an existing record is
+     * written.
+     */
+    async create(type, body, workspaceId, grantedTypes) {
+        const record = await this.writer.create(type, body.values, workspaceId, body.relations, body.locale, body.localeGroupId, 
+        // Revisions record a *user* id, and a token is not a user. Writing
+        // the token id into that column would make the history resolve it to
+        // a nonexistent person; null is the honest answer for "not a user".
+        // Attributing a token's writes is a real gap — it wants its own
+        // column, not a misused one.
+        null);
+        return this.readBack(type, record.id, workspaceId, grantedTypes, body);
+    }
+    /**
+     * Update an entry's values and apply its relation deltas. On a publishable
+     * type this moves a published row back to `draft` while its published
+     * version stays live — the admin's **Modified** state — so an edit never
+     * silently changes what the world is reading.
+     *
+     * **A genuine partial update**, and this is a deliberate divergence from the
+     * admin's `PATCH`, which replaces the whole values bag because the editor
+     * always submits the full document. An API client does not: it sends the two
+     * fields it changed. Under replace semantics that silently nulls everything
+     * else — and since `required` only bites at publish time, the damage is
+     * invisible until a later publish fails on fields the caller never touched.
+     * A method named PATCH that destroys unsent data is a data-loss footgun, so
+     * the stored values are merged under the submitted ones here.
+     *
+     * Merge is **by key presence**, so nulling a field explicitly still works:
+     * `{"excerpt": null}` clears it, while omitting `excerpt` leaves it alone.
+     *
+     * `locale` here is the **addressing** locale — the query string's, which
+     * picks the row out of a translation group. It is deliberately not
+     * `body.locale`: that field is create-only (it stamps a new row's locale),
+     * and reading it here would let a body that omits it silently retarget a
+     * group write at the default-locale row. Which is exactly what it did, until
+     * a live check caught a German update rewriting the English article.
+     */
+    async update(type, locator, body, workspaceId, grantedTypes, locale) {
+        const row = await this.entries.resolveWritableRow(type, locator, workspaceId, locale);
+        const id = row['id'];
+        await this.writer.update(type, id, 
+        // `toRecord` yields the stored column-backed values — scalars, media
+        // ids, and owning single-relation FKs. Join-backed relations have no
+        // column and are absent from it, which is correct: those move only
+        // through `relations` deltas, and a delta left unsent changes
+        // nothing by construction.
+        this.mergedValues(type, row, body), workspaceId, body.relations, null);
+        return this.readBack(type, id, workspaceId, grantedTypes, { locale });
+    }
+    /**
+     * Save many entries of one type in a single request — the batch form of
+     * {@link create} and {@link update}, and the reason it is one method rather
+     * than two: an import is a list of records, some of which the caller already
+     * has and some of which it does not, and splitting that into two calls would
+     * make the client sort them first.
+     *
+     * **Each item is dispatched to the very same `create` / `update` above.**
+     * Nothing about what a write means is restated here — validation, relation
+     * deltas, media checks, revision numbering, the outbox, i18n's sibling sync
+     * all come from the one pipeline, so "saved in bulk" and "saved one at a
+     * time" cannot mean different things.
+     *
+     * **Partial success, item by item.** The items are written one transaction
+     * at a time (`EntryWriterService` opens its own per write, taking the
+     * workspace's shared content lock), so there is no batch to roll back even
+     * in principle — and rejecting forty-nine good entries because the fiftieth
+     * names a relation that does not exist would defeat the point of the
+     * endpoint. Every item therefore gets a verdict, failures carry the status
+     * and message their single-entry call would have produced, and the caller
+     * retries the ones it can fix. This is the same contract the bulk-publish
+     * commit already reports through its `skipped` list.
+     *
+     * **Written in order, one after another** rather than concurrently. Every
+     * write takes the workspace's shared content lock and (on a localized type)
+     * an advisory lock over the translation group, so a batch touching siblings
+     * would spend a fan-out contending with itself; sequential also makes the
+     * per-item results deterministic, which a caller diffing two runs relies on.
+     */
+    async bulkSave(type, items, workspaceId, grantedTypes) {
+        const results = [];
+        for (const [index, item] of items.entries()) {
+            // Resolved inside the loop, and inside the try: a malformed
+            // locator is this item's problem, not the request's. Failing the
+            // whole call on it would make one mis-addressed row cost every
+            // other row's write — the very thing the per-item contract exists
+            // to prevent.
+            let op = public_bulk_1.BULK_SAVE_OP.Create;
+            try {
+                const resolved = (0, bulk_save_op_1.resolveBulkSaveOp)(item);
+                op = resolved.op;
+                const entry = resolved.op === public_bulk_1.BULK_SAVE_OP.Create
+                    ? await this.create(type, item, workspaceId, grantedTypes)
+                    : await this.update(type, resolved.locator, item, workspaceId, grantedTypes, resolved.locale);
+                results.push({ index, op: resolved.op, ok: true, entry });
+            }
+            catch (error) {
+                results.push({
+                    index,
+                    op,
+                    ok: false,
+                    error: toBulkSaveError(error)
+                });
+            }
+        }
+        return {
+            items: results,
+            created: results.filter((result) => result.ok && result.op === public_bulk_1.BULK_SAVE_OP.Create).length,
+            updated: results.filter((result) => result.ok && result.op === public_bulk_1.BULK_SAVE_OP.Update).length,
+            failed: results.filter((result) => !result.ok).length
+        };
+    }
+    /**
+     * The values bag an update submits: the stored values with the caller's
+     * merged over them (see {@link update}), minus any single relation the
+     * caller is setting through `relations`.
+     *
+     * That subtraction is what makes the two channels coexist. `toRecord`
+     * re-supplies every column-backed field including single-relation FKs, so
+     * without it a `relations: { author: { set } }` would always arrive
+     * alongside a stored `values.author` and be rejected as "sent in both
+     * places" — a collision this method created rather than the caller.
+     */
+    mergedValues(type, row, body) {
+        const merged = { ...(0, entry_row_1.toRecord)(type, row).values, ...body.values };
+        for (const [field, delta] of Object.entries(body.relations ?? {})) {
+            // Only the STORED value is dropped. A field the caller put in both
+            // bags themselves stays, so the writer still sees the contradiction
+            // and rejects it — the point is to hide this method's own
+            // re-supplied value, not to paper over an ambiguous request.
+            if (delta.set !== undefined &&
+                !Object.hasOwn(body.values ?? {}, field)) {
+                delete merged[field];
+            }
+        }
+        return merged;
+    }
+    /**
+     * Publish many entries at once.
+     *
+     * **Delegates to `BulkPublishEntriesUseCase` — the admin's own** — rather
+     * than looping over {@link publish}. That use-case selects the candidate
+     * rows `FOR UPDATE` and re-validates them inside **one** transaction, which
+     * is the only thing that closes the window between "this draft validates"
+     * and "publish it"; a loop of single publishes would reopen it once per id.
+     * It also reports the ids it skipped and why (already published, blocked by
+     * validation, not found in this workspace), so a partial batch is legible
+     * rather than a flat count.
+     *
+     * The grant gate has already run in the caller, and the use-case is
+     * workspace-scoped, so an id from another workspace is reported as
+     * `not-found` — the same answer an id that never existed gets.
+     */
+    bulkPublish(type, ids, workspaceId) {
+        return this.bulkPublishEntries.execute(type, ids, workspaceId);
+    }
+    /**
+     * Take many entries off the air, reverting each to a draft.
+     *
+     * `{ count }` rather than a per-id verdict, because unpublishing has no
+     * gate to fail: an id that is not a live published row of this workspace is
+     * simply not one of the rows that changed. The count is the number that
+     * actually transitioned, and one `entry.unpublished` event is emitted per
+     * transition — never per submitted id.
+     */
+    bulkUnpublish(type, ids, workspaceId) {
+        return this.bulkUnpublishEntries.execute(type, ids, workspaceId);
+    }
+    /**
+     * Remove many entries — soft-deleting on a `paranoid` type (recoverable
+     * from the admin's trash) and hard-deleting otherwise, exactly as
+     * {@link remove} does for one.
+     *
+     * Rows, not records: on a localized type this deletes the listed locales
+     * and leaves their siblings live.
+     */
+    bulkRemove(type, ids, workspaceId) {
+        return this.writer.bulkRemove(type, ids, workspaceId);
+    }
+    /** Take an entry live. 422 when the stored draft no longer validates. */
+    async publish(type, locator, workspaceId, grantedTypes, locale) {
+        const row = await this.entries.resolveWritableRow(type, locator, workspaceId, locale);
+        const id = row['id'];
+        await this.publishEntry.execute(type, id, workspaceId);
+        return this.readBack(type, id, workspaceId, grantedTypes, { locale });
+    }
+    /** Take an entry back off the air, reverting it to a draft. */
+    async unpublish(type, locator, workspaceId, grantedTypes, locale) {
+        const row = await this.entries.resolveWritableRow(type, locator, workspaceId, locale);
+        const id = row['id'];
+        await this.unpublishEntry.execute(type, id, workspaceId);
+        return this.readBack(type, id, workspaceId, grantedTypes, { locale });
+    }
+    /**
+     * Remove an entry — soft delete on a `paranoid` type (recoverable from the
+     * admin's trash), a hard delete otherwise. Either way it leaves the public
+     * API immediately.
+     *
+     * Only **this** row: a translation is deleted on its own, so removing the
+     * German article leaves the English one live. Deleting a whole group means
+     * deleting each locale.
+     */
+    async remove(type, locator, workspaceId, locale) {
+        const row = await this.entries.resolveWritableRow(type, locator, workspaceId, locale);
+        await this.writer.remove(type, row['id'], workspaceId);
+    }
+    /**
+     * Re-read a just-written row through the public projection.
+     *
+     * `status: 'any'` because the row is usually a draft — the published-only
+     * default would 404 the thing that was just created. The locale is carried
+     * through so a sibling translation resolves to itself rather than to the
+     * default-locale row of its group.
+     */
+    readBack(type, id, workspaceId, grantedTypes, source) {
+        return this.entries.getOne(type, { id }, workspaceId, { locale: source.locale, status: 'any' }, grantedTypes);
+    }
+};
+exports.PublicEntryWritesService = PublicEntryWritesService;
+exports.PublicEntryWritesService = PublicEntryWritesService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [entry_writer_service_1.EntryWriterService,
+        public_entries_query_1.PublicEntriesQuery,
+        publish_entry_use_case_1.PublishEntryUseCase,
+        unpublish_entry_use_case_1.UnpublishEntryUseCase,
+        bulk_publish_entries_use_case_1.BulkPublishEntriesUseCase,
+        bulk_unpublish_entries_use_case_1.BulkUnpublishEntriesUseCase])
+], PublicEntryWritesService);
+/**
+ * One item's failure, in the vocabulary the single-entry routes already speak.
+ *
+ * A Nest `HttpException` carries both halves of what the caller needs — the
+ * status the same write would have failed with, and the body it would have been
+ * given, `issues` and all — so a 422's per-field detail survives being one row
+ * of a batch instead of being flattened to a sentence. Anything else is a bug
+ * rather than a rejection, and is reported as a 500 with its message so the item
+ * is still diagnosable; the batch keeps going either way, because one item
+ * throwing unexpectedly is not a reason to abandon the rest.
+ */
+function toBulkSaveError(error) {
+    if (error instanceof common_1.HttpException) {
+        const response = error.getResponse();
+        const body = typeof response === 'object' && response !== null
+            ? response
+            : {};
+        const message = body['message'];
+        return {
+            status: error.getStatus(),
+            message: typeof message === 'string' ? message : error.message,
+            ...(body['issues'] === undefined ? {} : { issues: body['issues'] })
+        };
+    }
+    return {
+        status: common_1.HttpStatus.INTERNAL_SERVER_ERROR,
+        message: error instanceof Error ? error.message : String(error)
+    };
+}

package/dist/lib/public-api/infrastructure/public-expansion.query.d.ts

@@ -0,0 +1,98 @@
+import { type Database } from '@orthacms/database';
+import { type AnyContentType } from '../../types/content-type';
+import { type MediaAssetResolver } from '../../extension/media-asset-resolver';
+import { RelationLinkService } from '../../entries/infrastructure/persistence/relation-link.service';
+import type { PublicMediaFieldView, PublicRelationFieldView } from '../types/public-expansion';
+/** A generated content row seen as a bag of values by property name. */
+type Row = Record<string, unknown>;
+/**
+ * Upper bound on how many fields one request may expand, per kind. The cost of
+ * a preview scales with the number of **fields**, not rows (each relation field
+ * is one or two queries spanning the whole page), so this is the knob that
+ * actually bounds a request — the admin caps only the raw string length, which
+ * on a public endpoint would leave a type with a dozen relations open to a
+ * request asking for all of them.
+ */
+export declare const MAX_EXPANDED_FIELDS = 10;
+/**
+ * Resolves the public API's opt-in **relation** and **media** expansions for a
+ * page of entries.
+ *
+ * Both are batched across the whole page — one bounded set of queries per
+ * *field*, never one per row. Relations delegate to
+ * `RelationLinkService.previewForEntries` (windowed `row_number()` for the cap,
+ * `count(*) over` for the total, batched title resolution). Media deliberately
+ * does **not** reuse `MediaRefsQuery.forValues`: that method takes one entry's
+ * values, so calling it per row would be exactly the N+1 the relation preview
+ * was built to avoid. Instead every media id on the page is collected and
+ * resolved in a single batched lookup.
+ */
+export declare class PublicExpansionQuery {
+    private readonly db;
+    private readonly relationLinks;
+    private readonly media?;
+    constructor(db: Database, relationLinks: RelationLinkService, media?: MediaAssetResolver | undefined);
+    /**
+     * Validate a `?relationFields=` list: every name must be a relation field
+     * on the type, and its target must be a content type the workspace was
+     * granted. An ungranted target is a **400**, matching how `?filter=` treats
+     * a traversal into one — a public caller should not be able to expand into
+     * content the workspace does not expose, and saying so beats silently
+     * returning an empty field.
+     */
+    parseRelationFields(type: AnyContentType, raw: string | undefined, granted: ReadonlySet<string>): string[];
+    /** Validate a `?mediaFields=` list: every name must be a media field. */
+    parseMediaFields(type: AnyContentType, raw: string | undefined): string[];
+    /**
+     * One capped page of links per requested relation field, for every row on
+     * the page, keyed by entry id.
+     *
+     * `publishedOnly` is the public difference: a draft target is neither shown
+     * nor counted, so `total` is the number of links a caller can actually
+     * reach.
+     */
+    relationsForRows(type: AnyContentType, fields: string[], rows: Row[], workspaceId: string, limit?: number): Promise<Map<string, Record<string, PublicRelationFieldView>>>;
+    /**
+     * Hydrate already-read link views (the `/relations` sibling routes' output
+     * from `readAll` / `readField`) into the same full-entry shape the list
+     * preview returns, so both surfaces speak one contract.
+     */
+    hydrateRelationViews(type: AnyContentType, views: Record<string, {
+        items: {
+            id: string;
+        }[];
+        total: number;
+    }>, workspaceId: string): Promise<Record<string, PublicRelationFieldView>>;
+    /**
+     * Load every linked entry named by a preview, keyed by field and then by
+     * id. One `IN (…)` read per relation field's target type, projected through
+     * the same {@link toPublicEntry} the entry routes use — so a linked record
+     * has exactly the shape a consumer already handles.
+     *
+     * Linked entries are returned **unexpanded**: nothing here recurses, which
+     * is what bounds a request to one level of the graph.
+     */
+    private linkedEntriesById;
+    /**
+     * The assets of each requested media field, for every row on the page,
+     * keyed by entry id. One batched resolver lookup for the whole page.
+     *
+     * A no-op when no media plugin is registered (nothing binds the resolver),
+     * exactly like the admin's media read — content boots without media.
+     */
+    mediaForRows(type: AnyContentType, fields: string[], rows: Row[], workspaceId: string, limit?: number): Promise<Map<string, Record<string, PublicMediaFieldView>>>;
+    /**
+     * Every field of one kind — what `?relations=preview` / `?media=preview`
+     * expand when the caller names no fields.
+     *
+     * A type with more expandable fields than the cap is a **400** telling the
+     * caller to name the ones they want, rather than a silently truncated
+     * response: quietly dropping fields would read as "this entry has no
+     * links" and be near-impossible to notice.
+     */
+    private allFieldsOfKind;
+    /** Shared parse: split, trim, de-duplicate, bound, then per-kind checks. */
+    private parseFields;
+}
+export {};
+//# sourceMappingURL=public-expansion.query.d.ts.map

package/dist/lib/public-api/infrastructure/public-expansion.query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-expansion.query.d.ts","sourceRoot":"","sources":["../../../../src/lib/public-api/infrastructure/public-expansion.query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE7E,OAAO,EAEH,KAAK,kBAAkB,EAC1B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gEAAgE,CAAC;AAErG,OAAO,KAAK,EACR,oBAAoB,EAEpB,uBAAuB,EAC1B,MAAM,2BAA2B,CAAC;AAInC,wEAAwE;AACxE,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAKnC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAwCtC;;;;;;;;;;;;GAYG;AACH,qBACa,oBAAoB;IAEP,OAAO,CAAC,QAAQ,CAAC,EAAE;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAG9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAJY,EAAE,EAAE,QAAQ,EAC9B,aAAa,EAAE,mBAAmB,EAGlC,KAAK,CAAC,EAAE,kBAAkB,YAAA;IAG/C;;;;;;;OAOG;IACH,mBAAmB,CACf,IAAI,EAAE,cAAc,EACpB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,MAAM,EAAE;IA8BX,yEAAyE;IACzE,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE;IAiBzE;;;;;;;OAOG;IACG,gBAAgB,CAClB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,GAAG,EAAE,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,SAA0B,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC;IAyChE;;;;OAIG;IACG,oBAAoB,CACtB,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,EACjE,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAqBnD;;;;;;;;OAQG;YACW,iBAAiB;IAsD/B;;;;;;OAMG;IACG,YAAY,CACd,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,EAAE,GAAG,EAAE,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,SAA0B,GAChC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IA+F7D;;;;;;;;OAQG;IACH,OAAO,CAAC,eAAe;IAgBvB,4EAA4E;IAC5E,OAAO,CAAC,WAAW;CA+BtB"}