@ram_28/kf-ai-sdk 2.0.1 → 2.0.2

package/sdk/api/client.ts

@@ -161,24 +161,31 @@ export function getApiBaseUrl(): string {
   return apiConfig.baseUrl || "";
 }
 
+/**
+ * Parse error response body and throw an Error with the server's message.
+ */
+async function throwApiError(response: Response, context: string): Promise<never> {
+  let errorBody: any;
+  try { errorBody = await response.json(); } catch {}
+  const message = errorBody?.error || errorBody?.message || response.statusText;
+  throw new Error(`${context}: ${message}`);
+}
+
 /**
  * Create a resource client for the specified Business Object
  * @param bo_id - Business Object identifier (e.g., "user", "leave", "vendor")
  * @returns Resource client with CRUD operations matching API spec
  */
 export function api<T = any>(bo_id: string): ResourceClientType<T> {
-  const baseUrl = apiConfig.baseUrl;
-  const defaultHeaders = apiConfig.headers;
-
   return {
     async get(id: string): Promise<T> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/read`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/read`, {
         method: "GET",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        throw new Error(`Failed to get ${bo_id} ${id}: ${response.statusText}`);
+        await throwApiError(response, `Failed to get ${bo_id} ${id}`);
       }
 
       const responseData: ReadResponseType<T> = await response.json();
@@ -188,45 +195,41 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     async create(
       data: Partial<T> & { _id?: string }
     ): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/create`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/create`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(`Failed to create ${bo_id}: ${response.statusText}`);
+        await throwApiError(response, `Failed to create ${bo_id}`);
       }
 
       return response.json();
     },
 
     async update(id: string, data: Partial<T>): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/update`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/update`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to update ${bo_id} ${id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to update ${bo_id} ${id}`);
       }
 
       return response.json();
     },
 
     async delete(id: string): Promise<DeleteResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/delete`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/delete`, {
         method: "DELETE",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to delete ${bo_id} ${id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to delete ${bo_id} ${id}`);
       }
 
       return response.json();
@@ -238,14 +241,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...options,
       };
 
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/list`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/list`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        throw new Error(`Failed to list ${bo_id}: ${response.statusText}`);
+        await throwApiError(response, `Failed to list ${bo_id}`);
       }
 
       const responseData: ListResponseType<T> = await response.json();
@@ -261,14 +264,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...(options?.Filter && { Filter: options.Filter }),
       };
 
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/metric`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/metric`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        throw new Error(`Failed to count ${bo_id}: ${response.statusText}`);
+        await throwApiError(response, `Failed to count ${bo_id}`);
       }
 
       const result = await response.json();
@@ -282,16 +285,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     // ============================================================
 
     async draft(data: Partial<T>): Promise<DraftResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/draft`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/draft`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to create draft for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to create draft for ${bo_id}`);
       }
 
       return response.json();
@@ -301,32 +302,28 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
       id: string,
       data: Partial<T>
     ): Promise<CreateUpdateResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/draft`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/draft`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to update draft for ${bo_id} ${id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to update draft for ${bo_id} ${id}`);
       }
 
       return response.json();
     },
 
     async draftPatch(id: string, data: Partial<T>): Promise<DraftResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/draft`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/${id}/draft`, {
         method: "PATCH",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to patch draft for ${bo_id} ${id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to patch draft for ${bo_id} ${id}`);
       }
 
       return response.json();
@@ -335,16 +332,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     async draftInteraction(
       data: Partial<T> & { _id?: string }
     ): Promise<DraftResponseType & { _id: string }> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/draft`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/draft`, {
         method: "PATCH",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(data),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to create interactive draft for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to create interactive draft for ${bo_id}`);
       }
 
       const json = await response.json();
@@ -368,16 +363,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...options,
       };
 
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/metric`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/metric`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to get metrics for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to get metrics for ${bo_id}`);
       }
 
       return response.json();
@@ -389,16 +382,14 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
         ...options,
       };
 
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/pivot`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/pivot`, {
         method: "POST",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
         body: JSON.stringify(requestBody),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to get pivot data for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to get pivot data for ${bo_id}`);
       }
 
       return response.json();
@@ -409,15 +400,13 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
     // ============================================================
 
     async fields(): Promise<FieldsResponseType> {
-      const response = await fetch(`${baseUrl}/api/app/${bo_id}/fields`, {
+      const response = await fetch(`${getApiBaseUrl()}/api/app/${bo_id}/fields`, {
         method: "GET",
-        headers: defaultHeaders,
+        headers: getDefaultHeaders(),
       });
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to get fields for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to get fields for ${bo_id}`);
       }
 
       return response.json();
@@ -428,17 +417,15 @@ export function api<T = any>(bo_id: string): ResourceClientType<T> {
       fieldId: string
     ): Promise<TResult[]> {
       const response = await fetch(
-        `${baseUrl}/api/app/${bo_id}/${instanceId}/field/${fieldId}/fetch`,
+        `${getApiBaseUrl()}/api/app/${bo_id}/${instanceId}/field/${fieldId}/fetch`,
         {
           method: "GET",
-          headers: defaultHeaders,
+          headers: getDefaultHeaders(),
         }
       );
 
       if (!response.ok) {
-        throw new Error(
-          `Failed to fetch field ${fieldId} for ${bo_id}: ${response.statusText}`
-        );
+        await throwApiError(response, `Failed to fetch field ${fieldId} for ${bo_id}`);
       }
 
       const responseData: { Data: TResult[] } = await response.json();

package/sdk/api/metadata.ts

@@ -81,20 +81,6 @@ export interface MetadataItemType {
  *
  * @param options - Optional list options (filters, sorting, pagination)
  * @returns Promise resolving to list of metadata items
- *
- * @example
- * ```typescript
- * // List all metadata
- * const all = await listMetadata();
- *
- * // List with filters
- * const businessObjects = await listMetadata({
- *   Filter: {
- *     Operator: "AND",
- *     Condition: [{ LhsField: "Kind", Operator: "eq", RhsValue: "BusinessObject" }]
- *   }
- * });
- * ```
  */
 export async function listMetadata(
   options?: ListOptionsType
@@ -131,18 +117,34 @@ export async function listMetadata(
 }
 
 /**
- * Field metadata structure
+ * Field metadata structure — matches new Constraint/View/Property backend shape
  */
 export interface FieldMetadataType {
   Id: string;
   Name: string;
   Type: string;
+  ReadOnly?: boolean;
   Required?: boolean;
-  Unique?: boolean;
-  Computed?: boolean;
-  Values?: {
-    Mode: "Static" | "Dynamic";
-    Items?: Array<{ Value: string; Label: string }>;
+  Constraint?: {
+    Required?: boolean;
+    Enum?: string[];
+    Length?: number;
+    IntegerPart?: number;
+    FractionPart?: number;
+    PrimaryKey?: boolean;
+    DefaultValue?: unknown;
+    Precision?: "Second" | "Millisecond";
+    Format?: "Plain" | "Markdown";
+  };
+  View?: {
+    DataObject?: { Type: string; Id: string };
+    Fields?: Record<string, { Type: string }>;
+    Search?: string[];
+    Filter?: Record<string, unknown>;
+    Sort?: unknown[];
+    BusinessEntity?: string;
   };
+  Property?: FieldMetadataType | Record<string, FieldMetadataType>;
+  DefaultValue?: unknown;
   [key: string]: any;
 }

package/sdk/base-types.ts

@@ -6,11 +6,11 @@
 export type {
   // String fields
   StringFieldType,
+  TextFieldType,
   TextAreaFieldType,
 
   // Numeric fields
   NumberFieldType,
-  LongFieldType,
 
   // Boolean field
   BooleanFieldType,
@@ -20,21 +20,17 @@ export type {
   DateTimeFieldType,
 
   // Complex fields
-  CurrencyFieldType,
-  CurrencyValueType,
-  JSONFieldType,
   ReferenceFieldType,
   ExtractReferenceType,
   ExtractFetchFieldType,
 
-  // JSON types
-  JSONValueType,
-  JSONObjectType,
-  JSONArrayType,
-
   // Select fields
   SelectFieldType,
 
+  // New field types
+  UserFieldType,
+  FileFieldType,
+
   // Container types
   ArrayFieldType,
   ObjectFieldType,

package/sdk/bdo/core/BaseBdo.ts

@@ -13,22 +13,19 @@ import type {
   PivotResponseType,
   DraftResponseType,
 } from "../../types/common";
-import type { StringFieldType, SystemFields, UserRefType } from "../../types/base-fields";
+import type { SystemFields } from "../../types/base-fields";
 import { api } from "../../api/client";
 import { Item, type ItemType } from "./Item";
 import { BaseField } from "../fields/BaseField";
 import { StringField } from "../fields/StringField";
 import { DateTimeField } from "../fields/DateTimeField";
-import { ReferenceField } from "../fields/ReferenceField";
+import { UserField } from "../fields/UserField";
 import type { ValidationResultType, BdoMetaType } from "./types";
 import { ExpressionEngine, type BDOMetadata } from "../expressions";
 
 // Re-export SystemFields type for consumers
 export type { SystemFields } from "../../types/base-fields";
 
-// System BDO ID for user references
-const USER_BO_ID = "SYS_User";
-
 /**
  * Abstract base class for Business Data Objects
  *
@@ -38,18 +35,6 @@ const USER_BO_ID = "SYS_User";
  * @template TEntity - The full entity type with all fields
  * @template TEditable - Fields that this role can create/update (defaults to TEntity without system fields)
  * @template TReadonly - Fields that this role can only read (defaults to empty)
- *
- * @example
- * ```typescript
- * class AdminProduct extends BaseBdo<ProductType> {
- *   readonly meta = { _id: "BDO_Product", name: "Product" };
- *
- *   // Re-expose only methods this role can use
- *   public async get(id: StringFieldType) { return super.get(id); }
- *   public async list(options?: ListOptionsType) { return super.list(options); }
- *   // create, update, delete NOT exposed - TypeScript error if called
- * }
- * ```
  */
 export abstract class BaseBdo<
   TEntity extends Record<string, unknown>,
@@ -65,23 +50,13 @@ export abstract class BaseBdo<
   // SYSTEM FIELDS (inherited by all BDOs)
   // ============================================================
 
-  readonly _id = new StringField({ id: "_id", label: "ID" });
-  readonly _created_at = new DateTimeField({ id: "_created_at", label: "Created At" });
-  readonly _modified_at = new DateTimeField({ id: "_modified_at", label: "Modified At" });
-  readonly _created_by = new ReferenceField<UserRefType>({
-    id: "_created_by",
-    label: "Created By",
-    referenceBdo: USER_BO_ID,
-    referenceFields: ["_id", "username"],
-  });
-  readonly _modified_by = new ReferenceField<UserRefType>({
-    id: "_modified_by",
-    label: "Modified By",
-    referenceBdo: USER_BO_ID,
-    referenceFields: ["_id", "username"],
-  });
-  readonly _version = new StringField({ id: "_version", label: "Version" });
-  readonly _m_version = new StringField({ id: "_m_version", label: "Metadata Version" });
+  readonly _id = new StringField({ _id: "_id", Name: "ID", Type: "String", ReadOnly: true });
+  readonly _created_at = new DateTimeField({ _id: "_created_at", Name: "Created At", Type: "DateTime", ReadOnly: true });
+  readonly _modified_at = new DateTimeField({ _id: "_modified_at", Name: "Modified At", Type: "DateTime", ReadOnly: true });
+  readonly _created_by = new UserField({ _id: "_created_by", Name: "Created By", Type: "User", ReadOnly: true });
+  readonly _modified_by = new UserField({ _id: "_modified_by", Name: "Modified By", Type: "User", ReadOnly: true });
+  readonly _version = new StringField({ _id: "_version", Name: "Version", Type: "String", ReadOnly: true });
+  readonly _m_version = new StringField({ _id: "_m_version", Name: "Metadata Version", Type: "String", ReadOnly: true });
 
   // ============================================================
   // FIELD DEFINITIONS (auto-discovered)
@@ -190,7 +165,7 @@ export abstract class BaseBdo<
   /**
    * Get a single record by ID
    */
-  protected async get(id: StringFieldType): Promise<ItemType<TEditable, TReadonly>> {
+  protected async get(id: string): Promise<ItemType<TEditable, TReadonly>> {
     const data = await api<TEditable & TReadonly>(this.meta._id).get(id);
     return new Item<TEditable & TReadonly>(this, data as Partial<TEditable & TReadonly>) as ItemType<TEditable, TReadonly>;
   }
@@ -237,7 +212,7 @@ export abstract class BaseBdo<
    * Update an existing record
    */
   protected async update(
-    id: StringFieldType,
+    id: string,
     data: Partial<TEditable>
   ): Promise<CreateUpdateResponseType> {
     return api<TEntity>(this.meta._id).update(id, data as Partial<TEntity>);
@@ -250,7 +225,7 @@ export abstract class BaseBdo<
   /**
    * Delete a record by ID
    */
-  protected async delete(id: StringFieldType): Promise<DeleteResponseType> {
+  protected async delete(id: string): Promise<DeleteResponseType> {
     return api<TEntity>(this.meta._id).delete(id);
   }
 
@@ -287,7 +262,7 @@ export abstract class BaseBdo<
    * Patch an existing draft - compute fields during editing
    */
   protected async draftPatch(
-    id: StringFieldType,
+    id: string,
     data: Partial<TEditable>
   ): Promise<DraftResponseType> {
     return api<TEntity>(this.meta._id).draftPatch(id, data as Partial<TEntity>);

package/sdk/bdo/core/Item.ts

@@ -3,7 +3,13 @@
 // Wraps a record with field accessors for type-safe manipulation
 // ============================================================
 
-import type { ValidationResultType, FieldMetaType } from "./types";
+import type {
+  ValidationResultType,
+  BaseFieldMetaType,
+  EditableFieldAccessorType,
+  ReadonlyFieldAccessorType,
+  FieldAccessorType,
+} from "./types";
 import type { BaseField } from "../fields/BaseField";
 
 /**
@@ -19,32 +25,8 @@ interface BdoLike {
   ): ValidationResultType;
 }
 
-/**
- * Editable field accessor — has get(), set(), validate()
- */
-export interface EditableFieldAccessorType<T> {
-  readonly meta: FieldMetaType;
-  get(): T | undefined;
-  set(value: T): void;
-  validate(): ValidationResultType;
-}
-
-/**
- * Readonly field accessor — has get(), validate(), NO set()
- */
-export interface ReadonlyFieldAccessorType<T> {
-  readonly meta: FieldMetaType;
-  get(): T | undefined;
-  validate(): ValidationResultType;
-}
-
-/**
- * Field accessor with get/set/validate methods + meta object (union type)
- */
-export type FieldAccessorType<T> = EditableFieldAccessorType<T> | ReadonlyFieldAccessorType<T>;
-
-// Re-export FieldMetaType for convenience
-export type { FieldMetaType };
+// Re-export accessor types for convenience
+export type { EditableFieldAccessorType, ReadonlyFieldAccessorType, FieldAccessorType, BaseFieldMetaType };
 
 /**
  * Create editable accessor type for each field in TEditable
@@ -78,31 +60,16 @@ export type ItemType<
  * Item class that wraps a record with field accessors
  *
  * Each field is accessible as a property returning an accessor with:
- * - id: field identifier
- * - label: display label
+ * - label: display name
+ * - required: whether field is required
+ * - readOnly: whether field is read-only
+ * - defaultValue: default value
+ * - meta: full raw backend meta
  * - get(): get current value
- * - set(value): set value
+ * - set(value): set value (editable fields only)
  * - validate(): validate current value
  *
  * @template T - The type of the underlying data
- *
- * @example
- * ```typescript
- * const product = new AdminProduct();
- * const item = await product.get("product_123");
- *
- * // Field accessor access
- * item.Title.get()  // get value
- * item.Title.set("New Title")  // set value (editable fields only)
- * item.Title.meta.id  // "Title"
- * item.Title.meta.label  // "Product Title"
- * item.Title.meta.isEditable  // true if field is editable
- * item.Title.validate()  // validate
- *
- * // Methods
- * const result = item.validate();  // validate all fields
- * const raw = item.toJSON();  // get raw data
- * ```
  */
 export class Item<T extends Record<string, unknown>> {
   private _data: Partial<T>;
@@ -201,13 +168,13 @@ export class Item<T extends Record<string, unknown>> {
     const fields = this._bdo.getFields();
     const fieldDef = fields[fieldId];
 
-    // Use field's meta directly (includes options for SelectField, reference for ReferenceField)
-    const meta: FieldMetaType = fieldDef?.meta ?? {
-      id: fieldId,
-      label: fieldId,
-      isEditable: true,
+    // Get raw meta from field definition
+    const meta: BaseFieldMetaType = fieldDef?.meta ?? {
+      _id: fieldId,
+      Name: fieldId,
+      Type: "String",
     };
-    const isEditable = meta.isEditable;
+    const isReadOnly = fieldDef?.readOnly ?? false;
 
     // Shared validate function
     const validate = (): ValidationResultType => {
@@ -231,11 +198,15 @@ export class Item<T extends Record<string, unknown>> {
       return { valid: true, errors: [] };
     };
 
-    // Create accessor — only add set() for editable fields
+    // Create accessor — only add set() for non-readOnly fields
     let accessor: FieldAccessorType<unknown>;
 
-    if (isEditable) {
+    if (!isReadOnly) {
       accessor = {
+        label: fieldDef?.label ?? fieldId,
+        required: fieldDef?.required ?? false,
+        readOnly: false,
+        defaultValue: fieldDef?.defaultValue,
         meta,
         get: () => this._data[fieldId as keyof T],
         set: (value: unknown) => {
@@ -245,6 +216,10 @@ export class Item<T extends Record<string, unknown>> {
       };
     } else {
       accessor = {
+        label: fieldDef?.label ?? fieldId,
+        required: fieldDef?.required ?? false,
+        readOnly: true,
+        defaultValue: fieldDef?.defaultValue,
         meta,
         get: () => this._data[fieldId as keyof T],
         validate,
@@ -265,6 +240,9 @@ export class Item<T extends Record<string, unknown>> {
     const allValues = this.toJSON() as Record<string, unknown>;
 
     for (const [fieldId, fieldDef] of Object.entries(fields)) {
+      // Skip readonly fields — users can't edit them, so validation errors are confusing
+      if (fieldDef.readOnly) continue;
+
       const value = this._data[fieldId as keyof T];
 
       // 1. Type validation