@headroom-cms/admin-api 0.1.1

package/dist/node.d.ts

@@ -0,0 +1,644 @@
+/**
+ * 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>;
+}
+
+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 SaveDraftResult = components["schemas"]["SaveDraftResult"];
+type UploadURLResult = components["schemas"]["UploadURLResult"];
+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>;
+}
+
+/**
+ * Upload a file from the local filesystem.
+ * Node.js only — uses fs/promises.
+ */
+declare function uploadFile(client: HeadroomAdminClient, host: string, filePath: string, alt?: string): Promise<AdminMediaItem>;
+
+export { uploadFile };

package/dist/node.js

@@ -0,0 +1,41 @@
+// src/mime.ts
+var MIME_MAP = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".mp4": "video/mp4",
+  ".pdf": "application/pdf"
+};
+function mimeFromFilename(filename) {
+  const ext = filename.includes(".") ? "." + filename.split(".").pop().toLowerCase() : "";
+  return MIME_MAP[ext] || "application/octet-stream";
+}
+
+// src/node.ts
+async function uploadFile(client, host, filePath, alt) {
+  const fs = await import("fs/promises");
+  const path = await import("path");
+  const data = await fs.readFile(filePath);
+  const filename = path.basename(filePath);
+  const contentType = mimeFromFilename(filename);
+  const { mediaId, uploadUrl } = await client.getUploadUrl(host, {
+    filename,
+    contentType,
+    size: data.length
+  });
+  const uploadRes = await fetch(uploadUrl, {
+    method: "PUT",
+    body: data,
+    headers: { "Content-Type": contentType }
+  });
+  if (!uploadRes.ok) {
+    throw new Error(`S3 upload failed: ${uploadRes.status}`);
+  }
+  return client.completeUpload(host, mediaId, { filename, alt });
+}
+export {
+  uploadFile
+};