@headroom-cms/admin-api 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,757 @@
+/**
+ * Provides JWT tokens for API authentication.
+ * Implementations handle token acquisition, caching, and refresh.
+ */
+interface TokenProvider {
+    /** Return a valid JWT access token. May refresh if expired. */
+    getToken(): Promise<string>;
+    /** Called when the API returns 401. Return a new token to retry, or throw. */
+    onUnauthorized?(): Promise<string>;
+}
+/**
+ * Simple token provider that returns a fixed token.
+ * Use for scripts and CLI tools that authenticate once upfront.
+ */
+declare class StaticTokenProvider implements TokenProvider {
+    private token;
+    constructor(token: string);
+    getToken(): Promise<string>;
+}
+
+interface components {
+    schemas: {
+        APIKeyCreateResult: {
+            /** Format: int64 */
+            createdAt: number;
+            key: string;
+            keyId: string;
+            label: string;
+        };
+        APIKeyList: {
+            keys?: components["schemas"]["APIKeyMetadata"][];
+        };
+        APIKeyMetadata: {
+            /** Format: int64 */
+            createdAt: number;
+            keyId: string;
+            label: string;
+            /** Format: int64 */
+            lastUsedAt?: number | null;
+        };
+        AdminBlockTypeList: {
+            blockTypes?: components["schemas"]["BlockType"][];
+        };
+        AdminCollectionList: {
+            collections?: components["schemas"]["Collection"][];
+        };
+        AdminContentList: {
+            cursor?: string;
+            hasMore: boolean;
+            items: components["schemas"]["ContentMetadata"][];
+        };
+        AuditEvent: {
+            action: string;
+            adminId: string;
+            /** Format: int64 */
+            createdAt: number;
+            details?: string;
+            errorMsg?: string;
+            eventId: string;
+            host?: string;
+            status: string;
+            /** Format: int64 */
+            updatedAt?: number;
+        };
+        AuditEventList: {
+            hasMore: boolean;
+            items: components["schemas"]["AuditEvent"][];
+        };
+        BlockType: {
+            fields?: components["schemas"]["FieldDef"][];
+            icon?: string;
+            label: string;
+            name: string;
+            previewTemplate?: string;
+        };
+        Collection: {
+            fields?: components["schemas"]["FieldDef"][];
+            label: string;
+            labelSingular: string;
+            name: string;
+            singleton?: boolean;
+            slug?: string;
+            version?: number;
+        };
+        CompleteUploadRequest: {
+            alt?: string;
+            caption?: string;
+            filename: string;
+        };
+        Content: {
+            body?: {
+                [key: string]: unknown;
+            };
+            collection: string;
+            contentId: string;
+            coverUrl?: string;
+            /** Format: int64 */
+            lastPublishedAt?: number;
+            /** Format: int64 */
+            publishedAt?: number;
+            slug?: string;
+            snippet?: string;
+            tags?: string[];
+            title: string;
+        };
+        ContentDetail: {
+            content: components["schemas"]["Content"];
+            draft?: components["schemas"]["DraftContent"];
+            publishedBlockId?: string;
+        };
+        ContentMetadata: {
+            collection: string;
+            contentId: string;
+            coverUrl?: string;
+            /** Format: int64 */
+            lastDraftAt?: number;
+            lastDraftBlockId?: string;
+            /** Format: int64 */
+            lastPublishedAt?: number;
+            /** Format: int64 */
+            publishedAt?: number;
+            publishedBlockId?: string;
+            slug?: string;
+            snippet?: string;
+            tags?: string[];
+            title: string;
+        };
+        CreateAPIKeyRequest: {
+            label: string;
+        };
+        CreateContentRequest: {
+            collection: string;
+            params: components["schemas"]["SaveDraftParams"];
+        };
+        CreateSiteRequest: {
+            host: string;
+            name: string;
+        };
+        CreateWebhookRequest: {
+            description?: string;
+            enabled?: boolean;
+            events: string[];
+            url: string;
+        };
+        DraftContent: {
+            blockId: string;
+            body?: {
+                [key: string]: unknown;
+            };
+            collection: string;
+            contentId: string;
+            coverUrl?: string;
+            /** Format: int64 */
+            createdAt: number;
+            createdBy: string;
+            slug?: string;
+            snippet?: string;
+            tags?: string[];
+            title?: string;
+        };
+        DraftVersion: {
+            /** Format: int64 */
+            createdAt: number;
+            createdBy: string;
+            title?: string;
+        };
+        DraftVersionList: {
+            versions?: components["schemas"]["DraftVersion"][];
+        };
+        Error: {
+            code: string;
+            error: string;
+        };
+        FieldDef: {
+            label: string;
+            name: string;
+            options?: {
+                [key: string]: unknown;
+            };
+            type: string;
+        };
+        Media: {
+            alt?: string;
+            caption?: string;
+            filename: string;
+            height?: number;
+            mediaId: string;
+            mimeType: string;
+            /** Format: int64 */
+            size: number;
+            /** Format: int64 */
+            uploadedAt: number;
+            url: string;
+            width?: number;
+        };
+        MediaList: {
+            cursor?: string;
+            hasMore: boolean;
+            items: components["schemas"]["Media"][];
+        };
+        RetryDeliveryResult: {
+            deliveryId: string;
+        };
+        RotateSecretResult: {
+            secret: string;
+        };
+        SaveDraftParams: {
+            body: {
+                [key: string]: unknown;
+            };
+            coverUrl?: string;
+            slug?: string;
+            snippet?: string;
+            tags?: string[];
+            title?: string;
+        };
+        SaveDraftResult: {
+            blockId: string;
+            contentId: string;
+            /** Format: int64 */
+            createdAt: number;
+        };
+        Site: {
+            admins?: components["schemas"]["SiteAdmin"][];
+            /** Format: int64 */
+            createdAt: number;
+            host: string;
+            name: string;
+            schemaVersion: number;
+            status: string;
+            /** Format: int64 */
+            updatedAt: number;
+        };
+        SiteAdmin: {
+            id: string;
+            /** @enum {string} */
+            role: "admin" | "editor";
+        };
+        SiteList: {
+            items?: components["schemas"]["Site"][];
+        };
+        UpdateAPIKeyRequest: {
+            label: string;
+        };
+        UpdateAdminsRequest: {
+            admins: components["schemas"]["SiteAdmin"][];
+        };
+        UpdateMediaRequest: {
+            alt?: string;
+            caption?: string;
+        };
+        UpdateSiteRequest: {
+            name?: string;
+            status?: string;
+        };
+        UpdateWebhookRequest: {
+            description?: string;
+            enabled?: boolean;
+            events?: string[];
+            url?: string;
+        };
+        UploadURLRequest: {
+            contentType: string;
+            filename: string;
+            /** Format: int64 */
+            size: number;
+        };
+        UploadURLResult: {
+            /** Format: int64 */
+            expiresAt: number;
+            mediaId: string;
+            uploadUrl: string;
+        };
+        Webhook: {
+            /** Format: int64 */
+            createdAt: number;
+            description?: string;
+            enabled: boolean;
+            events: string[];
+            host?: string;
+            secret?: string;
+            /** Format: int64 */
+            updatedAt?: number;
+            url: string;
+            webhookId: string;
+        };
+        WebhookDelivery: {
+            attempts?: number;
+            /** Format: int64 */
+            createdAt: number;
+            deliveryId: string;
+            /** Format: int64 */
+            duration?: number;
+            error?: string;
+            event: string;
+            payload?: string;
+            responseBody?: string;
+            responseStatus?: number;
+            status: string;
+            webhookId: string;
+        };
+        WebhookDeliveryList: {
+            deliveries: components["schemas"]["WebhookDelivery"][];
+            hasMore: boolean;
+        };
+        WebhookList: {
+            webhooks?: components["schemas"]["Webhook"][];
+        };
+        WebhookTestResult: {
+            /** Format: int64 */
+            durationMs: number;
+            error?: string;
+            requestPayload: string;
+            responseBody?: string;
+            statusCode?: number;
+            success: boolean;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+type Site = components["schemas"]["Site"];
+type SiteAdmin = components["schemas"]["SiteAdmin"];
+type Collection = components["schemas"]["Collection"] & {
+    relationships?: RelationshipDef[];
+    singletonContentId?: string;
+};
+type FieldDefinition = components["schemas"]["FieldDef"];
+type BlockType = components["schemas"]["BlockType"] & {
+    previewData?: Record<string, unknown>;
+};
+type ContentItem = components["schemas"]["ContentMetadata"] & {
+    coverMediaId?: string;
+    relationships?: Record<string, ContentRef[]>;
+};
+type ContentDetail = components["schemas"]["ContentDetail"];
+type DraftContent = components["schemas"]["DraftContent"] & {
+    relationships?: Record<string, ContentRef[]>;
+};
+type SaveDraftResult = components["schemas"]["SaveDraftResult"];
+type MediaItem = components["schemas"]["Media"];
+type UploadURLRequest = components["schemas"]["UploadURLRequest"];
+type UploadURLResult = components["schemas"]["UploadURLResult"];
+type CompleteUploadRequest = components["schemas"]["CompleteUploadRequest"];
+type ApiKeyItem = components["schemas"]["APIKeyMetadata"];
+type ApiKeyCreateResponse = components["schemas"]["APIKeyCreateResult"];
+type Webhook = components["schemas"]["Webhook"];
+type WebhookDelivery = components["schemas"]["WebhookDelivery"];
+type AuditEvent = components["schemas"]["AuditEvent"];
+interface AdminMediaItem {
+    mediaId: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    uploadedAt: number;
+    url: string;
+    alt?: string;
+    caption?: string;
+    tags: string[];
+    userTags: string[];
+    folderId?: string;
+    urls?: Record<string, string>;
+}
+interface MediaFolder {
+    folderId: string;
+    name: string;
+    createdAt: number;
+    count: number;
+}
+interface RelationshipDef {
+    name: string;
+    label: string;
+    targetCollection: string;
+    multiple: boolean;
+}
+interface ContentRef {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+}
+interface ReferencesResult {
+    count: number;
+    items: {
+        contentId: string;
+        collection: string;
+        title: string;
+        fieldName: string;
+        type?: string;
+    }[];
+}
+interface BulkMediaRequest {
+    mediaIds: string[];
+    action: "delete" | "move" | "addTags" | "removeTags";
+    folderId?: string;
+    tags?: string[];
+}
+interface BulkMediaResult {
+    succeeded: string[];
+    failed: {
+        mediaId: string;
+        error: string;
+    }[];
+}
+interface MediaUsageResponse {
+    references: {
+        contentId: string;
+        collection: string;
+        title: string;
+    }[];
+    note: string;
+}
+interface DuplicateCheckResponse {
+    duplicates: AdminMediaItem[];
+}
+interface CollectionInput {
+    name: string;
+    label: string;
+    labelSingular?: string;
+    slug?: string;
+    singleton?: boolean;
+    fields: FieldDefinition[];
+    relationships?: RelationshipDef[];
+}
+interface BlockTypeInput {
+    name: string;
+    label: string;
+    icon?: string;
+    fields: FieldDefinition[];
+}
+interface CreateContentParams {
+    collection: string;
+    params: SaveDraftParams;
+}
+interface SaveDraftParams {
+    title?: string;
+    slug?: string;
+    snippet?: string;
+    tags?: string[];
+    coverUrl?: string;
+    coverMediaId?: string;
+    coverWidth?: number;
+    coverHeight?: number;
+    body?: Record<string, unknown>;
+    createVersion?: boolean;
+    relationships?: Record<string, string[]>;
+}
+interface ContentListParams {
+    collection?: string;
+    q?: string;
+    search?: "prefix" | "full";
+    tag?: string;
+    status?: "draft" | "published" | "changed" | "unpublished";
+    sort?: string;
+    relatedTo?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface MediaListParams {
+    tag?: string;
+    folderId?: string;
+    q?: string;
+    sort?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface MediaTransformParams {
+    w?: number;
+    h?: number;
+    fit?: string;
+    format?: string;
+    q?: number;
+    cx?: number;
+    cy?: number;
+    cw?: number;
+    ch?: number;
+}
+interface SaveTransformRequest {
+    width?: number;
+    height?: number;
+    fit?: string;
+    format?: string;
+    quality?: number;
+    cropX?: number;
+    cropY?: number;
+    cropW?: number;
+    cropH?: number;
+    filename?: string;
+}
+interface AuditListParams {
+    action?: string;
+    before?: number;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+
+declare class HeadroomAdminClient {
+    private baseUrl;
+    private tokenProvider;
+    constructor(baseUrl: string, tokenProvider: TokenProvider);
+    /**
+     * Low-level fetch — public so admin UI hooks can migrate incrementally.
+     * Prefer typed methods (listSites, createContent, etc.) in new code.
+     */
+    apiFetch<T>(path: string, options?: RequestInit): Promise<T>;
+    private handleResponse;
+    listSites(includeArchived?: boolean): Promise<Site[]>;
+    createSite(host: string, name: string): Promise<Site>;
+    getSite(host: string): Promise<Site>;
+    updateSite(host: string, data: {
+        name?: string;
+        status?: string;
+    }): Promise<Site>;
+    deleteSite(host: string): Promise<void>;
+    updateSiteAdmins(host: string, admins: SiteAdmin[]): Promise<void>;
+    purgeSite(host: string): Promise<void>;
+    inviteToSite(host: string, email: string, adminUrl: string): Promise<{
+        email: string;
+        sub: string;
+        existed: boolean;
+    }>;
+    listCollections(host: string): Promise<Collection[]>;
+    createCollection(host: string, input: CollectionInput): Promise<Collection>;
+    getCollection(host: string, name: string): Promise<Collection>;
+    updateCollection(host: string, name: string, input: CollectionInput): Promise<Collection>;
+    deleteCollection(host: string, name: string): Promise<void>;
+    listBlockTypes(host: string): Promise<BlockType[]>;
+    createBlockType(host: string, input: BlockTypeInput): Promise<BlockType>;
+    getBlockType(host: string, name: string): Promise<BlockType>;
+    updateBlockType(host: string, name: string, input: BlockTypeInput): Promise<BlockType>;
+    deleteBlockType(host: string, name: string): Promise<void>;
+    listContent(host: string, params?: ContentListParams): Promise<PaginatedResponse<ContentItem>>;
+    createContent(host: string, params: CreateContentParams): Promise<SaveDraftResult>;
+    getContent(host: string, contentId: string): Promise<ContentDetail>;
+    deleteContent(host: string, contentId: string): Promise<void>;
+    saveDraft(host: string, contentId: string, draft: SaveDraftParams): Promise<SaveDraftResult>;
+    publishContent(host: string, contentId: string): Promise<ContentItem>;
+    unpublishContent(host: string, contentId: string): Promise<void>;
+    discardDraft(host: string, contentId: string): Promise<void>;
+    getPublishedContent(host: string, contentId: string): Promise<ContentItem & {
+        body?: Record<string, unknown>;
+    }>;
+    listVersions(host: string, contentId: string): Promise<{
+        versions: {
+            blockId: string;
+            createdAt: number;
+            createdBy: string;
+        }[];
+    }>;
+    getVersion(host: string, contentId: string, blockId: string): Promise<{
+        body: Record<string, unknown>;
+    }>;
+    getReferences(host: string, contentId: string): Promise<ReferencesResult>;
+    listMedia(host: string, params?: MediaListParams): Promise<PaginatedResponse<AdminMediaItem>>;
+    getMedia(host: string, mediaId: string): Promise<AdminMediaItem>;
+    updateMedia(host: string, mediaId: string, data: {
+        alt?: string;
+        caption?: string;
+        userTags?: string[];
+        folderId?: string | null;
+    }): Promise<AdminMediaItem>;
+    deleteMedia(host: string, mediaId: string): Promise<void>;
+    getUploadUrl(host: string, params: {
+        filename: string;
+        contentType: string;
+        size: number;
+    }): Promise<UploadURLResult>;
+    completeUpload(host: string, mediaId: string, params: {
+        filename: string;
+        alt?: string;
+        caption?: string;
+        folderId?: string;
+    }): Promise<AdminMediaItem>;
+    /**
+     * Convenience: download from URL and upload through the media pipeline.
+     * Works in both Node.js and browsers (uses fetch + Uint8Array, no Node APIs).
+     */
+    uploadFromUrl(host: string, url: string, filename: string, alt?: string): Promise<AdminMediaItem>;
+    listMediaFolders(host: string): Promise<MediaFolder[]>;
+    createMediaFolder(host: string, name: string): Promise<MediaFolder>;
+    updateMediaFolder(host: string, folderId: string, name: string): Promise<MediaFolder>;
+    deleteMediaFolder(host: string, folderId: string): Promise<void>;
+    bulkMediaOperation(host: string, params: BulkMediaRequest): Promise<BulkMediaResult>;
+    checkDuplicate(host: string, filename: string, size: number): Promise<DuplicateCheckResponse>;
+    getTransformUrl(host: string, mediaId: string, params: MediaTransformParams): Promise<{
+        url: string;
+    }>;
+    saveTransform(host: string, mediaId: string, params: SaveTransformRequest): Promise<AdminMediaItem>;
+    getMediaUsage(host: string, mediaId: string): Promise<MediaUsageResponse>;
+    listApiKeys(host: string): Promise<ApiKeyItem[]>;
+    createApiKey(host: string, label: string): Promise<ApiKeyCreateResponse>;
+    updateApiKey(host: string, keyId: string, label: string): Promise<ApiKeyItem>;
+    deleteApiKey(host: string, keyId: string): Promise<void>;
+    listWebhooks(host: string): Promise<Webhook[]>;
+    createWebhook(host: string, data: {
+        url: string;
+        events: string[];
+    }): Promise<Webhook>;
+    getWebhook(host: string, webhookId: string): Promise<Webhook>;
+    updateWebhook(host: string, webhookId: string, data: {
+        url?: string;
+        events?: string[];
+    }): Promise<Webhook>;
+    deleteWebhook(host: string, webhookId: string): Promise<void>;
+    testWebhook(host: string, webhookId: string): Promise<void>;
+    rotateWebhookSecret(host: string, webhookId: string): Promise<{
+        secret: string;
+    }>;
+    listWebhookDeliveries(host: string, webhookId: string): Promise<PaginatedResponse<WebhookDelivery>>;
+    getWebhookDelivery(host: string, webhookId: string, deliveryId: string): Promise<WebhookDelivery>;
+    retryDelivery(host: string, webhookId: string, deliveryId: string): Promise<void>;
+    listTags(host: string): Promise<{
+        tags: {
+            tag: string;
+            count: number;
+        }[];
+    }>;
+    createTag(host: string, tag: string): Promise<void>;
+    deleteTag(host: string, tag: string): Promise<void>;
+    listAuditEvents(host: string, params?: AuditListParams): Promise<PaginatedResponse<AuditEvent>>;
+    listUsers(): Promise<{
+        users: {
+            sub: string;
+            email: string;
+            status: string;
+            createdAt: number;
+            mfaEnabled: boolean;
+        }[];
+    }>;
+    deleteUser(sub: string): Promise<void>;
+    disableUserMfa(sub: string): Promise<void>;
+    resolveAdmins(subs: string[]): Promise<{
+        users: Record<string, {
+            sub: string;
+            email: string;
+        } | null>;
+    }>;
+    listSuperAdmins(): Promise<{
+        superAdminIds: string[];
+    }>;
+    updateSuperAdmins(superAdminIds: string[]): Promise<void>;
+}
+
+declare class HeadroomApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+    /** Alias for `message` — eases migration from admin's ApiError which used `detail`. */
+    get detail(): string;
+}
+
+declare function text(t: string, styles?: Record<string, boolean | string>): {
+    type: "text";
+    text: string;
+    styles: Record<string, string | boolean>;
+};
+declare function link(href: string, label: string): {
+    type: "link";
+    href: string;
+    content: {
+        type: "text";
+        text: string;
+        styles: Record<string, string | boolean>;
+    }[];
+};
+declare function block(type: string, content?: unknown[], props?: Record<string, unknown>, children?: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function heading(level: number, ...content: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function paragraph(...content: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function bulletItem(...content: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function numberedItem(...content: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function checkItem(checked: boolean, ...content: unknown[]): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+declare function codeBlock(language: string, code: string): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+interface ImageProps {
+    url?: string;
+    mediaId?: string;
+    filename?: string;
+    width?: number;
+    height?: number;
+    caption?: string;
+    alt?: string;
+}
+declare function image(props: ImageProps): {
+    id: string;
+    type: string;
+    props: {
+        textAlignment: string;
+    };
+    content: unknown[];
+    children: unknown[];
+};
+
+export { type AdminMediaItem, type ApiKeyCreateResponse, type ApiKeyItem, type AuditEvent, type AuditListParams, type BlockType, type BlockTypeInput, type BulkMediaRequest, type BulkMediaResult, type Collection, type CollectionInput, type CompleteUploadRequest, type ContentDetail, type ContentItem, type ContentListParams, type ContentRef, type CreateContentParams, type DraftContent, type DuplicateCheckResponse, type FieldDefinition, HeadroomAdminClient, HeadroomApiError, type ImageProps, type MediaFolder, type MediaItem, type MediaListParams, type MediaTransformParams, type MediaUsageResponse, type PaginatedResponse, type ReferencesResult, type RelationshipDef, type SaveDraftParams, type SaveDraftResult, type SaveTransformRequest, type Site, type SiteAdmin, StaticTokenProvider, type TokenProvider, type UploadURLRequest, type UploadURLResult, type Webhook, type WebhookDelivery, block, bulletItem, checkItem, codeBlock, heading, image, link, numberedItem, paragraph, text };