@ram_28/kf-ai-sdk 2.0.19 → 2.0.20-beta.1

package/sdk/components/hooks/useActivityForm/useActivityForm.ts

@@ -10,9 +10,12 @@ import { useForm as useReactHookForm } from 'react-hook-form';
 import { useQuery } from '@tanstack/react-query';
 
 import type { Activity } from '../../../workflow/Activity';
-import type { UseActivityFormOptions, UseActivityFormReturn } from './types';
+import type {
+  UseActivityFormOptions,
+  UseActivityFormReturn,
+  AllActivityFields,
+} from './types';
 
-import type { CreateUpdateResponseType } from '../../../types/common';
 import { createActivityResolver } from './createActivityResolver';
 import { createActivityItemProxy } from './createActivityItemProxy';
 import {
@@ -297,13 +300,13 @@ export function useActivityForm<A extends Activity<any, any, any>>(
   );
 
   // ============================================================
-  // HANDLE SUBMIT — activity.update() + activity.complete()
+  // HANDLE SUBMIT — activity.update()
   // ============================================================
 
   const handleSubmit = useCallback(
     (
       onSuccess?: (
-        data: CreateUpdateResponseType,
+        data: AllActivityFields<A>,
         e?: React.BaseSyntheticEvent,
       ) => void | Promise<void>,
       onError?: (
@@ -316,7 +319,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
           setIsSubmitting(true);
 
           try {
-            // Only send dirty (changed) fields — matches useBDOForm behavior
+            // Only send dirty (changed) fields — matches useBDOForm update behavior
             // Use getValues() to capture Image/File values set via setValue()
             // that RHF resolver doesn't include in `data`
             const cleanedData: Record<string, unknown> = {};
@@ -336,7 +339,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
                 : value;
             }
 
-            // Send remaining dirty fields via update
+            // Save via activity.update()
             if (Object.keys(cleanedData).length > 0) {
               await activityRef.update(
                 activity_instance_id,
@@ -344,10 +347,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
               );
             }
 
-            // Complete the activity — advances the workflow
-            const result = await activityRef.complete(activity_instance_id);
-
-            await onSuccess?.(result, event);
+            await onSuccess?.(data as AllActivityFields<A>, event);
           } catch (error) {
             onError?.(toError(error), event);
           } finally {
@@ -362,6 +362,68 @@ export function useActivityForm<A extends Activity<any, any, any>>(
     [rhf, activityRef, readonlyFieldNames, allFields, activity_instance_id],
   ) as UseActivityFormReturn<A>['handleSubmit'];
 
+  // ============================================================
+  // HANDLE COMPLETE — activity.update() + activity.complete()
+  // ============================================================
+
+  const handleComplete = useCallback(
+    (
+      onSuccess?: (
+        data: AllActivityFields<A>,
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
+      onError?: (
+        error: any,
+        e?: React.BaseSyntheticEvent,
+      ) => void | Promise<void>,
+    ) => {
+      return rhf.handleSubmit(
+        async (data, event) => {
+          setIsSubmitting(true);
+
+          try {
+            // Only send dirty (changed) fields — matches useBDOForm update behavior
+            // Use getValues() to capture Image/File values set via setValue()
+            // that RHF resolver doesn't include in `data`
+            const cleanedData: Record<string, unknown> = {};
+            const readonlySet = new Set(readonlyFieldNames);
+            const dirtyFields = rhf.formState.dirtyFields;
+            const allValues = rhf.getValues() as Record<string, unknown>;
+
+            for (const key of Object.keys(allValues)) {
+              if (readonlySet.has(key) || !dirtyFields[key]) continue;
+              const value =
+                allValues[key] !== undefined
+                  ? allValues[key]
+                  : (data as Record<string, unknown>)[key];
+              const field = allFields[key];
+              cleanedData[key] = field
+                ? coerceFieldValue(field, value)
+                : value;
+            }
+
+            if (Object.keys(cleanedData).length > 0) {
+              await activityRef.update(
+                activity_instance_id,
+                cleanedData as any,
+              );
+            }
+            await activityRef.complete(activity_instance_id);
+            await onSuccess?.(data as AllActivityFields<A>, event);
+          } catch (error) {
+            onError?.(toError(error), event);
+          } finally {
+            setIsSubmitting(false);
+          }
+        },
+        (errors, event) => {
+          onError?.(errors, event);
+        },
+      );
+    },
+    [rhf, activityRef, readonlyFieldNames, allFields, activity_instance_id],
+  ) as UseActivityFormReturn<A>['handleComplete'];
+
   // ============================================================
   // CLEAR ERRORS
   // ============================================================
@@ -386,6 +448,7 @@ export function useActivityForm<A extends Activity<any, any, any>>(
     // Form methods
     register,
     handleSubmit,
+    handleComplete,
     watch: rhf.watch as any,
     setValue: rhf.setValue as any,
     getValues: rhf.getValues as any,

package/sdk/components/hooks/useActivityTable/types.ts

@@ -1,4 +1,5 @@
 import type { Activity } from '../../../workflow/Activity';
+import type { ActivityInstanceFieldsType } from '../../../workflow/types';
 import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
 import type { UseFilterOptionsType } from '../useFilter/types';
 import type { SortType } from '../../../types/common';
@@ -15,12 +16,12 @@ export type ActivityTableStatusType =
   (typeof ActivityTableStatus)[keyof typeof ActivityTableStatus];
 
 /**
- * Row type — inferred from Activity's getInProgressList() return type.
- * Resolves to ActivityInstanceType (proxy with .get()/.set()).
+ * Row type for activity table data.
+ * System fields and entity fields are flat at the top level.
  */
 export type ActivityRowType<A extends Activity<any, any, any>> =
-  A extends { getInProgressList(opts?: any): Promise<(infer R)[]> }
-    ? R
+  A extends Activity<infer E, any, any>
+    ? ActivityInstanceFieldsType & E
     : never;
 
 export interface UseActivityTableOptionsType<

package/sdk/components/hooks/useActivityTable/useActivityTable.ts

@@ -13,24 +13,22 @@ export function useActivityTable<A extends Activity<any, any, any>>(
   const { activity, status, ...rest } = options;
   const { businessProcessId, activityId } = activity.meta;
 
+  const ops = useMemo(() => activity._getOps(), [activity]);
+
   const listFn = useMemo(
     () =>
       status === 'inprogress'
-        ? async (opts: any) => ({
-            Data: (await activity.getInProgressList(opts)) as ActivityRowType<A>[],
-          })
-        : async (opts: any) => ({
-            Data: (await activity.getCompletedList(opts)) as ActivityRowType<A>[],
-          }),
-    [activity, status],
+        ? (opts: any) => ops.inProgressList(opts)
+        : (opts: any) => ops.completedList(opts),
+    [ops, status],
   );
 
   const countFn = useMemo(
     () =>
       status === 'inprogress'
-        ? async (opts: any) => ({ Count: await activity.inProgressCount(opts) })
-        : async (opts: any) => ({ Count: await activity.completedCount(opts) }),
-    [activity, status],
+        ? (opts: any) => ops.inProgressCount(opts)
+        : (opts: any) => ops.completedCount(opts),
+    [ops, status],
   );
 
   return useTable<ActivityRowType<A>>({

package/sdk/components/hooks/useBDOForm/createItemProxy.ts

@@ -21,8 +21,8 @@ import type {
  * Key principle: Item has NO state. It's a view over RHF's state.
  * Editable fields get set(), readonly fields do not.
  *
- * In create mode (no _id), attachment and fetch operations use 'draft' as the
- * instanceId, which the backend accepts as a placeholder.
+ * In create mode (no _id), uses "draft" as the instanceId for attachment
+ * uploads and fetch operations — no draftInteraction() call needed.
  *
  * @param bdo - The BDO instance for field metadata
  * @param form - The RHF useForm return object
@@ -36,8 +36,6 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
   const accessorCache = new Map<string, EditableFormFieldAccessorType<unknown> | ReadonlyFormFieldAccessorType<unknown>>();
 
   const boIdShared = bdo.getBoId();
-
-  /** Returns the real _id in edit mode, or 'draft' in create mode */
   const getInstanceId = (): string =>
     (form.getValues("_id" as Path<FieldValues>) as string) || "draft";
 
@@ -150,16 +148,15 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
           validate,
         };
 
-        // Enrich Image/File field accessors with attachment methods (draft-based upload)
+        // Enrich Image/File field accessors with attachment methods
         if (fieldMeta.Type === "Image" || fieldMeta.Type === "File") {
           const boId = boIdShared;
 
           if (fieldMeta.Type === "Image") {
-            // Image: single file upload — always uploads immediately (draft in create mode)
+            // Image: single file upload
             (accessor as any).upload = async (file: File): Promise<FileType> => {
               validateFileExtension(file.name, "Image");
               const id = getInstanceId();
-
               const [uploadInfo] = await api(boId).getUploadUrl(id, prop, [
                 { FileName: file.name, Size: file.size, FileExtension: extractFileExtension(file.name) },
               ]);
@@ -195,11 +192,10 @@ export function createItemProxy<B extends BaseBdo<any, any, any>>(
               return api(boId).getDownloadUrl(instanceId, prop, val._id, viewType);
             };
           } else {
-            // File field — multi-file, always uploads immediately (draft in create mode)
+            // File field — multi-file
             (accessor as any).upload = async (files: File[]): Promise<FileType[]> => {
               for (const file of files) validateFileExtension(file.name, "File");
               const id = getInstanceId();
-
               const requests = files.map((file) => ({
                 FileName: file.name,
                 Size: file.size,

package/sdk/components/hooks/useBDOTable/types.ts

@@ -1,32 +1,22 @@
-import type { ListOptionsType, SortType } from '../../../types/common';
 import type { UseTableReturnType, PaginationStateType } from '../useTable/types';
 import type { UseFilterOptionsType } from '../useFilter/types';
+import type { SortType } from '../../../types/common';
 
-/** Structural constraint — any object with list() and count() */
-export interface BDOTableSourceType {
-  meta: { readonly _id: string; readonly name: string };
-  list(options?: ListOptionsType): Promise<any[]>;
-  count(options?: ListOptionsType): Promise<number>;
-}
-
-/** Infer row type from BDO's list() return type */
-export type BDORowType<B extends BDOTableSourceType> =
-  B extends { list(opts?: any): Promise<(infer R)[]> } ? R : never;
-
-export interface UseBDOTableOptionsType<B extends BDOTableSourceType> {
-  /** BDO instance — list() and count() are called for data */
-  bdo: B;
+export interface UseBDOTableOptionsType<T> {
+  /** BDO instance — only meta._id is used (for API routing) */
+  bdo: {
+    meta: { readonly _id: string; readonly name: string };
+  };
   /** Initial state */
   initialState?: {
     sort?: SortType;
     pagination?: PaginationStateType;
-    filter?: UseFilterOptionsType<BDORowType<B>>;
+    filter?: UseFilterOptionsType<T>;
   };
   /** Error callback */
   onError?: (error: Error) => void;
-  /** Success callback — receives Item rows from current page */
-  onSuccess?: (data: BDORowType<B>[]) => void;
+  /** Success callback — receives rows from current page */
+  onSuccess?: (data: T[]) => void;
 }
 
-export type UseBDOTableReturnType<B extends BDOTableSourceType> =
-  UseTableReturnType<BDORowType<B>>;
+export type UseBDOTableReturnType<T> = UseTableReturnType<T>;

package/sdk/components/hooks/useBDOTable/useBDOTable.ts

@@ -1,20 +1,16 @@
+import { api } from '../../../api/client';
 import { useTable } from '../useTable';
-import type {
-  BDOTableSourceType,
-  BDORowType,
-  UseBDOTableOptionsType,
-  UseBDOTableReturnType,
-} from './types';
+import type { UseBDOTableOptionsType, UseBDOTableReturnType } from './types';
 
-export function useBDOTable<B extends BDOTableSourceType>(
-  options: UseBDOTableOptionsType<B>,
-): UseBDOTableReturnType<B> {
+export function useBDOTable<T = any>(
+  options: UseBDOTableOptionsType<T>,
+): UseBDOTableReturnType<T> {
   const { bdo, ...rest } = options;
 
-  return useTable<BDORowType<B>>({
+  return useTable<T>({
     queryKey: ['table', bdo.meta._id],
-    listFn: async (opts) => ({ Data: await bdo.list(opts) }),
-    countFn: async (opts) => ({ Count: await bdo.count(opts) }),
+    listFn: (opts) => api<T>(bdo.meta._id).list(opts),
+    countFn: (opts) => api<T>(bdo.meta._id).count(opts),
     ...rest,
   });
 }

package/sdk/table.types.ts

@@ -14,8 +14,6 @@ export type {
 
 export type {
   // BDO wrapper types
-  BDOTableSourceType,
-  BDORowType,
   UseBDOTableOptionsType,
   UseBDOTableReturnType,
 } from './components/hooks/useBDOTable/types';

package/sdk/types/constants.ts

@@ -351,7 +351,7 @@ export const AuthStatus = {
  */
 export const AuthProviderName = {
   Google: "google",
-  Azure: "azure",
+  Microsoft: "microsoft",
   GitHub: "github",
   Custom: "custom",
 } as const;

package/sdk/workflow/Activity.ts

@@ -23,15 +23,13 @@ import { createActivityInstance } from "./ActivityInstance";
 import type { ActivityInstanceType } from "./ActivityInstance";
 import type { ActivityInstanceFieldsType, ActivityOperations } from "./types";
 import type {
+  ListResponseType,
   ListOptionsType,
   MetricOptionsType,
   MetricResponseType,
 } from "../types/common";
 import { BaseField } from "../bdo/fields/BaseField";
 
-/** Activity system fields treated as readonly on list results */
-type ActivitySystemReadonlyType = Omit<ActivityInstanceFieldsType, '_id'>;
-
 // ============================================================
 // ABSTRACT BASE CLASS
 // ============================================================
@@ -130,48 +128,18 @@ export abstract class Activity<
 
   /**
    * List in-progress activity instances.
-   * Each row is wrapped in an ActivityInstance proxy with field accessors.
+   * Accepts optional filter/sort/pagination options.
    */
-  async getInProgressList(
-    options?: ListOptionsType,
-  ): Promise<ActivityInstanceType<
-    ActivityInstanceFieldsType & TEntity,
-    TEditable,
-    TReadonly & ActivitySystemReadonlyType
-  >[]> {
-    const ops = this._ops();
-    const response = await ops.inProgressList(options);
-    const fields = this._discoverFields();
-    return response.Data.map((data) =>
-      createActivityInstance<
-        ActivityInstanceFieldsType & TEntity,
-        TEditable,
-        TReadonly & ActivitySystemReadonlyType
-      >(ops, (data as any)._id, data as (ActivityInstanceFieldsType & TEntity), fields),
-    );
+  async getInProgressList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().inProgressList(options);
   }
 
   /**
    * List completed activity instances.
-   * Each row is wrapped in an ActivityInstance proxy with field accessors.
+   * Accepts optional filter/sort/pagination options.
    */
-  async getCompletedList(
-    options?: ListOptionsType,
-  ): Promise<ActivityInstanceType<
-    ActivityInstanceFieldsType & TEntity,
-    TEditable,
-    TReadonly & ActivitySystemReadonlyType
-  >[]> {
-    const ops = this._ops();
-    const response = await ops.completedList(options);
-    const fields = this._discoverFields();
-    return response.Data.map((data) =>
-      createActivityInstance<
-        ActivityInstanceFieldsType & TEntity,
-        TEditable,
-        TReadonly & ActivitySystemReadonlyType
-      >(ops, (data as any)._id, data as (ActivityInstanceFieldsType & TEntity), fields),
-    );
+  async getCompletedList(options?: ListOptionsType): Promise<ListResponseType<ActivityInstanceFieldsType & TEntity>> {
+    return this._ops().completedList(options);
   }
 
   /**

package/dist/constants-DEmYwKfC.cjs

@@ -1 +0,0 @@
-"use strict";const t={EQ:"EQ",NE:"NE",GT:"GT",GTE:"GTE",LT:"LT",LTE:"LTE",Between:"Between",NotBetween:"NotBetween",IN:"IN",NIN:"NIN",Empty:"Empty",NotEmpty:"NotEmpty",Contains:"Contains",NotContains:"NotContains",MinLength:"MinLength",MaxLength:"MaxLength",Length:"Length"},e={And:"And",Or:"Or",Not:"Not"},n={Constant:"Constant",BDOField:"BDOField",AppVariable:"AppVariable"},o={ASC:"ASC",DESC:"DESC"},i={Sum:"Sum",Avg:"Avg",Count:"Count",Max:"Max",Min:"Min",DistinctCount:"DistinctCount",BlankCount:"BlankCount",NotBlankCount:"NotBlankCount",Concat:"Concat",DistinctConcat:"DistinctConcat"},a={List:"List",Metric:"Metric",Pivot:"Pivot"},r={Create:"create",Update:"update"},c={Interactive:"interactive",NonInteractive:"non-interactive"},s={OnBlur:"onBlur",OnChange:"onChange",OnSubmit:"onSubmit",OnTouched:"onTouched",All:"all"},d={Loading:"loading",Authenticated:"authenticated",Unauthenticated:"unauthenticated"},u={Google:"google",Azure:"azure",GitHub:"github",Custom:"custom"},C={Id:"_id",CreatedAt:"_created_at",ModifiedAt:"_modified_at",CreatedBy:"_created_by",ModifiedBy:"_modified_by",Version:"_version",MergeVersion:"_m_version"},E={GET:"GET",POST:"POST",PATCH:"PATCH",DELETE:"DELETE"},p={SEARCH_DEBOUNCE_MS:300,PAGE_SIZE:10,PAGE:1,SEARCH_MAX_LENGTH:255},T={Date:"$__d__",DateTime:"$__dt__"},l={Success:"success"};exports.AuthProviderName=u;exports.AuthStatus=d;exports.ConditionOperator=t;exports.DateEncodingKey=T;exports.Defaults=p;exports.DeleteStatus=l;exports.FormOperation=r;exports.GroupOperator=e;exports.HttpMethod=E;exports.InteractionMode=c;exports.MetricType=i;exports.QueryType=a;exports.RHSType=n;exports.SortDirection=o;exports.SystemField=C;exports.ValidationMode=s;

package/docs/README.md

@@ -1,57 +0,0 @@
-# @ram_28/kf-ai-sdk Documentation
-
-React SDK for building web applications with type-safe hooks for forms, tables, workflow, and authentication.
-
-## Authentication
-
-**[`useAuth`](./useAuth/README.md)** — Cookie-based authentication with `AuthProvider`, login/logout, session management, and role checks. Wrap your app in `<AuthProvider>` and use `useAuth()` to access `user`, `isAuthenticated`, `login()`, `logout()`.
-
-## BDO (Business Data Objects)
-
-BDO is the data access layer. See the [BDO module docs](./bdo/README.md) for field classes, Item proxy, and the three-generics pattern.
-
-### When working with field types and metadata
-
-**See [Fields](./fields/README.md)** · [API Reference](./fields/api_reference.md)
-
-All 13 field classes (`StringField`, `NumberField`, `SelectField`, `ReferenceField`, `FileField`, etc.), the `BaseField<T>` contract, field-specific getters (`length`, `options`, `precision`, `format`), and pre-built UI components for attachments.
-
-### When building a form for a BDO record
-
-**Use [`useBDOForm`](./useBDOForm/README.md)** · [API Reference](./useBDOForm/api_reference.md)
-
-Create, edit, or view a single BDO record. Automatic validation, per-field server sync, and `handleSubmit` to persist.
-
-### When building a table of BDO records
-
-**Use [`useBDOTable`](./useBDOTable/README.md)** · [API Reference](./useBDOTable/api_reference.md)
-
-List BDO records with sorting, search, filtering, and pagination. Rows are proxies with `.get()` accessors.
-
-### When building a CRUD page (table + form dialog)
-
-**Use `useBDOTable` + `useBDOForm` together.**
-
-The table lists records; clicking a row opens a form dialog to create or edit.
-
-## Workflow
-
-Workflow orchestrates multi-step business processes (e.g., employee submits leave → manager approves). See the [Workflow module docs](./workflow/README.md) for `Workflow`, `Activity`, and instance management.
-
-### When building a form for a workflow activity
-
-**Use [`useActivityForm`](./useActivityForm/README.md)** · [API Reference](./useActivityForm/api_reference.md)
-
-Fill in an activity's input fields. Same API shape as `useBDOForm` but operates on activity instances. Context-derived readonly fields from prior activities are discovered automatically from BP metadata.
-
-### When building a table of workflow activities
-
-**Use [`useActivityTable`](./useActivityTable/README.md)** · [API Reference](./useActivityTable/api_reference.md)
-
-List in-progress or completed activity instances. Same API shape as `useBDOTable` with activity system fields (`Status`, `AssignedTo`, `CompletedAt`, `BPInstanceId`).
-
-### When building a workflow page (table + form dialog)
-
-**Use `useActivityTable` + `useActivityForm` together.**
-
-The table lists activity instances; clicking a row opens a form dialog.

package/docs/bdo/README.md

@@ -1,161 +0,0 @@
-# BDO (Business Data Object)
-
-Type-safe, role-based data access layer. Each BDO class extends `BaseBdo<TEntity, TEditable, TReadonly>` and exposes CRUD methods filtered by role permissions.
-
-## Imports
-
-```typescript
-// Page component — import the generated role-specific BDO class
-import { AdminProduct } from "../bdo/admin/Product";
-```
-
-```typescript
-// BDO class definition — used by the js_sdk generator
-import { BaseBdo, StringField, NumberField, BooleanField, DateField, SelectField, ReferenceField } from "@ram_28/kf-ai-sdk/bdo";
-import type { StringFieldType, NumberFieldType, BooleanFieldType, DateFieldType, SelectFieldType, ReferenceFieldType, SystemFieldsType } from "@ram_28/kf-ai-sdk/types";
-import type { ListOptionsType } from "@ram_28/kf-ai-sdk/api/types";
-```
-
-## Common Mistakes (READ FIRST)
-
-1. **`create()` returns `ItemType`, not `{ _id }`** — It returns a proxy-wrapped item with field accessors, not `CreateUpdateResponseType`. Use `item._id` to get the ID.
-2. **Use `.get()` to read field values** — `item.Title` returns a field accessor object, not the value. Use `item.Title.get()`.
-3. **Field names use `_name` not `name`** — System fields like `_created_by` return `{ _id, _name }`. Access the display name with `item._created_by.get()?._name`.
-4. **Memoize BDO instances in React** — Wrap in `useMemo` to prevent re-creation on every render:
-   ```typescript
-   const product = useMemo(() => new AdminProduct(), []);
-   ```
-
-## Quick Start
-
-```typescript
-const product = new AdminProduct();
-
-// Create — returns ItemType (proxy with field accessors)
-const item = await product.create({ Title: "Widget", Price: 29.99 });
-item._id;           // "abc123"
-item.Title.get();   // "Widget"
-item.Price.get();   // 29.99
-
-// List
-const items = await product.list({ Page: 1, PageSize: 10 });
-items[0].Title.get();
-
-// Get single item
-const found = await product.get("abc123");
-found.Title.get();  // "Widget"
-
-// Update — returns { _id: string }
-await product.update("abc123", { Price: 39.99 });
-
-// Delete — returns { status: string }
-await product.delete("abc123");
-```
-
-## Usage Guide
-
-### CRUD Operations
-
-```typescript
-const product = new AdminProduct();
-
-// Create — returns ItemType with field accessors
-const item = await product.create({
-  Title: "Widget",
-  Price: 29.99,
-  Category: "Electronics",
-});
-item._id; // direct string access
-
-// Get single item
-const item = await product.get("abc123");
-
-// Update — returns { _id: string }
-const { _id } = await product.update("abc123", { Price: 39.99 });
-
-// Delete — returns { status: string }
-const { status } = await product.delete("abc123");
-
-// Count
-const total = await product.count();
-const filtered = await product.count({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { Operator: "eq", LHSField: "Category", RHSValue: "Electronics" },
-    ],
-  },
-});
-```
-
-### ItemType Field Accessors
-
-Every `get()`, `list()`, and `create()` call returns `ItemType` — a proxy with typed field accessors.
-
-```typescript
-const item = await product.get("abc123");
-
-// Read values
-item._id;                    // string (direct, not an accessor)
-item.Title.get();            // string | undefined
-item.Price.getOrDefault(0);  // number (never undefined)
-
-// Write values (editable fields only)
-item.Title.set("New Title");
-
-// Field metadata
-item.Title.label;        // "Product Title"
-item.Title.required;     // true
-item.Title.readOnly;     // false
-item.Title.defaultValue; // undefined
-item.Title.meta;         // raw backend field meta
-
-// Validation
-item.Title.validate();   // { valid: boolean, errors: string[] }
-item.validate();         // validates all fields, returns { valid, errors }
-
-// Serialize
-item.toJSON();           // { Title: "New Title", Price: 29.99, ... }
-```
-
-### List with Filter, Sort, and Pagination
-
-```typescript
-const items = await product.list({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { Operator: "eq", LHSField: "Category", RHSValue: "Electronics" },
-      { Operator: "gte", LHSField: "Price", RHSValue: 10 },
-    ],
-  },
-  Sort: [{ Price: "DESC" }],
-  Page: 1,
-  PageSize: 20,
-});
-```
-
-### Metric (Aggregation)
-
-```typescript
-const result = await product.metric({
-  GroupBy: ["Category"],
-  Metric: [{ Field: "Price", Type: "Avg" }],
-});
-// result.Data = [{ Category: "Electronics", Price: 299.5 }, ...]
-```
-
-### Pivot (Cross-Tabulation)
-
-```typescript
-const result = await product.pivot({
-  Row: ["Category"],
-  Column: ["IsActive"],
-  Metric: [{ Field: "_id", Type: "Count" }],
-});
-// result.Data = { RowHeader: [...], ColumnHeader: [...], Value: [[...]] }
-```
-
-## Further Reading
-
-- [API Reference](./api_reference.md) — full method signatures, parameter types, and return types