@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/public-api/infrastructure/public-expansion.query.js

@@ -0,0 +1,384 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicExpansionQuery = exports.MAX_EXPANDED_FIELDS = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const drizzle_orm_1 = require("drizzle-orm");
+const database_1 = require("@orthacms/database");
+const content_domain_1 = require("@orthacms/content-domain");
+const content_type_1 = require("../../types/content-type");
+const fields_1 = require("../../types/fields");
+const media_asset_resolver_1 = require("../../extension/media-asset-resolver");
+const relation_link_service_1 = require("../../entries/infrastructure/persistence/relation-link.service");
+const public_list_entries_query_dto_1 = require("../http/dto/public-list-entries-query.dto");
+const public_entry_row_1 = require("./public-entry-row");
+/**
+ * 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.
+ */
+exports.MAX_EXPANDED_FIELDS = 10;
+/**
+ * Route prefix the public API reports for an asset's bytes.
+ *
+ * The `MEDIA_ASSET_RESOLVER` hands back the **admin's** URLs, which derive their
+ * scope from the caller's workspace *membership* — something a token does not
+ * have, so a bearer got a 404 on every one of them. Media-server's
+ * `/api/v1/media` sibling derives the same scope from the token's resolved
+ * workspace instead, so these are the URLs a public consumer can actually fetch,
+ * with the very token it already holds.
+ *
+ * A literal rather than an import: content-server does not depend on
+ * media-server (the dependency runs the other way — media binds content's
+ * resolver port), so this package cannot ask for the route. It mirrors the
+ * default `publicBasePath` the media config already hardcodes.
+ */
+const PUBLIC_MEDIA_BASE_PATH = '/api/v1/media/assets';
+/**
+ * Rewrites a track's admin URL to the public one.
+ *
+ * The resolver builds `/api/media/assets/<id>/raw`, whose scope comes from the
+ * caller's workspace **membership** — which a bearer token does not have. The
+ * id is the only part worth keeping, so it is lifted out and re-addressed
+ * against the public base, same as {@link publicAssetUrl} does for the asset
+ * itself. A src that does not match is passed through: an unexpected shape is
+ * better published as-is than silently rewritten to a 404.
+ */
+function publicTrackUrl(src) {
+    const id = /\/assets\/([^/]+)\/raw/.exec(src)?.[1];
+    return id ? publicAssetUrl(id) : src;
+}
+/** The public download URL for one asset, optionally a generated derivative. */
+function publicAssetUrl(id, variant) {
+    const base = `${PUBLIC_MEDIA_BASE_PATH}/${id}/raw`;
+    return variant ? `${base}?variant=${variant}` : base;
+}
+/**
+ * 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.
+ */
+let PublicExpansionQuery = class PublicExpansionQuery {
+    db;
+    relationLinks;
+    media;
+    constructor(db, relationLinks, media) {
+        this.db = db;
+        this.relationLinks = relationLinks;
+        this.media = media;
+    }
+    /**
+     * 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, raw, granted) {
+        if (!raw?.trim()) {
+            // No list given: expand everything expandable. An ungranted target
+            // is skipped rather than refused — the caller didn't name it, so
+            // there is nothing to correct them about, and this matches what the
+            // `/relations` sibling route returns.
+            return this.allFieldsOfKind(type, 'relationFields', (spec) => spec.type === fields_1.CONTENT_FIELD_TYPE.Relation &&
+                !!spec.relation &&
+                granted.has(spec.relation.to().name));
+        }
+        return this.parseFields(type, raw, 'relationFields', (name, spec) => {
+            if (spec.type !== fields_1.CONTENT_FIELD_TYPE.Relation || !spec.relation) {
+                throw new common_1.BadRequestException(`relationFields: "${name}" is not a relation field on "${type.name}".`);
+            }
+            const target = spec.relation.to();
+            if (!granted.has(target.name)) {
+                throw new common_1.BadRequestException(`relationFields: "${name}" cannot be expanded — this workspace has no access to "${target.name}".`);
+            }
+        });
+    }
+    /** Validate a `?mediaFields=` list: every name must be a media field. */
+    parseMediaFields(type, raw) {
+        if (!raw?.trim()) {
+            return this.allFieldsOfKind(type, 'mediaFields', (spec) => spec.type === fields_1.CONTENT_FIELD_TYPE.Media);
+        }
+        return this.parseFields(type, raw, 'mediaFields', (name, spec) => {
+            if (spec.type !== fields_1.CONTENT_FIELD_TYPE.Media) {
+                throw new common_1.BadRequestException(`mediaFields: "${name}" is not a media field on "${type.name}".`);
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    async relationsForRows(type, fields, rows, workspaceId, limit = public_list_entries_query_dto_1.DEFAULT_EXPANSION_LIMIT) {
+        const out = new Map();
+        if (!fields.length || !rows.length) {
+            return out;
+        }
+        const previews = await this.relationLinks.previewForEntries(type, fields, rows, workspaceId, limit, { publishedOnly: true });
+        // The preview yields ordered link ids; hydrate them into full entries
+        // with one batched read per distinct TARGET TYPE, so a page costs a
+        // query per type rather than per link.
+        const entriesById = await this.linkedEntriesById(type, fields, previews, workspaceId);
+        for (const [entryId, byField] of previews) {
+            const view = {};
+            for (const [field, value] of Object.entries(byField)) {
+                const linked = entriesById.get(field);
+                view[field] = {
+                    // Preserve the preview's link order, and drop any id the
+                    // hydration didn't return (it named a target the caller
+                    // can't see — already excluded from `total` upstream).
+                    items: value.items
+                        .map((ref) => linked?.get(ref.id))
+                        .filter((entry) => !!entry),
+                    total: value.total
+                };
+            }
+            out.set(entryId, view);
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async hydrateRelationViews(type, views, workspaceId) {
+        const fields = Object.keys(views);
+        const linked = await this.linkedEntriesById(type, fields, new Map([['one', views]]), workspaceId);
+        const out = {};
+        for (const [field, view] of Object.entries(views)) {
+            const byId = linked.get(field);
+            out[field] = {
+                items: view.items
+                    .map((ref) => byId?.get(ref.id))
+                    .filter((entry) => !!entry),
+                total: view.total
+            };
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async linkedEntriesById(type, fields, previews, workspaceId) {
+        const idsByField = new Map();
+        for (const byField of previews.values()) {
+            for (const [field, value] of Object.entries(byField)) {
+                let ids = idsByField.get(field);
+                if (!ids) {
+                    ids = new Set();
+                    idsByField.set(field, ids);
+                }
+                for (const ref of value.items)
+                    ids.add(ref.id);
+            }
+        }
+        const out = new Map();
+        await Promise.all(fields.map(async (field) => {
+            const ids = idsByField.get(field);
+            const target = type.fields[field]?.relation?.to();
+            if (!target || !ids?.size)
+                return;
+            const cols = target.table;
+            const rows = (await this.db
+                .select()
+                .from(target.table)
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['id'], [...ids]), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId), target.publishable
+                ? (0, drizzle_orm_1.eq)(cols['status'], content_type_1.ENTRY_STATUS.Published)
+                : undefined, target.paranoid
+                ? (0, drizzle_orm_1.isNull)(cols['deletedAt'])
+                : undefined)));
+            out.set(field, new Map(rows.map((row) => [
+                row['id'],
+                (0, public_entry_row_1.toPublicEntry)(target, row)
+            ])));
+        }));
+        return out;
+    }
+    /**
+     * 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.
+     */
+    async mediaForRows(type, fields, rows, workspaceId, limit = public_list_entries_query_dto_1.DEFAULT_EXPANSION_LIMIT) {
+        const out = new Map();
+        if (!this.media || !fields.length || !rows.length) {
+            return out;
+        }
+        // Collect every id on the page first, so the resolver is hit once.
+        // Refs rather than ids: a media value carries a per-usage `alt` and a
+        // `decorative` flag since `ORT-83`, and those are what a public consumer
+        // needs to emit a correct `<img alt>` — the asset row's own description
+        // is only the fallback.
+        const idsByRowField = new Map();
+        const all = new Set();
+        for (const row of rows) {
+            const entryId = row['id'];
+            if (typeof entryId !== 'string')
+                continue;
+            const byField = new Map();
+            for (const field of fields) {
+                const refs = mediaRefsOf(row[field]);
+                if (!refs.length)
+                    continue;
+                byField.set(field, refs);
+                for (const ref of refs)
+                    all.add(ref.id);
+            }
+            idsByRowField.set(entryId, byField);
+        }
+        if (!all.size) {
+            return out;
+        }
+        const resolved = await this.media.resolve([...all], workspaceId);
+        for (const [entryId, byField] of idsByRowField) {
+            const view = {};
+            for (const [field, refs] of byField) {
+                // An id the resolver didn't return names an asset that is gone
+                // or lives in another workspace. The admin keeps it as a
+                // `missing` placeholder to preserve ordering in an editor; a
+                // public read has no such need and simply omits it, so every
+                // ref it returns is a real asset.
+                const present = refs
+                    .map((ref) => {
+                    const asset = resolved.get(ref.id);
+                    return asset ? { ref, asset } : null;
+                })
+                    .filter((pair) => pair !== null);
+                // `total` counts every asset actually attached, before the
+                // limit — so a lowered limit is visible as `items.length <
+                // total` rather than silently passing off a slice as the whole.
+                const items = present.slice(0, limit).map(({ ref, asset }) => ({
+                    id: asset.id,
+                    name: asset.name,
+                    // The resolver's own URLs are the admin's; rewrite to
+                    // the token-fetchable route. Presence of a derivative is
+                    // still read from the resolver — it is what knows
+                    // whether one was generated — but the address is ours.
+                    url: publicAssetUrl(asset.id),
+                    ...(asset.thumbUrl
+                        ? { thumbUrl: publicAssetUrl(asset.id, 'thumb') }
+                        : {}),
+                    ...(asset.previewUrl
+                        ? {
+                            previewUrl: publicAssetUrl(asset.id, 'preview')
+                        }
+                        : {}),
+                    kind: asset.kind,
+                    mimeType: asset.mimeType,
+                    alt: publicAlt(ref, asset.alt),
+                    // Rewritten to the token-fetchable route, exactly like
+                    // `url` above: the resolver hands back the admin's
+                    // addresses, which a bearer cannot reach (`ORT-92`).
+                    tracks: asset.tracks.map((track) => ({
+                        kind: track.kind,
+                        srclang: track.srclang,
+                        label: track.label,
+                        src: publicTrackUrl(track.src),
+                        ...(track.default ? { default: true } : {})
+                    })),
+                    ...(ref.decorative === true
+                        ? { decorative: true }
+                        : {})
+                }));
+                view[field] = { items, total: present.length };
+            }
+            out.set(entryId, view);
+        }
+        return out;
+    }
+    /**
+     * 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.
+     */
+    allFieldsOfKind(type, param, matches) {
+        const names = Object.entries(type.fields)
+            .filter(([, spec]) => matches(spec))
+            .map(([name]) => name);
+        if (names.length > exports.MAX_EXPANDED_FIELDS) {
+            throw new common_1.BadRequestException(`${param}: "${type.name}" has ${names.length} expandable fields, more than the ${exports.MAX_EXPANDED_FIELDS} a single request may expand — name the ones you need with \`${param}\`.`);
+        }
+        return names;
+    }
+    /** Shared parse: split, trim, de-duplicate, bound, then per-kind checks. */
+    parseFields(type, raw, param, check) {
+        if (!raw)
+            return [];
+        const names = [
+            ...new Set(raw
+                .split(',')
+                .map((name) => name.trim())
+                .filter(Boolean))
+        ];
+        if (names.length > exports.MAX_EXPANDED_FIELDS) {
+            throw new common_1.BadRequestException(`${param}: at most ${exports.MAX_EXPANDED_FIELDS} fields may be expanded per request.`);
+        }
+        for (const name of names) {
+            const spec = type.fields[name];
+            if (!spec) {
+                throw new common_1.BadRequestException(`${param}: unknown field "${name}" on "${type.name}".`);
+            }
+            check(name, spec);
+        }
+        return names;
+    }
+};
+exports.PublicExpansionQuery = PublicExpansionQuery;
+exports.PublicExpansionQuery = PublicExpansionQuery = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, database_1.InjectDatabase)()),
+    tslib_1.__param(2, (0, common_1.Optional)()),
+    tslib_1.__param(2, (0, media_asset_resolver_1.InjectMediaAssetResolver)()),
+    tslib_1.__metadata("design:paramtypes", [Object, relation_link_service_1.RelationLinkService, Object])
+], PublicExpansionQuery);
+/** The asset ids stored in a media field — one id, or an ordered list. */
+function mediaRefsOf(value) {
+    return (Array.isArray(value) ? value : [value])
+        .map(content_domain_1.toMediaValueRef)
+        .filter((ref) => ref !== null && !!ref.id);
+}
+/**
+ * The alt text a public consumer should render for one usage.
+ *
+ * `decorative` resolves to `''` — the value an `<img alt="">` needs to be
+ * skipped by a screen reader, which is a different claim from omitting the
+ * attribute. A per-usage `alt` otherwise overrides the asset row's default,
+ * because alt text is per usage: the same logo is "Acme logo" in a header and
+ * decorative in a footer strip (`ORT-83`).
+ */
+function publicAlt(ref, assetAlt) {
+    if (ref.decorative === true)
+        return '';
+    if (typeof ref.alt === 'string' && ref.alt.trim() !== '')
+        return ref.alt;
+    return assetAlt;
+}

package/dist/lib/public-api/types/public-bulk.d.ts

@@ -0,0 +1,77 @@
+import type { PublicEntry } from './public-entry';
+/**
+ * Wire contracts for the public API's **batch** writes — one request that saves,
+ * publishes, unpublishes or deletes many entries of one content type.
+ *
+ * Shared by every surface that offers them: the public REST routes and the MCP
+ * `content_bulk_*` tools. Defined once here so a client that learned a shape
+ * from the OpenAPI document reads the tool's output without a second mapping.
+ *
+ * Only the **save** contract is new. Bulk publish / unpublish / delete answer in
+ * the shapes the admin's own bulk routes already publish (`BulkPublishResult`,
+ * `BulkActionResult`), because they run the very same use-cases — see
+ * `PublicEntryWritesService`.
+ */
+/** What a bulk-save item does to the store. */
+export declare const BULK_SAVE_OP: {
+    /** Insert a new entry — a draft on a publishable type. */
+    readonly Create: "create";
+    /** Merge values onto an entry that already exists. */
+    readonly Update: "update";
+};
+/** One item's operation. */
+export type BulkSaveOp = (typeof BULK_SAVE_OP)[keyof typeof BULK_SAVE_OP];
+/**
+ * Why one item of a batch did not go through.
+ *
+ * Carries the **status the equivalent single-entry call would have returned**
+ * (404 for an entry that isn't there, 422 for values that don't validate, 400
+ * for a malformed item) rather than a bulk-specific error vocabulary, so a
+ * client already handling the single-entry API needs no new branch — and so a
+ * per-item failure stays diagnosable at all, which a flattened boolean would
+ * not be.
+ */
+export interface PublicBulkError {
+    /** The HTTP status the same write would have failed with on its own. */
+    status: number;
+    /** The message, as the single-entry route would have phrased it. */
+    message: string;
+    /** The per-field issues of a 422, when there are any. */
+    issues?: unknown;
+}
+/** What became of one submitted item, positionally matched to the request. */
+export interface PublicBulkSaveItemResult {
+    /** The item's 0-based position in the submitted `items` array. */
+    index: number;
+    /** Which operation the item resolved to. @see BULK_SAVE_OP */
+    op: BulkSaveOp;
+    /** Whether the write landed. */
+    ok: boolean;
+    /** The saved entry, in the same shape a single-entry write returns. */
+    entry?: PublicEntry;
+    /** Why it did not, when `ok` is false. */
+    error?: PublicBulkError;
+}
+/**
+ * The response of a bulk save: one result per submitted item, **in request
+ * order**, plus the tallies.
+ *
+ * **Partial success is the contract**, not a degraded mode. The items are
+ * written one transaction at a time (see `PublicEntryWritesService.bulkSave`),
+ * so a batch cannot be rolled back as a unit — and rejecting 49 good entries
+ * because the fiftieth names a missing relation would make the endpoint useless
+ * for the imports it exists to serve. The response is therefore always a 200
+ * with the per-item verdicts, exactly as the bulk-publish commit reports its
+ * `skipped` ids, and a caller retries the failures it can fix.
+ */
+export interface PublicBulkSaveResult {
+    /** One entry per submitted item, in request order. */
+    items: PublicBulkSaveItemResult[];
+    /** How many items were inserted. */
+    created: number;
+    /** How many existing entries were changed. */
+    updated: number;
+    /** How many items did not save. */
+    failed: number;
+}
+//# sourceMappingURL=public-bulk.d.ts.map

package/dist/lib/public-api/types/public-bulk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-bulk.d.ts","sourceRoot":"","sources":["../../../../src/lib/public-api/types/public-bulk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;;;;;;;GAYG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,YAAY;IACrB,0DAA0D;;IAE1D,sDAAsD;;CAEhD,CAAC;AAEX,4BAA4B;AAC5B,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE1E;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC5B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACrC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,EAAE,EAAE,UAAU,CAAC;IACf,gCAAgC;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,uEAAuE;IACvE,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACjC,sDAAsD;IACtD,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/dist/lib/public-api/types/public-bulk.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BULK_SAVE_OP = void 0;
+/**
+ * Wire contracts for the public API's **batch** writes — one request that saves,
+ * publishes, unpublishes or deletes many entries of one content type.
+ *
+ * Shared by every surface that offers them: the public REST routes and the MCP
+ * `content_bulk_*` tools. Defined once here so a client that learned a shape
+ * from the OpenAPI document reads the tool's output without a second mapping.
+ *
+ * Only the **save** contract is new. Bulk publish / unpublish / delete answer in
+ * the shapes the admin's own bulk routes already publish (`BulkPublishResult`,
+ * `BulkActionResult`), because they run the very same use-cases — see
+ * `PublicEntryWritesService`.
+ */
+/** What a bulk-save item does to the store. */
+exports.BULK_SAVE_OP = {
+    /** Insert a new entry — a draft on a publishable type. */
+    Create: 'create',
+    /** Merge values onto an entry that already exists. */
+    Update: 'update'
+};

package/dist/lib/public-api/types/public-entry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Wire contracts for the public content API (`/api/v1/...`). Kept separate from
+ * the admin's `EntryRecord` on purpose: this is a **published contract** an
+ * external site or app builds against, so it must be free to stay still while
+ * the admin's internal shape evolves.
+ */
+import type { PublicMediaFieldView, PublicRelationFieldView } from './public-expansion';
+/**
+ * One entry as the public API serves it: the storage envelope plus a flat
+ * `values` bag keyed by field name.
+ *
+ * `values` carries the entry's **own** data only — text, richtext, number,
+ * money, boolean, date, datetime, select, multiselect, and json. Every
+ * **reference** field is omitted: `relation` in all four cardinalities and
+ * `media`. Neither is resolvable through this API yet, so returning a bare
+ * uuid would hand a consumer an identifier it has no route to follow.
+ *
+ * That omission is **provisional**, not the intended end state. The schema
+ * endpoint still describes the omitted fields, because they are part of the
+ * real content model; when relation and media reads land they begin appearing
+ * in `values`, which only ever adds keys.
+ *
+ * `status` is carried on publishable types. It used to be omitted as a
+ * constant — this API only ever served published rows — but a write-scoped
+ * token can now create drafts and read them back with `?status=`, so it is real
+ * information again. Adding it is additive: a consumer that ignored the key
+ * before still sees `published` on every entry a read-only token can reach.
+ */
+export interface PublicEntry {
+    /** Entry id — the `:id` segment of the single-entry route. */
+    id: string;
+    /**
+     * `draft` or `published` — only on `publishable` types. A read-only token
+     * only ever sees `published`.
+     *
+     * `draft` with a non-null {@link publishedAt} is the admin's **Modified**
+     * state: live content with unpublished edits on top. Saving a published
+     * entry moves it back to `draft` while its published *version* stays live,
+     * so the pair is what tells those apart — neither field alone does.
+     */
+    status?: string;
+    /** ISO creation timestamp. */
+    createdAt: string;
+    /** ISO last-updated timestamp. */
+    updatedAt: string;
+    /**
+     * ISO timestamp of when this entry last went live — only on `publishable`
+     * types. Never null in a public response: an entry with no published
+     * version is not served at all.
+     */
+    publishedAt?: string | null;
+    /** Locale slug of this row — only on `i18n` types. */
+    locale?: string;
+    /** Shared translation-group id — only on `i18n` types, so a consumer can
+     * correlate an entry with its other translations. */
+    localeGroupId?: string;
+    /** The entry's own field values, keyed by field name (see the note above
+     * on which kinds are omitted). */
+    values: Record<string, unknown>;
+    /**
+     * Relation links, keyed by field name — present only when the caller opts
+     * in with `?relations=preview&relationFields=…`. Each field carries at most
+     * one page of refs plus the true count of *visible* links.
+     */
+    relations?: Record<string, PublicRelationFieldView>;
+    /**
+     * Media assets, keyed by field name — present only when the caller opts in
+     * with `?media=preview&mediaFields=…`. Read the URL caveat on
+     * {@link PublicMediaRef} before pointing a browser at one.
+     */
+    media?: Record<string, PublicMediaFieldView>;
+    /**
+     * The entry's **other** locale rows — the rest of its translation group —
+     * present only when the caller opts in with `?translations=preview` on a
+     * localized type. Ordered by locale slug, and each is a full
+     * {@link PublicEntry} honouring the same `?fields=` selection as the root,
+     * so a language switcher reads `[entry, ...entry.translations]`.
+     *
+     * The entry itself is **not** repeated here: it is the row you asked for,
+     * in the locale you asked for. Only published, non-deleted siblings appear,
+     * so a locale that exists but is still a draft is absent — the same
+     * visibility rule as every other public read. Siblings are not themselves
+     * expanded: their `relations`, `media`, and `translations` are absent.
+     */
+    translations?: PublicEntry[];
+}
+/** One page of public entries. */
+export interface PublicEntryListView {
+    items: PublicEntry[];
+    /** Total matching entries, ignoring pagination. */
+    total: number;
+    /** 1-based page number this page represents. */
+    page: number;
+    /** Rows per page actually applied. */
+    pageSize: number;
+}
+//# sourceMappingURL=public-entry.d.ts.map

package/dist/lib/public-api/types/public-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-entry.d.ts","sourceRoot":"","sources":["../../../../src/lib/public-api/types/public-entry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACR,oBAAoB,EACpB,uBAAuB,EAC1B,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IACxB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;yDACqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;sCACkC;IAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACpD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7C;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAChC;AAED,kCAAkC;AAClC,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CACpB"}

package/dist/lib/public-api/types/public-entry.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Wire contracts for the public content API (`/api/v1/...`). Kept separate from
+ * the admin's `EntryRecord` on purpose: this is a **published contract** an
+ * external site or app builds against, so it must be free to stay still while
+ * the admin's internal shape evolves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });