opacacms 0.1.0

package/src/types.ts

@@ -0,0 +1,577 @@
+import type { Session, User } from "better-auth";
+import type { Context } from "hono";
+import type { icons } from "lucide-react";
+import type {
+  AdminConfig,
+  CollectionHooks,
+  FieldType,
+  AccessConfig as ValidationAccessConfig,
+  ApiConfig as ValidationApiConfig,
+  Collection as ValidationCollection,
+  Field as ValidationField,
+  Global as ValidationGlobal,
+  OpacaConfig as ValidationOpacaConfig,
+} from "./validation";
+
+export type { FieldType };
+
+export type IconName = keyof typeof icons;
+
+// --- Field Types ---
+
+export interface BaseField {
+  name: string;
+  label?: string;
+  placeholder?: string;
+  required?: boolean;
+  unique?: boolean;
+  localized?: boolean;
+  defaultValue?: unknown;
+  validate?: (value: unknown) => boolean | string;
+  access?: FieldAccessConfig;
+  admin?: {
+    description?: string;
+    condition?: (data: Record<string, unknown>, siblingData: Record<string, unknown>) => boolean;
+    hidden?: boolean;
+    readOnly?: boolean;
+    width?: string;
+    style?: any;
+    className?: string;
+    components?: {
+      Field?: string;
+      Cell?: string;
+    };
+  };
+  references?: {
+    table: string;
+    column: string;
+    onDelete?: "cascade" | "set null" | "restrict" | "no action";
+  };
+}
+
+export interface TextField extends BaseField {
+  type: "text";
+}
+
+export interface SlugField extends BaseField {
+  type: "slug";
+  from: string;
+  format?: (value: string) => string;
+}
+
+export interface TextAreaField extends BaseField {
+  type: "textarea";
+}
+
+export interface NumberField extends BaseField {
+  type: "number";
+  options?: {
+    min?: number;
+    max?: number;
+    step?: number;
+    [key: string]: any;
+  };
+}
+
+export interface RichTextField extends BaseField {
+  type: "richtext";
+  options?: {
+    defaultMode?: "simple" | "notion";
+    [key: string]: any;
+  };
+}
+
+export interface RelationshipField extends BaseField {
+  type: "relationship";
+  relationTo: string;
+  hasMany?: boolean;
+  displayField?: string;
+}
+
+export interface SelectField extends BaseField {
+  type: "select";
+  options?: {
+    choices: (string | { label: string; value: string })[];
+    [key: string]: any;
+  };
+}
+
+export interface RadioField extends BaseField {
+  type: "radio";
+  options: {
+    choices: (string | { label: string; value: string })[];
+    [key: string]: unknown;
+  };
+}
+
+export interface DateField extends BaseField {
+  type: "date";
+}
+
+export interface BooleanField extends BaseField {
+  type: "boolean";
+  options?: {
+    display?: "switch" | "toggle" | "checkbox" | "select";
+    [key: string]: unknown;
+  };
+}
+
+export interface JSONField extends BaseField {
+  type: "json";
+}
+
+export interface FileField extends BaseField {
+  type: "file";
+  bucket?: string;
+  options?: {
+    allowedmime_types?: string[];
+    maxFileSize?: number;
+    metaFields?: Field[];
+    [key: string]: unknown;
+  };
+}
+
+export interface BlocksField extends BaseField {
+  type: "blocks";
+  blocks: {
+    slug: string;
+    fields: Field[];
+    label?: string;
+  }[];
+}
+
+export interface GroupField extends BaseField {
+  type: "group";
+  fields: Field[];
+}
+
+export interface RowField extends Omit<BaseField, "name"> {
+  type: "row";
+  name?: string; // Allow optional name for row
+  fields: Field[];
+  label?: string;
+}
+
+export interface CollapsibleField extends Omit<BaseField, "name"> {
+  type: "collapsible";
+  name?: string; // Allow optional name for collapsible
+  label: string;
+  fields: Field[];
+  options?: {
+    initiallyCollapsed?: boolean;
+    useAsTitle?: string;
+    [key: string]: any;
+  };
+}
+
+export interface ArrayField extends BaseField {
+  type: "array";
+  fields: Field[];
+}
+
+export interface TabsField extends Omit<BaseField, "name"> {
+  type: "tabs";
+  name?: string; // Allow optional name for tabs
+  tabs: {
+    label: string;
+    fields: Field[];
+  }[];
+}
+
+export interface JoinField extends Omit<BaseField, "name"> {
+  type: "join";
+  name?: string; // join requires name, but schema-generator tests assume optional
+  collection: string;
+  on: string;
+}
+
+export interface VirtualField extends BaseField {
+  type: "virtual";
+  resolve: (args: {
+    data: any;
+    req: any;
+    user: User;
+    session: Session;
+    apiKey?: ApiKey;
+  }) => any | Promise<any>;
+  returnType?: "string" | "number" | "boolean" | "json";
+}
+
+export type Field =
+  | TextField
+  | SlugField
+  | TextAreaField
+  | NumberField
+  | RichTextField
+  | RelationshipField
+  | SelectField
+  | VirtualField
+  | RadioField
+  | DateField
+  | BooleanField
+  | JSONField
+  | FileField
+  | BlocksField
+  | GroupField
+  | RowField
+  | CollapsibleField
+  | TabsField
+  | JoinField
+  | ArrayField;
+
+export interface ApiKey {
+  id: string;
+  name: string | null;
+  permissions?: Record<string, string[]> | null;
+  referenceId: string;
+}
+
+export interface AccessArgs {
+  req: Context;
+  user: User | null;
+  session: Session | null;
+  apiKey?: ApiKey | null;
+  data?: unknown;
+  operation?: "read" | "create" | "update" | "delete";
+}
+
+export interface FieldAccessConfig {
+  /** If true, the field is removed from API and UI. */
+  hidden?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
+  /** If true, the data is shown but cannot be edited. */
+  readOnly?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
+  /** If true, the input is visually disabled. */
+  disabled?: boolean | ((args: AccessArgs) => boolean | Promise<boolean>);
+}
+
+export interface AccessConfig
+  extends Omit<ValidationAccessConfig, "read" | "create" | "update" | "delete"> {
+  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
+  extends Omit<
+    ValidationCollection,
+    "fields" | "hooks" | "access" | "admin" | "apiPath" | "versions" | "webhooks"
+  > {
+  fields: Field[];
+  apiPath?: string;
+  hooks?: CollectionHooks;
+  access?: AccessConfig;
+  icon?: IconName;
+  versions?: {
+    drafts?: boolean;
+    maxRevisions?: number;
+    autosave?: boolean;
+  };
+  webhooks?: {
+    events: string[];
+    url: string;
+    headers?: Record<string, string>;
+  }[];
+  admin?:
+  | {
+    defaultColumns?: string[];
+    useAsTitle?: string;
+    hidden?: boolean;
+    disableAdmin?: boolean;
+    views?: {
+      name: string;
+      filter: Record<string, any>;
+      defaultColumns?: string[];
+    }[];
+    bulkActions?: {
+      label: string;
+      action: (args: { selectedIds: string[]; db: DatabaseAdapter }) => Promise<unknown>;
+    }[];
+  }
+  | boolean;
+}
+
+export interface Global extends Omit<ValidationGlobal, "fields" | "access"> {
+  fields: Field[];
+  access?: AccessConfig;
+  label?: string;
+  icon?: IconName;
+}
+
+export interface OpacaConfig<Resource extends string = string>
+  extends Omit<
+    ValidationOpacaConfig,
+    "collections" | "globals" | "admin" | "api" | "access" | "trustedOrigins" | "auth" | "i18n"
+  > {
+  collections: Collection[];
+  globals?: Global[];
+  db: DatabaseAdapter;
+  admin?: AdminConfig;
+  api?: ApiConfig;
+  access?: OpacaAccessConfig<Resource>;
+  trustedOrigins?: string[] | ((request?: Request) => string[] | Promise<string[]>);
+  auth?: OpacaAuthConfig;
+  i18n?: {
+    locales: string[];
+    defaultLocale: string;
+  };
+}
+
+export interface OpacaAuthConfig {
+  /**
+   * Defines the primary identity strategies for accessing the CMS.
+   */
+  strategies?: {
+    emailPassword?: boolean; // Defaults to true
+    magicLink?: {
+      enabled: boolean;
+      sendEmail: (data: { email: string; url: string; token: string }) => Promise<void>;
+    };
+  };
+
+  /**
+   * Strictly typed social providers.
+   * Only the providers explicitly supported by the OpacaCMS UI are allowed.
+   */
+  socialProviders?: {
+    github?: {
+      clientId: string;
+      clientSecret: string;
+    };
+    google?: {
+      clientId: string;
+      clientSecret: string;
+    };
+  };
+
+  /**
+   * Session configuration overrides.
+   */
+  session?: {
+    expiresInDays?: number; // Defaults to 30
+    updateAgeSeconds?: number; // Defaults to 86400 (1 day)
+  };
+
+  /**
+   * Declaring plugins statically by configuration.
+   */
+  features?: {
+    apiKeys?: {
+      enabled: boolean;
+    };
+    mfa?: {
+      enabled: boolean;
+      issuer: string;
+    };
+  };
+}
+
+export interface OpacaAccessConfig<Resource extends string = string> {
+  /**
+   * Define roles and their permissions.
+   * Key is the role name (e.g., 'editor').
+   * Value is a map of resource names to allowed actions.
+   */
+  roles: Record<string, Partial<Record<Resource | "user" | "session", string[]>>>;
+}
+
+export interface ApiConfig {
+  maxLimit?: number;
+  rateLimit?: {
+    windowMs?: number;
+    limit?: number;
+    enabled?: boolean;
+    store?: any;
+    provider?: (c: Context) => any;
+    keyGenerator?: (c: Context) => string | Promise<string>;
+  };
+}
+
+export type { AdminConfig };
+
+export interface FindOptions {
+  limit?: number;
+  page?: number;
+  sort?: string;
+}
+
+export interface PaginatedResult<T> {
+  docs: T[];
+  folders?: string[];
+  totalDocs: number;
+  limit: number;
+  totalPages: number;
+  page: number;
+  pagingCounter: number;
+  hasPrevPage: boolean;
+  hasNextPage: boolean;
+  prevPage: number | null;
+  nextPage: number | null;
+}
+
+export interface DatabaseAdapter {
+  name: string;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  /**
+   * Internal ORM instance (e.g. Drizzle instance)
+   */
+  readonly db?: unknown;
+  readonly raw?: unknown;
+  unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+  count(collection: string, query?: Record<string, unknown>): Promise<number>;
+
+  // CRUD
+  create<T extends object>(collection: string, data: Partial<T>): Promise<T>;
+  find<T extends object>(
+    collection: string,
+    query?: Record<string, unknown>,
+    options?: FindOptions,
+  ): Promise<PaginatedResult<T>>;
+  findOne<T extends object>(collection: string, query: Record<string, unknown>): Promise<T | null>;
+  update<T extends object>(
+    collection: string,
+    query: Record<string, unknown>,
+    data: Partial<T>,
+  ): Promise<T>;
+  updateMany?<T extends object>(
+    collection: string,
+    query: Record<string, unknown>,
+    data: Partial<T>,
+  ): Promise<number>;
+  delete(collection: string, query: Record<string, unknown>): Promise<boolean>;
+  deleteMany?(collection: string, query: Record<string, unknown>): Promise<number>;
+
+  // Globals
+  findGlobal?<T extends object>(slug: string): Promise<T | null>;
+  updateGlobal?<T extends object>(slug: string, data: Partial<T>): Promise<T>;
+
+  // Schema management
+  migrate(collections: Collection[], globals?: Global[]): Promise<void>;
+
+  /**
+   * Run file-based migrations from the migrations directory.
+   */
+  runMigrations?(): Promise<void>;
+
+  /**
+   * Wether to automatically push schema changes to the database (on the fly).
+   * Defaults to true in development, false in production.
+   */
+  push?: boolean;
+  pushDestructive?: boolean;
+  migrationDir?: string;
+}
+
+/**
+ * Serializable version of a collection, safe for Next.js Client Components.
+ * Strips out hooks and access functions.
+ */
+export interface SerializableCollection {
+  slug: string;
+  apiPath?: string;
+  label?: string;
+  icon?: IconName;
+  versions?: {
+    drafts?: boolean;
+    maxRevisions?: number;
+    autosave?: boolean;
+  };
+  fields: {
+    name?: string;
+    type: FieldType;
+    label?: string;
+    localized?: boolean;
+    admin?: {
+      description?: string;
+      hidden?: boolean;
+      readOnly?: boolean;
+      components?: {
+        Field?: string;
+        Cell?: string;
+      };
+    };
+    required?: boolean;
+    unique?: boolean;
+    defaultValue?: unknown;
+    options?: {
+      defaultMode?: "simple" | "notion";
+      [key: string]: unknown;
+    };
+    fields?: SerializableCollection["fields"];
+    relationTo?: string;
+    hasMany?: boolean;
+    displayField?: string;
+    collection?: string;
+    on?: string;
+    blocks?: {
+      slug: string;
+      fields: SerializableCollection["fields"];
+      label?: string;
+    }[];
+    tabs?: {
+      label: string;
+      fields: SerializableCollection["fields"];
+    }[];
+  }[];
+  timestamps?: boolean | { createdAt?: string; updatedAt?: string };
+  auth?: boolean;
+  admin?:
+  | {
+    defaultColumns?: string[];
+    useAsTitle?: string;
+    hidden?: boolean;
+    disableAdmin?: boolean;
+    views?: {
+      name: string;
+      filter: Record<string, any>;
+      defaultColumns?: string[];
+    }[];
+  }
+  | boolean;
+  hidden?: boolean;
+}
+
+/**
+ * Serializable version of the config, safe for Next.js Client Components.
+ * Strips out database adapter and functions.
+ */
+export interface SerializableConfig {
+  appName?: string;
+  serverURL?: string;
+  i18n?: {
+    locales: string[];
+    defaultLocale: string;
+  };
+  collections: SerializableCollection[];
+  globals?: {
+    slug: string;
+    label?: string;
+    icon?: IconName;
+    fields: {
+      name?: string;
+      type: FieldType;
+      label?: string;
+      required?: boolean;
+      defaultValue?: unknown;
+      options?: {
+        defaultMode?: "simple" | "notion";
+        [key: string]: unknown;
+      };
+      fields?: SerializableCollection["fields"];
+      blocks?: {
+        slug: string;
+        fields: SerializableCollection["fields"];
+        label?: string;
+      }[];
+      tabs?: {
+        label: string;
+        fields: SerializableCollection["fields"];
+      }[];
+    }[];
+  }[];
+  needsInit?: boolean;
+  storages?: Record<string, unknown>;
+}

package/src/utils/lexical.ts

@@ -0,0 +1,37 @@
+/**
+ * Converts Lexical JSON state to plain text.
+ * Useful for displaying previews in tables or search results.
+ */
+export function lexicalToPlainText(jsonString: string): string {
+  if (!jsonString) return "";
+
+  try {
+    const data = JSON.parse(jsonString);
+    if (!data.root || !data.root.children) return "";
+
+    return traverseNodes(data.root.children);
+  } catch (err) {
+    // If it's not valid JSON, it might already be plain text or a different format
+    if (typeof jsonString === "string" && !jsonString.startsWith("{")) {
+      return jsonString;
+    }
+    return "";
+  }
+}
+
+function traverseNodes(children: any[]): string {
+  let text = "";
+  for (const child of children) {
+    if (child.text) {
+      text += child.text;
+    } else if (child.children) {
+      text += traverseNodes(child.children);
+    }
+
+    // Add space for block-level elements
+    if (child.type === "paragraph" || child.type === "heading" || child.type === "listitem") {
+      text += " ";
+    }
+  }
+  return text.trim();
+}

package/src/utils/logger.ts

@@ -0,0 +1,73 @@
+/**
+ * Core Logger Utility for OpacaCMS.
+ * Standardizes console output across the package with ANSI colors and standard prefixes.
+ */
+
+const RESET = "\x1b[0m";
+const BLUE = "\x1b[34m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const GRAY = "\x1b[90m";
+
+const PREFIX = `${BLUE}[OpacaCMS]${RESET}`;
+
+export const logger = {
+  /**
+   * General information logging.
+   * Useful for successful operations, initialization steps, etc.
+   */
+  info: (message: string, ...args: any[]) => {
+    console.log(`${PREFIX} ${message}`, ...args);
+  },
+
+  /**
+   * Action logging. Usually highlighted in green.
+   * e.g., "Created table users", "Connected to DB"
+   */
+  success: (message: string, ...args: any[]) => {
+    console.log(`${PREFIX} ${GREEN}${message}${RESET}`, ...args);
+  },
+
+  /**
+   * Dim/Debug logging.
+   * e.g., "Starting schema push...", "Syncing database..."
+   */
+  debug: (message: string, ...args: any[]) => {
+    console.log(`${PREFIX} ${GRAY}${message}${RESET}`, ...args);
+  },
+
+  /**
+   * Warning logging.
+   * For non-fatal errors or deprecated warnings.
+   */
+  warn: (message: string, ...args: any[]) => {
+    console.warn(`${PREFIX} ${YELLOW}Warning: ${message}${RESET}`, ...args);
+  },
+
+  /**
+   * Error logging.
+   * For fatal errors, exceptions, and validation failures.
+   */
+  error: (message: string, ...args: any[]) => {
+    console.error(`${PREFIX} ${RED}Error: ${message}${RESET}`, ...args);
+  },
+
+  /**
+   * Raw formatting function if manual concatenation is needed.
+   */
+  format: (color: "green" | "red" | "yellow" | "gray", msg: string) => {
+    switch (color) {
+      case "green":
+        return `${GREEN}${msg}${RESET}`;
+      case "red":
+        return `${RED}${msg}${RESET}`;
+      case "yellow":
+        return `${YELLOW}${msg}${RESET}`;
+      case "gray":
+        return `${GRAY}${msg}${RESET}`;
+      default:
+        return msg;
+    }
+  },
+};