@bettercms-ai/sdk 1.18.0 → 1.19.0

package/dist/index.d.cts

@@ -426,7 +426,17 @@ declare class BetterCMSError extends Error {
      * hint which field or rule failed (FLO-474). Mirrors the forms client's `fieldErrors`.
      */
     readonly fieldErrors?: Record<string, string>;
-    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string, fieldErrors?: Record<string, string>);
+    /**
+     * The parsed response body, when there was one.
+     *
+     * Several refusals carry STRUCTURED detail that neither `message` nor `fieldErrors` can hold,
+     * and which is the whole point of the refusal: a component publish 409s with the full
+     * `readiness` tuple (what evidence is missing, whether a human still has to approve it) and
+     * 422s with the `issues` naming the Layouts it would break. Collapsing those to a sentence
+     * leaves a caller able to report that something failed and not what to do about it.
+     */
+    readonly body?: unknown;
+    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string, fieldErrors?: Record<string, string>, body?: unknown);
     toJSON(): {
         name: string;
         message: string;
@@ -628,10 +638,40 @@ interface ManagedComponentInput {
     name?: string;
     slug?: string;
     category?: string;
+    sectionType?: string | null;
+    /**
+     * The organisational Group, by NAME. The API resolves it against the project's Groups and
+     * creates it when missing — a caller filing a whole site's components into folders has a name
+     * ("Sections"), never an id.
+     */
+    group?: string;
+    groupId?: string | null;
     description?: string;
     blockJson?: unknown[];
     props?: unknown[];
 }
+/**
+ * The catalogue shape: what each component IS, without its block trees.
+ *
+ * The default list carries every component's draft AND live `blockJson`, which on a
+ * componentized site is the largest response this API produces — and a caller asking which
+ * components exist wants none of it. This shape also carries `sectionType`, `status` and the
+ * Group, the three facts that decide whether a component is insertable, whether it is on the
+ * live site, and where an editor finds it.
+ */
+interface ManagedComponentSummary {
+    id: string;
+    projectId: string | null;
+    name: string;
+    slug: string;
+    category: string;
+    sectionType: string | null;
+    status: string | null;
+    groupId: string | null;
+    groupName: string | null;
+    updatedAt: string | null;
+    builtin?: boolean;
+}
 /**
  * A set of sections that repeat across the project's pages, proposed as one component.
  * Derived per request from the pages' DRAFT blocks — never stored.
@@ -809,6 +849,9 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     /** Update a form by id (passing `fields` replaces the array). */
     updateForm(id: string, input: ManagedFormInput): Promise<ManagedForm>;
     listComponents(): Promise<ManagedComponent[]>;
+    listComponents(options: {
+        select: "summary";
+    }): Promise<ManagedComponentSummary[]>;
     getComponent(id: string): Promise<ManagedComponent>;
     createComponent(input: ManagedComponentInput): Promise<ManagedComponent>;
     updateComponent(id: string, input: ManagedComponentInput): Promise<ManagedComponent>;
@@ -1437,4 +1480,4 @@ declare function inviteMember(client: BetterCMSAdminClient, workspaceId: string,
 declare function updateMemberRole(client: BetterCMSAdminClient, workspaceId: string, memberId: string, role: MemberRole): Promise<Member>;
 declare function removeMember(client: BetterCMSAdminClient, workspaceId: string, memberId: string): Promise<void>;
 
-export { type AddPageFieldsInput, type ApiKeyUsage, type ApiKeyWithRaw, type AuthResult, BetterCMSError as BCMSClientError, ErrorCodes as BCMSErrorCodes, BetterCMS, BetterCMSAdminClient, type BetterCMSAdminOptions, BetterCMSDeliveryClient, BetterCMSError, BetterCMSManagementClient, type BetterCMSManagementOptions, type BetterCMSReadClient, type BetterCMSSiteOptions, type CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };
+export { type AddPageFieldsInput, type ApiKeyUsage, type ApiKeyWithRaw, type AuthResult, BetterCMSError as BCMSClientError, ErrorCodes as BCMSErrorCodes, BetterCMS, BetterCMSAdminClient, type BetterCMSAdminOptions, BetterCMSDeliveryClient, BetterCMSError, BetterCMSManagementClient, type BetterCMSManagementOptions, type BetterCMSReadClient, type BetterCMSSiteOptions, type CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedComponentSummary, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };

package/dist/index.d.ts

@@ -426,7 +426,17 @@ declare class BetterCMSError extends Error {
      * hint which field or rule failed (FLO-474). Mirrors the forms client's `fieldErrors`.
      */
     readonly fieldErrors?: Record<string, string>;
-    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string, fieldErrors?: Record<string, string>);
+    /**
+     * The parsed response body, when there was one.
+     *
+     * Several refusals carry STRUCTURED detail that neither `message` nor `fieldErrors` can hold,
+     * and which is the whole point of the refusal: a component publish 409s with the full
+     * `readiness` tuple (what evidence is missing, whether a human still has to approve it) and
+     * 422s with the `issues` naming the Layouts it would break. Collapsing those to a sentence
+     * leaves a caller able to report that something failed and not what to do about it.
+     */
+    readonly body?: unknown;
+    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string, fieldErrors?: Record<string, string>, body?: unknown);
     toJSON(): {
         name: string;
         message: string;
@@ -628,10 +638,40 @@ interface ManagedComponentInput {
     name?: string;
     slug?: string;
     category?: string;
+    sectionType?: string | null;
+    /**
+     * The organisational Group, by NAME. The API resolves it against the project's Groups and
+     * creates it when missing — a caller filing a whole site's components into folders has a name
+     * ("Sections"), never an id.
+     */
+    group?: string;
+    groupId?: string | null;
     description?: string;
     blockJson?: unknown[];
     props?: unknown[];
 }
+/**
+ * The catalogue shape: what each component IS, without its block trees.
+ *
+ * The default list carries every component's draft AND live `blockJson`, which on a
+ * componentized site is the largest response this API produces — and a caller asking which
+ * components exist wants none of it. This shape also carries `sectionType`, `status` and the
+ * Group, the three facts that decide whether a component is insertable, whether it is on the
+ * live site, and where an editor finds it.
+ */
+interface ManagedComponentSummary {
+    id: string;
+    projectId: string | null;
+    name: string;
+    slug: string;
+    category: string;
+    sectionType: string | null;
+    status: string | null;
+    groupId: string | null;
+    groupName: string | null;
+    updatedAt: string | null;
+    builtin?: boolean;
+}
 /**
  * A set of sections that repeat across the project's pages, proposed as one component.
  * Derived per request from the pages' DRAFT blocks — never stored.
@@ -809,6 +849,9 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     /** Update a form by id (passing `fields` replaces the array). */
     updateForm(id: string, input: ManagedFormInput): Promise<ManagedForm>;
     listComponents(): Promise<ManagedComponent[]>;
+    listComponents(options: {
+        select: "summary";
+    }): Promise<ManagedComponentSummary[]>;
     getComponent(id: string): Promise<ManagedComponent>;
     createComponent(input: ManagedComponentInput): Promise<ManagedComponent>;
     updateComponent(id: string, input: ManagedComponentInput): Promise<ManagedComponent>;
@@ -1437,4 +1480,4 @@ declare function inviteMember(client: BetterCMSAdminClient, workspaceId: string,
 declare function updateMemberRole(client: BetterCMSAdminClient, workspaceId: string, memberId: string, role: MemberRole): Promise<Member>;
 declare function removeMember(client: BetterCMSAdminClient, workspaceId: string, memberId: string): Promise<void>;
 
-export { type AddPageFieldsInput, type ApiKeyUsage, type ApiKeyWithRaw, type AuthResult, BetterCMSError as BCMSClientError, ErrorCodes as BCMSErrorCodes, BetterCMS, BetterCMSAdminClient, type BetterCMSAdminOptions, BetterCMSDeliveryClient, BetterCMSError, BetterCMSManagementClient, type BetterCMSManagementOptions, type BetterCMSReadClient, type BetterCMSSiteOptions, type CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };
+export { type AddPageFieldsInput, type ApiKeyUsage, type ApiKeyWithRaw, type AuthResult, BetterCMSError as BCMSClientError, ErrorCodes as BCMSErrorCodes, BetterCMS, BetterCMSAdminClient, type BetterCMSAdminOptions, BetterCMSDeliveryClient, BetterCMSError, BetterCMSManagementClient, type BetterCMSManagementOptions, type BetterCMSReadClient, type BetterCMSSiteOptions, type CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedComponentSummary, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };

package/dist/index.js

@@ -35,13 +35,24 @@ var BetterCMSError = class _BetterCMSError extends Error {
    * hint which field or rule failed (FLO-474). Mirrors the forms client's `fieldErrors`.
    */
   fieldErrors;
-  constructor(message, status, code, bodyCode, fieldErrors) {
+  /**
+   * The parsed response body, when there was one.
+   *
+   * Several refusals carry STRUCTURED detail that neither `message` nor `fieldErrors` can hold,
+   * and which is the whole point of the refusal: a component publish 409s with the full
+   * `readiness` tuple (what evidence is missing, whether a human still has to approve it) and
+   * 422s with the `issues` naming the Layouts it would break. Collapsing those to a sentence
+   * leaves a caller able to report that something failed and not what to do about it.
+   */
+  body;
+  constructor(message, status, code, bodyCode, fieldErrors, body) {
     super(message);
     this.name = "BetterCMSError";
     this.status = status;
     this.code = code;
     this.bodyCode = bodyCode;
     this.fieldErrors = fieldErrors;
+    this.body = body;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _BetterCMSError);
     }
@@ -68,6 +79,7 @@ var BetterCMSError = class _BetterCMSError extends Error {
     let bodyCode;
     let fieldErrors;
     let code = statusToCode(res.status);
+    let raw;
     try {
       const body = await res.json();
       if (body?.errors && typeof body.errors === "object") {
@@ -83,9 +95,10 @@ var BetterCMSError = class _BetterCMSError extends Error {
         if (field) message = `${field}: ${detail}`;
       }
       if (body?.code) bodyCode = body.code;
+      raw = body;
     } catch {
     }
-    return new _BetterCMSError(message, res.status, code, bodyCode, fieldErrors);
+    return new _BetterCMSError(message, res.status, code, bodyCode, fieldErrors, raw);
   }
 };
 
@@ -706,9 +719,10 @@ async function updateForm(client, id, input) {
 }
 
 // src/methods/management/components.ts
-async function listComponents(client) {
+async function listComponents(client, options) {
+  const query = options?.select ? `?select=${options.select}` : "";
   const res = await client.fetchJSON(
-    client.url("/management/components"),
+    client.url(`/management/components${query}`),
     { method: "GET" }
   );
   return res.data;
@@ -949,9 +963,8 @@ var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
   updateForm(id, input) {
     return updateForm(this, id, input);
   }
-  // ── Components: discover + author reusable symbols ──
-  listComponents() {
-    return listComponents(this);
+  listComponents(options) {
+    return options?.select ? listComponents(this, { select: options.select }) : listComponents(this);
   }
   getComponent(id) {
     return getComponent(this, id);