@inneropen/marvin-sdk 2.0.0 → 3.0.0

package/dist/marvin-BAslemIz.d.cts

@@ -0,0 +1,666 @@
+import { PublishedEntryType, MarvinResource, MarvinEntry, MarvinAsset, MarvinCollection, MarvinEntryType, MarvinSite, GetResourcesOptions as GetResourcesOptions$1 } from './types/index.cjs';
+import { H as HttpClient } from './HttpClient-CdF3IHM1.cjs';
+
+/**
+ * Marvin SDK Configuration
+ */
+interface MarvinConfig {
+    apiUrl: string;
+    siteClientToken: string;
+    workspaceSlug: string;
+    /** Enable automatic initialization on client creation */
+    autoInitialize?: boolean;
+    /** Cache duration in milliseconds (default: 5 minutes) */
+    cacheDuration?: number;
+    /** Enable debug logging for HTTP requests and responses */
+    debug?: boolean;
+    /** Custom logger function (defaults to console) */
+    logger?: {
+        log: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
+}
+declare function createConfigFromEnv(overrides?: Partial<MarvinConfig>): MarvinConfig;
+
+/**
+ * Base error class for all Marvin SDK errors
+ */
+declare class MarvinError extends Error {
+    readonly code?: string | undefined;
+    readonly statusCode?: number | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined);
+}
+/**
+ * HTTP/API request errors
+ */
+declare class MarvinApiError extends MarvinError {
+    readonly statusCode: number;
+    readonly endpoint: string;
+    readonly responseBody?: string | undefined;
+    constructor(message: string, statusCode: number, endpoint: string, responseBody?: string | undefined);
+    static fromResponse(status: number, statusText: string, endpoint: string, body?: string): MarvinApiError;
+}
+/**
+ * Authentication/authorization errors
+ */
+declare class MarvinAuthError extends MarvinError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Configuration errors
+ */
+declare class MarvinConfigError extends MarvinError {
+    constructor(message: string);
+}
+/**
+ * Validation errors
+ */
+declare class MarvinValidationError extends MarvinError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Resource not found errors (404)
+ */
+declare class MarvinNotFoundError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, endpoint: string);
+}
+/**
+ * Network/connectivity errors
+ */
+declare class MarvinNetworkError extends MarvinError {
+    readonly originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * Server errors (5xx)
+ */
+declare class MarvinServerError extends MarvinError {
+    readonly endpoint: string;
+    constructor(message: string, statusCode: number, endpoint: string);
+}
+
+/**
+ * Pagination response types and helpers
+ */
+interface PaginationMeta {
+    total?: number;
+    page?: number;
+    limit?: number;
+    offset?: number;
+    hasMore?: boolean;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    meta?: PaginationMeta;
+}
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+    page?: number;
+}
+/**
+ * Create a paginated response
+ */
+declare function createPaginatedResponse<T>(data: T[], meta?: PaginationMeta): PaginatedResponse<T>;
+/**
+ * Extract data from paginated response
+ */
+declare function extractData<T>(response: PaginatedResponse<T> | T[]): T[];
+/**
+ * Check if response is paginated
+ */
+declare function isPaginatedResponse<T>(response: PaginatedResponse<T> | T[]): response is PaginatedResponse<T>;
+/**
+ * Calculate pagination offset from page number
+ */
+declare function pageToOffset(page: number, limit: number): number;
+/**
+ * Calculate page number from offset
+ */
+declare function offsetToPage(offset: number, limit: number): number;
+
+/**
+ * Simple in-memory cache for SDK data
+ *
+ * Stores data with automatic expiration based on timestamp.
+ * Thread-safe in single-threaded environments (browser/Node.js).
+ */
+declare class MarvinCache {
+    private duration;
+    private maxEntries;
+    private cache;
+    constructor(duration?: number, maxEntries?: number);
+    /**
+     * Get cached data by key
+     * Returns undefined if not found or expired
+     */
+    get<T = unknown>(key: string): T | undefined;
+    /**
+     * Set cached data with optional tags for invalidation
+     */
+    set<T = unknown>(key: string, data: T, tags?: string[]): void;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Delete a specific cache entry
+     */
+    delete(key: string): void;
+    /**
+     * Invalidate all cache entries with a specific tag
+     * Useful for invalidating related data after mutations
+     *
+     * @example
+     * ```typescript
+     * // Cache entries with tags
+     * cache.set('entry:1', data, ['entries', 'entry:1']);
+     * cache.set('entries:list', data, ['entries']);
+     *
+     * // Invalidate all entries
+     * cache.invalidateByTag('entries');
+     * ```
+     */
+    invalidateByTag(tag: string): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxEntries: number;
+        oldestEntry: number | null;
+        newestEntry: number | null;
+    };
+    /**
+     * Remove expired entries (garbage collection)
+     * Returns number of entries removed
+     */
+    prune(): number;
+}
+
+/**
+ * HTTP Client for Marvin Publishing API
+ *
+ * Wrapper around core HttpClient for Publishing API specifics
+ */
+
+declare class MarvinHttpClient extends HttpClient {
+    constructor(config: MarvinConfig);
+    /**
+     * Fetch endpoint (backward compatibility)
+     */
+    fetch<T>(endpoint: string): Promise<T>;
+}
+
+declare class RenderersModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    list(): Promise<PublishedEntryType[]>;
+}
+
+/**
+ * Resource - Rich object representing a single resource
+ */
+
+declare class Resource {
+    private data;
+    private http;
+    private workspaceSlug;
+    constructor(data: MarvinResource, http: MarvinHttpClient, workspaceSlug: string);
+    get id(): string;
+    get name(): string;
+    get slug(): string;
+    get resourceType(): string | undefined;
+    get description(): string | undefined;
+    get externalId(): string | undefined;
+    get url(): string | undefined;
+    get metadata(): Record<string, unknown> | undefined;
+    get createdAt(): string;
+    get updatedAt(): string;
+    /**
+     * Get all entries that reference this resource
+     */
+    entries(): Promise<MarvinEntry[]>;
+    /**
+     * Get assets related to this resource (future)
+     */
+    assets(): Promise<MarvinAsset[]>;
+    /**
+     * Get raw resource data
+     */
+    toJSON(): MarvinResource;
+}
+
+/**
+ * Resources Module - Manage resources
+ */
+
+interface GetResourcesOptions {
+    resourceType?: string;
+    limit?: number;
+    offset?: number;
+}
+declare class ResourcesModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    /**
+     * Get all published resources
+     */
+    list(options?: GetResourcesOptions): Promise<MarvinResource[]>;
+    /**
+     * Get a single resource by slug
+     */
+    get(slug: string): Promise<Resource>;
+    /**
+     * Get entries that reference this resource
+     */
+    entries(slug: string): Promise<MarvinEntry[]>;
+}
+
+/**
+ * Assets Module - Manage assets
+ */
+
+interface GetAssetsOptions {
+    type?: string;
+    limit?: number;
+    offset?: number;
+}
+declare class AssetsModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    /**
+     * Get all published assets
+     */
+    list(options?: GetAssetsOptions): Promise<MarvinAsset[]>;
+    /**
+     * Get a single published asset by slug or ID
+     */
+    get(slugOrId: string): Promise<MarvinAsset>;
+    /**
+     * Convenience: Get all images
+     */
+    images(options?: Omit<GetAssetsOptions, 'type'>): Promise<MarvinAsset[]>;
+    /**
+     * Convenience: Get all videos
+     */
+    videos(options?: Omit<GetAssetsOptions, 'type'>): Promise<MarvinAsset[]>;
+    /**
+     * Convenience: Get all documents
+     */
+    documents(options?: Omit<GetAssetsOptions, 'type'>): Promise<MarvinAsset[]>;
+}
+
+/**
+ * Collection - Rich object representing a single collection
+ */
+
+declare class Collection {
+    private data;
+    private http;
+    private workspaceSlug;
+    constructor(data: MarvinCollection, http: MarvinHttpClient, workspaceSlug: string);
+    get id(): string;
+    get name(): string;
+    get slug(): string;
+    get description(): string | undefined;
+    get icon(): string | undefined;
+    get color(): string | undefined;
+    get sortOrder(): number;
+    get isSmart(): boolean;
+    get smartRules(): Record<string, unknown> | undefined;
+    get createdAt(): string;
+    get updatedAt(): string;
+    /**
+     * Get all entries in this collection
+     */
+    entries(): Promise<MarvinEntry[]>;
+    /**
+     * Get assets in this collection (future)
+     */
+    assets(): Promise<MarvinAsset[]>;
+    /**
+     * Get collection metadata (future)
+     */
+    metadata(): Promise<any>;
+    /**
+     * Get raw collection data
+     */
+    toJSON(): MarvinCollection;
+}
+
+/**
+ * Collections Module - Manage collections
+ */
+
+declare class CollectionsModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    /**
+     * Get all collections
+     */
+    list(): Promise<MarvinCollection[]>;
+    /**
+     * Get a single collection by slug
+     * Returns null if collection is not found (404)
+     */
+    get(slug: string): Promise<Collection | null>;
+    /**
+     * Get entries in a collection
+     * Returns empty array if collection is not found
+     */
+    entries(slug: string): Promise<MarvinEntry[]>;
+    /**
+     * Try multiple collection slugs in fallback order
+     * Returns the first collection that exists and has entries
+     *
+     * @param slugs - Collection slugs to try in order
+     * @param options - Options for fallback behavior
+     * @returns Entries from the first matching collection, or empty array
+     *
+     * @example
+     * ```ts
+     * // Try bench-notes, then journal, then blog
+     * const entries = await collections.fallback(['bench-notes', 'journal', 'blog']);
+     * ```
+     */
+    fallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
+}
+
+declare class Entry {
+    private data;
+    private http;
+    private workspaceSlug;
+    constructor(data: MarvinEntry, http: MarvinHttpClient, workspaceSlug: string);
+    get id(): string;
+    get title(): string;
+    get slug(): string;
+    get summary(): string | undefined;
+    get description(): string | undefined;
+    /**
+     * @deprecated Use field('body') or dataJson instead. Will be removed in v3.0.0
+     */
+    get contentMarkdown(): string | undefined;
+    /**
+     * Schema-driven content data (replaces contentMarkdown in v2.0.0).
+     * Access specific fields using the field() helper method.
+     * @since 2.0.0
+     */
+    get dataJson(): Record<string, unknown> | undefined;
+    get metadata(): Record<string, unknown> | undefined;
+    get status(): string;
+    get publishedAt(): string | undefined;
+    get createdAt(): string;
+    get updatedAt(): string;
+    get entryTypeId(): string;
+    get entryType(): MarvinEntryType | undefined;
+    /**
+     * Get entry assets
+     */
+    get assets(): MarvinAsset[];
+    /**
+     * Get entry collections
+     */
+    get collections(): MarvinCollection[];
+    /**
+     * Get a specific field value from the entry's schema-driven content (dataJson).
+     *
+     * @param key - Field key as defined in the entry type's schema
+     * @returns The field value, or undefined if not present
+     * @since 2.0.0
+     *
+     * @example
+     * ```typescript
+     * const entry = await client.entries.get('my-entry');
+     * const body = entry.field('body');           // Get markdown body
+     * const difficulty = entry.field('difficulty'); // Get difficulty level
+     * const heroImage = entry.field('heroImage');  // Get hero image UUID
+     * ```
+     */
+    field<T = unknown>(key: string): T | undefined;
+    /**
+     * Get all fields from the entry's schema-driven content.
+     * @since 2.0.0
+     */
+    get fields(): Record<string, unknown>;
+    /**
+     * Get related entries (future)
+     */
+    relatedEntries(): Promise<MarvinEntry[]>;
+    /**
+     * Get raw entry data
+     */
+    toJSON(): MarvinEntry;
+}
+
+/**
+ * Entries Module - Manage entries
+ */
+
+interface GetEntriesOptions {
+    entryType?: string;
+    collection?: string;
+    limit?: number;
+    offset?: number;
+    status?: string;
+}
+declare class EntriesModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    /**
+     * Get all published entries
+     */
+    list(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
+    /**
+     * Get a single entry by slug
+     * Returns null if entry is not found (404)
+     */
+    get(slug: string): Promise<Entry | null>;
+    /**
+     * Convenience: Get all pages
+     */
+    pages(options?: Omit<GetEntriesOptions, 'entryType'>): Promise<MarvinEntry[]>;
+    /**
+     * Convenience: Get all blog posts
+     */
+    posts(options?: Omit<GetEntriesOptions, 'entryType'>): Promise<MarvinEntry[]>;
+    /**
+     * Convenience: Get all projects
+     */
+    projects(options?: Omit<GetEntriesOptions, 'entryType'>): Promise<MarvinEntry[]>;
+}
+
+/**
+ * Workspace - First-class object representing a Marvin workspace
+ */
+
+declare class Workspace {
+    private http;
+    private _site;
+    private _slug;
+    entries: EntriesModule;
+    collections: CollectionsModule;
+    assets: AssetsModule;
+    resources: ResourcesModule;
+    renderers: RenderersModule;
+    constructor(http: MarvinHttpClient, slug: string);
+    /**
+     * Get workspace slug
+     */
+    get slug(): string;
+    /**
+     * Get site configuration (cached after first load)
+     */
+    get site(): MarvinSite | null;
+    /**
+     * Load site configuration
+     */
+    loadSite(): Promise<MarvinSite>;
+    /**
+     * Get workspace info (name and slug only)
+     */
+    getInfo(): Promise<{
+        slug: string;
+        name: string;
+    }>;
+    /**
+     * Get workspace settings (future)
+     */
+    settings(): Promise<any>;
+}
+
+declare class MarvinClient {
+    private config;
+    private http;
+    private cache;
+    private workspace;
+    private initialized;
+    constructor(config: MarvinConfig);
+    /**
+     * Initialize the SDK
+     * Preloads site configuration and metadata
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the workspace object
+     */
+    getWorkspace(): Promise<Workspace>;
+    /**
+     * Get site configuration (cached)
+     */
+    get site(): MarvinSite | null;
+    /**
+     * Get workspace info (name and slug)
+     */
+    getWorkspaceInfo(): Promise<{
+        slug: string;
+        name: string;
+    }>;
+    /**
+     * Get entries module
+     */
+    get entries(): EntriesModule;
+    /**
+     * Get collections module
+     */
+    get collections(): CollectionsModule;
+    /**
+     * Get assets module
+     */
+    get assets(): AssetsModule;
+    /**
+     * Get resources module
+     */
+    get resources(): ResourcesModule;
+    /**
+     * Get renderers module
+     */
+    get renderers(): RenderersModule;
+    /**
+     * Get a single entry by slug
+     */
+    entry(slug: string): Promise<Entry | null>;
+    /**
+     * Get a single collection by slug
+     */
+    collection(slug: string): Promise<Collection | null>;
+    /**
+     * Get all pages
+     */
+    pages(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
+    /**
+     * Get all blog posts
+     */
+    posts(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
+    /**
+     * Get all projects
+     */
+    projects(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
+    /**
+     * Get a single resource by slug
+     */
+    resource(slug: string): Promise<Resource>;
+    /**
+     * Try multiple collection slugs in fallback order
+     * Returns entries from the first collection that exists and has content
+     *
+     * @param slugs - Collection slugs to try in order
+     * @param options - Options for fallback behavior
+     * @returns Entries from the first matching collection, or empty array
+     *
+     * @example
+     * ```ts
+     * // Try bench-notes, then journal, then blog
+     * const entries = await client.collectionFallback(['bench-notes', 'journal', 'blog']);
+     * ```
+     */
+    collectionFallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntry[]>;
+    /**
+     * @deprecated Use workspace.site or marvin.site instead
+     * Get site configuration
+     */
+    getSite(): Promise<MarvinSite>;
+    /**
+     * @deprecated Use workspace.entries.list() instead
+     * Get all published entries
+     */
+    getEntries(options?: GetEntriesOptions): Promise<MarvinEntry[]>;
+    /**
+     * @deprecated Use workspace.entries.get() instead
+     * Get a single published entry by slug
+     */
+    getEntry(slug: string): Promise<MarvinEntry | null>;
+    /**
+     * @deprecated Use workspace.collections.list() instead
+     * Get all collections
+     */
+    getCollections(): Promise<MarvinCollection[]>;
+    /**
+     * @deprecated Use workspace.collections.get() instead
+     * Get a single collection by slug
+     */
+    getCollection(slug: string): Promise<MarvinCollection | null>;
+    /**
+     * @deprecated Use workspace.collections.entries() instead
+     * Get all entries in a collection
+     */
+    getCollectionEntries(slug: string): Promise<MarvinEntry[]>;
+    /**
+     * @deprecated Use workspace.assets.list() instead
+     * Get all published assets
+     */
+    getAssets(options?: GetAssetsOptions): Promise<MarvinAsset[]>;
+    /**
+     * @deprecated Use workspace.resources.list() instead
+     * Get all published resources
+     */
+    getResources(options?: GetResourcesOptions$1): Promise<MarvinResource[]>;
+    /**
+     * @deprecated Use workspace.resources.get() instead
+     * Get a single resource by slug
+     */
+    getResource(slug: string): Promise<MarvinResource>;
+    /**
+     * @deprecated Use workspace.resources.entries() instead
+     * Get entries that reference a resource
+     */
+    getResourceEntries(slug: string): Promise<MarvinEntry[]>;
+}
+
+export { Collection as C, Entry as E, type MarvinConfig as M, type PaginatedResponse as P, Resource as R, Workspace as W, MarvinClient as a, MarvinApiError as b, MarvinAuthError as c, MarvinCache as d, MarvinConfigError as e, MarvinError as f, MarvinNetworkError as g, MarvinNotFoundError as h, MarvinServerError as i, MarvinValidationError as j, type PaginationMeta as k, type PaginationParams as l, createConfigFromEnv as m, createPaginatedResponse as n, extractData as o, isPaginatedResponse as p, offsetToPage as q, pageToOffset as r };