@inneropen/marvin-sdk 2.0.1 → 3.0.1

package/dist/marvin-C5tRQ2nD.d.ts

@@ -0,0 +1,611 @@
+import { k as PublishedEntryType, h as MarvinResource, M as MarvinAsset, c as MarvinCollection, e as MarvinEntryListItem, j as PublishedCollectionSummary, d as MarvinEntry, P as PublishedAssetRead, l as PublishedResourceRead, i as MarvinSite, m as components, b as GetResourcesOptions$1 } from './index-D5zkKa4N.js';
+import { H as HttpClient } from './HttpClient-CdF3IHM1.js';
+
+/**
+ * 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;
+    constructor(data: MarvinResource);
+    get name(): string;
+    get slug(): string;
+    get resourceType(): string;
+    get description(): string | null | undefined;
+    get externalId(): string | null | undefined;
+    get url(): string | null | undefined;
+    get metadataJson(): {
+        [key: string]: unknown;
+    } | null | undefined;
+    get entries(): string[];
+    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 entry slugs that reference this resource
+     */
+    entries(slug: string): Promise<string[]>;
+}
+
+/**
+ * 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;
+    constructor(data: MarvinCollection);
+    get name(): string;
+    get slug(): string;
+    get description(): string | null | undefined;
+    get isSmart(): boolean;
+    get smartRules(): {
+        [key: string]: unknown;
+    } | null | undefined;
+    get metadataJson(): {
+        [key: string]: unknown;
+    } | null | undefined;
+    get entryCount(): number;
+    get entries(): MarvinEntryListItem[];
+    toJSON(): MarvinCollection;
+}
+
+/**
+ * Collections Module - Manage collections
+ */
+
+declare class CollectionsModule {
+    private http;
+    private workspaceSlug;
+    constructor(http: MarvinHttpClient, workspaceSlug: string);
+    /**
+     * Get all collections
+     */
+    list(): Promise<PublishedCollectionSummary[]>;
+    /**
+     * 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<MarvinEntryListItem[]>;
+    /**
+     * Try multiple collection slugs in fallback order
+     * Returns the first collection that exists and has entries
+     */
+    fallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntryListItem[]>;
+}
+
+/**
+ * Entry - Rich object representing a single entry
+ */
+
+declare class Entry {
+    private raw;
+    constructor(raw: MarvinEntry);
+    get title(): string;
+    get slug(): string;
+    get summary(): string | null | undefined;
+    get entryType(): string;
+    get entryTypeInfo(): {
+        slug: string;
+        renderer?: string | null;
+        package?: string | null;
+        version?: string | null;
+        config?: {
+            [key: string]: unknown;
+        } | null;
+        publishable: boolean;
+        submittable: boolean;
+        routable: boolean;
+    } | null | undefined;
+    get data(): {
+        [key: string]: unknown;
+    };
+    get metadataJson(): {
+        [key: string]: unknown;
+    } | null | undefined;
+    get publishedAt(): string | null | undefined;
+    get order(): number | null | undefined;
+    get assets(): PublishedAssetRead[];
+    get collections(): PublishedCollectionSummary[];
+    get resources(): PublishedResourceRead[];
+    field<T = unknown>(key: string): T | undefined;
+    get fields(): Record<string, unknown>;
+    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<MarvinEntryListItem[]>;
+    /**
+     * 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<MarvinEntryListItem[]>;
+    /**
+     * Convenience: Get all blog posts
+     */
+    posts(options?: Omit<GetEntriesOptions, 'entryType'>): Promise<MarvinEntryListItem[]>;
+    /**
+     * Convenience: Get all projects
+     */
+    projects(options?: Omit<GetEntriesOptions, 'entryType'>): Promise<MarvinEntryListItem[]>;
+}
+
+/**
+ * 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;
+    }>;
+}
+
+declare class MarvinClient {
+    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<{
+        slug: string;
+        title: string;
+        entryType: string;
+        entryTypeInfo?: components["schemas"]["PublishedEntryTypeInfo"] | null;
+        summary?: string | null;
+        publishedAt?: string | null;
+        status: string;
+        collections: string[];
+        assetSlugs: string[];
+        resourceSlugs: string[];
+        order?: number | null;
+    }[]>;
+    /**
+     * Get all blog posts
+     */
+    posts(options?: GetEntriesOptions): Promise<{
+        slug: string;
+        title: string;
+        entryType: string;
+        entryTypeInfo?: components["schemas"]["PublishedEntryTypeInfo"] | null;
+        summary?: string | null;
+        publishedAt?: string | null;
+        status: string;
+        collections: string[];
+        assetSlugs: string[];
+        resourceSlugs: string[];
+        order?: number | null;
+    }[]>;
+    /**
+     * Get all projects
+     */
+    projects(options?: GetEntriesOptions): Promise<{
+        slug: string;
+        title: string;
+        entryType: string;
+        entryTypeInfo?: components["schemas"]["PublishedEntryTypeInfo"] | null;
+        summary?: string | null;
+        publishedAt?: string | null;
+        status: string;
+        collections: string[];
+        assetSlugs: string[];
+        resourceSlugs: string[];
+        order?: number | null;
+    }[]>;
+    /**
+     * 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
+     */
+    collectionFallback(slugs: string[], options?: {
+        requireEntries?: boolean;
+    }): Promise<MarvinEntryListItem[]>;
+    /**
+     * @deprecated Use workspace.site or marvin.site instead
+     */
+    getSite(): Promise<MarvinSite>;
+    /**
+     * @deprecated Use workspace.entries.list() instead
+     */
+    getEntries(options?: GetEntriesOptions): Promise<MarvinEntryListItem[]>;
+    /**
+     * @deprecated Use workspace.entries.get() instead
+     */
+    getEntry(slug: string): Promise<MarvinEntry | null>;
+    /**
+     * @deprecated Use workspace.collections.list() instead
+     */
+    getCollections(): Promise<PublishedCollectionSummary[]>;
+    /**
+     * @deprecated Use workspace.collections.get() instead
+     */
+    getCollection(slug: string): Promise<MarvinCollection | null>;
+    /**
+     * @deprecated Use workspace.collections.entries() instead
+     */
+    getCollectionEntries(slug: string): Promise<MarvinEntryListItem[]>;
+    /**
+     * @deprecated Use workspace.assets.list() instead
+     */
+    getAssets(options?: GetAssetsOptions): Promise<MarvinAsset[]>;
+    /**
+     * @deprecated Use workspace.resources.list() instead
+     */
+    getResources(options?: GetResourcesOptions$1): Promise<MarvinResource[]>;
+    /**
+     * @deprecated Use workspace.resources.get() instead
+     */
+    getResource(slug: string): Promise<MarvinResource>;
+    /**
+     * @deprecated Use workspace.resources.entries() instead
+     */
+    getResourceEntries(slug: string): Promise<string[]>;
+}
+
+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 };