@orthacms/content-server 0.0.0-reserve.0

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

@@ -0,0 +1,248 @@
+import { type Database } from '@orthacms/database';
+import { type ContentEntryExtension } from '../../extension/entry-extension';
+import { type AnyContentType } from '../../types/content-type';
+import { RelationLinkService } from '../../entries/infrastructure/persistence/relation-link.service';
+import type { PublicMediaFieldView, PublicRelationFieldView } from '../types/public-expansion';
+import { PublicExpansionQuery } from './public-expansion.query';
+import { type EntryVisibility, type PublicEntryQueryDto, type PublicListEntriesQueryDto } from '../http/dto/public-list-entries-query.dto';
+import type { PublicEntry, PublicEntryListView } from '../types/public-entry';
+/**
+ * How a request names the **one** entry it wants. Two spellings, one meaning:
+ * an entry id, or a translation group whose row for the requested locale is
+ * taken (see `getOne`). Every single-entry read takes a locator rather than an
+ * id, so each route exists in both spellings by construction — a group-addressed
+ * caller is never told "that one is id-only", and neither form can drift on what
+ * it hides.
+ */
+export type EntryLocator = {
+    readonly id: string;
+} | {
+    readonly localeGroupId: string;
+};
+/**
+ * The read side of the public content API. Generic over the content type like
+ * the admin's `EntriesService` — the physical table and the sortable columns
+ * are derived from `type` per request, so one service serves every code-defined
+ * collection and single.
+ *
+ * It **reuses** the admin's query machinery where the semantics are identical —
+ * the same ILIKE search predicate and the same query-builder filter engine, so
+ * one query language covers both surfaces — but it is deliberately **not** built
+ * on `EntriesService` itself. Several of that service's knobs (`?deleted=only`
+ * most obviously) select rows this API must never serve, and reaching through it
+ * to subtract them would make the visibility rule an argument about what was
+ * *not* passed. Instead the public read states its own WHERE, so "what can a
+ * token see?" is answerable by reading one method:
+ *
+ * - the **workspace** the request resolved to, always;
+ * - **published only**, on publishable types — a draft is unfinished work and
+ *   never leaves the admin;
+ * - **not soft-deleted**, on paranoid types;
+ * - the bound `CONTENT_ENTRY_EXTENSION`'s scope, so a localized type reads the
+ *   requested locale (and the same rules the admin gets) for free.
+ *
+ * `?search=` and `?filter=` narrow that set further; neither can widen it, since
+ * both are AND-ed onto the predicate above.
+ */
+export declare class PublicEntriesQuery {
+    private readonly db;
+    private readonly expansion;
+    private readonly relationLinks;
+    private readonly extension?;
+    constructor(db: Database, expansion: PublicExpansionQuery, relationLinks: RelationLinkService, extension?: ContentEntryExtension | undefined);
+    /**
+     * One page of a type's publicly readable entries. Count and page share the
+     * WHERE and run concurrently, so the request pays the slower of the two.
+     */
+    list(type: AnyContentType, query: PublicListEntriesQueryDto, workspaceId: string, grantedTypes: ReadonlySet<string>): Promise<PublicEntryListView>;
+    /**
+     * Attach the opt-in relation / media / translation previews to an
+     * already-projected page. Every resolver is batched across the whole page,
+     * so this adds a bounded number of queries per requested field (and one for
+     * translations) — never one per row.
+     */
+    private attachExpansions;
+    /**
+     * Whether this request wants sibling translations — and a **400** when it
+     * asks for them on a type that isn't localized.
+     *
+     * Refusing rather than returning an empty list is the same call
+     * `relationFields` makes for a non-relation field: the type has no
+     * translation group at all, so `[]` would read as "this entry has no other
+     * locales" when the truth is "this content is not localized".
+     */
+    private wantsTranslations;
+    /** Guard a locale-only feature against a type that has no locale rows. */
+    private assertLocalized;
+    /**
+     * The sibling translations of every entry on a page, keyed by entry id.
+     *
+     * **One** query for the whole page: the group ids are collected and read
+     * with a single `locale_group_id IN (…)`, which the
+     * `(locale_group_id, locale)` index serves. No cap is applied — a group
+     * holds at most one row per configured locale, so its size is bounded by
+     * the host's own config rather than by user data.
+     *
+     * Deliberately built on {@link liveWhere} and not `readableWhere`: the
+     * extension's `listScope` pins the read to a **single** locale, which is
+     * exactly what a translation lookup must not do. Everything else about
+     * visibility is unchanged — workspace, published-only, not soft-deleted —
+     * so a locale that exists only as a draft stays invisible here too.
+     */
+    private translationsForEntries;
+    /**
+     * The sibling translations of one entry — the `/translations` sibling route,
+     * for a consumer that has the entry and wants its other locales without
+     * re-reading it. 404 for an entry that isn't publicly readable, exactly like
+     * the entry route; 400 on a type that isn't localized.
+     */
+    translationsOf(type: AnyContentType, locator: EntryLocator, workspaceId: string, query: PublicEntryQueryDto): Promise<PublicEntry[]>;
+    /**
+     * The SELECT list for a `?fields=` selection, or `undefined` to select the
+     * whole row. Narrowing this is the point of a sparse fieldset: without it
+     * the query still reads (and Postgres still detoasts) a richtext column the
+     * caller asked to leave out, and only the serializer saves any bytes.
+     *
+     * The envelope is always included — `toPublicEntry` reads those columns
+     * unconditionally, and they are what make an entry addressable. The WHERE
+     * and ORDER BY may reference columns outside this list; SQL allows that, so
+     * filtering and sorting stay unrestricted by the selection.
+     */
+    private projection;
+    /**
+     * One publicly readable entry, addressed by **either** spelling of
+     * {@link EntryLocator}.
+     *
+     * By id: a draft, a soft-deleted row, an entry in another workspace, and an
+     * id that never existed are all the same 404 — an unpublished entry must not
+     * be distinguishable from a missing one.
+     *
+     * By translation group, the read a localized front-end actually wants: a
+     * consumer that knows an article by its group id ("this story") renders it
+     * in whatever locale the visitor is in by varying `?locale=` alone, instead
+     * of keeping a per-locale id map — the group id is the stable identity of
+     * the story across languages, while each locale's `id` is not. A group with
+     * no published row in the requested locale is the same 404 as an unknown
+     * group: the caller asked for content that isn't live in that language, and
+     * which of the two it is isn't theirs to learn.
+     */
+    getOne(type: AnyContentType, locator: EntryLocator, workspaceId: string, query: PublicEntryQueryDto, grantedTypes: ReadonlySet<string>): Promise<PublicEntry>;
+    /**
+     * The row a locator names, for a **write** — its id addresses the write, and
+     * its stored values are what a partial update merges onto.
+     *
+     * Resolved with `status: 'any'`, because writes address rows in whatever
+     * state they are in — the overwhelmingly common case is editing a draft,
+     * which the published-only default would hide. Everything else about the
+     * lookup is the read rule verbatim (workspace, not soft-deleted, the
+     * requested locale), so a token can never reach across a workspace with a
+     * write that it could not reach with a read.
+     *
+     * Lives here rather than in the write service so there is exactly one
+     * implementation of "which row does this locator mean?" — a second one that
+     * forgot the workspace clause is the failure this avoids.
+     */
+    resolveWritableRow(type: AnyContentType, locator: EntryLocator, workspaceId: string, locale?: string): Promise<Record<string, unknown>>;
+    /**
+     * The full predicate for a **single-entry** read: the locator, the
+     * locale-independent visibility rule, and — for a group locator only — the
+     * extension's locale scope.
+     *
+     * That asymmetry is the point. A **group** id names a whole translation
+     * group, so the locale is what picks the row out of it; `LIMIT 1` never has
+     * to break a tie. An **entry id** already names exactly one row, so AND-ing
+     * the locale scope onto it can do nothing except turn a valid id into a 404
+     * whenever that row is not in the default locale. That used to be the
+     * behaviour, documented as a sharp edge; the write API made it untenable,
+     * since updating a German article by its own id would have needed
+     * `?locale=de` appended to a request that already named the row uniquely.
+     *
+     * The narrowing is safe because `liveWhere` still carries the whole of the
+     * *visibility* rule — workspace, publish state, soft delete. The extension's
+     * `listScope` is, per its own name and its one implementation, about
+     * choosing rows out of a *set*; a request that names one row has already
+     * chosen.
+     *
+     * What the asymmetry must **not** cost is validation. Dropping the scope
+     * from an id read also dropped the only thing that looks at `?locale=`, so
+     * `?locale=zz` went from a 400 to being silently ignored — a typo that
+     * quietly returns another language's content, on a contract that says
+     * every route taking a locale rejects an unknown one. Hence the discarded
+     * call below: `listScope` validates as well as narrows (see the port's
+     * docs), and only the narrowing is unwanted here.
+     */
+    private entryWhere;
+    /** The 404 message for a locator that matched nothing readable. */
+    private notFoundFor;
+    /**
+     * One page of a single relation field's links — the only relation read that
+     * `?relations=preview` cannot express, and therefore the only one with a
+     * route of its own.
+     */
+    relationField(type: AnyContentType, locator: EntryLocator, field: string, page: number, pageSize: number, workspaceId: string, grantedTypes: ReadonlySet<string>, locale?: string, visibility?: EntryVisibility): Promise<PublicRelationFieldView>;
+    /** Every media field of one entry, resolved to asset metadata + URLs. */
+    mediaOf(type: AnyContentType, locator: EntryLocator, workspaceId: string, locale?: string, limit?: number, visibility?: EntryVisibility): Promise<Record<string, PublicMediaFieldView>>;
+    /**
+     * The full row of one publicly readable entry, or a 404 — the shared
+     * pre-step of the sibling routes, so `/relations/:field`, `/media`, and
+     * `/translations` are exactly as invisible for a draft or foreign entry as
+     * the entry read itself, in either addressing form.
+     */
+    private readableRow;
+    /**
+     * Translate one `?filter=` payload — the same query-builder tree the admin
+     * records list takes — against a surface derived from the type.
+     *
+     * Two departures from the admin's version, both deliberate:
+     *
+     * - **Grant-pruned.** `grantedTypes` is passed, so a relation whose target
+     *   the workspace was never granted is omitted from the surface and a rule
+     *   naming it 400s. Without it, `author.name eq "Ada"` would let a token
+     *   infer relation data by watching which entries come back — data this API
+     *   deliberately does not return. The admin's list leaves this unset on
+     *   purpose (there it is a SQL whitelist, not a visibility boundary); here
+     *   it is exactly a visibility boundary.
+     * - **No `status`.** The read already forces `status = published`, so a
+     *   `status` rule could only be a no-op or match nothing. Dropping it from
+     *   the schema turns a confusingly empty page into a clear 400.
+     *
+     * Built lazily — the surface walks the type's whole relation graph to the
+     * hop budget, so an unfiltered list (the common case) never pays for it.
+     * A malformed filter throws `FilterException`, which is a 400.
+     */
+    private filterPredicate;
+    /**
+     * The predicate every public read shares — the whole visibility rule in one
+     * place. `and(undefined, …)` collapses the clauses a type doesn't have, so
+     * a plain non-publishable, non-paranoid type reduces to the workspace scope.
+     */
+    private readableWhere;
+    /**
+     * The locale-**independent** half of {@link readableWhere}: workspace,
+     * published-only, not soft-deleted. Split out for the one read that must
+     * span locales — a translation lookup, whose whole job is to find the rows
+     * `listScope` would have filtered away — so that read narrows the entry
+     * visibility rule in exactly one respect and inherits the rest verbatim.
+     */
+    private liveWhere;
+    /**
+     * The publish-state clause. `published` — the default and everything a
+     * read-only token can ask for — is the API's headline rule; the other two
+     * exist so a write-scoped token can read back what it just created.
+     *
+     * A non-publishable type has no `status` column and every row is simply
+     * live, so this is a no-op there rather than an error: the caller asked for
+     * a distinction the type does not make.
+     */
+    private statusWhere;
+    /**
+     * Translate `?sort=` (`col` ascending, `-col` descending) into an ORDER BY,
+     * always with an `id` tiebreaker so paging is stable across requests.
+     * Sortable = the envelope timestamps, `publishedAt` (publishable types),
+     * `locale` (i18n types), and the type's **scalar** fields — the same
+     * whitelist rule the admin list uses, so a sort key never reaches
+     * `asc(undefined)`. Unknown or excluded keys fall back to newest-updated.
+     */
+    private orderBy;
+}
+//# sourceMappingURL=public-entries.query.d.ts.map

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

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