@createcms/core 0.1.1

package/dist/plugins/i18n/index.d.ts

@@ -0,0 +1,562 @@
+import * as better_call from 'better-call';
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import { AnyPgTable, PgDatabase } from 'drizzle-orm/pg-core';
+import { AnyColumn, SQL } from 'drizzle-orm';
+
+type ResolvedUserConfig = {
+    table: AnyPgTable;
+    tableName: string;
+    schemaName: string | null;
+    idColumn: AnyColumn;
+    /** The camelCase key used in the Drizzle table definition (e.g. "id"). */
+    idColumnKey: string;
+    /** The actual database column name (e.g. "id" or "user_id"). */
+    idColumnDbName: string;
+    allColumns: Record<string, AnyColumn>;
+    /** Allowlist (camelCase keys) of columns exposable via `withUser`. */
+    exposeColumns: string[];
+    sqlTableRef: string;
+};
+
+type DrizzleInstance = PgDatabase<any, Record<string, unknown>, any>;
+
+declare const notificationTypeEnum: drizzle_orm_pg_core.PgEnum<["mention", "comment", "threadResolved", "approvalRequested", "approvalApproved", "approvalRejected", "mergeRequestOpened", "mergeRequestMerged", "mergeRequestClosed", "mergeRequestReopened", "published", "custom"]>;
+
+type NotificationType = (typeof notificationTypeEnum.enumValues)[number];
+type NotificationPayload = {
+    id: string;
+    recipientId: string;
+    actorId: string | null;
+    type: NotificationType;
+    title: string;
+    body: string | null;
+    resourceType: string | null;
+    resourceId: string | null;
+    collection: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: Date;
+};
+type OnNotificationHandler = (notification: NotificationPayload) => void | Promise<void>;
+type NotificationInput = Omit<NotificationPayload, 'id' | 'createdAt'>;
+
+type NotificationService = ReturnType<typeof createNotificationService>;
+declare function createNotificationService(db: DrizzleInstance, handlers: OnNotificationHandler[]): {
+    notify(input: NotificationInput): Promise<NotificationPayload>;
+    notifyMany(inputs: NotificationInput[]): Promise<NotificationPayload[]>;
+};
+
+/**
+ * Per-request scope produced by a ScopeConditionFactory.
+ * `where` — appended to SELECT/UPDATE/DELETE queries.
+ * `insertColumns` — snake_case column name → value pairs merged directly
+ *   into the raw SQL INSERT via `scopedInsert` / `scopedInsertBatch`.
+ */
+type TableScope = {
+    where?: SQL;
+    insertColumns?: Record<string, unknown>;
+};
+/**
+ * `roots` scope additionally supports a per-NEW-ENTRY column contributor: a
+ * plugin can compute fresh insert columns once per newly-created logical entry
+ * (e.g. a freshly minted translation-group id), which the static `insertColumns`
+ * channel (same value on every row) can't express. Called once per
+ * createRoot / root-duplication. Generic — core names no column. (Seam D.)
+ */
+type RootTableScope = TableScope & {
+    newEntryColumns?: () => Record<string, unknown>;
+    /**
+     * Scope columns to EXCLUDE from cross-scope read filtering — columns the
+     * plugin varies INDEPENDENTLY of a query so that cross-scope reads (a
+     * reference/host/usage that legitimately spans them) must not filter on them.
+     * The i18n plugin declares `['language']` (a host/reference in any sibling
+     * language still counts; the read path already resolved a specific sibling).
+     * Generic — core names no column; passed to `rootScopeConditions` as its
+     * `exclude`. Empty/absent → every scope column filters. (Seam D6.)
+     */
+    crossScopeExclude?: readonly string[];
+};
+/**
+ * A plugin-provided resolver for reference values (rootId / group-key strings),
+ * carried on the resolved scope and consumed by the read path and the A/B
+ * co-render walk. Core ships an IDENTITY default (`coreReferenceResolver`)
+ * reproducing the single-language, no-plugin behaviour byte-for-byte; the i18n
+ * plugin supplies a real one that understands translation groups + the fallback
+ * chain. Core never names any i18n concept — it knows only this interface.
+ *
+ * `db` AND `scopeColumns` are passed PER CALL (not closed over): `db` so a
+ * caller inside a transaction (e.g. the A/B →running guard under FOR UPDATE)
+ * resolves against its own tx handle; `scopeColumns` because the MERGED root
+ * scope columns (tenant + language) exist only AFTER every scope factory has
+ * run — the i18n factory that builds the resolver sees only its OWN column at
+ * build time. The resolver therefore closes over just its resolution POLICY
+ * (e.g. the i18n active language + fallback chain). `scopeColumns` is the
+ * scope predicate; the resolver excludes its own cross-scope columns.
+ * (Seam B.)
+ */
+type ReferenceResolver = {
+    /**
+     * Read-time render pick: stored reference value → the ONE rootId it renders
+     * as (omit a key to leave it unresolved). Identity default: `value → value`.
+     */
+    resolveRenderTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, collection: string, storedValues: string[]): Promise<Map<string, string>>;
+    /**
+     * Conflict superset: stored reference keys → ALL rootIds they could render as
+     * (a group key expands to its whole group). Used by the A/B co-render walk;
+     * collection-agnostic (a reference may target any collection). Identity
+     * default: the existing, non-archived roots among `storedKeys` (by id).
+     */
+    resolveConflictTargets(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, storedKeys: string[]): Promise<string[]>;
+    /** rootIds → all their group siblings. Identity default: the input rootIds. */
+    expandGroup(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+    /** rootIds → the group keys a host could embed them by. Default: `[]`. */
+    groupKeysFor(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<string[]>;
+};
+/** One variant branch of a running A/B test on a referenced root. */
+type RunningAbTestVariant = {
+    branchId: string;
+    isControl: boolean;
+};
+/** A running A/B test on one root: the test plus its variant branches. */
+type RunningAbTest = {
+    testId: string;
+    trafficPercentage: number;
+    variants: RunningAbTestVariant[];
+};
+/**
+ * A plugin-provided resolver that reports which referenced roots currently have
+ * a RUNNING A/B test (with that test's variant branches). Carried on the
+ * resolved scope and consumed by the read path's reference loader to fan the one
+ * XOR-guaranteed varying block's branches out to the client (AB_FANOUT F2). Core
+ * ships NO default — when absent (no ab-test plugin) the read path assumes no
+ * running tests and every embed stays on its deterministic single pick (F0).
+ * Core never names any A/B concept beyond this interface. (Seam F.)
+ */
+type AbTestResolver = {
+    /**
+     * The subset of `rootIds` that have a running test, each mapped to its test +
+     * variant branches. `db` AND `scopeColumns` are passed PER CALL (same
+     * rationale as {@link ReferenceResolver}). The caller passes already
+     * render-resolved (active-language) rootIds, so this needs no group expansion.
+     */
+    runningTests(db: DrizzleInstance, scopeColumns: Record<string, unknown> | undefined, rootIds: string[]): Promise<Map<string, RunningAbTest>>;
+};
+type ResolvedScope = {
+    roots?: RootTableScope;
+    assets?: TableScope;
+    assetFolders?: TableScope;
+    redirects?: TableScope;
+    /**
+     * Plugin-provided reference resolver (i18n translation-group resolution). When
+     * absent, callers use core's identity default. Generic — see `ReferenceResolver`.
+     */
+    referenceResolver?: ReferenceResolver;
+    /**
+     * Plugin-provided running-A/B-test resolver (AB_FANOUT F2 server fan-out).
+     * When absent, the read path assumes no running tests. Generic — see
+     * {@link AbTestResolver}.
+     */
+    abTestResolver?: AbTestResolver;
+    /**
+     * Opaque per-plugin context slots, keyed by plugin id. Core never reads it;
+     * each plugin stashes its own per-request context here from a scope factory
+     * and reads it back via its own exported accessor. Merged generically in
+     * computeScope (shallow, last-writer-wins per slot).
+     */
+    pluginContext?: Record<string, unknown>;
+};
+/**
+ * Factory registered by plugins during `init`.
+ * Called once per request with the middleware result to produce
+ * table-level WHERE conditions and extra INSERT values.
+ */
+type ScopeConditionFactory = (mwResult: MiddlewareResult) => ResolvedScope;
+type CMSOperation = 'read' | 'create' | 'update' | 'delete';
+type BlockTypes = {
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: string;
+    richText: string;
+    image: string;
+    select: string;
+    reference: string;
+};
+type BlockPropertyType = keyof BlockTypes;
+type SelectOption = {
+    readonly label: string;
+    readonly value: string;
+};
+type BlockPropertySpec<T extends BlockPropertyType> = {
+    type: T;
+    required?: boolean;
+    defaultValue?: BlockTypes[T];
+    label: string;
+    description?: string;
+    placeholder?: string;
+} & (T extends 'select' ? {
+    options: readonly SelectOption[];
+} : {}) & (T extends 'reference' ? {
+    collection: string;
+} : {});
+/** Discriminated union over all concrete block-property specs. */
+type BlockProperty = {
+    [K in BlockPropertyType]: BlockPropertySpec<K>;
+}[BlockPropertyType];
+/** Scalar property subset usable as an event parameter (no references/media). */
+type ScalarBlockProperty = Extract<BlockProperty, {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'date';
+}>;
+/**
+ * Declares a meaningful event a functional block can emit (e.g. a form's
+ * `submitSuccess`). Living on the block DEFINITION makes it the single source of
+ * truth for the typed `fire(...)` union, the test-creation goal picker, and the
+ * analytics wire name. `name` overrides the GA4/dataLayer wire name (defaults to
+ * `cms_<blockType>_<eventKey>`, computed by the measurement layer). Whether an
+ * event counts as a conversion is decided per test in the UI, not here.
+ */
+type EventDeclaration = {
+    /** Analytics wire-name override (snake_case). Defaults to cms_<type>_<key>. */
+    name?: string;
+    /** Typed parameters carried with the event (scalar only). */
+    params?: Record<string, ScalarBlockProperty>;
+    /** Human label for the goal picker. */
+    label?: string;
+};
+type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TEvents extends Record<string, EventDeclaration> = Record<string, never>> = {
+    properties: TProps;
+    label: string;
+    description?: string;
+    previewImageUrl?: string;
+    /** Events this (functional) block can emit — see {@link EventDeclaration}. */
+    events?: TEvents;
+} & ({
+    allowChildren?: false;
+} | {
+    allowChildren: true;
+    allowedChildBlocks?: string[];
+});
+type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
+type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
+    properties: TProps;
+};
+type SlugConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    root: string;
+    allowRoot?: boolean;
+    normalize?: boolean;
+    nested?: boolean;
+};
+type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition> = Record<string, AnyBlockDefinition>> = {
+    slug?: SlugConfig;
+    root: RootDefinition<TProps>;
+    blocks?: TBlocks;
+    label: string;
+    description?: string;
+    /**
+     * Marks this collection as one whose roots are meant to be EMBEDDED into other
+     * roots via a `reference` property (a "reusable block" library). Purely an
+     * ergonomic hint — it informs editor pickers and which endpoints to surface; it
+     * NEVER gates safety (the delete-in-use guard protects every referenced root
+     * regardless of this flag). Any collection can still be a reference target.
+     */
+    reusableBlock?: boolean;
+};
+type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
+type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {
+    name: string;
+    blocks: Record<string, AnyBlockDefinition>;
+};
+type DataRetentionConfig = {
+    keepDays: number;
+    keepMinCommits: number;
+    /**
+     * Grace period (days) before a soft-archived root (`archivedAt`) is physically
+     * hard-deleted by pruning. Defaults to `keepDays` when omitted — a trash
+     * window after which the page and its whole history are reclaimed.
+     */
+    archiveKeepDays?: number;
+};
+/**
+ * Subset of the incoming request forwarded to the authMiddleware.
+ * Available for all call styles (HTTP router and direct server-side calls).
+ */
+type CMSMiddlewareRequest = {
+    body?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    headers?: HeadersInit;
+    request?: Request;
+};
+/** Result that user middleware can return to extend context */
+type MiddlewareResult = {
+    userId?: string;
+    [key: string]: unknown;
+};
+/** Base ctx injected by withCMSContext middleware. */
+type CMSProcedureCtx = {
+    db: DrizzleInstance;
+    collections: Record<string, CollectionWithName>;
+    dataRetention?: DataRetentionConfig;
+    scopeConditions?: ScopeConditionFactory[];
+    notificationService?: NotificationService;
+    resolvedUser?: ResolvedUserConfig;
+};
+
+type SchemaNamespace = 'cms';
+type ColumnScalarType = 'text' | 'boolean' | 'integer' | 'timestamp' | 'jsonb' | 'tsvector';
+type ColumnType<EnumTarget extends string = string> = ColumnScalarType | {
+    enum: EnumTarget;
+};
+type DefaultValue = {
+    kind: 'literal';
+    value: boolean | number | string | string[] | Record<string, unknown>;
+} | {
+    kind: 'sql';
+    value: string;
+};
+type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+type IndexUsing = 'btree' | 'gin';
+type ColumnDefinition<ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    type: ColumnType<EnumTarget>;
+    columnName?: string;
+    notNull?: boolean;
+    primaryKey?: boolean;
+    unique?: boolean;
+    default?: DefaultValue;
+    defaultId?: boolean;
+    defaultIdPrefix?: string;
+    defaultNow?: boolean;
+    jsonType?: string;
+    references?: {
+        table: ReferenceTarget;
+        column: string;
+        onDelete?: ForeignKeyAction;
+        onUpdate?: ForeignKeyAction;
+    };
+};
+type TableColumns<ReferenceTarget extends string = string, EnumTarget extends string = string> = Record<string, ColumnDefinition<ReferenceTarget, EnumTarget>>;
+type IndexDefinition<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+    unique?: boolean;
+    using?: IndexUsing;
+    where?: string;
+};
+type CompositePrimaryKey<ColumnName extends string> = {
+    columns: readonly ColumnName[];
+};
+type TableLevelForeignKey<ColumnName extends string = string> = {
+    columns: readonly ColumnName[];
+    foreignTable: string;
+    foreignColumns: readonly string[];
+    name?: string;
+    onDelete?: ForeignKeyAction;
+    onUpdate?: ForeignKeyAction;
+};
+type TableDefinition<Columns extends TableColumns = TableColumns, ReferenceTarget extends string = string, EnumTarget extends string = string> = {
+    tableName?: string;
+    indexPrefix?: string;
+    columns: Columns;
+    indexes?: Record<string, IndexDefinition<Extract<keyof Columns, string>>>;
+    compositePrimaryKey?: CompositePrimaryKey<Extract<keyof Columns, string>>;
+    foreignKeys?: TableLevelForeignKey<Extract<keyof Columns, string>>[];
+};
+type EnumDefinition = {
+    values: readonly string[];
+    enumName?: string;
+};
+type EnumMap = Record<string, EnumDefinition>;
+type TableMap = Record<string, TableDefinition>;
+type SchemaModule<_Namespace extends SchemaNamespace = SchemaNamespace, Tables extends TableMap = {}, Enums extends EnumMap = {}, Extensions = {}> = {
+    enums?: Enums;
+    tables?: Tables;
+    extend?: Extensions;
+};
+
+type CMSPluginContext = CMSProcedureCtx & {
+    collections: Record<string, CollectionWithName>;
+};
+
+type CMSEndpointMeta = {
+    permissionResource?: string;
+    operation: CMSOperation;
+    scope: 'collection' | 'system';
+    collection?: string;
+    /**
+     * When `true`, this endpoint is intentionally exempt from the auth /
+     * permission / scope / hook chain — it handles its own access control
+     * (e.g. a public asset redirect). Every other endpoint must carry full
+     * `cms` metadata; `toCMSEndpoints` throws on a missing one (fail-closed).
+     */
+    public?: boolean;
+};
+
+/**
+ * Extends the core MiddlewareResult to require `language`. Use this to type your
+ * authMiddleware when the i18n plugin is active. `L` is the language union from
+ * the configured `languages` universe (e.g. 'en' | 'de').
+ *
+ * @example
+ * ```ts
+ * import { resolveLanguage } from '@createcms/core/plugins/i18n';
+ *
+ * authMiddleware: async (ctx): Promise<MultilingualMiddlewareResult<'en' | 'de'>> => {
+ *   const session = await getSession(ctx);
+ *   const language = resolveLanguage(ctx, session.locale) ?? 'en';
+ *   return { userId: session.userId, language };
+ * }
+ * ```
+ */
+type MultilingualMiddlewareResult<L extends string = string> = MiddlewareResult & {
+    language: L;
+};
+/**
+ * Resolves the active language from the incoming request context.
+ * Priority: body.language -> query.language -> fallback.
+ *
+ * The CMS is routing-agnostic: HOW you derive the language (URL prefix `/de`,
+ * domain, Accept-Language header, cookie) is the consumer's middleware concern.
+ * This helper only reads an explicit per-request override; pass the negotiated
+ * default as `fallback`.
+ */
+declare function resolveLanguage(ctx: {
+    request?: CMSMiddlewareRequest;
+}, fallback?: string): string | undefined;
+type I18nContext = {
+    language: string;
+    fallback: readonly string[];
+    languages: readonly string[];
+};
+/**
+ * Read the resolved i18n context (active language + fallback chain + configured
+ * universe) from a ResolvedScope. The plugin's own accessor for the OPAQUE
+ * `pluginContext.i18n` slot it stashes per request (Seam C); core never names
+ * i18n. Undefined when the i18n plugin did not scope the request.
+ */
+declare function getI18nContext(scope: ResolvedScope | undefined): I18nContext | undefined;
+/**
+ * i18n plugin config. `languages` is the static UNIVERSE of supported languages
+ * (a const tuple → a typed language union); `defaultLanguage` is the seed +
+ * fallback head and must be a member of the universe. Per-tenant activation of a
+ * SUBSET is a runtime concern handled by the consumer's middleware (it returns
+ * the active `language`); this plugin validates that the active language is in
+ * the universe. See I18N_DESIGN.md §7.
+ */
+type I18nConfig<L extends readonly string[]> = {
+    languages: L;
+    defaultLanguage: L[number];
+    /**
+     * Per-language fallback chains (ordered languages to try AFTER the active one
+     * when a translation is missing). `default` is the catch-all for languages not
+     * listed; absent → every language falls back to `defaultLanguage`. An explicit
+     * empty array opts a language OUT of any fallback (`{ de: [] }` → a missing `de`
+     * translation stays unresolved rather than falling back). Example:
+     * `{ default: ['en'], 'fr-CA': ['fr', 'en'] }`.
+     */
+    fallback?: Partial<Record<L[number] | 'default', readonly L[number][]>>;
+};
+declare function i18n<const L extends readonly string[]>(config: I18nConfig<L>): {
+    id: "i18n";
+    schema: SchemaModule<"cms", {}, {}, {}>;
+    $ERROR_CODES: {
+        readonly LANGUAGE_REQUIRED: {
+            readonly status: 400;
+            readonly message: "language is required -- authMiddleware must return { language } when the i18n plugin is active";
+        };
+        readonly LANGUAGE_NOT_ENABLED: {
+            readonly status: 400;
+            readonly message: "the resolved language is not one of the configured i18n languages";
+        };
+        readonly TRANSLATION_SOURCE_NOT_FOUND: {
+            readonly status: 404;
+            readonly message: "Translation source root not found in this collection / active language";
+        };
+        readonly TRANSLATION_EXISTS: {
+            readonly status: 409;
+            readonly message: "A translation in the target language already exists for this entry";
+        };
+        readonly TRANSLATION_PARENT_NOT_TRANSLATED: {
+            readonly status: 409;
+            readonly message: "The parent has no translation in the target language — translate the parent first";
+        };
+        readonly TRANSLATION_LANGUAGE_NOT_ENABLED: {
+            readonly status: 400;
+            readonly message: "targetLanguage is not one of the configured i18n languages";
+        };
+    };
+    collectionEndpoints: (def: CollectionWithName, ctx: CMSPluginContext) => {
+        /**
+         * Creates a sibling-language version of an existing entry, inheriting its translation key and seeding from the source's main tree (or blank).
+         * @param sourceRootId The root to translate from (must exist in the active language).
+         * @param targetLanguage The language for the new root (must be configured in the plugin).
+         * @param targetSlug Optional slug for the target root; defaults to the source slug if not provided.
+         * @param seed How to initialize the target root's draft: 'copy' (default) copies the source's main tree, 'blank' starts empty.
+         * @param message Optional commit message for the initial draft; defaults to 'Translation (language)'.
+         * @returns The new root id, draft branch id, initial commit id, target language, and inherited translation key.
+         * @throws TRANSLATION_LANGUAGE_NOT_ENABLED if targetLanguage is not in the configured language universe.
+         * @throws TRANSLATION_SOURCE_NOT_FOUND if sourceRootId does not exist in the active language/tenant.
+         * @throws TRANSLATION_EXISTS if a translation to targetLanguage already exists for this entry.
+         * @throws TRANSLATION_PARENT_NOT_TRANSLATED if the source has a parent that has no translation in the target language.
+         * @throws SLUG_EMPTY_NOT_ALLOWED if the target slug is empty and the collection disallows root slugs.
+         * @example await cmsClient.pages.createTranslation({ sourceRootId: 'root_abc', targetLanguage: 'de', seed: 'copy' })
+         */
+        createTranslation: better_call.Endpoint<`/${string}/createTranslation`, "POST", {
+            sourceRootId: string;
+            targetLanguage: string;
+            targetSlug?: string;
+            seed?: "copy" | "blank";
+            message?: string;
+        }, Record<string, any> | undefined, [], {
+            rootId: string;
+            branchId: string;
+            commitId: string;
+            language: string;
+            translationKey: string;
+        }, {
+            $Infer: {
+                body: {
+                    sourceRootId: string;
+                    targetLanguage: string;
+                    targetSlug?: string;
+                    seed?: "copy" | "blank";
+                    message?: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+        /**
+         * Retrieves all language variants (siblings) of a given entry, bypassing per-language read scope.
+         * @param rootId The root id (must exist in the active language and tenant).
+         * @returns The translation key (group id) and an array of all siblings with their language, root id, slug, and resolved path.
+         * @throws TRANSLATION_SOURCE_NOT_FOUND if rootId does not exist or has no translation key.
+         * @example await cmsClient.pages.listTranslations({ rootId: 'root_abc' })
+         */
+        listTranslations: better_call.Endpoint<`/${string}/listTranslations`, "GET", undefined, {
+            rootId: string;
+        }, [], {
+            translationKey: string;
+            translations: {
+                language: string;
+                rootId: string;
+                slug: string | null;
+                path: string | null;
+            }[];
+        }, {
+            $Infer: {
+                query: {
+                    rootId: string;
+                };
+            };
+            cms: CMSEndpointMeta;
+        }, undefined>;
+    };
+    init(_ctx: CMSPluginContext): {
+        context: {
+            scopeConditions: ScopeConditionFactory[];
+        };
+    };
+};
+
+export { getI18nContext, i18n, resolveLanguage };
+export type { I18nConfig, I18nContext, MultilingualMiddlewareResult };