@zenith-open/zenithcms-types 0.1.0

package/dist/database.d.ts

@@ -0,0 +1,111 @@
+import { CollectionConfig } from './index';
+/**
+ * Zenith Database Adapter Contract
+ * ────────────────────────────────
+ * Hardened interface for database agnostic operations.
+ * Use generics <T> to ensure type safety in higher level services.
+ */
+export interface DatabaseAdapter {
+    name: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getHealth(): 'ok' | 'connecting' | 'disconnected' | 'error';
+    /** Syncs the provided collection config with the physical DB schema */
+    registerCollection(config: CollectionConfig): Promise<void>;
+    /** Lists all existing collections/tables in the database */
+    getExistingCollections(): Promise<string[]>;
+    find<T = unknown>(collection: string, query: Record<string, unknown>, options?: FindOptions): Promise<T[]>;
+    findOne<T = unknown>(collection: string, query: Record<string, unknown>, options?: BaseOptions): Promise<T | null>;
+    create<T = unknown>(collection: string, data: Partial<T>, options?: BaseOptions): Promise<T>;
+    update<T = unknown>(collection: string, id: string, data: Partial<T>, options?: BaseOptions): Promise<T | null>;
+    updateMany(collection: string, query: Record<string, unknown>, data: unknown, options?: BaseOptions): Promise<number>;
+    delete(collection: string, id: string, options?: BaseOptions): Promise<boolean>;
+    deleteMany(collection: string, query: Record<string, unknown>, options?: BaseOptions): Promise<number>;
+    count(collection: string, query: Record<string, unknown>): Promise<number>;
+    aggregate<T = unknown>(collection: string, pipeline: unknown[], options?: BaseOptions): Promise<T[]>;
+    /**
+     * Atomically finds a single document and updates it, returning either
+     * the original (returnDocument: 'before') or updated (returnDocument: 'after') document.
+     * Returns null if no document matches the query.
+     */
+    findOneAndUpdate<T = unknown>(collection: string, query: Record<string, unknown>, update: Record<string, unknown>, options?: BaseOptions & {
+        returnDocument?: 'before' | 'after';
+    }): Promise<T | null>;
+    /**
+     * Executes multiple operations in a transaction.
+     * If the adapter does not support transactions (e.g. standalone Mongo),
+     * this will execute the function without a transaction context.
+     */
+    transaction<T>(fn: (session: unknown) => Promise<T>): Promise<T>;
+    createAuditLog(data: AuditLogData, options?: BaseOptions): Promise<void>;
+    createVersion(data: VersionData, options?: BaseOptions): Promise<void>;
+    getVersions(collection: string, documentId: string): Promise<VersionData[]>;
+    createWebhookDelivery(data: WebhookDeliveryData): Promise<void>;
+    getWebhookDeliveries(webhookId: string, limit?: number): Promise<WebhookDeliveryRecord[]>;
+    /**
+     * Full-text / pattern search across specified fields in a collection.
+     * Each adapter translates this into its native search primitive
+     * (MongoDB $regex/$text, Postgres ILIKE/pg_trgm).
+     */
+    search<T = unknown>(collection: string, query: string, fields: string[], limit?: number, options?: BaseOptions): Promise<T[]>;
+}
+export interface BaseOptions {
+    session?: unknown;
+    tenantId?: string;
+    siteId?: string;
+    expectedVersion?: number;
+}
+export interface FindOptions extends BaseOptions {
+    sort?: string | Record<string, unknown>;
+    skip?: number;
+    limit?: number;
+    select?: string | string[];
+    populate?: string | string[];
+}
+export interface AuditLogData {
+    userId: string;
+    userEmail: string;
+    userName?: string;
+    action: string;
+    collectionName: string;
+    documentId?: string;
+    changes?: unknown;
+    ip?: string;
+    userAgent?: string;
+    timestamp?: Date;
+    status?: 'success' | 'failed';
+    resource?: string;
+    siteId?: string;
+    hash?: string;
+    previousHash?: string;
+}
+export interface VersionData {
+    collectionName: string;
+    collectionSlug: string;
+    documentId: string;
+    snapshot: unknown;
+    delta?: unknown;
+    createdBy: string;
+    timestamp: Date;
+}
+export interface WebhookDeliveryData {
+    webhookId?: string;
+    collectionSlug?: string;
+    event: string;
+    url: string;
+    payload?: unknown;
+    success: boolean;
+    responseStatus?: number;
+    timestamp?: Date;
+}
+export interface WebhookDeliveryRecord {
+    id: string;
+    webhookId?: string;
+    collectionSlug?: string;
+    event: string;
+    url: string;
+    payload?: unknown;
+    success: boolean;
+    responseStatus?: number;
+    timestamp: Date | string;
+}

package/dist/database.js

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

package/dist/database.js.map

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

package/dist/generated.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Zenith Auto-Generated TypeScript Definitions
+ * This file is automatically re-compiled on database register & boot.
+ * DO NOT MODIFY MANUALLY.
+ */
+export interface ZenithDocument {
+    _id: string;
+    createdAt: string;
+    updatedAt: string;
+    status?: 'draft' | 'published' | 'archived' | string;
+}
+export interface Authors extends ZenithDocument {
+    name: string;
+    avatar?: {
+        url: string;
+        alt?: string;
+    };
+    bio?: string;
+}
+export interface Posts extends ZenithDocument {
+    title: string;
+    coverImage?: {
+        url: string;
+        alt?: string;
+    };
+    content?: string;
+    publishedAt?: string | Date;
+    author?: Record<string, unknown>;
+}
+export interface Categories extends ZenithDocument {
+    title: string;
+    slug: string;
+}
+export interface Products extends ZenithDocument {
+    name: string;
+    slug: string;
+    price: number;
+    description?: string;
+    gallery?: {
+        image?: {
+            url: string;
+            alt?: string;
+        };
+    }[];
+    inStock?: boolean;
+}
+export interface Pages extends ZenithDocument {
+    title: string;
+    slug: string;
+    layout?: ({
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    } | {
+        blockType: 'undefined';
+    })[];
+}
+export interface AuditTarget1781217670604 extends ZenithDocument {
+    title: string;
+}
+export interface Media extends ZenithDocument {
+    name?: string;
+    url?: string;
+    alt?: string;
+    folder?: string;
+    mimetype?: string;
+    size?: number;
+}
+export interface SiteSettings extends ZenithDocument {
+    siteName: string;
+    supportEmail?: string;
+    logo?: {
+        url: string;
+        alt?: string;
+    };
+    favicon?: {
+        url: string;
+        alt?: string;
+    };
+    primaryColor?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    ogImage?: {
+        url: string;
+        alt?: string;
+    };
+    socialLinks?: {
+        platform?: ('Twitter' | 'Instagram' | 'Facebook' | 'LinkedIn' | 'GitHub' | 'YouTube');
+        url?: string;
+    }[];
+    copyrightText?: string;
+    headerLinks?: {
+        label: string;
+        url: string;
+    }[];
+    footerLinks?: {
+        label: string;
+        url: string;
+    }[];
+}
+export interface ZenithCollections {
+    'authors': Authors;
+    'posts': Posts;
+    'categories': Categories;
+    'products': Products;
+    'pages': Pages;
+    'audit-target-1781217670604': AuditTarget1781217670604;
+    'media': Media;
+    'site-settings': SiteSettings;
+}
+/**
+ * Fully Typed React SDK Data Hook Mappings
+ */
+export type ZenithQuery<T> = {
+    where?: Record<string, any>;
+    sort?: string | Record<string, any>;
+    limit?: number;
+    skip?: number;
+    select?: string[];
+    populate?: string[];
+    locale?: string;
+};

package/dist/generated.js

@@ -0,0 +1,7 @@
+/**
+ * Zenith Auto-Generated TypeScript Definitions
+ * This file is automatically re-compiled on database register & boot.
+ * DO NOT MODIFY MANUALLY.
+ */
+export {};
+//# sourceMappingURL=generated.js.map

package/dist/generated.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Zenith CMS — Core Type System
+ * ─────────────────────────────
+ * Strictly typed configuration schema for collections, fields, and plugins.
+ * Uses Discriminated Unions for robust field-level validation and IntelliSense.
+ */
+import type React from 'react';
+export interface ZenithDocument {
+    _id?: string;
+    id?: string;
+    siteId?: string | null;
+    _status?: 'draft' | 'published' | string;
+    _version?: number;
+    workflowStatus?: string;
+    deletedAt?: Date | null;
+    [key: string]: unknown;
+}
+export type FieldType = 'text' | 'number' | 'email' | 'textarea' | 'checkbox' | 'date' | 'select' | 'media' | 'richtext' | 'json' | 'group' | 'tabs' | 'array' | 'relation' | 'blocks' | 'boolean' | 'code' | 'collapsible' | 'join' | 'point' | 'radio' | 'row' | 'ui' | 'dz';
+export interface BlockDefinition {
+    slug: string;
+    labels?: {
+        singular: string;
+        plural: string;
+    };
+    fields: FieldConfig[];
+    admin?: {
+        description?: string;
+        icon?: string;
+        imageURL?: string;
+        category?: string;
+    };
+}
+export interface FieldAdminConfig {
+    placeholder?: string;
+    description?: string;
+    hidden?: boolean;
+    readOnly?: boolean;
+    width?: string;
+    condition?: (data: unknown, siblingData: unknown) => boolean;
+    readAccess?: string[];
+    writeAccess?: string[];
+}
+export interface BaseFieldConfig {
+    name: string;
+    label?: string;
+    required?: boolean;
+    unique?: boolean;
+    localized?: boolean;
+    virtual?: boolean;
+    defaultValue?: unknown;
+    admin?: FieldAdminConfig;
+    hooks?: {
+        beforeChange?: (value: unknown) => unknown | Promise<unknown>;
+        afterRead?: (value: unknown) => unknown | Promise<unknown>;
+        validate?: (value: unknown, data: unknown) => boolean | string | Promise<boolean | string>;
+    };
+    access?: {
+        read?: (user: unknown) => boolean;
+        update?: (user: unknown) => boolean;
+        create?: (user: unknown) => boolean;
+    };
+}
+export interface TextFieldConfig extends BaseFieldConfig {
+    type: 'text' | 'email' | 'textarea' | 'password' | 'uid' | 'color';
+    minLength?: number;
+    maxLength?: number;
+}
+export interface NumberFieldConfig extends BaseFieldConfig {
+    type: 'number';
+    min?: number;
+    max?: number;
+}
+export interface CheckboxFieldConfig extends BaseFieldConfig {
+    type: 'checkbox' | 'boolean';
+}
+export interface SelectFieldConfig extends BaseFieldConfig {
+    type: 'select';
+    options: (string | {
+        label: string;
+        value: string;
+    })[];
+    hasMany?: boolean;
+}
+export interface MediaFieldConfig extends BaseFieldConfig {
+    type: 'media';
+    hasMany?: boolean;
+    options?: {
+        focalPoint?: boolean;
+        blurhash?: boolean;
+        responsive?: boolean;
+    };
+}
+export type OnDeletePolicy = 'SET_NULL' | 'CASCADE' | 'RESTRICT' | 'NO_ACTION';
+export interface RelationFieldConfig extends BaseFieldConfig {
+    type: 'relation';
+    relationTo: string | string[];
+    hasMany?: boolean;
+    junctionTable?: string;
+    pivotFields?: FieldConfig[];
+    onDelete?: OnDeletePolicy;
+}
+export interface ArrayFieldConfig extends BaseFieldConfig {
+    type: 'array';
+    fields: FieldConfig[];
+    minRows?: number;
+    maxRows?: number;
+}
+export interface GroupFieldConfig extends BaseFieldConfig {
+    type: 'group';
+    fields: FieldConfig[];
+}
+export interface BlocksFieldConfig extends BaseFieldConfig {
+    type: 'blocks';
+    blocks: BlockDefinition[];
+}
+export interface RichTextFieldConfig extends BaseFieldConfig {
+    type: 'richtext';
+    format?: 'html' | 'json';
+}
+export interface BasicFieldConfig extends BaseFieldConfig {
+    type: 'date' | 'json';
+}
+export interface CodeFieldConfig extends BaseFieldConfig {
+    type: 'code';
+    language?: string;
+    minLength?: number;
+    maxLength?: number;
+}
+export interface CollapsibleFieldConfig extends BaseFieldConfig {
+    type: 'collapsible';
+    fields: FieldConfig[];
+    initCollapsed?: boolean;
+}
+export interface JoinFieldConfig extends Omit<BaseFieldConfig, 'required'> {
+    type: 'join';
+    collection: string | string[];
+    on: string;
+    maxDepth?: number;
+    where?: Record<string, unknown>;
+    defaultLimit?: number;
+    defaultSort?: string;
+}
+export interface PointFieldConfig extends BaseFieldConfig {
+    type: 'point';
+}
+export interface RadioFieldConfig extends BaseFieldConfig {
+    type: 'radio';
+    options: (string | {
+        label: string;
+        value: string;
+    })[];
+    layout?: 'horizontal' | 'vertical';
+}
+export interface RowFieldConfig extends Omit<BaseFieldConfig, 'required' | 'unique' | 'localized' | 'virtual' | 'defaultValue' | 'admin' | 'hooks' | 'access'> {
+    type: 'row';
+    fields: FieldConfig[];
+    admin?: {
+        className?: string;
+    };
+}
+export interface UIFieldConfig extends Omit<BaseFieldConfig, 'required' | 'unique' | 'localized' | 'virtual' | 'defaultValue' | 'hooks' | 'access'> {
+    type: 'ui';
+    admin?: {
+        components?: {
+            Field?: React.ComponentType<unknown>;
+        };
+        condition?: (data: unknown, siblingData: unknown) => boolean;
+    };
+}
+export interface DZFieldConfig extends BaseFieldConfig {
+    type: 'dz';
+    /** List of available component types (block slugs) for this dynamic zone */
+    components?: string[];
+}
+export type FieldConfig = TextFieldConfig | NumberFieldConfig | CheckboxFieldConfig | SelectFieldConfig | MediaFieldConfig | RelationFieldConfig | ArrayFieldConfig | GroupFieldConfig | BlocksFieldConfig | RichTextFieldConfig | BasicFieldConfig | CodeFieldConfig | CollapsibleFieldConfig | JoinFieldConfig | PointFieldConfig | RadioFieldConfig | RowFieldConfig | UIFieldConfig | DZFieldConfig;
+export interface CollectionConfig {
+    name: string;
+    slug: string;
+    labels?: {
+        singular: string;
+        plural: string;
+    };
+    fields: FieldConfig[];
+    drafts?: boolean;
+    seo?: boolean;
+    timestamps?: boolean;
+    singleton?: boolean;
+    versions?: boolean;
+    maxVersions?: number;
+    scheduling?: boolean;
+    publicRead?: boolean;
+    softDelete?: boolean;
+    hooks?: {
+        beforeValidate?: (data: unknown, user: unknown, context: {
+            hookType: string;
+        }) => unknown | Promise<unknown>;
+        beforeCreate?: (data: unknown, user: unknown, context: {
+            hookType: string;
+        }) => unknown | Promise<unknown>;
+        afterCreate?: (doc: unknown, user: unknown, context: {
+            hookType: string;
+        }) => void | Promise<void>;
+        beforeUpdate?: (data: unknown, user: unknown, context: {
+            hookType: string;
+        }) => unknown | Promise<unknown>;
+        afterUpdate?: (doc: unknown, user: unknown, context: {
+            hookType: string;
+        }) => void | Promise<void>;
+        beforeDelete?: (id: string, user: unknown, context: {
+            hookType: string;
+        }) => void | Promise<void>;
+        afterDelete?: (id: string, user: unknown, context: {
+            hookType: string;
+        }) => void | Promise<void>;
+        afterRead?: (doc: unknown, user: unknown, context: {
+            hookType: string;
+        }) => unknown | Promise<unknown>;
+        afterError?: (error: Error, data: unknown, user: unknown) => void | Promise<void>;
+    };
+    access?: {
+        /** Return false to deny, or an object to merge as query constraints (Row-Level Security). */
+        read?: (user: unknown, context?: {
+            req?: unknown;
+        }) => boolean | object;
+        /** Return false to deny, or an object to constrain which documents the user may create. */
+        create?: (user: unknown, context?: {
+            req?: unknown;
+        }) => boolean;
+        /** Return false to deny, or an object to constrain which documents the user may update. */
+        update?: (user: unknown, context?: {
+            req?: unknown;
+        }) => boolean | object;
+        /** Return false to deny, or an object to constrain which documents the user may delete. */
+        delete?: (user: unknown, context?: {
+            req?: unknown;
+        }) => boolean | object;
+    };
+    admin?: {
+        group?: string;
+        hidden?: boolean;
+        useAsTitle?: string;
+        displayTemplate?: string;
+        defaultColumns?: string[];
+        icon?: string;
+        previewUrl?: string | ((doc: unknown) => string);
+    };
+    endpoints?: {
+        path: string;
+        method: 'get' | 'post' | 'put' | 'delete' | 'patch';
+        handler: (req: unknown, res: unknown) => void | Promise<void>;
+    }[];
+}
+export type GlobalConfig = CollectionConfig;
+export interface ZenithPlugin {
+    /** Unique identifier (slug). Use reverse-domain notation: `zenith-seo`, `acme-analytics` */
+    id: string;
+    /** Display name shown in admin UI */
+    name: string;
+    version?: string;
+    description?: string;
+    author?: string;
+    /** Plugin home page / documentation URL */
+    homepage?: string;
+    /** NPM package name if installable via package manager */
+    packageName?: string;
+    downloads?: number;
+    /** Minimum Zenith engine version required */
+    minEngineVersion?: string;
+    /** Other plugin IDs this plugin depends on */
+    dependencies?: string[];
+    /** Whether the plugin is active. Disabled plugins are not applied. */
+    enabled?: boolean;
+    /**
+     * JSON Schema for plugin configuration options.
+     * Used by the admin UI to render a settings form.
+     */
+    configSchema?: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'url' | 'secret';
+        label: string;
+        description?: string;
+        default?: unknown;
+        options?: Array<{
+            label: string;
+            value: string;
+        }>;
+        required?: boolean;
+    }>;
+    /** Runtime config values (set by admin UI) */
+    config?: Record<string, unknown>;
+    /**
+     * Transform the CMS config (add collections, fields, hooks, etc.).
+     * Called at engine bootstrap for each enabled plugin.
+     */
+    apply: (config: CMSConfig, pluginConfig?: Record<string, unknown>) => CMSConfig | void;
+    /** Called after all plugins are applied, before routes are mounted */
+    onInit?: (ctx: PluginContext) => void | Promise<void>;
+    /** Called after the engine is fully started and listening */
+    onReady?: (ctx: PluginContext) => void | Promise<void>;
+    /** Called when the engine is shutting down */
+    onDestroy?: (ctx: PluginContext) => void | Promise<void>;
+}
+export interface PluginContext {
+    /** Express application instance */
+    app: unknown;
+    /** Active database adapter */
+    adapter: unknown;
+    /** Current CMS config (after all plugins applied) */
+    config: CMSConfig;
+    /** Hook registry — use to register lifecycle hooks */
+    hooks: {
+        on: <T = unknown>(hook: string, handler: (payload: T) => T | Promise<T> | void, priority?: number) => () => void;
+        emit: (hook: string, payload: unknown) => Promise<void>;
+    };
+    /** Register admin UI components */
+    admin: {
+        registerComponent: (slot: string, component: {
+            id: string;
+            label: string;
+            icon?: string;
+        }) => void;
+    };
+    /** Logger instance */
+    logger: {
+        info: (msg: string, meta?: Record<string, unknown>) => void;
+        warn: (msg: string, meta?: Record<string, unknown>) => void;
+        error: (msg: string, meta?: Record<string, unknown>) => void;
+        debug: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+}
+export type DeploymentProvider = 'cloudflare' | 'netlify' | 'vercel' | 'custom';
+export interface DeploymentConfig {
+    provider: DeploymentProvider;
+    hookUrl: string;
+    triggerOn?: string[];
+    autoTrigger?: boolean;
+}
+export interface WebhookTarget {
+    url: string;
+    events: string[];
+    secret?: string;
+}
+export interface CMSConfig {
+    collections: CollectionConfig[];
+    globals?: GlobalConfig[];
+    plugins?: ZenithPlugin[];
+    webhooks?: WebhookTarget[];
+    deployment?: DeploymentConfig;
+    cors?: {
+        origins: string[];
+    };
+}
+export * from './generated';
+export * from './database';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Zenith CMS — Core Type System
+ * ─────────────────────────────
+ * Strictly typed configuration schema for collections, fields, and plugins.
+ * Uses Discriminated Unions for robust field-level validation and IntelliSense.
+ */
+export * from './generated';
+export * from './database';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmXH,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@zenith-open/zenithcms-types",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "lint": "echo 'Lint bypassed for types'"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}