opacacms 0.2.0 → 0.3.0

package/dist/types.d.ts

@@ -1,8 +1,9 @@
-import type { z } from "zod";
+import type { Faker } from "@faker-js/faker";
 import type { Session as BetterAuthSession, User as BetterAuthUser, Prettify } from "better-auth";
 import type { Context } from "hono";
 import type { icons } from "lucide-react";
-import type { AdminConfig, CollectionHooks, FieldType, AccessConfig as ValidationAccessConfig } from "./validation";
+import type { z } from "zod";
+import type { AdminConfig, FieldType } from "./validation";
 export type { FieldType };
 export type Session = BetterAuthSession;
 export type User = Prettify<BetterAuthUser & {
@@ -11,53 +12,95 @@ export type User = Prettify<BetterAuthUser & {
     banReason?: string | null;
     bannedUntil?: Date | null;
 }>;
-export type IconName = keyof typeof icons;
+export type LucideIcons = keyof typeof icons;
+/**
+ * Base properties shared by all field types in OpacaCMS.
+ */
 export interface BaseField {
+    /** The unique identifier for the field within the collection. Used as the database column name. */
     name: string;
+    /** The human-readable label displayed in the Admin UI. */
     label?: string;
+    /** Informational text displayed inside the input field when empty. */
     placeholder?: string;
+    /** Whether the field is required to have a value. */
     required?: boolean;
+    /** Whether the field's value must be unique across all records in the collection. */
     unique?: boolean;
+    /** Whether the field supports localized values (multi-language). */
     localized?: boolean;
+    /** The default value assigned to the field when a new record is created. */
     defaultValue?: unknown;
+    /** Custom validation logic or Zod schema for the field. */
     validate?: ((value: unknown) => boolean | string) | z.ZodTypeAny;
+    /** Access control configuration for this specific field. */
     access?: FieldAccessConfig;
+    /** Configuration for the Admin UI representation of the field. */
     admin?: {
+        /** Optional description displayed below the field in the Admin UI. */
         description?: string;
+        /** Logical condition that determines if the field should be visible in the Admin UI. */
         condition?: (data: Record<string, unknown>, siblingData: Record<string, unknown>) => boolean;
+        /** Logical condition that determines if the field should be marked as required in the Admin UI. */
+        requiredCondition?: (data: Record<string, unknown>, siblingData: Record<string, unknown>) => boolean;
+        /** If true, the field is hidden from the Admin UI forms but still accessible via API. */
         hidden?: boolean;
+        /** If true, the field is visible but cannot be edited in the Admin UI. */
         readOnly?: boolean;
+        /** The preferred width of the field in the Admin UI grid (e.g., '50%', '33%'). */
         width?: string;
+        /** Custom CSS styles for the field's container in the Admin UI. */
         style?: any;
+        /** Additional CSS class names for the field's container. */
         className?: string;
+        /** Custom UI components to override the default field and cell rendering. */
         components?: {
+            /** Path or name of a custom React component for the field input. */
             Field?: string;
+            /** Path or name of a custom React component for the table cell. */
             Cell?: string;
         };
+        /** Arbitrary props passed to the custom field component. */
         customProps?: Record<string, unknown>;
     };
+    /** Deprecated: Use admin.requiredCondition instead. */
+    requiredCondition?: (data: any) => boolean;
+    /** Deprecated: Use admin.condition instead. */
+    condition?: (data: any) => boolean;
+    /** Database reference configuration for foreign keys. */
     references?: {
+        /** Target table/collection name. */
         table: string;
+        /** Target column name (usually 'id'). */
         column: string;
+        /** Referential integrity action on record deletion. */
         onDelete?: "cascade" | "set null" | "restrict" | "no action";
     };
 }
+/** A simple single-line text input field. */
 export interface TextField extends BaseField {
     type: "text";
 }
+/** A URL-friendly string field, often generated from another field. */
 export interface SlugField extends BaseField {
     type: "slug";
+    /** The field name to generate the slug from (e.g., 'title'). */
     from: string;
+    /** Custom function to format the slug value. */
     format?: (value: string) => string;
 }
 export interface TextAreaField extends BaseField {
     type: "textarea";
 }
+/** A numeric input field with optional constraints. */
 export interface NumberField extends BaseField {
     type: "number";
     options?: {
+        /** Minimum allowed value. */
         min?: number;
+        /** Maximum allowed value. */
         max?: number;
+        /** Stepping interval for the numeric input. */
         step?: number;
         [key: string]: any;
     };
@@ -69,15 +112,21 @@ export interface RichTextField extends BaseField {
         [key: string]: any;
     };
 }
+/** A field for linking records from another collection. */
 export interface RelationshipField extends BaseField {
     type: "relationship";
+    /** The slug of the target collection to relate to. */
     relationTo: string;
+    /** If true, allows selecting multiple related records. */
     hasMany?: boolean;
+    /** The field from the target collection to use as the display label. */
     displayField?: string;
 }
+/** A dropdown or multi-select field with predefined choices. */
 export interface SelectField extends BaseField {
     type: "select";
     options?: {
+        /** The list of available options. Can be simple strings or label/value objects. */
         choices: (string | {
             label: string;
             value: string;
@@ -85,9 +134,11 @@ export interface SelectField extends BaseField {
         [key: string]: any;
     };
 }
+/** A set of radio buttons for selecting a single option from a list. */
 export interface RadioField extends BaseField {
     type: "radio";
     options: {
+        /** The list of available options. */
         choices: (string | {
             label: string;
             value: string;
@@ -98,9 +149,11 @@ export interface RadioField extends BaseField {
 export interface DateField extends BaseField {
     type: "date";
 }
+/** A simple true/false toggle or checkbox field. */
 export interface BooleanField extends BaseField {
     type: "boolean";
     options?: {
+        /** How to render the field in the Admin UI. */
         display?: "switch" | "toggle" | "checkbox" | "select";
         [key: string]: unknown;
     };
@@ -108,65 +161,98 @@ export interface BooleanField extends BaseField {
 export interface JSONField extends BaseField {
     type: "json";
 }
+/** A field for uploading and managing files. */
 export interface FileField extends BaseField {
     type: "file";
+    /** The storage bucket to use for this field. */
     bucket?: string;
     options?: {
+        /** Allowed MIME types (e.g., ['image/jpeg', 'application/pdf']). */
         allowedmime_types?: string[];
+        /** Maximum file size in bytes. */
         maxFileSize?: number;
+        /** Additional metadata fields to store alongside the file. */
         metaFields?: Field[];
         [key: string]: unknown;
     };
 }
+/** A dynamic field that allows users to add multiple blocks of different types. */
 export interface BlocksField extends BaseField {
     type: "blocks";
+    /** The list of available block types for this field. */
     blocks: {
+        /** Unique identifier for the block type. */
         slug: string;
+        /** The fields that compose this block. */
         fields: Field[];
+        /** Human-readable label for the block type. */
         label?: string;
     }[];
 }
+/** A logical grouping of fields. If a name is provided, the data will be nested under that key. */
 export interface GroupField extends BaseField {
     type: "group";
+    /** The fields that belong to this group. */
     fields: Field[];
 }
+/** A layout field that renders its children in a single horizontal row. */
 export interface RowField extends Omit<BaseField, "name"> {
     type: "row";
+    /** Optional name. If provided, the row's data will be nested. */
     name?: string;
+    /** The fields to render in this row. */
     fields: Field[];
+    /** Optional label for the row header. */
     label?: string;
 }
+/** A layout field that allows sections to be expanded or collapsed. */
 export interface CollapsibleField extends Omit<BaseField, "name"> {
     type: "collapsible";
+    /** Optional name. If provided, the data will be nested. */
     name?: string;
+    /** The human-readable label for the collapsible header. */
     label: string;
+    /** The fields to render inside the collapsible section. */
     fields: Field[];
     options?: {
+        /** Whether the section starts collapsed or expanded. */
         initiallyCollapsed?: boolean;
-        useAsTitle?: string;
         [key: string]: any;
     };
 }
+/** A field that allows users to add multiple instances of a set of fields. */
 export interface ArrayField extends BaseField {
     type: "array";
+    /** The fields that each array item will contain. */
     fields: Field[];
 }
+/** A layout field that organizes child fields into clickable tabs. */
 export interface TabsField extends Omit<BaseField, "name"> {
     type: "tabs";
+    /** Optional name. If provided, the data will be nested. */
     name?: string;
+    /** The list of tabs to render. */
     tabs: {
+        /** The human-readable label for the tab. */
         label: string;
+        /** The fields to render within this tab. */
         fields: Field[];
     }[];
 }
+/** A field that allows joining data from another collection based on a shared key. */
 export interface JoinField extends Omit<BaseField, "name"> {
     type: "join";
+    /** Optional name for the join mapping. */
     name?: string;
+    /** The slug of the target collection to join with. */
     collection: string;
+    /** The field name on the target collection to join on. */
     on: string;
 }
+/** A read-only field whose value is computed dynamically at runtime. */
 export interface VirtualField extends BaseField {
     type: "virtual";
+    /** Function to resolve the field's value. */
     resolve: (args: {
         data: any;
         req: any;
@@ -174,6 +260,7 @@ export interface VirtualField extends BaseField {
         session: Session;
         apiKey?: ApiKey;
     }) => any | Promise<any>;
+    /** The data type of the resolved value. */
     returnType?: "string" | "number" | "boolean" | "json";
 }
 export interface UIField extends BaseField {
@@ -191,8 +278,20 @@ export interface AccessArgs {
     user: User | null;
     session: Session | null;
     apiKey?: ApiKey | null;
-    data?: unknown;
-    operation?: "read" | "create" | "update" | "delete";
+    data?: any;
+    id?: string;
+    operation: "read" | "create" | "update" | "delete";
+}
+export interface CollectionHookArgs<T = any> {
+    req: Context;
+    user: User | null;
+    session: Session | null;
+    apiKey?: ApiKey | null;
+    data: T;
+    originalDoc?: T;
+    query?: any;
+    id?: string;
+    operation: "create" | "update" | "delete";
 }
 export interface FieldAccessConfig {
     /** If true, the field is removed from API and UI. */
@@ -202,35 +301,98 @@ export interface FieldAccessConfig {
     /** If true, the input is visually disabled. */
     disabled?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
 }
-export interface AccessConfig extends Omit<ValidationAccessConfig, "read" | "create" | "update" | "delete"> {
+export interface AccessConfig {
     read?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
     create?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
     update?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
     delete?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
-}
-export type { CollectionHooks };
-export interface Collection {
+    requireApiKey?: boolean;
+}
+export interface CollectionHooks<T = any> {
+    beforeCreate?: (args: CollectionHookArgs<T>) => T | Promise<T> | void;
+    afterCreate?: (args: CollectionHookArgs<T>) => void | Promise<void>;
+    beforeUpdate?: (args: CollectionHookArgs<T>) => T | Promise<T> | void;
+    afterUpdate?: (args: CollectionHookArgs<T>) => void | Promise<void>;
+    beforeDelete?: (args: CollectionHookArgs<T>) => void | Promise<void>;
+    afterDelete?: (args: CollectionHookArgs<T>) => void | Promise<void>;
+}
+/** Configuration for an outgoing webhook triggered by CMS events. */
+export interface OutgoingWebhookConfig<T = any> {
+    /** Outgoing webhooks are triggered by CMS events like 'after:create'. */
+    type: "outgoing";
+    /** The list of events that trigger this webhook. */
+    events: Array<"after:create" | "after:update" | "after:delete">;
+    /** The destination URL for the webhook payload. */
+    url: string;
+    /** Optional custom HTTP headers to include in the request. */
+    headers?: Record<string, string>;
+    /** Number of retry attempts in case of failure (uses exponential backoff). */
+    retries?: number;
+    /** Request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Function to reshape the payload data before sending. */
+    transform?: (data: T) => any;
+}
+/** Configuration for an incoming webhook providing a public API endpoint. */
+export interface IncomingWebhookConfig<T = any> {
+    /** Incoming webhooks provide a public endpoint for third-party integrations (e.g., Stripe). */
+    type: "incoming";
+    /** The public URL path where OpacaCMS will listen for requests. */
+    path: string;
+    /** Secret or function used to verify the request signature (HMAC-SHA256). */
+    verifySignature?: string | ((req: Request) => boolean | Promise<boolean>);
+    /** The HTTP header that contains the signature (defaults to 'x-opaca-signature'). */
+    signatureHeader?: string;
+    /** Function to map the third-party payload to your CMS collection fields. */
+    mapPayload?: (payload: any) => Partial<T> | Promise<Partial<T>>;
+    /** Callback executed after a successful record synchronization. */
+    onSuccess?: (args: {
+        data: T;
+        payload: any;
+        operation: "create" | "update";
+    }) => void | Promise<void>;
+}
+/** Represents any webhook configuration supported by OpacaCMS. */
+export type WebhookConfig<T = any> = OutgoingWebhookConfig<T> | IncomingWebhookConfig<T>;
+/**
+ * Configuration for an OpacaCMS collection.
+ */
+export interface Collection<T = any> {
+    /** Unique URL-friendly identifier for the collection. */
     slug: string;
+    /** Human-readable name for the collection. */
     label?: string;
-    icon?: IconName;
+    /** Lucide icon displayed in the Admin UI sidebar. */
+    icon?: LucideIcons;
+    /** Custom base path for the collection's API endpoints. */
     apiPath?: string;
+    /** List of fields that define the collection's schema. */
     fields: Field[];
-    hooks?: CollectionHooks;
+    /** Lifecycle hooks for custom logic before/after database operations. */
+    hooks?: CollectionHooks<T>;
+    /** Access control configuration for the collection. */
     access?: AccessConfig;
+    /** Versioning and draft support configuration. */
     versions?: {
+        /** Enable draft/published states for records. */
         drafts?: boolean;
+        /** Maximum number of historical versions to retain per record. */
         maxRevisions?: number;
+        /** Enable automatic background saving of drafts. */
         autosave?: boolean;
+        /** Whether records must be explicitly published to be visible via standard 'read' operations. */
+        requirePublish?: boolean;
     };
+    /** Automatically manage createdAt and updatedAt fields. */
     timestamps?: boolean | {
         createdAt?: string;
         updatedAt?: string;
     };
-    webhooks?: {
-        events: string[];
-        url: string;
-        headers?: Record<string, string>;
-    }[];
+    /**
+     * Configuration for external webhooks.
+     * Supports both 'outgoing' (triggered by events) and 'incoming' (public endpoints).
+     */
+    webhooks?: WebhookConfig<T>[];
     auth?: boolean;
     admin?: {
         /**
@@ -262,22 +424,26 @@ export interface Collection {
         }[];
     } | boolean;
     hidden?: boolean;
+    seed?: (faker: Faker) => Partial<T> | Promise<Partial<T>>;
 }
 export interface Global {
     slug: string;
     fields: Field[];
     access?: AccessConfig;
     label?: string;
-    icon?: IconName;
+    icon?: LucideIcons;
     timestamps?: boolean | {
         createdAt?: string;
         updatedAt?: string;
     };
+    seed?: (faker: Faker) => any | Promise<any>;
 }
 export interface OpacaPluginContext {
     config: OpacaConfig;
     logger: typeof import("./utils/logger").logger;
     settings?: Record<string, any>;
+    /** Environment variables (e.g. c.env in Cloudflare) */
+    env?: any;
 }
 export interface OpacaPlugin {
     /**
@@ -307,7 +473,7 @@ export interface OpacaPlugin {
     /**
      * Lucide icon name for the plugin
      */
-    icon?: IconName;
+    icon?: LucideIcons;
     /**
      * Callback fired during OpacaCMS initialization.
      * Use this to extend the schema (collections, globals).
@@ -352,41 +518,59 @@ export interface OpacaPlugin {
      * Defines a configuration schema for the plugin.
      * This will be used to generate a settings form in the Admin UI.
      */
-    configSchema?: Field[];
+    configSchema?: Field[] | z.ZodObject<any>;
     /**
      * Defines the administrative UI for the plugin.
-     * This can point to local files during development or contain inlined source for production.
      */
     adminUI?: {
-        /** The name of the custom element/component to render */
-        component?: string;
-        /** Absolute path to the source file (.tsx) - Used in dev/Node/Bun */
-        filePath?: string;
-        /** The inlined transpiled source code - Used in Workers/Production */
-        source?: string;
+        /** The type of rendering to use. 'iframe' or 'ssr' both result in an iframe in the Admin UI. */
+        type: "iframe" | "ssr";
+        /** The path to the plugin's administrative UI. */
+        path: string;
     };
     /** Runtime settings for the plugin */
     settings?: Record<string, any>;
 }
+/**
+ * Root configuration for an OpacaCMS instance.
+ */
 export interface OpacaConfig<Resource extends string = string> {
+    /** The name of your application, displayed in the Admin UI and emails. */
     appName?: string;
+    /** The base URL where the CMS server is hosted. */
     serverURL?: string;
+    /** A secure random string used for signing cookies and tokens. */
     secret?: string;
+    /** The database adapter used for data persistence (e.g., Drizzle, SQLite). */
     db: DatabaseAdapter;
+    /** Configuration for the internal logger. */
     logger?: OpacaLoggerConfig;
+    /** List of collections that define your content models. */
     collections: Collection[];
+    /** List of global singletons for site-wide settings. */
     globals?: Global[];
+    /** Configuration for the Admin UI dashboard and layout. */
     admin?: AdminConfig;
+    /** Configuration for the REST and GraphQL APIs. */
     api?: ApiConfig;
+    /** Root access control configuration for roles and permissions. */
     access?: OpacaAccessConfig<Resource>;
+    /** List of origins allowed to make cross-origin requests. */
     trustedOrigins?: string[] | ((request?: Request) => string[] | Promise<string[]>);
+    /** Configuration for authentication strategies and social providers. */
     auth?: OpacaAuthConfig;
+    /** Internationalization settings for multi-language support. */
     i18n?: {
+        /** List of supported locale codes. */
         locales: string[];
+        /** The default locale code for the application. */
         defaultLocale: string;
     };
+    /** Configuration for file storage backends (e.g., S3, local). */
     storages?: Record<string, any>;
+    /** Automatically run database migrations on server startup. */
     runMigrationsOnStartup?: boolean;
+    /** List of plugins to extend CMS functionality. */
     plugins?: OpacaPlugin[];
 }
 export interface OpacaLoggerConfig {
@@ -453,6 +637,14 @@ export interface OpacaAccessConfig<Resource extends string = string> {
 }
 export interface ApiConfig {
     maxLimit?: number;
+    rest?: {
+        enabled?: boolean;
+    };
+    graphql?: {
+        enabled?: boolean;
+        path?: string;
+        graphiql?: boolean;
+    };
     rateLimit?: {
         windowMs?: number;
         limit?: number;
@@ -464,7 +656,7 @@ export interface ApiConfig {
     openAPI?: {
         enabled?: boolean;
         path?: string;
-        theme?: "alternate" | "default" | "moon" | "purple" | "solarized" | "bluePlanet" | "saturn" | "kepler" | "mars" | "deepSpace" | "none" | string;
+        theme?: "alternate" | "default" | "moon" | "purple" | "solarized" | "bluePlanet" | "saturn" | "kepler" | "mars" | "deepSpace" | "none";
         layout?: "modern" | "classic" | string;
         hideModels?: boolean;
         hideDownloadButton?: boolean;
@@ -476,6 +668,9 @@ export interface FindOptions {
     limit?: number;
     page?: number;
     sort?: string;
+    after?: string;
+    before?: string;
+    cursorColumn?: string;
 }
 export interface PaginatedResult<T> {
     docs: T[];
@@ -489,6 +684,8 @@ export interface PaginatedResult<T> {
     hasNextPage: boolean;
     prevPage: number | null;
     nextPage: number | null;
+    nextCursor?: string | null;
+    prevCursor?: string | null;
 }
 export interface DatabaseAdapter {
     name: string;
@@ -497,8 +694,8 @@ export interface DatabaseAdapter {
     /**
      * Internal ORM instance (e.g. Drizzle instance)
      */
-    readonly db?: unknown;
-    readonly raw?: unknown;
+    readonly db?: any;
+    readonly raw?: any;
     unsafe(sql: string, params?: unknown[]): Promise<unknown>;
     count(collection: string, query?: Record<string, unknown>): Promise<number>;
     create<T extends object>(collection: string, data: Partial<T>): Promise<T>;
@@ -531,7 +728,7 @@ export interface SerializableCollection {
     slug: string;
     apiPath?: string;
     label?: string;
-    icon?: IconName;
+    icon?: LucideIcons;
     versions?: {
         drafts?: boolean;
         maxRevisions?: number;
@@ -550,10 +747,14 @@ export interface SerializableCollection {
                 Field?: string;
                 Cell?: string;
             };
+            condition?: (data: any) => boolean;
+            requiredCondition?: (data: any) => boolean;
         };
         required?: boolean;
         unique?: boolean;
         defaultValue?: unknown;
+        condition?: (data: any) => boolean;
+        requiredCondition?: (data: any) => boolean;
         options?: {
             defaultMode?: "simple" | "notion";
             [key: string]: unknown;
@@ -619,7 +820,7 @@ export interface SerializableConfig {
     globals?: {
         slug: string;
         label?: string;
-        icon?: IconName;
+        icon?: LucideIcons;
         fields: {
             name?: string;
             type: FieldType;
@@ -672,7 +873,7 @@ export interface SerializableConfig {
         /**
          * Icon to be used in the admin UI.
          */
-        icon?: IconName;
+        icon?: LucideIcons;
         /**
          * Assets to be loaded in the admin UI.
          */
@@ -680,20 +881,30 @@ export interface SerializableConfig {
             styles?: string[];
             scripts?: string[];
         };
-        /**
-         * Admin UI configuration.
-         */
         adminUI?: {
-            /**
-             * The name of the custom element to register.
-             */
-            component?: string;
-            /**
-             * The inlined transpiled source code - Used in Workers/Production
-             */
-            source?: string;
+            type: "iframe" | "ssr";
+            path: string;
         };
         settings?: Record<string, any>;
         configSchema?: SerializableCollection["fields"];
     }[];
+    api?: {
+        rest?: {
+            enabled?: boolean;
+        };
+        graphql?: {
+            enabled?: boolean;
+            path?: string;
+            graphiql?: boolean;
+        };
+        openAPI?: {
+            enabled?: boolean;
+            path?: string;
+            theme?: "none" | "default" | "alternate" | "moon" | "purple" | "solarized" | "bluePlanet" | "deepSpace" | "saturn" | "kepler" | "elysiajs" | "fastify" | "mars" | "laserwave" | string;
+            layout?: "modern" | "classic" | string;
+            hideModels?: boolean;
+            hideDownloadButton?: boolean;
+            customCss?: string;
+        };
+    };
 }

package/dist/utils/context.d.ts

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface RequestContextData {
+    userId?: string | null;
+    previousData?: any;
+}
+export declare const requestContext: AsyncLocalStorage<RequestContextData>;
+/**
+ * Gets the current user ID from the request context.
+ */
+export declare function getUserIdFromContext(): string | null;
+/**
+ * Gets the stashed previous data from the request context.
+ */
+export declare function getPreviousDataFromContext(): any;

package/dist/utils/logger.d.ts

@@ -8,6 +8,8 @@ export declare class OpacaLogger {
     debug(message: string, ...args: any[]): void;
     warn(message: string, ...args: any[]): void;
     error(message: string, ...args: any[]): void;
+    log(message: string, ...args: any[]): void;
+    bold(msg: string): string;
     format(color: "green" | "red" | "yellow" | "gray", msg: string): string;
 }
 export declare const logger: OpacaLogger;

package/dist/utils/string.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sanitizes a string to be a valid GraphQL name.
+ * GraphQL names must match /[_a-zA-Z][_a-zA-Z0-9]* /
+ */
+export declare function sanitizeGraphQLName(name: string): string;
+/**
+ * Generates a random name for a migration.
+ * Uses a combination of an adjective and a noun.
+ */
+export declare function getRandomMigrationName(): string;