@bettercms-ai/sdk 1.7.0 → 1.8.1

package/dist/index.d.cts

@@ -404,18 +404,28 @@ declare class BetterCMSError extends Error {
      * shares a status with others (e.g. 409 slug-conflict vs 409 project-deleted).
      */
     readonly bodyCode?: string;
-    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string);
+    /**
+     * Per-field validation messages from a 400 `{ errors: { field: message } }` body.
+     * The backend returns validation failures in this shape (not `message`/`error`), so
+     * without this the SDK collapsed every validation 400 to a bare "Bad Request" with no
+     * 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>);
     toJSON(): {
         name: string;
         message: string;
         status: number;
         code: BetterCMSErrorCode;
         bodyCode: string | undefined;
+        fieldErrors: Record<string, string> | undefined;
     };
     /**
-     * Factory — creates a BetterCMSError from a failed fetch Response. Reads the
-     * body's `message` (or `error`) for the human message and `code` for a
-     * machine-readable condition the SDK surfaces as `bodyCode`.
+     * Factory — creates a BetterCMSError from a failed fetch Response. Reads the body's
+     * `message` (or `error`) for the human message and `code` for a machine-readable
+     * condition surfaced as `bodyCode`. Validation failures arrive as `{ errors: {...} }`
+     * (no `message`/`error`), so fall back to the first field error for the message and
+     * expose the full map as `fieldErrors` (FLO-474).
      */
     static from(res: Response): Promise<BetterCMSError>;
 }
@@ -594,12 +604,20 @@ interface BetterCMSManagementOptions {
     baseUrl?: string;
     /** A content:manage scoped API key. */
     apiKey: string;
+    /**
+     * Target project (id or slug), sent as the X-BCMS-Project header.
+     * REQUIRED for workspace-scoped keys — content writes (createEntry, createPage,
+     * createModel, …) must land in a project. Project-scoped keys (`bcms_proj_…`)
+     * don't need it; if set, it must match the key's own project.
+     */
+    project?: string;
     /** Request timeout per attempt in ms. Defaults to 10000. */
     timeout?: number;
 }
 declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     readonly timeout: number;
     private readonly _apiKey;
+    private readonly _project?;
     constructor(options: BetterCMSManagementOptions);
     headers(): Record<string, string>;
     /** Management API URL: baseUrl + path (path is workspace-scoped via the key). */

package/dist/index.d.ts

@@ -404,18 +404,28 @@ declare class BetterCMSError extends Error {
      * shares a status with others (e.g. 409 slug-conflict vs 409 project-deleted).
      */
     readonly bodyCode?: string;
-    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string);
+    /**
+     * Per-field validation messages from a 400 `{ errors: { field: message } }` body.
+     * The backend returns validation failures in this shape (not `message`/`error`), so
+     * without this the SDK collapsed every validation 400 to a bare "Bad Request" with no
+     * 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>);
     toJSON(): {
         name: string;
         message: string;
         status: number;
         code: BetterCMSErrorCode;
         bodyCode: string | undefined;
+        fieldErrors: Record<string, string> | undefined;
     };
     /**
-     * Factory — creates a BetterCMSError from a failed fetch Response. Reads the
-     * body's `message` (or `error`) for the human message and `code` for a
-     * machine-readable condition the SDK surfaces as `bodyCode`.
+     * Factory — creates a BetterCMSError from a failed fetch Response. Reads the body's
+     * `message` (or `error`) for the human message and `code` for a machine-readable
+     * condition surfaced as `bodyCode`. Validation failures arrive as `{ errors: {...} }`
+     * (no `message`/`error`), so fall back to the first field error for the message and
+     * expose the full map as `fieldErrors` (FLO-474).
      */
     static from(res: Response): Promise<BetterCMSError>;
 }
@@ -594,12 +604,20 @@ interface BetterCMSManagementOptions {
     baseUrl?: string;
     /** A content:manage scoped API key. */
     apiKey: string;
+    /**
+     * Target project (id or slug), sent as the X-BCMS-Project header.
+     * REQUIRED for workspace-scoped keys — content writes (createEntry, createPage,
+     * createModel, …) must land in a project. Project-scoped keys (`bcms_proj_…`)
+     * don't need it; if set, it must match the key's own project.
+     */
+    project?: string;
     /** Request timeout per attempt in ms. Defaults to 10000. */
     timeout?: number;
 }
 declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     readonly timeout: number;
     private readonly _apiKey;
+    private readonly _project?;
     constructor(options: BetterCMSManagementOptions);
     headers(): Record<string, string>;
     /** Management API URL: baseUrl + path (path is workspace-scoped via the key). */

package/dist/index.js

@@ -28,12 +28,20 @@ var BetterCMSError = class _BetterCMSError extends Error {
    * shares a status with others (e.g. 409 slug-conflict vs 409 project-deleted).
    */
   bodyCode;
-  constructor(message, status, code, bodyCode) {
+  /**
+   * Per-field validation messages from a 400 `{ errors: { field: message } }` body.
+   * The backend returns validation failures in this shape (not `message`/`error`), so
+   * without this the SDK collapsed every validation 400 to a bare "Bad Request" with no
+   * hint which field or rule failed (FLO-474). Mirrors the forms client's `fieldErrors`.
+   */
+  fieldErrors;
+  constructor(message, status, code, bodyCode, fieldErrors) {
     super(message);
     this.name = "BetterCMSError";
     this.status = status;
     this.code = code;
     this.bodyCode = bodyCode;
+    this.fieldErrors = fieldErrors;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _BetterCMSError);
     }
@@ -44,25 +52,40 @@ var BetterCMSError = class _BetterCMSError extends Error {
       message: this.message,
       status: this.status,
       code: this.code,
-      bodyCode: this.bodyCode
+      bodyCode: this.bodyCode,
+      fieldErrors: this.fieldErrors
     };
   }
   /**
-   * Factory — creates a BetterCMSError from a failed fetch Response. Reads the
-   * body's `message` (or `error`) for the human message and `code` for a
-   * machine-readable condition the SDK surfaces as `bodyCode`.
+   * Factory — creates a BetterCMSError from a failed fetch Response. Reads the body's
+   * `message` (or `error`) for the human message and `code` for a machine-readable
+   * condition surfaced as `bodyCode`. Validation failures arrive as `{ errors: {...} }`
+   * (no `message`/`error`), so fall back to the first field error for the message and
+   * expose the full map as `fieldErrors` (FLO-474).
    */
   static async from(res) {
     let message = res.statusText || "An error occurred";
     let bodyCode;
+    let fieldErrors;
+    let code = statusToCode(res.status);
     try {
       const body = await res.json();
+      if (body?.errors && typeof body.errors === "object") {
+        fieldErrors = body.errors;
+        code = ErrorCodes.VALIDATION_ERROR;
+      }
       if (body?.message) message = body.message;
       else if (body?.error) message = body.error;
+      else if (fieldErrors) {
+        const [field, detail] = Object.entries(fieldErrors).find(
+          ([, v]) => typeof v === "string" && v.length > 0
+        ) ?? [];
+        if (field) message = `${field}: ${detail}`;
+      }
       if (body?.code) bodyCode = body.code;
     } catch {
     }
-    return new _BetterCMSError(message, res.status, statusToCode(res.status), bodyCode);
+    return new _BetterCMSError(message, res.status, code, bodyCode, fieldErrors);
   }
 };
 
@@ -673,15 +696,18 @@ var RETRY_DELAYS2 = [1e3, 2e3, 4e3];
 var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
   timeout;
   _apiKey;
+  _project;
   constructor(options) {
     super({ workspace: "", baseUrl: options.baseUrl ?? DEFAULT_BASE_URL2 });
     this._apiKey = options.apiKey;
+    this._project = options.project;
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT2;
   }
   headers() {
     return {
       "Content-Type": "application/json",
-      "X-API-Key": this._apiKey
+      "X-API-Key": this._apiKey,
+      ...this._project ? { "X-BCMS-Project": this._project } : {}
     };
   }
   /** Management API URL: baseUrl + path (path is workspace-scoped via the key). */