@ram_28/kf-ai-sdk 2.0.12 → 2.0.14

package/docs/bdo.md

@@ -5,801 +5,220 @@ Type-safe, role-based data access layer for business objects.
 ## Imports
 
 ```typescript
-// BDO class (from your generated code)
-import { AdminProduct } from "../bdo/admin/Product";
-
-// Field types (from your generated code)
-import type {
-  AdminProductEditableFieldType,
-  AdminProductReadonlyFieldType,
-  AdminProductFieldType,
-} from "../bdo/admin/Product";
+// BDO class (from generated code)
+import { AdminProduct } from "@/bdo/admin/Product";
+import type { AdminProductEditableFieldType, AdminProductFieldType } from "@/bdo/admin/Product";
 
 // SDK types
-import type {
-  ItemType,
-  BdoMetaType,
-  ValidationResultType,
-  SelectOptionType,
-  EditableFieldAccessorType,
-  ReadonlyFieldAccessorType,
-  BaseFieldMetaType,
-} from "@ram_28/kf-ai-sdk/bdo/types";
-
-// System fields
-import type { SystemFieldsType } from "@ram_28/kf-ai-sdk/bdo/types";
-
-// API types (for method params/responses)
-import type {
-  ListOptionsType,
-  CreateUpdateResponseType,
-  DeleteResponseType,
-  DraftResponseType,
-  MetricOptionsType,
-  MetricResponseType,
-  PivotOptionsType,
-  PivotResponseType,
-} from "@ram_28/kf-ai-sdk/api/types";
-```
-
-## BDO Meta
-
-Every BDO has a `meta` property identifying the business object.
-
-```typescript
-const product = new AdminProduct();
-
-product.meta._id;   // "BDO_Product"
-product.meta.name;  // "Product"
-```
-
-Use `meta._id` anywhere a source identifier is needed (e.g., `useTable`, `useFilter`).
-
----
-
-## Field Definitions
-
-Fields are readonly properties on the BDO class, constructed with raw backend meta JSON.
-
-```typescript
-// In the generated BDO class
-readonly Title = new StringField({
-  _id: "Title",
-  Name: "Product Title",
-  Type: "String",
-  Constraint: { Required: true, Length: 255 },
-});
-```
-
-### BaseField Getters
-
-Every field exposes these getters:
-
-| Getter | Type | Source |
-|--------|------|--------|
-| `field.id` | `string` | `_meta._id` |
-| `field.label` | `string` | `_meta.Name` |
-| `field.readOnly` | `boolean` | `_meta.ReadOnly` |
-| `field.required` | `boolean` | `_meta.Constraint.Required` or `_meta.Required` |
-| `field.defaultValue` | `unknown` | `_meta.DefaultValue` or `_meta.Constraint.DefaultValue` |
-| `field.primaryKey` | `boolean` | `_meta.Constraint.PrimaryKey` |
-| `field.meta` | `BaseFieldMetaType` | Full raw backend meta object |
-
-### Usage
-
-```typescript
-const product = new AdminProduct();
-
-// react-hook-form register
-register(product.Title.id);
-
-// UI labels
-<label>{product.Title.label}</label>
-
-// Required indicator
-{product.Title.required && <span>*</span>}
-
-// Filter by field
-const items = await product.list({
-  Filter: {
-    Operator: "And",
-    Condition: [{
-      LHSField: product.Price.id,
-      Operator: "GT",
-      RHSValue: 50,
-      RHSType: "Constant",
-    }],
-  },
-});
-```
-
----
-
-## Methods
-
-All `BaseBdo` methods are `protected`. Role BDOs selectively re-expose them as `public` based on permissions. For full request/response type definitions, see [api.md](api.md).
-
-### get
-
-Fetches a single record by ID.
-
-```typescript
-async get(id: string): Promise<ItemType<TEditable, TReadonly>>
-```
-
-Returns an [ItemType](#itemtype--runtime-accessor-pattern) with field accessors.
-
-```typescript
-const item = await product.get("prod_abc123");
-
-console.log(item._id);           // "prod_abc123"
-console.log(item.Title.get());   // "Wireless Headphones"
-console.log(item.Title.label);   // "Product Title"
-```
-
----
-
-### list
-
-Fetches paginated records with optional filtering, sorting, and pagination.
-
-```typescript
-async list(options?: ListOptionsType): Promise<ItemType<TEditable, TReadonly>[]>
-```
-
-Returns an array of [ItemType](#itemtype--runtime-accessor-pattern).
-
-```typescript
-const items = await product.list({
-  Filter: {
-    Operator: "And",
-    Condition: [{
-      LHSField: product.Category.id,
-      Operator: "EQ",
-      RHSValue: "Electronics",
-      RHSType: "Constant",
-    }],
-  },
-  Sort: [{ [product.Price.id]: "ASC" }],
-  Page: 1,
-  PageSize: 20,
-});
-
-items.forEach((item) => {
-  console.log(item.Title.get(), item.Price.get());
-});
-```
-
----
-
-### count
-
-Returns the count of records matching filter criteria.
-
-```typescript
-async count(options?: ListOptionsType): Promise<number>
-```
-
-Uses the same `ListOptionsType` for filtering. Returns the count directly as a `number`.
-
-```typescript
-const total = await product.count();
-console.log(`Total products: ${total}`);
-
-// With filter
-const lowStock = await product.count({
-  Filter: {
-    Operator: "And",
-    Condition: [{
-      LHSField: product.Stock.id,
-      Operator: "LT",
-      RHSValue: 10,
-      RHSType: "Constant",
-    }],
-  },
-});
+import type { ItemType, SystemFieldsType } from "@ram_28/kf-ai-sdk/bdo/types";
+import type { ListOptionsType, CreateUpdateResponseType, DeleteResponseType } from "@ram_28/kf-ai-sdk/api/types";
 ```
 
 ---
 
-### create
+## Common Mistakes (READ FIRST)
 
-Creates a new record.
-
-```typescript
-async create(data: Partial<TEditable>): Promise<ItemType<TEditable, TReadonly>>
-```
-
-Returns an [ItemType](#itemtype--runtime-accessor-pattern) with the new `_id` from the API response and the input data as field accessors.
-
-```typescript
-const newItem = await product.create({
-  Title: "Wireless Headphones",
-  Price: 99.99,
-  Category: "Electronics",
-});
-
-console.log(newItem._id);          // New record ID
-console.log(newItem.Title.get());  // "Wireless Headphones"
-```
-
----
-
-### update
-
-Updates an existing record.
-
-```typescript
-async update(id: string, data: Partial<TEditable>): Promise<CreateUpdateResponseType>
-```
-
-Returns `{ _id: string }`.
-
-```typescript
-const result = await product.update("prod_abc123", {
-  Price: 79.99,
-  Stock: 45,
-});
-
-console.log("Updated:", result._id);
-```
-
----
-
-### delete
-
-Deletes a record by ID.
-
-```typescript
-async delete(id: string): Promise<DeleteResponseType>
-```
+### 1. Guessing field names instead of reading BDO files
 
-Returns `{ status: "success" }`.
+ALWAYS read `src/bdo/{role}/*.ts` BEFORE writing page code. Use EXACT field names from the class.
 
 ```typescript
-const result = await product.delete("prod_abc123");
+// ❌ WRONG — guessing
+bdo.productName  bdo.isActive  bdo.unitPrice
 
-if (result.status === "success") {
-  console.log("Deleted successfully");
-}
+// ✅ CORRECT — exact snake_case from BDO file
+bdo.product_name  bdo.is_active  bdo.unit_price
 ```
 
----
-
-### draft
-
-Previews computed field values for a new record without saving.
+### 2. Rendering ItemType fields directly in JSX without `.get()`
 
-```typescript
-async draft(data: Partial<TEditable>): Promise<DraftResponseType>
-```
+`bdo.list()`, `bdo.get()`, `bdo.create()` return `ItemType` — each field is an accessor object, NOT a value.
 
-Returns computed field values as `{ [fieldName: string]: any }`.
-
-```typescript
-const draftResult = await product.draft({
-  Price: 100,
-  DiscountPercent: 15,
-});
+```tsx
+// ❌ WRONG — renders [object Object]
+const item = await bdo.get(id);
+<span>{item.product_name}</span>
 
-console.log("Computed discount:", draftResult.DiscountAmount);
-console.log("Computed final price:", draftResult.FinalPrice);
+// ✅ CORRECT — call .get()
+<span>{item.product_name.get()}</span>
+<span>{item.product_name.get() ?? "—"}</span>
 ```
 
----
-
-### draftPatch
+**Key distinction:** `useTable().rows` are plain objects (access `row.field` directly). `bdo.get()`/`bdo.list()` return ItemType proxies (must call `item.field.get()`).
 
-Previews computed field values for an existing record being edited.
-
-```typescript
-async draftPatch(id: string, data: Partial<TEditable>): Promise<DraftResponseType>
-```
+### 3. Rendering Image/File/Reference values in detail pages
 
-```typescript
-const draftResult = await product.draftPatch("prod_abc123", {
-  Price: 120,
-  DiscountPercent: 20,
-});
+These field types return complex objects from `.get()` — NOT renderable as React children.
 
-console.log("Updated discount:", draftResult.DiscountAmount);
-```
+```tsx
+// ❌ WRONG — FileType/ImageFieldType are objects, not ReactNode
+<span>{item.product_image.get()}</span>       // ImageFieldType = FileType | null
+<span>{item.attachments.get()}</span>          // FileFieldType = FileType[]
+<span>{item.category.get()}</span>             // Reference = { _id, _name, ... }
 
----
+// ✅ CORRECT — extract the renderable value
+// Image: use ImageThumbnail component (NEVER use src="#")
+import { ImageThumbnail } from "@/components/ui/image-thumbnail";
+<ImageThumbnail boId={bdo.meta._id} instanceId={item._id} fieldId={bdo.product_image.id} value={item.product_image.get()} imgClassName="w-24 h-24 object-cover rounded" />
 
-### draftInteraction
+// Image: if you only need the filename as text
+const img = item.product_image.get();
+<span>{img ? (img as any).FileName : "No image"}</span>
 
-Creates/updates a draft without requiring an instance ID. Returns computed fields along with a temporary `_id`.
+// File array: use FilePreview component
+import { FilePreview } from "@/components/ui/file-preview";
+<FilePreview boId={bdo.meta._id} instanceId={item._id} fieldId={bdo.attachments.id} value={item.attachments.get()} />
 
-```typescript
-async draftInteraction(data: Partial<TEditable>): Promise<DraftResponseType & { _id: string }>
-```
+// Reference: access _name
+const ref = item.category.get();
+<span>{ref ? (ref as any)._name : "—"}</span>
 
-```typescript
-const result = await product.draftInteraction({
-  Price: 100,
-  DiscountPercent: 10,
-});
+// Number: format
+<span>{(item.unit_price.get() ?? 0).toFixed(2)}</span>
 
-console.log(result._id);              // Temporary draft ID
-console.log(result.DiscountAmount);    // Computed value
+// Boolean: display
+<span>{item.is_active.get() ? "Yes" : "No"}</span>
 ```
 
----
+### 4. Calling protected methods
 
-### createItem
-
-Creates an `ItemType` wrapper synchronously (no API call). Useful for creating an empty item for form binding.
-
-```typescript
-createItem(data?: Partial<TEditable>): ItemType<TEditable, TReadonly>
-```
+Only methods the role has permission for are `public`. Check the BDO file.
 
 ```typescript
-const emptyItem = product.createItem();
-emptyItem.Title.set("Draft Product");
-emptyItem.Price.set(0);
+// ❌ WRONG — if delete is not in the role's BDO class
+await bdo.delete(id);  // TS2445: Property 'delete' is protected
 
-const validation = emptyItem.validate();
-console.log(validation.valid);   // false (required fields missing)
+// ✅ CORRECT — use api() for methods not on the BDO class
+import { api } from "@ram_28/kf-ai-sdk/api";
+await api(bdo.meta._id).delete(id);
 ```
 
----
-
-### metric
-
-Performs aggregation queries on records.
+### 5. Not handling `.get()` return type (undefined)
 
 ```typescript
-async metric(options: Omit<MetricOptionsType, "Type">): Promise<MetricResponseType>
-```
-
-The `Type` field is added internally. Pass only `GroupBy`, `Metric`, and optional `Filter`.
+// ❌ WRONG — might be undefined
+const title: string = item.product_name.get();
 
-```typescript
-// Total count
-const response = await product.metric({
-  GroupBy: [],
-  Metric: [{ Field: "_id", Type: "Count" }],
-});
-console.log("Total:", response.Data[0]["count__id"]);
-
-// Group by category with multiple metrics
-const byCategory = await product.metric({
-  GroupBy: ["Category"],
-  Metric: [
-    { Field: "Stock", Type: "Sum" },
-    { Field: "Price", Type: "Avg" },
-  ],
-});
-byCategory.Data.forEach((row) => {
-  console.log(`${row.Category}: ${row["sum_Stock"]} stock, $${row["avg_Price"]} avg`);
-});
+// ✅ CORRECT — provide fallback
+const title = item.product_name.get() ?? "";
+const price = item.unit_price.get() ?? 0;
 ```
 
 ---
 
-### pivot
-
-Creates pivot table aggregations with row and column dimensions.
+## BDO Meta & Fields
 
 ```typescript
-async pivot(options: Omit<PivotOptionsType, "Type">): Promise<PivotResponseType>
-```
-
-The `Type` field is added internally. Pass only `Row`, `Column`, `Metric`, and optional `Filter`.
+const product = new AdminProduct();
+product.meta._id;     // "BDO_Product" — use as source in useTable, api()
+product.meta.name;    // "Product"
 
-```typescript
-const response = await product.pivot({
-  Row: ["Category"],
-  Column: ["Region"],
-  Metric: [{ Field: "Stock", Type: "Sum" }],
-});
-
-const { RowHeader, ColumnHeader, Value } = response.Data;
-
-RowHeader.forEach((row, ri) => {
-  ColumnHeader.forEach((col, ci) => {
-    console.log(`${row.Key} - ${col.Key}: ${Value[ri][ci]}`);
-  });
-});
+// Field getters (all field types)
+product.product_name.id        // "product_name" — use in register(), watch(), setValue()
+product.product_name.label     // "product_name" — display label
+product.product_name.required  // boolean
+product.product_name.readOnly  // boolean
+product.product_name.defaultValue  // unknown
 ```
 
----
-
 ## Field Classes
 
-All field classes extend `BaseField<T>` and accept raw backend meta JSON as the constructor parameter.
+| Class | Extra Getters | Notes |
+|-------|--------------|-------|
+| `StringField` | `length` | May have `Constraint.Enum` — see useForm Mistake #3 |
+| `NumberField` | `integerPart`, `fractionPart` | |
+| `BooleanField` | — | |
+| `DateField` | — | Format: YYYY-MM-DD |
+| `DateTimeField` | `precision` | Format: YYYY-MM-DDTHH:MM:SS |
+| `SelectField` | **`options`**, `fetchOptions(instanceId)` | `.options` returns `{ value, label }[]` |
+| `ReferenceField` | `fetchOptions(instanceId)`, `referenceBdo` | Value is object `{ _id, _name, ... }` |
+| `TextField` | `format` | Long text |
+| `UserField` | `fetchOptions(instanceId)` | Value: `{ _id, _name }` |
+| `ImageField` | — | Value: `FileType \| null` |
+| `FileField` | — | Value: `FileType[]` |
 
-| Class | Backend Type | Extra Getters |
-|-------|-------------|---------------|
-| `StringField` | `"String"` | `length` |
-| `NumberField` | `"Number"` | `integerPart`, `fractionPart` |
-| `BooleanField` | `"Boolean"` | — |
-| `DateField` | `"Date"` | — |
-| `DateTimeField` | `"DateTime"` | `precision` |
-| `SelectField<T>` | `"String"` | `options`, `fetchOptions()` |
-| `ReferenceField<T>` | `"Reference"` | `referenceBdo`, `referenceFields`, `searchFields`, `fetchOptions()` |
-| `TextField` | `"Text"` | `format` |
-| `UserField` | `"User"` | `businessEntity` |
-| `FileField` | `"File"` | — |
-| `ArrayField<T>` | `"Array"` | `elementType` |
-| `ObjectField<T>` | `"Object"` | `properties` |
-
-### SelectField
-
-Options from `Constraint.Enum` are available synchronously via the `options` getter:
-
-```typescript
-product.Status.options;
-// [{ value: "active", label: "active" }, { value: "inactive", label: "inactive" }]
-```
-
-Dynamic options can be fetched from the backend via `fetchOptions()`:
-
-```typescript
-async fetchOptions(instanceId?: string): Promise<SelectOptionType<T>[]>
-```
-
-```typescript
-const statusOptions = await product.Status.fetchOptions();
-// [{ value: "active", label: "Active" }, { value: "inactive", label: "Inactive" }]
-```
-
-### ReferenceField
-
-Reference configuration is derived from `View.DataObject` in the raw meta:
-
-```typescript
-product.SupplierInfo.referenceBdo;     // "BDO_Supplier"
-product.SupplierInfo.referenceFields;  // ["_id", "SupplierName", "Email"]
-product.SupplierInfo.searchFields;     // ["SupplierName"]
-```
-
-Referenced records can be fetched via `fetchOptions()`:
-
-```typescript
-async fetchOptions(instanceId?: string): Promise<TRef[]>
-```
-
-```typescript
-const suppliers = await product.SupplierInfo.fetchOptions();
-// [{ _id: "sup_1", SupplierName: "Acme Corp", Email: "contact@acme.com" }, ...]
-```
+**CRITICAL**: Only `SelectField` has `.options` getter. `StringField` with `Constraint.Enum` does NOT.
 
 ---
 
-## ItemType — Runtime Accessor Pattern
-
-`ItemType<TEditable, TReadonly>` is what `get()`, `list()`, `create()`, and `createItem()` return. It wraps API response data with a Proxy, providing field accessors for every field.
-
-### Field Accessor Access
-
-```typescript
-const item = await product.get("prod_abc123");
-
-// Get value (NOT direct access — always use .get())
-item.Title.get();          // "Wireless Headphones"
-
-// Field metadata
-item.Title.label;          // "Product Title"
-item.Title.required;       // true
-item.Title.readOnly;       // false
-item.Title.defaultValue;   // undefined
-item.Title.meta;           // full raw backend meta (BaseFieldMetaType)
-
-// Set value (only on editable fields)
-item.Title.set("New Title");
-
-// Validate (type + expression rules)
-const result = item.Title.validate();
-// { valid: true, errors: [] }
-```
-
-### Direct `_id` Access
+## Methods
 
-`_id` is the only field accessed directly (not as an accessor):
+All methods are `protected` on `BaseBdo`. Role BDOs selectively expose them as `public`.
 
 ```typescript
-item._id;  // "prod_abc123"
-```
+// Read
+const item = await bdo.get(id);            // ItemType — call .get() on fields
+const items = await bdo.list(options?);     // ItemType[] — call .get() on fields
+const count = await bdo.count(options?);    // number
 
-### Editable vs Readonly Accessors
+// Write
+const created = await bdo.create(data);    // ItemType
+const result = await bdo.update(id, data); // { _id: string }
+const deleted = await bdo.delete(id);      // { status: "success" }
 
-Fields in `TEditable` get a `set()` method. Fields in `TReadonly` do not.
+// Draft
+const draft = await bdo.draft(data);       // { [field]: computed_value }
+const draftPatch = await bdo.draftPatch(id, data);
+const draftInt = await bdo.draftInteraction(data);  // { _id, ...computed }
 
-**Editable field accessor:**
+// Analytics
+const metric = await bdo.metric({ GroupBy: [], Metric: [{ Field: "_id", Type: "Count" }] });
+// Access: metric.Data[0]["count__id"]  (key pattern: {type}_{Field})
 
-```typescript
-{
-  label: string,
-  required: boolean,
-  readOnly: false,          // always false for editable
-  defaultValue: unknown,
-  meta: BaseFieldMetaType,
-  get(): T | undefined,
-  set(value: T): void,      // only on editable fields
-  validate(): ValidationResultType,
-}
+const pivot = await bdo.pivot({ Row: ["category"], Column: ["status"], Metric: [{ Field: "_id", Type: "Count" }] });
+// Access: pivot.Data.RowHeader, pivot.Data.ColumnHeader, pivot.Data.Value[row][col]
 ```
 
-**Readonly field accessor:**
+### ListOptionsType
 
 ```typescript
-{
-  label: string,
-  required: boolean,
-  readOnly: true,            // always true for readonly
-  defaultValue: unknown,
-  meta: BaseFieldMetaType,
-  get(): T | undefined,
-  validate(): ValidationResultType,
-  // no set()
+interface ListOptionsType {
+  Field?: string[];                        // Specific fields (omit for all)
+  Filter?: FilterType;                     // See useFilter docs
+  Sort?: Record<string, "ASC" | "DESC">[]; // [{ "field": "ASC" }]
+  Page?: number;                           // 1-indexed
+  PageSize?: number;                       // Default: 10
 }
 ```
 
-### Item Methods
-
-```typescript
-// Validate all non-readonly fields
-item.validate();
-// { valid: boolean, errors: string[] }
-
-// Convert to plain object
-item.toJSON();
-// Partial<T> — raw data without accessors
-```
-
 ---
 
-## Type Definitions
+## ItemType Accessor Pattern
 
-### BdoMetaType
+`get()`, `list()`, `create()` return `ItemType` with Proxy-wrapped field accessors.
 
 ```typescript
-interface BdoMetaType {
-  readonly _id: string;   // Business object ID (e.g., "BDO_Product")
-  readonly name: string;  // Display name (e.g., "Product")
-}
-```
+const item = await bdo.get("id123");
 
-### ValidationResultType
-
-```typescript
-interface ValidationResultType {
-  valid: boolean;
-  errors: string[];
-}
+item._id;                  // "id123" — direct access (only _id)
+item.product_name.get();   // string | undefined
+item.product_name.set("New");  // editable fields only
+item.product_name.label;   // "product_name"
+item.product_name.required; // boolean
+item.toJSON();             // plain object
 ```
 
-### SelectOptionType
-
-```typescript
-interface SelectOptionType<T = string> {
-  value: T;
-  label: string;
-  disabled?: boolean;
-}
-```
-
-### SystemFieldsType
+## SystemFieldsType
 
 ```typescript
 type SystemFieldsType = {
   _id: string;
-  _created_at: DateTimeFieldType;
-  _modified_at: DateTimeFieldType;
-  _created_by: UserFieldType;     // { _id: string; _name: string }
-  _modified_by: UserFieldType;
+  _created_at: string;    // "YYYY-MM-DDTHH:MM:SS"
+  _modified_at: string;
+  _created_by: { _id: string; _name: string };
+  _modified_by: { _id: string; _name: string };
   _version: string;
   _m_version: string;
 };
-
-// Union of system field names (for Omit<> operations)
-type SystemFields = keyof SystemFieldsType;
-```
-
-### BaseFieldMetaType
-
-The raw backend meta shape stored by every field:
-
-```typescript
-interface BaseFieldMetaType {
-  _id: string;           // Field identifier
-  Name: string;          // Display name
-  Type: string;          // Field type ("String", "Number", "Reference", etc.)
-  ReadOnly?: boolean;
-  Required?: boolean;
-  Constraint?: BaseConstraintType;
-  DefaultValue?: unknown;
-}
-```
-
-### BaseConstraintType
-
-```typescript
-interface BaseConstraintType {
-  Required?: boolean;
-  PrimaryKey?: boolean;
-  DefaultValue?: unknown;
-}
-```
-
-### EditableFieldAccessorType
-
-```typescript
-interface EditableFieldAccessorType<T> {
-  readonly label: string;
-  readonly required: boolean;
-  readonly readOnly: boolean;
-  readonly defaultValue: unknown;
-  readonly meta: BaseFieldMetaType;
-  get(): T | undefined;
-  set(value: T): void;
-  validate(): ValidationResultType;
-}
-```
-
-### ReadonlyFieldAccessorType
-
-```typescript
-type ReadonlyFieldAccessorType<T> = {
-  readonly label: string;
-  readonly required: boolean;
-  readonly readOnly: boolean;
-  readonly defaultValue: unknown;
-  readonly meta: BaseFieldMetaType;
-  get(): T | undefined;
-  validate(): ValidationResultType;
-};
-```
-
----
-
-## Complete Example
-
-```typescript
-import { AdminProduct } from "../bdo/admin/Product";
-import type {
-  AdminProductEditableFieldType,
-  AdminProductFieldType,
-} from "../bdo/admin/Product";
-
-const product = new AdminProduct();
-
-// ---- Field metadata ----
-console.log(product.meta._id);       // "BDO_Product"
-console.log(product.Title.label);    // "Product Title"
-console.log(product.Title.required); // true
-
-// ---- Get a single item ----
-const item = await product.get("prod_abc123");
-console.log(item._id);              // "prod_abc123"
-console.log(item.Title.get());      // "Wireless Headphones"
-console.log(item.Price.get());      // 99.99
-
-// ---- List items with filter ----
-const items = await product.list({
-  Filter: {
-    Operator: "And",
-    Condition: [{
-      LHSField: product.Category.id,
-      Operator: "EQ",
-      RHSValue: "Electronics",
-      RHSType: "Constant",
-    }],
-  },
-  Sort: [{ [product.Price.id]: "ASC" }],
-  Page: 1,
-  PageSize: 20,
-});
-
-for (const item of items) {
-  console.log(item.Title.get(), item.Price.get());
-}
-
-// ---- Count ----
-const total = await product.count();
-console.log(`Total products: ${total}`);
-
-// ---- Create ----
-const newItem = await product.create({
-  Title: "New Product",
-  Price: 49.99,
-  Category: "Books",
-});
-console.log(newItem._id);          // New record ID
-console.log(newItem.Title.get());  // "New Product"
-
-// ---- Update ----
-const updateResult = await product.update("prod_abc123", {
-  Price: 79.99,
-});
-console.log(updateResult._id);     // "prod_abc123"
-
-// ---- Delete ----
-const deleteResult = await product.delete("prod_abc123");
-console.log(deleteResult.status);  // "success"
-
-// ---- Validate ----
-const emptyItem = product.createItem();
-emptyItem.Title.set("");
-const validation = emptyItem.validate();
-console.log(validation.valid);     // false
-console.log(validation.errors);    // ["Product Title is required"]
-
-// ---- SelectField options ----
-const statusOptions = await product.Status.fetchOptions();
-statusOptions.forEach((opt) => {
-  console.log(`${opt.value}: ${opt.label}`);
-});
-
-// ---- ReferenceField options ----
-const suppliers = await product.SupplierInfo.fetchOptions();
-suppliers.forEach((sup) => {
-  console.log(`${sup._id}: ${sup.SupplierName}`);
-});
-```
-
----
-
-## Common Mistakes
-
-### 1. Guessing field names instead of reading BDO files
-
-ALWAYS read the BDO `.ts` files (`src/bdo/{role}/*.ts`) BEFORE writing page code. Use the exact field names from the class — NEVER guess or invent field names.
-
-```typescript
-// ❌ WRONG — guessing field names that don't exist
-bdo.used        // TS2339: Property 'used' does not exist
-bdo.remaining   // TS2339: Property 'remaining' does not exist
-bdo.meta_title  // TS2339: actual field might be 'seo_title'
-bdo.tags        // TS2339: no such field exists
-
-// ✅ CORRECT — read the BDO file first, use exact names
-// Check src/bdo/employee/LeaveBalance.ts for actual fields
-bdo.UsedLeaves     // matches the actual field in the BDO class
-bdo.RemainingDays  // matches the actual field in the BDO class
 ```
 
-### 2. Inventing BDO classes that don't exist
-
-Check `src/bdo/{role}/index.ts` to see which BDO classes actually exist before importing.
+## API Types
 
 ```typescript
-// ❌ WRONG — ShippingAddress BDO doesn't exist
-import { customerShippingAddress } from "@/bdo/customer/ShippingAddress";
-
-// ✅ CORRECT — check index.ts first. shipping_address might just be a StringField on Order
-import { customerOrder } from "@/bdo/customer/Order";
-```
-
-### 3. Calling protected methods
-
-All `BaseBdo` methods are `protected` by default. Only the methods the role has permission for are re-exposed as `public` in the generated class. Read the BDO file to see which methods are available.
-
-```typescript
-// ❌ WRONG — if delete is not in the role's BDO class
-await bdo.delete(id);  // TS2445: Property 'delete' is protected
-
-// ✅ CORRECT — use api() for methods not exposed on the BDO class
-import { api } from "@ram_28/kf-ai-sdk/api";
-await api(bdo.meta._id).delete(id);
-
-// ✅ CORRECT — for create/update, prefer useForm
-const { handleSubmit } = useForm({ bdo });
-```
-
-### 4. Not handling `.get()` return type
-
-`ItemType` field `.get()` returns `T | undefined`. Always handle the undefined case.
-
-```typescript
-// ❌ WRONG — might be undefined
-const title: string = item.Title.get();
-
-// ✅ CORRECT — provide fallback
-const title = item.Title.get() ?? "";
-const price = item.Price.get() ?? 0;
-const active = item.IsActive.get() ?? false;
+interface CreateUpdateResponseType { _id: string; }
+interface DeleteResponseType { status: "success"; }
+interface FileType { _id: string; _name: string; FileName: string; FileExtension: string; Size: number; ContentType: string; }
+type ImageFieldType = FileType | null;
+type FileFieldType = FileType[];
+type AggregationType = "Sum" | "Avg" | "Count" | "Max" | "Min" | "DistinctCount" | "BlankCount" | "NotBlankCount" | "Concat" | "DistinctConcat";
 ```