@richardmcquiston01/online-catalog-cms 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,558 @@
+import { Readable } from 'node:stream';
+
+/** A text node with optional inline formatting. */
+interface TextNode {
+    type: 'text';
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}
+/** An inline hyperlink containing child inline nodes. */
+interface LinkNode {
+    type: 'link';
+    href: string;
+    children: InlineNode[];
+}
+/** Union of all inline content nodes. */
+type InlineNode = TextNode | LinkNode;
+/** A paragraph block. */
+interface ParagraphNode {
+    type: 'paragraph';
+    children: InlineNode[];
+    cssClass?: string;
+}
+/** A heading block (h1–h6). */
+interface HeadingNode {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    children: InlineNode[];
+    cssClass?: string;
+}
+/** An inline image embedded in the document. */
+interface RichTextImageNode {
+    type: 'image';
+    src: string;
+    alt: string;
+    cssClass?: string;
+}
+/** An ordered or unordered list. Each item is an array of inline nodes. */
+interface ListNode {
+    type: 'list';
+    ordered: boolean;
+    items: InlineNode[][];
+    cssClass?: string;
+}
+/** A block-level quote. */
+interface BlockquoteNode {
+    type: 'blockquote';
+    children: InlineNode[];
+    cssClass?: string;
+}
+/** Union of all block-level content nodes. */
+type RichTextNode = ParagraphNode | HeadingNode | RichTextImageNode | ListNode | BlockquoteNode;
+/**
+ * The JSON document schema for rich-text descriptions.
+ * CSS classes are per-node so consumers control styling without a theming API.
+ */
+interface RichTextDocument {
+    version: 1;
+    nodes: RichTextNode[];
+}
+
+/**
+ * A product category. Categories are hierarchical: a category may have a
+ * `parentId` pointing to another category.
+ */
+interface Category {
+    id: string;
+    name: string;
+    slug: string;
+    parentId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input for creating a new category. */
+interface CreateCategoryInput {
+    name: string;
+    slug?: string;
+    parentId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/** Fields that may be updated on an existing category. */
+interface UpdateCategoryInput {
+    name?: string;
+    slug?: string;
+    parentId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/** Filters for listing categories. */
+interface CategoryFilter {
+    parentId?: string | null;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+
+/** A media image associated with a product. */
+interface Image {
+    id: string;
+    productId: string;
+    url: string;
+    altText: string;
+    sortOrder: number;
+    createdAt: Date;
+}
+/** Input for associating a new image with a product. */
+interface CreateImageInput {
+    productId: string;
+    url: string;
+    altText: string;
+    sortOrder?: number;
+}
+
+/**
+ * A catalog product. `price` is stored in the smallest currency unit
+ * (e.g. cents) to avoid floating-point rounding issues.
+ */
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    description: RichTextDocument;
+    /** Price in smallest currency unit (e.g. cents). */
+    price: number;
+    sku: string | null;
+    categoryId: string | null;
+    images: Image[];
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Input for creating a new product. */
+interface CreateProductInput {
+    name: string;
+    description: RichTextDocument;
+    price: number;
+    slug?: string;
+    sku?: string | null;
+    categoryId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/** Fields that may be updated on an existing product. */
+interface UpdateProductInput {
+    name?: string;
+    slug?: string;
+    description?: RichTextDocument;
+    price?: number;
+    sku?: string | null;
+    categoryId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/** Filters for listing products. */
+interface ProductFilter {
+    categoryId?: string | null;
+    search?: string;
+    minPrice?: number;
+    maxPrice?: number;
+    limit?: number;
+    offset?: number;
+}
+
+/** Result returned by adapter.verify(). */
+interface VerificationResult {
+    ok: boolean;
+    issues: string[];
+}
+/** CRUD operations for products. */
+interface ProductRepository {
+    create(input: CreateProductInput): Promise<Product>;
+    get(id: string): Promise<Product | null>;
+    update(id: string, input: UpdateProductInput): Promise<Product>;
+    delete(id: string): Promise<void>;
+    list(filter?: ProductFilter): Promise<Product[]>;
+}
+/** CRUD operations for categories. */
+interface CategoryRepository {
+    create(input: CreateCategoryInput): Promise<Category>;
+    get(id: string): Promise<Category | null>;
+    update(id: string, input: UpdateCategoryInput): Promise<Category>;
+    delete(id: string): Promise<void>;
+    list(filter?: CategoryFilter): Promise<Category[]>;
+}
+/** CRUD operations for images. */
+interface ImageRepository {
+    create(input: CreateImageInput): Promise<Image>;
+    get(id: string): Promise<Image | null>;
+    delete(id: string): Promise<void>;
+    listByProduct(productId: string): Promise<Image[]>;
+}
+/**
+ * Contract that every database adapter must implement.
+ * Consumers pass an instance of a concrete adapter to `OnlineCatalog`.
+ */
+interface DatabaseAdapter {
+    /** Runs any pending migrations, creating schema on first run. */
+    initialize(): Promise<void>;
+    /** Checks that the schema matches what the library expects. */
+    verify(): Promise<VerificationResult>;
+    /** Releases all connections and cleans up resources. */
+    close(): Promise<void>;
+    readonly products: ProductRepository;
+    readonly categories: CategoryRepository;
+    readonly images: ImageRepository;
+}
+
+/** Options passed to a storage adapter's upload method. */
+interface UploadOptions {
+    /** MIME type of the file, e.g. "image/jpeg". */
+    contentType?: string;
+    /** Whether the file should be publicly readable. Defaults to true. */
+    public?: boolean;
+}
+/**
+ * Contract that every storage adapter must implement.
+ * Consumers pass an instance to `OnlineCatalog` for image/file handling.
+ */
+interface StorageAdapter {
+    /**
+     * Upload a file and return its public URL.
+     * @param file - File content as a Buffer or Readable stream.
+     * @param filename - Desired filename (may be modified by the adapter).
+     * @param options - Optional upload metadata.
+     * @returns The public URL at which the file can be accessed.
+     */
+    upload(file: Buffer | Readable, filename: string, options?: UploadOptions): Promise<string>;
+    /**
+     * Delete a file by its URL.
+     * No-ops silently if the file does not exist.
+     */
+    delete(url: string): Promise<void>;
+    /**
+     * Derive the public URL for a storage key without making a network call.
+     * Useful for building URLs after listing keys from the storage backend.
+     */
+    getPublicUrl(key: string): string;
+}
+
+/** Create a plain text inline node. */
+declare function text(content: string, options?: {
+    bold?: boolean;
+    italic?: boolean;
+    code?: boolean;
+}): TextNode;
+/** Create a hyperlink inline node. */
+declare function link(href: string, children: InlineNode[]): LinkNode;
+/** Create a paragraph block node. */
+declare function paragraph(children: InlineNode[], cssClass?: string): ParagraphNode;
+/** Create a heading block node (h1–h6). */
+declare function heading(level: 1 | 2 | 3 | 4 | 5 | 6, children: InlineNode[], cssClass?: string): HeadingNode;
+/** Create an inline image node. */
+declare function image(src: string, alt: string, cssClass?: string): RichTextImageNode;
+/** Create an unordered list node. */
+declare function unorderedList(items: InlineNode[][], cssClass?: string): ListNode;
+/** Create an ordered list node. */
+declare function orderedList(items: InlineNode[][], cssClass?: string): ListNode;
+/** Create a blockquote node. */
+declare function blockquote(children: InlineNode[], cssClass?: string): BlockquoteNode;
+/** Wrap an array of block nodes into a complete RichTextDocument. */
+declare function document(nodes: RichTextDocument['nodes']): RichTextDocument;
+
+/**
+ * Returns true if `value` is a valid {@link RichTextDocument}.
+ * Use this at system boundaries (e.g. API input) before persisting content.
+ */
+declare function isRichTextDocument(value: unknown): value is RichTextDocument;
+/**
+ * Throws a `TypeError` if `value` is not a valid {@link RichTextDocument}.
+ */
+declare function assertRichTextDocument(value: unknown): asserts value is RichTextDocument;
+
+interface InstallOptions {
+    /** If true, describe what would happen without making changes. */
+    dryRun?: boolean;
+}
+/** Wraps adapter initialization and verification with helpful logging. */
+declare class Installer {
+    private readonly adapter;
+    constructor(adapter: DatabaseAdapter);
+    /**
+     * Run database migrations and verify the resulting schema.
+     * @returns The verification result after migration.
+     */
+    install(options?: InstallOptions): Promise<VerificationResult>;
+    /** Check that the schema is correct without running migrations. */
+    verify(): Promise<VerificationResult>;
+}
+
+/** High-level category operations. */
+declare class CategoryService {
+    private readonly repo;
+    constructor(repo: CategoryRepository);
+    create(input: CreateCategoryInput): Promise<Category>;
+    get(id: string): Promise<Category | null>;
+    update(id: string, input: UpdateCategoryInput): Promise<Category>;
+    delete(id: string): Promise<void>;
+    list(filter?: CategoryFilter): Promise<Category[]>;
+}
+
+interface UploadImageInput {
+    productId: string;
+    file: Buffer | Readable;
+    filename: string;
+    altText: string;
+    contentType?: string;
+    sortOrder?: number;
+}
+/** Handles image uploads and associates them with products. */
+declare class ImageService {
+    private readonly repo;
+    private readonly storage?;
+    constructor(repo: ImageRepository, storage?: StorageAdapter | undefined);
+    /**
+     * Upload a file via the storage adapter and create an image record.
+     * Requires a storage adapter to be configured.
+     */
+    upload(input: UploadImageInput): Promise<Image>;
+    /** Associate an already-hosted image URL with a product. */
+    addUrl(input: CreateImageInput): Promise<Image>;
+    get(id: string): Promise<Image | null>;
+    delete(id: string): Promise<void>;
+    listByProduct(productId: string): Promise<Image[]>;
+}
+
+/** High-level product operations. Wraps the DB repository with slug generation. */
+declare class ProductService {
+    private readonly repo;
+    private readonly storage?;
+    constructor(repo: ProductRepository, storage?: StorageAdapter | undefined);
+    create(input: CreateProductInput): Promise<Product>;
+    get(id: string): Promise<Product | null>;
+    update(id: string, input: UpdateProductInput): Promise<Product>;
+    delete(id: string): Promise<void>;
+    list(filter?: ProductFilter): Promise<Product[]>;
+}
+
+interface OnlineCatalogConfig {
+    /** Database adapter for persisting catalog data. */
+    db: DatabaseAdapter;
+    /** Storage adapter for image/file uploads. Optional. */
+    storage?: StorageAdapter;
+}
+/**
+ * Main entry point for online-catalog-cms.
+ *
+ * @example
+ * ```ts
+ * const catalog = new OnlineCatalog({ db: new SQLiteAdapter({ filename: './catalog.db' }) });
+ * await catalog.initialize();
+ * const product = await catalog.products.create({ name: 'Widget', price: 999, description: ... });
+ * ```
+ */
+declare class OnlineCatalog {
+    readonly products: ProductService;
+    readonly categories: CategoryService;
+    readonly images: ImageService;
+    readonly installer: Installer;
+    private readonly db;
+    constructor(config: OnlineCatalogConfig);
+    /**
+     * Initialize the catalog. Runs database migrations on first use.
+     * Must be called before any other method.
+     */
+    initialize(): Promise<void>;
+    /** Release all resources held by the database adapter. */
+    close(): Promise<void>;
+}
+
+interface SQLRunner {
+    /** Execute a statement that returns no rows. */
+    run(sql: string, params?: unknown[]): Promise<void>;
+    /** Execute a query and return all rows. */
+    all<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Execute a query and return the first row, or undefined. */
+    get<T>(sql: string, params?: unknown[]): Promise<T | undefined>;
+}
+/**
+ * Shared logic for relational SQL adapters: migration runner and schema
+ * verification. Concrete adapters extend this and supply a `SQLRunner`.
+ */
+declare abstract class BaseSQLAdapter {
+    protected abstract readonly db: SQLRunner;
+    /** Dialect-specific table existence query — must return rows with a `name` column. */
+    protected abstract tableExistsQuery(table: string): string;
+    protected abstract get migrationSql(): string;
+    initialize(): Promise<void>;
+    verify(): Promise<VerificationResult>;
+}
+
+interface SQLiteConfig {
+    /** Path to the SQLite database file. Use ':memory:' for an in-memory DB. */
+    filename: string;
+}
+/** SQLite database adapter. Uses bun:sqlite in Bun, better-sqlite3 in Node.js. */
+declare class SQLiteAdapter extends BaseSQLAdapter implements DatabaseAdapter {
+    private runner?;
+    private closeHandle?;
+    private readonly config;
+    private _products?;
+    private _categories?;
+    private _images?;
+    constructor(config: SQLiteConfig);
+    protected get db(): SQLRunner;
+    get products(): ProductRepository;
+    get categories(): CategoryRepository;
+    get images(): ImageRepository;
+    /** Must be called before any other method. Sets up the SQLite driver. */
+    initialize(): Promise<void>;
+    protected get migrationSql(): string;
+    protected tableExistsQuery(table: string): string;
+    verify(): Promise<VerificationResult>;
+    close(): Promise<void>;
+}
+
+interface PostgresConfig {
+    /** postgres.js connection string or config object. */
+    url: string;
+}
+/** PostgreSQL database adapter using postgres.js. */
+declare class PostgresAdapter extends BaseSQLAdapter implements DatabaseAdapter {
+    protected readonly db: SQLRunner;
+    readonly products: ProductRepository;
+    readonly categories: CategoryRepository;
+    readonly images: ImageRepository;
+    private readonly sql;
+    constructor(config: PostgresConfig);
+    protected get migrationSql(): string;
+    protected tableExistsQuery(table: string): string;
+    verify(): Promise<VerificationResult>;
+    close(): Promise<void>;
+}
+
+interface MySQLConfig {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+}
+/** MySQL / MariaDB adapter using mysql2. */
+declare class MySQLAdapter extends BaseSQLAdapter implements DatabaseAdapter {
+    protected readonly db: SQLRunner;
+    readonly products: ProductRepository;
+    readonly categories: CategoryRepository;
+    readonly images: ImageRepository;
+    private readonly pool;
+    constructor(config: MySQLConfig);
+    protected get migrationSql(): string;
+    protected tableExistsQuery(table: string): string;
+    verify(): Promise<VerificationResult>;
+    close(): Promise<void>;
+}
+
+interface RedisConfig {
+    /** ioredis connection URL, e.g. 'redis://localhost:6379'. */
+    url: string;
+    /** Optional key prefix to namespace all catalog keys. Defaults to 'occ'. */
+    keyPrefix?: string;
+}
+/**
+ * Redis adapter. Data is stored as JSON strings in Redis hashes.
+ *
+ * Key layout:
+ *   {prefix}:product:{id}          — product JSON
+ *   {prefix}:products:all          — set of all product IDs
+ *   {prefix}:products:cat:{catId}  — set of product IDs by category
+ *   {prefix}:category:{id}         — category JSON
+ *   {prefix}:categories:all        — set of all category IDs
+ *   {prefix}:image:{id}            — image JSON
+ *   {prefix}:images:product:{pid}  — sorted set of image IDs by sort_order
+ */
+declare class RedisAdapter implements DatabaseAdapter {
+    private readonly client;
+    private readonly prefix;
+    readonly products: ProductRepository;
+    readonly categories: CategoryRepository;
+    readonly images: ImageRepository;
+    constructor(config: RedisConfig);
+    initialize(): Promise<void>;
+    verify(): Promise<VerificationResult>;
+    close(): Promise<void>;
+}
+
+interface MongoDBConfig {
+    /** MongoDB connection string, e.g. 'mongodb://localhost:27017'. */
+    url: string;
+    /** Database name. Defaults to 'online_catalog'. */
+    database?: string;
+}
+/** MongoDB adapter. Each entity type maps to its own collection. */
+declare class MongoDBAdapter implements DatabaseAdapter {
+    private readonly client;
+    private readonly dbName;
+    readonly products: ProductRepository;
+    readonly categories: CategoryRepository;
+    readonly images: ImageRepository;
+    constructor(config: MongoDBConfig);
+    initialize(): Promise<void>;
+    verify(): Promise<VerificationResult>;
+    close(): Promise<void>;
+}
+
+interface LocalStorageConfig {
+    /** Absolute path to the directory where uploaded files will be stored. */
+    uploadDir: string;
+    /**
+     * Base URL prefix for returned file URLs, e.g. 'http://localhost:3000/uploads'.
+     * Defaults to '/uploads' (a relative path).
+     */
+    baseUrl?: string;
+}
+/** Storage adapter that writes files to the local filesystem. */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly uploadDir;
+    private readonly baseUrl;
+    constructor(config: LocalStorageConfig);
+    upload(file: Buffer | Readable, filename: string, _options?: UploadOptions): Promise<string>;
+    delete(url: string): Promise<void>;
+    getPublicUrl(key: string): string;
+    private urlToKey;
+}
+
+interface S3Config {
+    bucket: string;
+    region: string;
+    /** Custom endpoint for S3-compatible services (MinIO, Cloudflare R2, etc.). */
+    endpoint?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Whether objects should default to public-read ACL. Defaults to true. */
+    publicRead?: boolean;
+}
+/** S3-compatible storage adapter using @aws-sdk/client-s3. */
+declare class S3Adapter implements StorageAdapter {
+    private readonly client;
+    private readonly bucket;
+    private readonly publicRead;
+    private readonly baseUrl;
+    private readonly aws;
+    constructor(config: S3Config);
+    upload(file: Buffer | Readable, filename: string, options?: UploadOptions): Promise<string>;
+    delete(url: string): Promise<void>;
+    getPublicUrl(key: string): string;
+    private urlToKey;
+}
+
+/**
+ * Storage adapter for externally-hosted images.
+ * `upload` is not supported — pass URLs directly in `CreateImageInput.url`
+ * and this adapter stores them as-is.
+ */
+declare class ExternalURLAdapter implements StorageAdapter {
+    upload(_file: Buffer | Readable, _filename: string, _options?: UploadOptions): Promise<string>;
+    delete(_url: string): Promise<void>;
+    getPublicUrl(key: string): string;
+}
+
+export { type BlockquoteNode, type Category, type CategoryFilter, type CategoryRepository, type CreateCategoryInput, type CreateImageInput, type CreateProductInput, type DatabaseAdapter, ExternalURLAdapter, type HeadingNode, type Image, type ImageRepository, type InlineNode, type InstallOptions, Installer, type LinkNode, type ListNode, LocalStorageAdapter, type LocalStorageConfig, MongoDBAdapter, type MongoDBConfig, MySQLAdapter, type MySQLConfig, OnlineCatalog, type OnlineCatalogConfig, type ParagraphNode, PostgresAdapter, type PostgresConfig, type Product, type ProductFilter, type ProductRepository, RedisAdapter, type RedisConfig, type RichTextDocument, type RichTextImageNode, type RichTextNode, S3Adapter, type S3Config, SQLiteAdapter, type SQLiteConfig, type StorageAdapter, type TextNode, type UpdateCategoryInput, type UpdateProductInput, type UploadOptions, type VerificationResult, assertRichTextDocument, blockquote, document, heading, image, isRichTextDocument, link, orderedList, paragraph, text, unorderedList };