@headroom-cms/admin-api 0.1.1

package/dist/seed.d.ts

@@ -0,0 +1,415 @@
+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 Collection = components["schemas"]["Collection"] & {
+    relationships?: RelationshipDef[];
+    singletonContentId?: string;
+};
+type FieldDefinition = components["schemas"]["FieldDef"];
+type ContentItem = components["schemas"]["ContentMetadata"] & {
+    coverMediaId?: string;
+    relationships?: Record<string, ContentRef[]>;
+};
+type SaveDraftResult = components["schemas"]["SaveDraftResult"];
+type ApiKeyItem = components["schemas"]["APIKeyMetadata"];
+type ApiKeyCreateResponse = components["schemas"]["APIKeyCreateResult"];
+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 RelationshipDef {
+    name: string;
+    label: string;
+    targetCollection: string;
+    multiple: boolean;
+}
+interface ContentRef {
+    contentId: string;
+    collection: string;
+    slug: string;
+    title: string;
+}
+interface CollectionInput {
+    name: string;
+    label: string;
+    labelSingular?: string;
+    slug?: string;
+    singleton?: boolean;
+    fields: FieldDefinition[];
+    relationships?: RelationshipDef[];
+}
+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 PaginatedResponse<T> {
+    items: T[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+
+/** Subset of HeadroomAdminClient used by seed helpers. */
+interface SeedClient {
+    createSite(host: string, name: string): Promise<Site>;
+    createCollection(host: string, input: CollectionInput): Promise<Collection>;
+    uploadFromUrl(host: string, url: string, filename: string): Promise<AdminMediaItem>;
+    listContent(host: string, params?: {
+        collection?: string;
+    }): Promise<PaginatedResponse<ContentItem>>;
+    createContent(host: string, params: {
+        collection: string;
+        params: SaveDraftParams;
+    }): Promise<SaveDraftResult>;
+    saveDraft(host: string, contentId: string, draft: SaveDraftParams): Promise<SaveDraftResult>;
+    publishContent(host: string, contentId: string): Promise<ContentItem>;
+    listApiKeys(host: string): Promise<ApiKeyItem[]>;
+    createApiKey(host: string, label: string): Promise<ApiKeyCreateResponse>;
+}
+type MediaMap = Map<string, {
+    mediaId: string;
+    url: string;
+    filename: string;
+    width: number;
+    height: number;
+}>;
+/** Idempotent site creation — swallows 409 conflict. */
+declare function ensureSite(client: SeedClient, host: string, name: string): Promise<void>;
+/** Idempotent collection creation — swallows 409 per collection. */
+declare function ensureCollections(client: SeedClient, host: string, collections: CollectionInput[]): Promise<void>;
+/** Batch upload images from URLs. Returns a sourceURL → media info map. */
+declare function uploadMediaUrls(client: SeedClient, host: string, urls: string[]): Promise<MediaMap>;
+/** Upsert content items by slug: update if exists, create if new, then publish. */
+declare function upsertContent(client: SeedClient, host: string, collection: string, items: {
+    draft: SaveDraftParams;
+    tags: string[];
+}[]): Promise<void>;
+/** Upsert singleton: find existing → saveDraft → publish. No createContent needed. */
+declare function upsertSingleton(client: SeedClient, host: string, collection: string, draft: SaveDraftParams): Promise<void>;
+/** Ensure at least one API key exists; returns the key string. */
+declare function ensureApiKey(client: SeedClient, host: string, label: string, existingKeyFromEnv?: string): Promise<string>;
+
+export { type MediaMap, type SeedClient, ensureApiKey, ensureCollections, ensureSite, uploadMediaUrls, upsertContent, upsertSingleton };

package/dist/seed.js

@@ -0,0 +1,143 @@
+// src/error.ts
+var HeadroomApiError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message || code);
+    this.name = "HeadroomApiError";
+    this.status = status;
+    this.code = code;
+  }
+  /** Alias for `message` — eases migration from admin's ApiError which used `detail`. */
+  get detail() {
+    return this.message;
+  }
+};
+
+// src/seed.ts
+function filenameFromUrl(url) {
+  const pathname = new URL(url).pathname;
+  const base = pathname.split("/").pop() || "image";
+  return base.includes(".") ? base : `${base}.jpg`;
+}
+async function ensureSite(client, host, name) {
+  try {
+    await client.createSite(host, name);
+    console.log(`  Site created: ${host}`);
+  } catch (e) {
+    if (e instanceof HeadroomApiError && e.status === 409) {
+      console.log(`  Site already exists: ${host}`);
+    } else {
+      throw e;
+    }
+  }
+}
+async function ensureCollections(client, host, collections) {
+  for (const coll of collections) {
+    try {
+      await client.createCollection(host, coll);
+      console.log(`  Created: ${coll.name}`);
+    } catch (e) {
+      if (e instanceof HeadroomApiError && e.status === 409) {
+        console.log(`  Already exists: ${coll.name}`);
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+async function uploadMediaUrls(client, host, urls) {
+  const mediaMap = /* @__PURE__ */ new Map();
+  for (const url of urls) {
+    try {
+      const filename = filenameFromUrl(url);
+      const media = await client.uploadFromUrl(host, url, filename);
+      mediaMap.set(url, {
+        mediaId: media.mediaId,
+        url: media.url,
+        filename: media.filename,
+        width: media.width ?? 0,
+        height: media.height ?? 0
+      });
+      console.log(`  Uploaded: ${filename} \u2192 ${media.mediaId}`);
+    } catch (e) {
+      console.warn(
+        `  Warning: failed to upload ${url}: ${e.message}`
+      );
+    }
+  }
+  return mediaMap;
+}
+async function upsertContent(client, host, collection, items) {
+  const existing = await client.listContent(host, { collection });
+  const slugMap = /* @__PURE__ */ new Map();
+  for (const item of existing.items) {
+    if (item.slug) {
+      slugMap.set(item.slug, item);
+    }
+  }
+  for (const item of items) {
+    const slug = item.draft.slug;
+    const title = item.draft.title || slug || "untitled";
+    const existingItem = slug ? slugMap.get(slug) : void 0;
+    try {
+      if (existingItem) {
+        const draftParams = { ...item.draft };
+        if (item.tags.length > 0) {
+          draftParams.tags = item.tags;
+        }
+        await client.saveDraft(host, existingItem.contentId, draftParams);
+        await client.publishContent(host, existingItem.contentId);
+        console.log(`  Updated & published: ${title}`);
+      } else {
+        const result = await client.createContent(host, {
+          collection,
+          params: item.draft
+        });
+        if (item.tags.length > 0) {
+          await client.saveDraft(host, result.contentId, {
+            ...item.draft,
+            tags: item.tags
+          });
+        }
+        await client.publishContent(host, result.contentId);
+        console.log(`  Created & published: ${title}`);
+      }
+    } catch (e) {
+      console.error(`  Failed: ${title} -`, e.message);
+    }
+  }
+}
+async function upsertSingleton(client, host, collection, draft) {
+  const existing = await client.listContent(host, { collection });
+  if (existing.items.length === 0) {
+    console.error(
+      `  Could not find existing singleton content for: ${collection}`
+    );
+    return;
+  }
+  const id = existing.items[0].contentId;
+  await client.saveDraft(host, id, draft);
+  await client.publishContent(host, id);
+  console.log(`  Singleton updated & published: ${collection}`);
+}
+async function ensureApiKey(client, host, label, existingKeyFromEnv) {
+  const existingKeys = await client.listApiKeys(host);
+  if (existingKeys.length > 0 && existingKeyFromEnv) {
+    console.log(
+      `  ${existingKeys.length} API key(s) already exist. Reusing from .env.`
+    );
+    return existingKeyFromEnv;
+  }
+  const keyResult = await client.createApiKey(host, label);
+  console.log(`  API key created.`);
+  return keyResult.key;
+}
+export {
+  ensureApiKey,
+  ensureCollections,
+  ensureSite,
+  uploadMediaUrls,
+  upsertContent,
+  upsertSingleton
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@headroom-cms/admin-api",
+  "version": "0.1.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.js",
+      "require": "./dist/auth.cjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "require": "./dist/node.cjs"
+    },
+    "./seed": {
+      "types": "./dist/seed.d.ts",
+      "import": "./dist/seed.js",
+      "require": "./dist/seed.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "generate:types": "bash scripts/generate-types.sh"
+  },
+  "devDependencies": {
+    "@types/node": "~24.10.13",
+    "@vitest/coverage-v8": "^4.0.18",
+    "openapi-typescript": "^7.10.1",
+    "tsup": "~8.5.0",
+    "typescript": "~5.9.3",
+    "vitest": "~4.0.18"
+  },
+  "peerDependencies": {
+    "amazon-cognito-identity-js": "^6.3.0"
+  },
+  "peerDependenciesMeta": {
+    "amazon-cognito-identity-js": {
+      "optional": true
+    }
+  }
+}