@bobbykim/manguito-cms-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,527 @@
+type SchemaFolders = {
+    content_types: string;
+    paragraph_types: string;
+    taxonomy_types: string;
+    enum_types: string;
+};
+type SchemaConfig = {
+    base_path?: string;
+    folders?: Partial<SchemaFolders>;
+};
+type ResolvedSchemaConfig = {
+    base_path: string;
+    folders: SchemaFolders;
+};
+type MigrationsConfig = {
+    table?: string;
+    folder?: string;
+};
+type ResolvedMigrationsConfig = {
+    table: string;
+    folder: string;
+} | null;
+type MigrationResult = {
+    applied: number;
+    skipped: number;
+};
+type MigrationStatus = {
+    pending: string[];
+    applied: string[];
+};
+interface DbAdapter {
+    readonly type: 'postgres' | 'mongodb';
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getTableNames(): Promise<string[]>;
+    tableExists(name: string): Promise<boolean>;
+}
+type PresignedOptions = {
+    folder: 'image' | 'video' | 'file';
+    filename: string;
+    mime_type: string;
+    expires_in?: number;
+};
+type PresignedResult = {
+    upload_url: string;
+    key: string;
+    expires_at: number;
+    method?: 'PUT' | 'POST';
+    fields?: Record<string, string>;
+};
+interface StorageAdapter {
+    readonly type: 'local' | 's3' | 'cloudinary';
+    delete(key: string): Promise<void>;
+    getUrl(key: string): string;
+    getPresignedUploadUrl(options: PresignedOptions): Promise<PresignedResult>;
+    upload?(key: string, data: Uint8Array, mimeType: string): Promise<void>;
+    /** Optional metadata lookup used to validate uploaded objects on confirm. */
+    stat?(key: string): Promise<{
+        size: number;
+        content_type?: string;
+    } | null>;
+    /**
+     * Cross-origin hosts the browser connects to during a presigned upload,
+     * as CSP connect-src origins (scheme + host, no path). Used to build the
+     * Content-Security-Policy. Adapters whose uploads are same-origin (local)
+     * omit this.
+     */
+    getUploadOrigins?(): string[];
+}
+type CorsConfig = {
+    enabled?: boolean;
+    origin: string | string[];
+    methods?: string[];
+    credentials?: boolean;
+};
+interface ServerAdapter {
+    readonly type: 'node' | 'lambda' | 'vercel';
+    getEntryPoint(): string;
+    cors: CorsConfig;
+}
+type ResolvedMediaConfig = {
+    max_file_size?: number;
+};
+type ResolvedRateLimitConfig = {
+    /**
+     * Rate limiting for public list endpoints (paginated collections, not
+     * single-item lookups). Set `findAll: '*'` to disable the list-endpoint
+     * limiter entirely.
+     */
+    findAll?: '*' | {
+        windowMs?: number;
+        maxPerIp?: number;
+        maxGlobal?: number;
+    };
+};
+interface APIAdapter {
+    readonly prefix: string;
+    readonly media?: ResolvedMediaConfig;
+    readonly rateLimit?: ResolvedRateLimitConfig;
+}
+interface AdminAdapter {
+    readonly prefix: string;
+}
+type ManguitoConfig = {
+    name?: string;
+    schema?: SchemaConfig;
+    db: DbAdapter;
+    migrations?: MigrationsConfig;
+    storage: StorageAdapter;
+    server: ServerAdapter;
+    api: APIAdapter;
+    admin: AdminAdapter;
+};
+type ResolvedManguitoConfig = {
+    name: string;
+    schema: ResolvedSchemaConfig;
+    db: DbAdapter;
+    migrations: ResolvedMigrationsConfig | null;
+    storage: StorageAdapter;
+    server: ServerAdapter;
+    api: APIAdapter;
+    admin: AdminAdapter;
+};
+
+declare function defineConfig(config: ManguitoConfig): ResolvedManguitoConfig;
+
+type DbColumnType = 'uuid' | 'varchar' | 'text' | 'integer' | 'decimal' | 'boolean' | 'timestamp';
+type DbColumn = {
+    column_name: string;
+    column_type: DbColumnType;
+    nullable: boolean;
+    check_constraint?: string[];
+    foreign_key?: {
+        table: string;
+        column: string;
+        on_delete: 'CASCADE' | 'SET NULL' | 'RESTRICT';
+    };
+    junction?: {
+        table_name: string;
+        left_column: string;
+        right_column: string;
+        right_table: string;
+        order_column: boolean;
+    };
+};
+type FieldValidation = {
+    required: boolean;
+    min?: number;
+    max?: number;
+    limit?: number;
+    max_size?: number;
+    pattern?: string;
+    max_items?: number;
+    allowed_values?: string[];
+    allowed_mime_types?: string[];
+};
+type RelationType = 'one-to-one' | 'one-to-many' | 'many-to-many';
+type UiComponent = {
+    component: 'text-input';
+} | {
+    component: 'rich-text-editor';
+} | {
+    component: 'number-input';
+    step: number;
+} | {
+    component: 'checkbox';
+} | {
+    component: 'date-picker';
+} | {
+    component: 'file-upload';
+    accepted_mime_types: string[];
+} | {
+    component: 'select';
+    options: string[];
+    enum_ref?: string;
+} | {
+    component: 'typeahead-select';
+    ref: string;
+    rel: RelationType;
+} | {
+    component: 'paragraph-embed';
+    ref: string;
+    rel: RelationType;
+    max?: number;
+};
+type FieldType = 'text/plain' | 'text/rich' | 'integer' | 'float' | 'boolean' | 'date' | 'image' | 'video' | 'file' | 'enum' | 'paragraph' | 'reference';
+type ParsedField = {
+    name: string;
+    label: string;
+    field_type: FieldType;
+    required: boolean;
+    nullable: boolean;
+    order: number;
+    validation: FieldValidation;
+    db_column: DbColumn | null;
+    ui_component: UiComponent;
+};
+type SystemField = {
+    name: string;
+    db_type: 'uuid' | 'timestamp' | 'varchar' | 'boolean' | 'integer';
+    primary_key?: boolean;
+    default?: string;
+    nullable: boolean;
+};
+
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: ParseError[];
+};
+type ParseErrorCode = 'INVALID_SCHEMA_TYPE' | 'INVALID_FIELD_TYPE' | 'UNKNOWN_BASE_PATH' | 'UNKNOWN_REF' | 'INVALID_REF_TARGET' | 'DUPLICATE_FIELD_NAME' | 'DUPLICATE_SCHEMA_NAME' | 'INVALID_MACHINE_NAME' | 'CIRCULAR_REFERENCE' | 'MISSING_REQUIRED_FIELD' | 'MAX_SIZE_EXCEEDS_GLOBAL_LIMIT' | 'SCHEMA_DIR_NOT_FOUND' | 'SCHEMA_FOLDER_NOT_FOUND' | 'DUPLICATE_SCHEMA_FOLDER' | 'ROUTES_FILE_NOT_FOUND' | 'FILE_READ_ERROR' | 'FILE_PARSE_ERROR' | 'DUPLICATE_HIERARCHY_LEVEL' | 'UNKNOWN_PERMISSION' | 'INVALID_PERMISSION';
+type ParseError = {
+    file: string;
+    code: ParseErrorCode;
+    message: string;
+    path?: string;
+};
+type SchemaType = 'content-type' | 'paragraph-type' | 'taxonomy-type' | 'enum-type';
+type SchemaFile = {
+    path: string;
+    raw: unknown;
+    schema_type: SchemaType;
+};
+/**
+ * Reads a single JSON or YAML schema file and returns the raw parsed object.
+ * Supported extensions: .json, .yaml, .yml
+ * Never throws — file system and parse errors are returned as Result failures.
+ */
+declare function loadSchemaFile(filePath: string): Result<unknown>;
+/**
+ * Walks each schema folder defined in config and collects all schema files.
+ * For each file:
+ *   - Validates that the filename prefix matches the folder's expected schema type.
+ *   - Reads and parses the file content via loadSchemaFile.
+ *
+ * Collects all errors rather than stopping at the first failure.
+ * Returns { ok: false, errors } only when structural problems prevent loading;
+ * individual file errors are accumulated and returned together.
+ */
+declare function walkSchemaDirectory(config: ResolvedSchemaConfig): Result<SchemaFile[]>;
+
+type ParsedSchemaBase = {
+    schema_type: SchemaType;
+    name: string;
+    label: string;
+    source_file: string;
+};
+type UiTab = {
+    name: string;
+    label: string;
+    fields: string[];
+};
+type UiMeta = {
+    tabs: UiTab[];
+};
+type JunctionTable = {
+    table_name: string;
+    left_column: string;
+    right_column: string;
+    right_table: string;
+    order_column: boolean;
+};
+type ContentDbMeta = {
+    table_name: string;
+    junction_tables: JunctionTable[];
+};
+type ParagraphDbMeta = {
+    table_name: string;
+};
+type TaxonomyDbMeta = {
+    table_name: string;
+};
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+type ContentApiMeta = {
+    default_base_path: string;
+    http_methods: HttpMethod[];
+    collection_path?: string;
+    item_path: string;
+};
+type TaxonomyApiMeta = {
+    collection_path: string;
+    item_path: string;
+};
+type ParsedContentType = ParsedSchemaBase & {
+    schema_type: 'content-type';
+    only_one: boolean;
+    default_base_path: string;
+    system_fields: SystemField[];
+    fields: ParsedField[];
+    ui: UiMeta;
+    db: ContentDbMeta;
+    api: ContentApiMeta;
+};
+type ParsedParagraphType = ParsedSchemaBase & {
+    schema_type: 'paragraph-type';
+    system_fields: SystemField[];
+    fields: ParsedField[];
+    db: ParagraphDbMeta;
+};
+type ParsedTaxonomyType = ParsedSchemaBase & {
+    schema_type: 'taxonomy-type';
+    system_fields: SystemField[];
+    fields: ParsedField[];
+    db: TaxonomyDbMeta;
+    api: TaxonomyApiMeta;
+};
+type ParsedEnumType = ParsedSchemaBase & {
+    schema_type: 'enum-type';
+    values: string[];
+};
+type ParsedSchema = ParsedContentType | ParsedParagraphType | ParsedTaxonomyType | ParsedEnumType;
+type ParseResult = {
+    ok: true;
+    schema: ParsedSchema;
+} | {
+    ok: false;
+    errors: ParseError[];
+};
+/**
+ * Parses a raw schema object (from JSON or YAML) into the corresponding
+ * Parsed* type. Returns a ParseResult — never throws for expected failures.
+ *
+ * sourceFile is optional but should be supplied for accurate error reporting.
+ */
+declare function parseSchema(raw: unknown, schemaType: SchemaType, sourceFile?: string): ParseResult;
+
+type PermissionTarget = 'content' | 'media' | 'taxonomy' | 'users' | 'roles';
+type PermissionAction = 'read' | 'create' | 'edit' | 'delete';
+type Permission = `${PermissionTarget}:${PermissionAction}`;
+type JWTPayload = {
+    user_id: string;
+    role: string;
+    token_version: number;
+    expires_at: number;
+};
+type User = {
+    id: string;
+    email: string;
+    password_hash: string;
+    role_id: string;
+    token_version: number;
+    must_change_password: boolean;
+    created_at: Date;
+    updated_at: Date;
+};
+type FilterOperator = {
+    gt?: number | string;
+    gte?: number | string;
+    lt?: number | string;
+    lte?: number | string;
+};
+type FilterValue = string | number | boolean | Array<string | number | boolean> | FilterOperator;
+type PaginatedResult<T> = {
+    ok: true;
+    data: T[];
+    meta: {
+        total: number;
+        page: number;
+        per_page: number;
+        total_pages: number;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+};
+type FindManyOptions = {
+    page?: number;
+    per_page?: number;
+    include?: string[];
+    published_only?: boolean;
+    filters?: Record<string, FilterValue>;
+    sort_by?: 'title' | 'created_at' | 'updated_at';
+    sort_order?: 'asc' | 'desc';
+    search?: {
+        term: string;
+        columns: string[];
+    };
+};
+type FindAllOptions = {
+    include?: string[];
+    published_only?: boolean;
+};
+type CreateInput<T> = Omit<T, 'id' | 'created_at' | 'updated_at'>;
+type UpdateInput<T> = Partial<Omit<T, 'id' | 'created_at' | 'updated_at'>>;
+interface ContentRepository<T> {
+    findMany(options: FindManyOptions): Promise<PaginatedResult<T>>;
+    findOne(id: string, include?: string[]): Promise<T | null>;
+    findBySlug(slug: string, include?: string[]): Promise<T | null>;
+    create(data: CreateInput<T>): Promise<T>;
+    update(id: string, data: UpdateInput<T>): Promise<T | null>;
+    delete(id: string): Promise<void>;
+    findAll(options: FindAllOptions): Promise<T[]>;
+}
+type MediaItem = {
+    id: string;
+    type: 'image' | 'video' | 'file';
+    url: string;
+    mime_type: string;
+    alt?: string;
+    file_size: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    reference_count: number;
+    created_at: Date;
+    updated_at: Date;
+};
+type CreateMediaInput = {
+    type: 'image' | 'video' | 'file';
+    url: string;
+    mime_type: string;
+    alt?: string;
+    file_size: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+};
+type MediaFindManyOptions = {
+    page?: number;
+    per_page?: number;
+    type?: 'image' | 'video' | 'file';
+    orphaned?: boolean;
+};
+interface MediaRepository {
+    findMany(options: MediaFindManyOptions): Promise<PaginatedResult<MediaItem>>;
+    findOne(id: string): Promise<MediaItem | null>;
+    create(data: CreateMediaInput): Promise<MediaItem>;
+    update(id: string, data: Partial<MediaItem>): Promise<MediaItem | null>;
+    delete(id: string): Promise<void>;
+    incrementReferenceCount(ids: string[]): Promise<void>;
+    decrementReferenceCount(ids: string[]): Promise<void>;
+}
+
+type ParsedBasePath = {
+    name: string;
+    path: string;
+};
+type ParsedRoutes = {
+    base_paths: ParsedBasePath[];
+};
+type ParsedRole = {
+    name: string;
+    label: string;
+    is_system: boolean;
+    hierarchy_level: number;
+    permissions: Permission[];
+};
+type ParsedRoles = {
+    roles: ParsedRole[];
+    valid_permissions: string[];
+};
+type SchemaRegistry = {
+    routes: ParsedRoutes;
+    roles: ParsedRoles;
+    /** All schemas keyed by machine name. When two schemas share a name, last-write-wins. */
+    schemas: Record<string, ParsedSchema>;
+    content_types: Record<string, ParsedContentType>;
+    paragraph_types: Record<string, ParsedParagraphType>;
+    taxonomy_types: Record<string, ParsedTaxonomyType>;
+    enum_types: Record<string, ParsedEnumType>;
+    /**
+     * All schemas in the original input order, preserving duplicates.
+     * Used by validateCrossReferences to detect DUPLICATE_SCHEMA_NAME errors —
+     * the keyed maps above deduplicate by name and would hide them.
+     */
+    all_schemas: readonly ParsedSchema[];
+};
+/**
+ * Assembles the final SchemaRegistry from all individually parsed schemas,
+ * routes, and roles.
+ *
+ * When two schemas share the same machine name, last-write-wins in the keyed
+ * maps. The all_schemas array preserves all entries (including duplicates) so
+ * that validateCrossReferences can detect DUPLICATE_SCHEMA_NAME errors.
+ *
+ * Also resolves enum refs: any enum field that uses `ref` (rather than inline
+ * `values`) has its allowed_values, check_constraint, and select options
+ * populated from the matching enum-type schema. Fields whose enum ref does not
+ * exist in the registry are left empty — validateCrossReferences will report
+ * UNKNOWN_REF for them.
+ */
+declare function buildSchemaRegistry(parsedSchemas: ParsedSchema[], parsedRoutes: ParsedRoutes, parsedRoles: ParsedRoles): SchemaRegistry;
+/**
+ * Validates cross-schema references after all schemas have been individually
+ * parsed and assembled into a registry. Returns all cross-reference errors.
+ *
+ * Error codes covered:
+ * - DUPLICATE_SCHEMA_NAME     — two schema files share the same machine name
+ * - UNKNOWN_REF               — ref or target points to a non-existent schema
+ * - INVALID_REF_TARGET        — ref points to a schema of the wrong type
+ * - CIRCULAR_REFERENCE        — paragraph A refs paragraph B which refs paragraph A
+ * - MAX_SIZE_EXCEEDS_GLOBAL_LIMIT — field max_size exceeds the global limit
+ *
+ * @param registry         The assembled SchemaRegistry (from buildSchemaRegistry).
+ * @param globalMaxFileSize Global max file size in bytes from api.media.max_file_size.
+ *   When provided, MAX_SIZE_EXCEEDS_GLOBAL_LIMIT is checked for all media fields.
+ */
+declare function validateCrossReferences(registry: SchemaRegistry, globalMaxFileSize?: number): ParseError[];
+/**
+ * Validates a raw routes.json object and produces a ParsedRoutes value.
+ * Returns Result<ParsedRoutes> — never throws for expected failures.
+ * sourceFile is optional; supply it for accurate error file paths.
+ */
+declare function parseRoutes(raw: unknown, sourceFile?: string): Result<ParsedRoutes>;
+
+/**
+ * Validates a raw roles.json object and produces a ParsedRoles value.
+ *
+ * Validation rules (all errors are accumulated — none stop early):
+ *   MISSING_REQUIRED_FIELD   — name, label, hierarchy_level, or permissions absent
+ *   INVALID_PERMISSION       — roles:create, roles:edit, or roles:delete present
+ *   UNKNOWN_PERMISSION       — any other unrecognised permission string
+ *   DUPLICATE_HIERARCHY_LEVEL — two roles share the same hierarchy_level value
+ *
+ * Returns Result<ParsedRoles> — never throws for expected failures.
+ * sourceFile is optional; supply it for accurate error file paths.
+ */
+declare function parseRoles(raw: unknown, sourceFile?: string): Result<ParsedRoles>;
+
+type ErrorCode = ParseErrorCode | 'NOT_FOUND' | 'SLUG_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'INTERNAL_ERROR' | 'VALIDATION_ERROR' | 'INVALID_SLUG_FORMAT' | 'SLUG_CONFLICT' | 'PUBLISH_VALIDATION_ERROR' | 'SINGLETON_ALREADY_EXISTS' | 'UNAUTHORIZED' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'INSUFFICIENT_PERMISSION' | 'INSUFFICIENT_PRIVILEGE' | 'INVALID_FILTER_FIELD' | 'INVALID_FILTER_OPERATOR' | 'INVALID_SORT_FIELD' | 'INVALID_PAGINATION' | 'INVALID_INCLUDE_FIELD' | 'UNSUPPORTED_MIME_TYPE' | 'STORAGE_ERROR' | 'MEDIA_IN_USE' | 'PRESIGNED_URL_EXPIRED' | 'FILE_TOO_LARGE' | 'RATE_LIMITED' | 'INVALID_CREDENTIALS' | 'PASSWORD_CHANGE_REQUIRED' | 'INVALID_ROLE';
+
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+
+export { type APIAdapter, type AdminAdapter, type ContentDbMeta, type ContentRepository, type CorsConfig, type CreateInput, type CreateMediaInput, type DbAdapter, type DbColumn, type DbColumnType, type ErrorCode, type FieldType, type FieldValidation, type FilterOperator, type FilterValue, type FindAllOptions, type FindManyOptions, type JWTPayload, type JunctionTable, type ManguitoConfig, type MediaFindManyOptions, type MediaItem, type MediaRepository, type MigrationResult, type MigrationStatus, type MigrationsConfig, type PaginatedResult, type ParagraphDbMeta, type ParseError, type ParseErrorCode, type ParseResult, type ParsedBasePath, type ParsedContentType, type ParsedEnumType, type ParsedField, type ParsedParagraphType, type ParsedRole, type ParsedRoles, type ParsedRoutes, type ParsedSchema, type ParsedSchemaBase, type ParsedTaxonomyType, type Permission, type PermissionAction, type PermissionTarget, type PresignedOptions, type PresignedResult, type RelationType, type ResolvedManguitoConfig, type ResolvedMediaConfig, type ResolvedMigrationsConfig, type ResolvedRateLimitConfig, type ResolvedSchemaConfig, type Result, type SchemaConfig, type SchemaFile, type SchemaFolders, type SchemaRegistry, type SchemaType, type ServerAdapter, type StorageAdapter, type SystemField, type TaxonomyDbMeta, type UiComponent, type UiMeta, type UiTab, type UpdateInput, type User, buildSchemaRegistry, defineConfig, hashPassword, loadSchemaFile, parseRoles, parseRoutes, parseSchema, validateCrossReferences, verifyPassword, walkSchemaDirectory };