@kywi-software/core 0.10.0 → 0.12.0

package/dist/db/audit-queries.d.ts

@@ -12,37 +12,37 @@ export declare function createAuditEntry(db: KywiDb, data: {
 }): Promise<{
     id: string;
     siteId: string;
-    createdAt: Date;
     contentId: string;
-    userId: string;
     action: string;
+    createdAt: Date;
+    userEmail: string;
+    userId: string;
+    changedFields: unknown;
     fromStatus: string | null;
     toStatus: string | null;
-    changedFields: unknown;
-    userEmail: string;
 }>;
 export declare function listAuditEntries(db: KywiDb, contentId: string, limit?: number): Promise<{
     id: string;
     siteId: string;
-    createdAt: Date;
     contentId: string;
-    userId: string;
     action: string;
+    createdAt: Date;
+    userEmail: string;
+    userId: string;
+    changedFields: unknown;
     fromStatus: string | null;
     toStatus: string | null;
-    changedFields: unknown;
-    userEmail: string;
 }[]>;
 export declare function listSiteAuditEntries(db: KywiDb, siteId: string, limit?: number): Promise<{
     id: string;
     siteId: string;
-    createdAt: Date;
     contentId: string;
-    userId: string;
     action: string;
+    createdAt: Date;
+    userEmail: string;
+    userId: string;
+    changedFields: unknown;
     fromStatus: string | null;
     toStatus: string | null;
-    changedFields: unknown;
-    userEmail: string;
 }[]>;
 //# sourceMappingURL=audit-queries.d.ts.map

package/dist/db/category-queries.d.ts

@@ -24,9 +24,9 @@ export declare function listCategories(db: KywiDb, siteId: string, parentId?: st
     sortOrder: number;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     isActive: boolean;
-    description: string | null;
     isInterestGroup: boolean;
     notes: string | null;
 }[]>;
@@ -38,9 +38,9 @@ export declare function getCategoryById(db: KywiDb, id: string, siteId?: string)
     sortOrder: number;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     isActive: boolean;
-    description: string | null;
     isInterestGroup: boolean;
     notes: string | null;
 } | null>;
@@ -62,9 +62,9 @@ export declare function createCategory(db: KywiDb, data: {
     sortOrder: number;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     isActive: boolean;
-    description: string | null;
     isInterestGroup: boolean;
     notes: string | null;
 }>;

package/dist/db/changeset-audit-queries.d.ts

@@ -13,20 +13,20 @@ export declare function createChangesetAuditEntry(db: KywiDb, data: {
 }): Promise<{
     id: string;
     siteId: string;
+    action: string;
     createdAt: Date;
     userId: string;
-    action: string;
-    changesetId: string;
     detail: unknown;
+    changesetId: string;
 }>;
 /** List a changeset's audit trail, newest first. */
 export declare function listChangesetAudit(db: KywiDb, changesetId: string, limit?: number): Promise<{
     id: string;
     siteId: string;
+    action: string;
     createdAt: Date;
     userId: string;
-    action: string;
-    changesetId: string;
     detail: unknown;
+    changesetId: string;
 }[]>;
 //# sourceMappingURL=changeset-audit-queries.d.ts.map

package/dist/db/changeset-queries.d.ts

@@ -37,9 +37,9 @@ export declare function createChangeset(db: KywiDb, data: {
     publishedAt: Date | null;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     createdBy: string;
-    description: string | null;
     scheduledPublishAt: Date | null;
     publishedBy: string | null;
 }>;
@@ -50,9 +50,9 @@ export declare function getChangeset(db: KywiDb, id: string, siteId?: string): P
     publishedAt: Date | null;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     createdBy: string;
-    description: string | null;
     scheduledPublishAt: Date | null;
     publishedBy: string | null;
 } | null>;
@@ -63,9 +63,9 @@ export declare function listChangesets(db: KywiDb, siteId: string, status?: stri
     publishedAt: Date | null;
     updatedAt: Date;
     name: string;
+    description: string | null;
     createdAt: Date;
     createdBy: string;
-    description: string | null;
     scheduledPublishAt: Date | null;
     publishedBy: string | null;
 }[]>;
@@ -93,20 +93,20 @@ export declare function addChangesetItem(db: KywiDb, data: {
     action: string;
 }): Promise<{
     id: string;
-    createdAt: Date;
     contentId: string;
     action: string;
-    changesetId: string;
+    createdAt: Date;
     versionId: string | null;
+    changesetId: string;
 }>;
 export declare function removeChangesetItem(db: KywiDb, itemId: string): Promise<void>;
 export declare function listChangesetItems(db: KywiDb, changesetId: string): Promise<{
     id: string;
-    createdAt: Date;
     contentId: string;
     action: string;
-    changesetId: string;
+    createdAt: Date;
     versionId: string | null;
+    changesetId: string;
 }[]>;
 export declare function publishChangeset(db: KywiDb, changesetId: string, publishedBy: string, opts?: PublishChangesetOptions): Promise<any>;
 export declare function rollbackChangeset(db: KywiDb, changesetId: string): Promise<any>;

package/dist/db/comment-queries.d.ts

@@ -6,11 +6,11 @@ export declare function listComments(db: KywiDb, contentId: string, status?: str
     status: string;
     body: string;
     updatedAt: Date;
-    createdAt: Date;
     contentId: string;
-    authorId: string | null;
+    createdAt: Date;
     authorName: string | null;
     authorEmail: string | null;
+    authorId: string | null;
 }[]>;
 export declare function listSiteComments(db: KywiDb, siteId: string, status?: string, limit?: number): Promise<{
     id: string;
@@ -19,11 +19,11 @@ export declare function listSiteComments(db: KywiDb, siteId: string, status?: st
     status: string;
     body: string;
     updatedAt: Date;
-    createdAt: Date;
     contentId: string;
-    authorId: string | null;
+    createdAt: Date;
     authorName: string | null;
     authorEmail: string | null;
+    authorId: string | null;
 }[]>;
 export declare function getCommentById(db: KywiDb, id: string, siteId?: string): Promise<{
     id: string;
@@ -32,11 +32,11 @@ export declare function getCommentById(db: KywiDb, id: string, siteId?: string):
     status: string;
     body: string;
     updatedAt: Date;
-    createdAt: Date;
     contentId: string;
-    authorId: string | null;
+    createdAt: Date;
     authorName: string | null;
     authorEmail: string | null;
+    authorId: string | null;
 } | null>;
 export declare function createComment(db: KywiDb, data: {
     siteId: string;
@@ -54,11 +54,11 @@ export declare function createComment(db: KywiDb, data: {
     status: string;
     body: string;
     updatedAt: Date;
-    createdAt: Date;
     contentId: string;
-    authorId: string | null;
+    createdAt: Date;
     authorName: string | null;
     authorEmail: string | null;
+    authorId: string | null;
 }>;
 export declare function updateComment(db: KywiDb, id: string, data: {
     body?: string;

package/dist/db/comment-subscription-queries.d.ts

@@ -2,8 +2,8 @@ import type { KywiDb } from './client.js';
 export declare function subscribe(db: KywiDb, contentId: string, email: string, userId?: string): Promise<{
     id: string;
     email: string;
-    createdAt: Date;
     contentId: string;
+    createdAt: Date;
     isActive: boolean;
     userId: string | null;
 }>;
@@ -11,8 +11,8 @@ export declare function unsubscribe(db: KywiDb, contentId: string, email: string
 export declare function listSubscribers(db: KywiDb, contentId: string): Promise<{
     id: string;
     email: string;
-    createdAt: Date;
     contentId: string;
+    createdAt: Date;
     isActive: boolean;
     userId: string | null;
 }[]>;

package/dist/db/component-instance-queries.d.ts

@@ -0,0 +1,197 @@
+import type { KywiComponentRow } from '../schema/components.js';
+import type { KywiDb } from './client.js';
+import type { LayoutDocument } from '../layout/types.js';
+import type { ComponentDefinitionLookup } from '../layout/module-permissions.js';
+/**
+ * Component ids reach us from layout JSONB, which is user data — a hand-edited
+ * or imported layout can carry a `componentId` that is not a UUID at all.
+ * Passing one to a `uuid` column comparison is a driver error ("invalid input
+ * syntax for type uuid") that would fail the whole layout save, so non-UUID
+ * links are simply not indexable (the renderer already treats them as
+ * unresolvable).
+ *
+ * Canonical (lower-case) form is required, deliberately. Postgres renders a
+ * `uuid` column lower-case and the renderer matches links against those strings
+ * byte-for-byte, so an upper-case link resolves to nothing on the page. Postgres
+ * would happily match it in a `uuid` comparison, though — indexing it would
+ * count an instance that no visitor can see and that the layout scan (a text
+ * `LIKE` on the canonical id) could never find again. What is indexed is exactly
+ * what the renderer can resolve.
+ */
+export declare function isIndexableComponentId(componentId: string): boolean;
+/**
+ * The definitions behind the `componentId` links a write ADDS, in the shape the
+ * admin-only-module gate reads. Returns undefined when the write adds no link —
+ * the common case, which then costs no query at all.
+ *
+ * ONE loader for every door that writes a layout: `PUT .../layout`, the content
+ * `PUT`/`PATCH` that carries a `layout` field, and `detachComponentEverywhere`.
+ * Linking a component introduces whatever modules its definition contains, so a
+ * door that gates modules but not links is not a gate; having each door build its
+ * own lookup is how one of them ends up not building it.
+ *
+ * Links whose id is not a canonical UUID are skipped: the renderer cannot resolve
+ * them either (and a `uuid` comparison against such a string is a driver error,
+ * not a miss), so they contribute nothing but a failed request.
+ */
+export declare function buildAddedComponentLookup(db: KywiDb, incoming: LayoutDocument, stored: LayoutDocument | null | undefined, siteId: string | undefined): Promise<ComponentDefinitionLookup | undefined>;
+export interface SyncComponentInstancesParams {
+    siteId: string;
+    contentId: string;
+    /** `kywi_content.content_type_name`, denormalised onto each row. */
+    contentType: string;
+    before: LayoutDocument | null | undefined;
+    after: LayoutDocument | null | undefined;
+}
+export interface SyncComponentInstancesResult {
+    added: number;
+    removed: number;
+}
+/**
+ * Bring the index rows for one content document in line with its new layout.
+ *
+ * Only the difference is written: moving a linked node around a page is not a
+ * change of placement, so a save that reshuffles a layout writes nothing here.
+ * Added links are filtered to components that actually exist in the SAME site —
+ * a link to a deleted or foreign component is left unindexed rather than
+ * blowing up the save on a foreign-key violation (the renderer degrades to the
+ * node's own inline copy for exactly those links).
+ */
+export declare function syncComponentInstances(db: KywiDb, params: SyncComponentInstancesParams): Promise<SyncComponentInstancesResult>;
+export interface ComponentUsageItem {
+    contentId: string;
+    contentType: string;
+    title: string | null;
+    nodeIds: string[];
+}
+export interface ComponentUsage {
+    /** Total placements on LIVE (not soft-deleted) documents. */
+    instances: number;
+    /** Distinct live documents holding at least one placement. */
+    pages: number;
+    /** Live documents only — what a "N instances across M pages" dialog names. */
+    items: ComponentUsageItem[];
+    /**
+     * Placements held by soft-deleted (trashed) documents, counted separately.
+     *
+     * A trashed page still holds the link, and restoring it brings the link back,
+     * so these are NOT zero-cost: the delete gate has to add them in (otherwise
+     * deleting the component leaves a restored page pointing at nothing), and
+     * detach-all rewrites trashed documents along with live ones. They are kept
+     * out of `instances`/`pages`/`items` because a user reading "this appears on
+     * 4 pages" means four pages they can navigate to.
+     */
+    trashedInstances: number;
+    trashedPages: number;
+}
+/**
+ * Where a component is placed, with the page titles the confirm dialogs name.
+ * One indexed read plus a join — the shape both the admin library and the save
+ * fork consume.
+ *
+ * Trashed documents are partitioned out of the headline numbers rather than
+ * dropped: see {@link ComponentUsage.trashedInstances}.
+ */
+export declare function getComponentUsage(db: KywiDb, componentId: string, siteId: string): Promise<ComponentUsage>;
+export interface ComponentUsageCount {
+    componentId: string;
+    instances: number;
+    pages: number;
+    trashedInstances: number;
+}
+/**
+ * Per-component placement counts for a whole site — one grouped read, so the
+ * library list doesn't fan out into a usage query per row.
+ *
+ * The live/trashed split matches {@link getComponentUsage} exactly, so the
+ * number in the library list is the same number the component's own usage
+ * dialog shows.
+ */
+export declare function listComponentUsageCounts(db: KywiDb, siteId: string): Promise<ComponentUsageCount[]>;
+/** Why one document was left alone by {@link detachComponentEverywhere}. */
+export type DetachSkipReason = 'invalidLayout' | 'adminOnlyModule';
+export interface DetachSkippedPage {
+    contentId: string;
+    contentType: string;
+    reason: DetachSkipReason;
+    detail: string;
+}
+export interface DetachEverywhereResult {
+    /** Documents rewritten. */
+    pages: number;
+    /** Placements materialised into independent copies. */
+    instances: number;
+    /**
+     * Documents deliberately left untouched, each with the reason. Empty on the
+     * happy path; when it is not empty the component still has instances and
+     * must not be deleted.
+     */
+    skipped: DetachSkippedPage[];
+}
+export interface DetachEverywhereOptions {
+    /**
+     * The role of the caller on whose behalf this rewrite happens. Materialising
+     * a component definition writes real module nodes into pages, so the same
+     * admin-only-module gate the layout PUT applies has to apply here — otherwise
+     * detach-all is a way to place an `html` module on every page in the site
+     * without ever passing that gate.
+     */
+    actorRole: string;
+}
+/**
+ * Materialise every placement of a component into an independent copy, so the
+ * component can be deleted without any page changing what it renders.
+ *
+ * Candidate documents come from a scan of the site's layouts (a `::text LIKE`
+ * on the component's own UUID), NOT from the instance index. The index is a
+ * derived cache; if it ever drifted, trusting it here would leave a page
+ * pointing at a component that is about to disappear. The scan is bounded by
+ * the site and only materialises rows that actually contain the id. Trashed
+ * (soft-deleted) documents are included deliberately: they still hold the link
+ * and restoring one must not resurrect a dangling reference.
+ *
+ * Two guards run per document, and BOTH are per-document skips rather than a
+ * failure of the whole operation:
+ *
+ *  - the rewritten document must pass `validateLayoutDocument`. A malformed
+ *    component definition would otherwise be copied into every referencing page
+ *    and make each of them permanently un-editable (every later layout PUT
+ *    would 400 on a document the user cannot repair through the UI). A page
+ *    whose layout was ALREADY invalid before the rewrite is skipped by the same
+ *    rule — it needs fixing regardless, and knowingly writing an invalid
+ *    document is never the better option;
+ *  - the rewritten document must not introduce an admin-only module the caller
+ *    could not have added by hand — the same differential check
+ *    `PUT .../layout` applies, with the same role.
+ *
+ * Skipping is the honest choice over failing everything: one bad page must not
+ * make the component undetachable — and so undeletable — everywhere else. The
+ * caller is told exactly which documents were left and why, the skipped pages
+ * keep their (still working) links, and the delete gate still sees those
+ * instances, so a component can never be deleted out from under a page.
+ *
+ * Everything — the layout rewrites, the index updates, and the sweep of any
+ * leftover index rows — happens in one transaction, and each layout is re-read
+ * `FOR UPDATE` inside it so a concurrent editor save can't be silently
+ * overwritten (it waits, then the detach sees its result).
+ */
+export declare function detachComponentEverywhere(db: KywiDb, component: Pick<KywiComponentRow, 'id' | 'siteId' | 'type' | 'moduleType' | 'definition'>, options: DetachEverywhereOptions): Promise<DetachEverywhereResult>;
+export interface ReindexResult {
+    documentsScanned: number;
+    instances: number;
+}
+/**
+ * Rebuild the instance index from the layouts themselves.
+ *
+ * This is what makes the index safe on an upgrade: the table ships empty while
+ * existing installs already have layouts full of `componentId` links, and
+ * `kywi migrate` runs this as a post-step so no operator has to know it exists.
+ * It is idempotent (it clears the scope it is about to rebuild) and doubles as
+ * the repair path if the index is ever suspected of drift.
+ *
+ * Only documents whose layout mentions a known component id are parsed, so the
+ * cost is one indexed-free scan plus a parse of the pages that actually use
+ * components — not a parse of every layout in the database.
+ */
+export declare function reindexComponentInstances(db: KywiDb, siteId?: string): Promise<ReindexResult>;
+//# sourceMappingURL=component-instance-queries.d.ts.map

package/dist/db/component-instance-queries.d.ts.map

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