@krantho/persistence 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Descoped
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auth.d.ts

@@ -0,0 +1,79 @@
+/** Role in the krantho permission system */
+export type Role = 'admin' | 'editor' | 'viewer';
+/** A user record in the database */
+export interface UserRecord {
+    id: string;
+    email: string | null;
+    name: string | null;
+    roles: Role[];
+    oidcSubject: string | null;
+    oidcIssuer: string | null;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Data for creating a new user */
+export interface CreateUserData {
+    email: string | null;
+    name: string | null;
+    roles: Role[];
+    oidcSubject?: string | undefined;
+    oidcIssuer?: string | undefined;
+}
+/** Data for updating a user */
+export interface UpdateUserData {
+    email?: string | undefined;
+    name?: string | undefined;
+    roles?: Role[] | undefined;
+    isActive?: boolean | undefined;
+    oidcSubject?: string | undefined;
+    oidcIssuer?: string | undefined;
+}
+/** A refresh token record */
+export interface RefreshTokenRecord {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    expiresAt: string;
+    createdAt: string;
+}
+/** Per-collection permission override */
+export interface UserPermission {
+    userId: string;
+    collection: string;
+    role: Role;
+}
+/** Auth adapter interface — users, refresh tokens, permissions */
+export interface IAuthAdapter {
+    /** Create a user and return the created record */
+    createUser(data: CreateUserData): Promise<UserRecord>;
+    /** Get a user by ID */
+    getUser(id: string): Promise<UserRecord | null>;
+    /** Get a user by email */
+    getUserByEmail(email: string): Promise<UserRecord | null>;
+    /** Get a user by OIDC identity (issuer + subject) */
+    getUserByOidc(issuer: string, subject: string): Promise<UserRecord | null>;
+    /** List all users */
+    listUsers(): Promise<UserRecord[]>;
+    /** Update a user */
+    updateUser(id: string, data: UpdateUserData): Promise<UserRecord | null>;
+    /** Delete a user (cascades refresh tokens and permissions) */
+    deleteUser(id: string): Promise<boolean>;
+    /** Store a refresh token hash for a user */
+    createRefreshToken(userId: string, tokenHash: string, expiresAt: string): Promise<string>;
+    /** Find a refresh token by hash */
+    getRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    /** Delete a refresh token by ID (used during rotation) */
+    deleteRefreshToken(id: string): Promise<void>;
+    /** Delete all refresh tokens for a user (used on logout/deactivation) */
+    deleteUserRefreshTokens(userId: string): Promise<void>;
+    /** Delete expired refresh tokens (cleanup on startup) */
+    deleteExpiredRefreshTokens(): Promise<number>;
+    /** Get all permission overrides for a user */
+    getUserPermissions(userId: string): Promise<UserPermission[]>;
+    /** Set a per-collection permission override (upsert) */
+    setUserPermission(userId: string, collection: string, role: Role): Promise<void>;
+    /** Delete a per-collection permission override */
+    deleteUserPermission(userId: string, collection: string): Promise<boolean>;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

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

package/dist/auth.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":""}

package/dist/content-contract.d.ts

@@ -0,0 +1,36 @@
+import { type AuthoredMetadata } from '@krantho/core';
+export type { AuthoredMetadata, ContentContract, ContractReference, DefaultProvenance, MetadataGroupContract, } from '@krantho/core';
+export { authoredMetadata } from '@krantho/core';
+/** An atomic document write refused a stale revision or a duplicate create. */
+export declare class ContentWriteConflict extends Error {
+    readonly currentVersion: number;
+    readonly expectedVersion: number;
+    constructor(currentVersion: number, expectedVersion: number);
+}
+/** The authored values a write names; one left undefined keeps the previous version's */
+export type AuthoredWrite = {
+    readonly [K in keyof AuthoredMetadata]?: AuthoredMetadata[K] | undefined;
+};
+/** The authored values a write names; the ones it leaves out stay undefined */
+export declare function authoredOf(write: AuthoredWrite): AuthoredWrite;
+/**
+ * The authored values a new version stores: what the write names and, for
+ * whatever it leaves out, the previous version's. A write that touches only
+ * fields or the body never clears a document's metadata, contract or
+ * provenance. A repository basis agreed at version zero takes the new version.
+ */
+export declare function nextAuthored(previous: AuthoredWrite | null, write: AuthoredWrite, version: number): AuthoredMetadata;
+/** Repository agreement is bookkeeping, not an author-owned value. */
+export declare function sameAuthoredValues(left: Partial<AuthoredMetadata>, right: Partial<AuthoredMetadata>): boolean;
+/**
+ * A `doc:<collection>/<slug>` SEO config row as the document it belongs to and
+ * its config object, unwrapping a config stored as JSON text. Null when the id
+ * names no document or the config is not an object, so a migration leaves the
+ * row where it is.
+ */
+export declare function documentSeoRow(id: string, config: unknown): {
+    collection: string;
+    slug: string;
+    config: Record<string, unknown>;
+} | null;
+//# sourceMappingURL=content-contract.d.ts.map

package/dist/content-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-contract.d.ts","sourceRoot":"","sources":["../src/content-contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAmC,MAAM,eAAe,CAAA;AAEtF,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,+EAA+E;AAC/E,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM;gBADvB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM;CAKnC;AAED,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,CAAC,IAAI,MAAM,gBAAgB,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS;CACzE,CAAA;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAO9D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,GAAG,IAAI,EAC9B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,MAAM,GACd,gBAAgB,CASlB;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,CAAC,gBAAgB,CAAC,EAC/B,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAC/B,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,OAAO,GACd;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAa9E"}

package/dist/content-contract.js

@@ -0,0 +1,70 @@
+import { authoredMetadata, canonicalJson } from '@krantho/core';
+export { authoredMetadata } from '@krantho/core';
+/** An atomic document write refused a stale revision or a duplicate create. */
+export class ContentWriteConflict extends Error {
+    currentVersion;
+    expectedVersion;
+    constructor(currentVersion, expectedVersion) {
+        super('Content has been modified by another user');
+        this.currentVersion = currentVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = 'ContentWriteConflict';
+    }
+}
+/** The authored values a write names; the ones it leaves out stay undefined */
+export function authoredOf(write) {
+    return {
+        metadata: write.metadata,
+        contract: write.contract,
+        defaults: write.defaults,
+        repositoryBasis: write.repositoryBasis,
+    };
+}
+/**
+ * The authored values a new version stores: what the write names and, for
+ * whatever it leaves out, the previous version's. A write that touches only
+ * fields or the body never clears a document's metadata, contract or
+ * provenance. A repository basis agreed at version zero takes the new version.
+ */
+export function nextAuthored(previous, write, version) {
+    const kept = authoredMetadata(previous ?? {});
+    const basis = write.repositoryBasis !== undefined ? write.repositoryBasis : kept.repositoryBasis;
+    return {
+        metadata: write.metadata ?? kept.metadata,
+        contract: write.contract !== undefined ? write.contract : kept.contract,
+        defaults: write.defaults ?? kept.defaults,
+        repositoryBasis: basis?.version === 0 ? { ...basis, version } : basis,
+    };
+}
+/** Repository agreement is bookkeeping, not an author-owned value. */
+export function sameAuthoredValues(left, right) {
+    const semantic = (input) => {
+        const { repositoryBasis: _basis, ...values } = authoredMetadata(input);
+        return canonicalJson(values);
+    };
+    return semantic(left) === semantic(right);
+}
+/**
+ * A `doc:<collection>/<slug>` SEO config row as the document it belongs to and
+ * its config object, unwrapping a config stored as JSON text. Null when the id
+ * names no document or the config is not an object, so a migration leaves the
+ * row where it is.
+ */
+export function documentSeoRow(id, config) {
+    const match = /^doc:([^/]+)\/(.+)$/.exec(id);
+    if (!match?.[1] || !match[2])
+        return null;
+    let value = config;
+    for (let depth = 0; typeof value === 'string' && depth < 2; depth++) {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return { collection: match[1], slug: match[2], config: value };
+}
+//# sourceMappingURL=content-contract.js.map

package/dist/content-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-contract.js","sourceRoot":"","sources":["../src/content-contract.ts"],"names":[],"mappings":"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"}

package/dist/content-query.d.ts

@@ -0,0 +1,48 @@
+import type { ContentDocument, ContentSummary, DocumentMeta, IPersistenceAdapter } from './index.js';
+/** What a query returns of each document */
+export type QueryProjection = 'meta' | 'summary' | 'full';
+/** Where a text match looks */
+export type MatchTarget = 'slug' | 'fields' | 'body';
+interface QueryBase<P extends QueryProjection> {
+    /** The collections to read; every collection when omitted */
+    collections?: readonly string[] | undefined;
+    /** One locale; every locale when omitted */
+    locale?: string | undefined;
+    projection: P;
+    /** Case-insensitive substring match; a document matches when any target contains the text */
+    match?: {
+        text: string;
+        in: readonly MatchTarget[];
+    } | undefined;
+    /** `field` or `field:asc|desc`, the sort whitelist of sort-columns.ts */
+    sort?: string | undefined;
+    /** At most this many items; every match when omitted */
+    limit?: number | undefined;
+    offset?: number | undefined;
+}
+/** The current version of each document (drafts included) */
+export interface CurrentQuery<P extends QueryProjection = QueryProjection> extends QueryBase<P> {
+    state: 'current';
+    status?: 'draft' | 'published' | 'archived' | undefined;
+}
+/** The live version of each document that has one */
+export interface PublishedQuery<P extends QueryProjection = QueryProjection> extends QueryBase<P> {
+    state: 'published';
+}
+export type ContentQuery<P extends QueryProjection = QueryProjection> = CurrentQuery<P> | PublishedQuery<P>;
+export type QueryItem<P extends QueryProjection> = P extends 'meta' ? DocumentMeta : P extends 'summary' ? ContentSummary : ContentDocument;
+/** One page of a query */
+export interface QueryPage<P extends QueryProjection> {
+    /** Each item; `snippet` is set when the query matched `body` or `fields` */
+    items: Array<QueryItem<P> & {
+        snippet?: string | undefined;
+    }>;
+    /** Whether another page follows (read as LIMIT n + 1, never a count) */
+    hasMore: boolean;
+}
+/** Adapter that can answer a content query. */
+export type QueryReader = IPersistenceAdapter & Required<Pick<IPersistenceAdapter, 'query'>>;
+/** Check if adapter can answer a content query. */
+export declare function canQuery(adapter: IPersistenceAdapter): adapter is QueryReader;
+export {};
+//# sourceMappingURL=content-query.d.ts.map

package/dist/content-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-query.d.ts","sourceRoot":"","sources":["../src/content-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAEpG,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAEzD,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEpD,UAAU,SAAS,CAAC,CAAC,SAAS,eAAe;IAC3C,6DAA6D;IAC7D,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3C,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,UAAU,EAAE,CAAC,CAAA;IACb,6FAA6F;IAC7F,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE,GAAG,SAAS,CAAA;IAChE,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IAC7F,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;CACxD;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,CAAE,SAAQ,SAAS,CAAC,CAAC,CAAC;IAC/F,KAAK,EAAE,WAAW,CAAA;CACnB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAChE,YAAY,CAAC,CAAC,CAAC,GACf,cAAc,CAAC,CAAC,CAAC,CAAA;AAErB,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,eAAe,IAAI,CAAC,SAAS,MAAM,GAC/D,YAAY,GACZ,CAAC,SAAS,SAAS,GACjB,cAAc,GACd,eAAe,CAAA;AAErB,0BAA0B;AAC1B,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,eAAe;IAClD,4EAA4E;IAC5E,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAA;IAC7D,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAA;AAE5F,mDAAmD;AACnD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,IAAI,WAAW,CAE7E"}

package/dist/content-query.js

@@ -0,0 +1,5 @@
+/** Check if adapter can answer a content query. */
+export function canQuery(adapter) {
+    return !!adapter.query;
+}
+//# sourceMappingURL=content-query.js.map

package/dist/content-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-query.js","sourceRoot":"","sources":["../src/content-query.ts"],"names":[],"mappings":"AAuDA,mDAAmD;AACnD,MAAM,UAAU,QAAQ,CAAC,OAA4B;IACnD,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,CAAA;AACxB,CAAC"}

package/dist/content-row.d.ts

@@ -0,0 +1,59 @@
+import { type AuthoredMetadata } from './content-contract.js';
+import type { ContentDocument, ContentSummary, DocumentMeta } from './index.js';
+/**
+ * Canonical shape of a content row's meta — what a list that reads no fields, body, HTML or
+ * sections returns — as understood by the shared mapper.
+ *
+ * Each adapter is responsible for normalizing its raw storage row into this shape
+ * (or one that extends it) before passing it to `contentDocumentFromRow`,
+ * `contentSummaryFromRow` or `documentMetaFromRow`. This
+ * keeps the shared mapping logic in one place (this file) while letting each
+ * adapter own its raw-row-to-normalized translation (JSON parsing for SQLite,
+ * Date-to-ISO for Postgres, null-coalescing for html/sections, etc.).
+ */
+export interface NormalizedMetaRow {
+    readonly collection: string;
+    readonly slug: string;
+    readonly locale: string;
+    readonly version: number;
+    /** The document's live version as of this row; null when nothing is live */
+    readonly liveVersion: number | null;
+    readonly status: string;
+    readonly source: string;
+    readonly changedBy: string | null;
+    /** ISO 8601 timestamp — every adapter must normalize to this format */
+    readonly createdAt: string;
+}
+/** A content row with its fields, read without its body, rendered HTML and sections */
+export interface NormalizedSummaryRow extends NormalizedMetaRow {
+    readonly fields: Record<string, unknown>;
+    /** The authored metadata groups; a summary leaves out the contract and provenance */
+    readonly metadata: AuthoredMetadata['metadata'];
+}
+/** A content row with its body, rendered HTML and sections */
+export interface NormalizedContentRow extends NormalizedSummaryRow {
+    readonly authored: AuthoredMetadata;
+    readonly body: string;
+    readonly html: string;
+    readonly sections: Record<string, string>;
+}
+/**
+ * Produce a full `ContentDocument` from a normalized row.
+ *
+ * Called by every persistence adapter after its own `normalizeRow` step.
+ * Having this in the shared package means a change to the `ContentDocument`
+ * shape only needs to be propagated here, not in every adapter.
+ */
+export declare function contentDocumentFromRow(row: NormalizedContentRow): ContentDocument;
+/**
+ * Produce a `ContentSummary` from a row read without its content: the meta and
+ * the fields, never the body, the rendered HTML or the sections.
+ */
+export declare function contentSummaryFromRow(row: NormalizedSummaryRow): ContentSummary;
+/**
+ * Produce a `DocumentMeta` (no body, no fields, no html, no sections) from a
+ * normalized row. Used when listing version history where the caller only
+ * needs metadata.
+ */
+export declare function documentMetaFromRow(row: NormalizedMetaRow): DocumentMeta;
+//# sourceMappingURL=content-row.d.ts.map

package/dist/content-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-row.d.ts","sourceRoot":"","sources":["../src/content-row.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,uBAAuB,CAAA;AAC/E,OAAO,KAAK,EACV,eAAe,EAGf,cAAc,EACd,YAAY,EACb,MAAM,YAAY,CAAA;AAWnB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;CAChD;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,oBAAoB,GAAG,eAAe,CAUjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,oBAAoB,GAAG,cAAc,CAG/E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,iBAAiB,GAAG,YAAY,CAsBxE"}

package/dist/content-row.js

@@ -0,0 +1,60 @@
+import { authoredMetadata } from './content-contract.js';
+import { statusOf } from './live-version.js';
+const VALID_STATUSES = new Set([
+    'draft',
+    'published',
+    'archived',
+    'deleted',
+]);
+const VALID_SOURCES = new Set(['filesystem', 'api', 'import']);
+/**
+ * Produce a full `ContentDocument` from a normalized row.
+ *
+ * Called by every persistence adapter after its own `normalizeRow` step.
+ * Having this in the shared package means a change to the `ContentDocument`
+ * shape only needs to be propagated here, not in every adapter.
+ */
+export function contentDocumentFromRow(row) {
+    const meta = documentMetaFromRow(row);
+    return {
+        meta,
+        fields: row.fields,
+        ...authoredMetadata(row.authored),
+        body: row.body,
+        html: row.html,
+        sections: row.sections,
+    };
+}
+/**
+ * Produce a `ContentSummary` from a row read without its content: the meta and
+ * the fields, never the body, the rendered HTML or the sections.
+ */
+export function contentSummaryFromRow(row) {
+    const meta = documentMetaFromRow(row);
+    return { meta, fields: row.fields, metadata: row.metadata };
+}
+/**
+ * Produce a `DocumentMeta` (no body, no fields, no html, no sections) from a
+ * normalized row. Used when listing version history where the caller only
+ * needs metadata.
+ */
+export function documentMetaFromRow(row) {
+    return {
+        collection: row.collection,
+        slug: row.slug,
+        locale: row.locale,
+        version: row.version,
+        liveVersion: row.liveVersion,
+        status: VALID_STATUSES.has(row.status)
+            ? statusOf(row.status, row.liveVersion)
+            : (console.warn(`[persistence] Unknown status "${row.status}" for ${row.collection}/${row.slug}, defaulting to "draft"`),
+                statusOf('draft', row.liveVersion)),
+        source: VALID_SOURCES.has(row.source)
+            ? row.source
+            : (console.warn(`[persistence] Unknown source "${row.source}" for ${row.collection}/${row.slug}, defaulting to "filesystem"`),
+                'filesystem'),
+        changedBy: row.changedBy,
+        createdAt: row.createdAt,
+    };
+}
+//# sourceMappingURL=content-row.js.map

package/dist/content-row.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-row.js","sourceRoot":"","sources":["../src/content-row.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAQ/E,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5C,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAgB;IACjE,OAAO;IACP,WAAW;IACX,UAAU;IACV,SAAS;CACV,CAAC,CAAA;AACF,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAgB,CAAC,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAA;AA0ClG;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAyB;IAC9D,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACrC,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC;QACjC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACvB,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAyB;IAC7D,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACrC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAA;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAsB;IACxD,OAAO;QACL,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;YACpC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC;YACvC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CACX,iCAAiC,GAAG,CAAC,MAAM,SAAS,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,yBAAyB,CACxG;gBACD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QACvC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;YACnC,CAAC,CAAE,GAAG,CAAC,MAAwB;YAC/B,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CACX,iCAAiC,GAAG,CAAC,MAAM,SAAS,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,IAAI,8BAA8B,CAC7G;gBACD,YAA6B,CAAC;QAClC,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAA;AACH,CAAC"}