@ram_28/kf-ai-sdk 2.0.15 → 2.0.17

package/docs/README.md

@@ -0,0 +1,51 @@
+# @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 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

@@ -0,0 +1,161 @@
+# 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

package/docs/bdo/api_reference.md

@@ -0,0 +1,281 @@
+```typescript
+import { BaseBdo, StringField, NumberField, BooleanField, DateField, SelectField, ReferenceField } from "@ram_28/kf-ai-sdk/bdo";
+import type {
+  ItemType,
+  EditableFieldAccessorType,
+  ReadonlyFieldAccessorType,
+  ValidationResultType,
+  BdoMetaType,
+} from "@ram_28/kf-ai-sdk/bdo/types";
+import type {
+  ListOptionsType,
+  FilterType,
+  ConditionGroupType,
+  ConditionType,
+  SortType,
+  CreateUpdateResponseType,
+  DeleteResponseType,
+  MetricOptionsType,
+  MetricResponseType,
+  PivotOptionsType,
+  PivotResponseType,
+} from "@ram_28/kf-ai-sdk/api/types";
+import type {
+  StringFieldType,
+  NumberFieldType,
+  BooleanFieldType,
+  DateFieldType,
+  DateTimeFieldType,
+  TextFieldType,
+  SelectFieldType,
+  ReferenceFieldType,
+  UserFieldType,
+  FileFieldType,
+  ImageFieldType,
+  ArrayFieldType,
+  ObjectFieldType,
+  SystemFieldsType,
+} from "@ram_28/kf-ai-sdk/types";
+```
+
+## Methods
+
+All methods are `protected` on `BaseBdo`. Subclasses expose them as `public` per role.
+
+| Method | Params | Returns |
+|--------|--------|---------|
+| `get(id)` | `id: string` | `Promise<ItemType<TEditable, TReadonly>>` |
+| `list(options?)` | `options?: ListOptionsType` | `Promise<ItemType<TEditable, TReadonly>[]>` |
+| `count(options?)` | `options?: ListOptionsType` | `Promise<number>` |
+| `create(data)` | `data: Partial<TEditable>` | `Promise<ItemType<TEditable, TReadonly>>` |
+| `update(id, data)` | `id: string, data: Partial<TEditable>` | `Promise<CreateUpdateResponseType>` |
+| `delete(id)` | `id: string` | `Promise<DeleteResponseType>` |
+| `metric(options)` | `options: Omit<MetricOptionsType, "Type">` | `Promise<MetricResponseType>` |
+| `pivot(options)` | `options: Omit<PivotOptionsType, "Type">` | `Promise<PivotResponseType>` |
+
+## Types
+
+### ItemType\<TEditable, TReadonly\>
+
+Proxy-wrapped record returned by `get()`, `list()`, and `create()`. Provides typed field accessors for each field.
+
+```typescript
+type ItemType<TEditable, TReadonly> = {
+  readonly _id: string;               // direct string access
+
+  // Editable fields → EditableFieldAccessorType<T>
+  // Readonly fields → ReadonlyFieldAccessorType<T>
+
+  validate(): ValidationResultType;   // validates all fields
+  toJSON(): Partial<TEditable & TReadonly>;
+};
+```
+
+### EditableFieldAccessorType\<T\>
+
+Accessor for fields the current role can write.
+
+```typescript
+interface EditableFieldAccessorType<T> {
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  set(value: T): void;
+  validate(): ValidationResultType;
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: false;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+}
+```
+
+### ReadonlyFieldAccessorType\<T\>
+
+Accessor for fields the current role can only read. Same as editable but no `set()`.
+
+```typescript
+interface ReadonlyFieldAccessorType<T> {
+  get(): T | undefined;
+  getOrDefault(fallback: T): T;
+  validate(): ValidationResultType;
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: true;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+}
+```
+
+### ValidationResultType
+
+```typescript
+interface ValidationResultType {
+  valid: boolean;
+  errors: string[];
+}
+```
+
+### ListOptionsType
+
+```typescript
+interface ListOptionsType {
+  Filter?: FilterType;
+  Sort?: SortType;
+  Page?: number;       // 1-indexed
+  PageSize?: number;
+  Search?: string;
+  Field?: string[];    // specific fields to return
+}
+```
+
+### FilterType / ConditionGroupType / ConditionType
+
+```typescript
+// Root filter — alias for ConditionGroupType
+type FilterType = ConditionGroupType;
+
+interface ConditionGroupType {
+  Operator: "And" | "Or" | "Not";
+  Condition: Array<ConditionType | ConditionGroupType>;
+}
+
+interface ConditionType {
+  Operator: string;        // "eq", "neq", "gt", "gte", "lt", "lte", "contains", "startswith", etc.
+  LHSField: string;        // field name
+  RHSValue: any;            // comparison value
+  RHSType?: string;         // defaults to "Constant"
+}
+```
+
+### SortType
+
+```typescript
+type SortType = Record<string, "ASC" | "DESC">[];
+// Example: [{ "Price": "DESC" }, { "Title": "ASC" }]
+```
+
+### CreateUpdateResponseType
+
+```typescript
+interface CreateUpdateResponseType {
+  _id: string;
+}
+```
+
+### DeleteResponseType
+
+```typescript
+interface DeleteResponseType {
+  status: string;
+}
+```
+
+### MetricOptionsType
+
+Omit `Type` when calling `bdo.metric()` — it is added automatically.
+
+```typescript
+interface MetricOptionsType {
+  Type: "Metric";                  // omit when calling bdo.metric()
+  GroupBy: string[];
+  Metric: MetricFieldType[];
+  Filter?: FilterType;
+}
+
+interface MetricFieldType {
+  Field: string;
+  Type: string;   // "Count" | "Sum" | "Avg" | "Max" | "Min"
+}
+```
+
+### MetricResponseType
+
+```typescript
+interface MetricResponseType {
+  Data: Record<string, any>[];
+}
+```
+
+### PivotOptionsType
+
+Omit `Type` when calling `bdo.pivot()` — it is added automatically.
+
+```typescript
+interface PivotOptionsType {
+  Type: "Pivot";                   // omit when calling bdo.pivot()
+  Row: string[];
+  Column: string[];
+  Metric: MetricFieldType[];
+  Filter?: FilterType;
+}
+```
+
+### PivotResponseType
+
+```typescript
+interface PivotResponseType {
+  Data: {
+    RowHeader: PivotHeaderItemType[];
+    ColumnHeader: PivotHeaderItemType[];
+    Value: (number | string | null)[][];
+  };
+}
+
+interface PivotHeaderItemType {
+  Key: string;
+  Children?: PivotHeaderItemType[] | null;
+}
+```
+
+### SystemFieldsType
+
+Seven system-managed fields inherited from `BaseBdo`. Never redeclare in subclasses.
+
+```typescript
+type SystemFieldsType = {
+  _id: StringFieldType;
+  _created_at: DateTimeFieldType;
+  _modified_at: DateTimeFieldType;
+  _created_by: UserFieldType;
+  _modified_by: UserFieldType;
+  _version: StringFieldType;
+  _m_version: StringFieldType;
+};
+```
+
+### Field Value Types
+
+| Type | Resolves To |
+|------|-------------|
+| `StringFieldType` | `string` |
+| `TextFieldType` | `string` |
+| `NumberFieldType` | `number` |
+| `BooleanFieldType` | `boolean` |
+| `DateFieldType` | `"YYYY-MM-DD"` |
+| `DateTimeFieldType` | `"YYYY-MM-DDThh:mm:ssZ"` |
+| `SelectFieldType<T>` | `T` |
+| `ReferenceFieldType<T>` | `T` |
+| `UserFieldType` | `{ _id: string; _name: string }` |
+| `ImageFieldType` | `FileType \| null` |
+| `FileFieldType` | `FileType[]` |
+| `ArrayFieldType<T>` | `T[]` |
+| `ObjectFieldType<T>` | `T` |
+
+### Generated Type Patterns
+
+The js_sdk generator creates these types per entity:
+
+```typescript
+// entities/Product.ts
+export type ProductType = {
+  ProductId: StringFieldType;
+  Title: StringFieldType;
+  Price: NumberFieldType;
+  // ... business fields
+} & SystemFieldsType;
+
+// admin/Product.ts
+type AdminProductEditableFieldType = Omit<ProductType, keyof SystemFieldsType>;
+type AdminProductReadonlyFieldType = Record<string, never>;
+// or Pick<ProductType, "Field1" | "Field2"> for limited access
+```

package/docs/examples/bdo/create-product.md

@@ -0,0 +1,69 @@
+# Create Product
+
+> Create a new product using `useBDOForm` with validation, select fields, and submit handling.
+
+```tsx
+import { useMemo } from "react";
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
+import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+import type { BuyerProductEntityType } from "@/bdo/buyer/Product";
+import type { FieldErrors } from "react-hook-form";
+
+export default function CreateProductForm() {
+  const product = useMemo(() => new BuyerProduct(), []);
+
+  const { register, handleSubmit, errors, isLoading, isSubmitting, watch, setValue }: UseBDOFormReturnType<BuyerProduct> =
+    useBDOForm({ bdo: product, defaultValues: { Title: "", Price: 0 } });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  const onSuccess = (data: { _id: string }) => console.log("Created:", data._id);
+  const onError = (err: FieldErrors<BuyerProductEntityType> | Error) => {
+    if (err instanceof Error) console.error(err.message);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSuccess, onError)}>
+      {/* Text input with register() */}
+      <label>{product.Title.label} {product.Title.required && <span>*</span>}</label>
+      <input {...register(product.Title.id)} />
+      {errors.Title && <p>{errors.Title.message}</p>}
+
+      <label>{product.Description.label}</label>
+      <textarea {...register(product.Description.id)} rows={3} />
+      {errors.Description && <p>{errors.Description.message}</p>}
+
+      {/* Number input with register() */}
+      <label>{product.Price.label} {product.Price.required && <span>*</span>}</label>
+      <input type="number" step="0.01" {...register(product.Price.id)} />
+      {errors.Price && <p>{errors.Price.message}</p>}
+
+      {/* Select field — watch/setValue, not register */}
+      <label>{product.Category.label} {product.Category.required && <span>*</span>}</label>
+      <select
+        value={watch(product.Category.id) ?? ""}
+        onChange={(e) => setValue(product.Category.id, e.target.value)}
+      >
+        <option value="">Select category</option>
+        {product.Category.options.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+      {errors.Category && <p>{errors.Category.message}</p>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Saving..." : "Add Product"}
+      </button>
+    </form>
+  );
+}
+```
+
+## Key Patterns
+
+- **Create mode** -- no `recordId` passed to `useBDOForm`; a draft is allocated on mount
+- **`register()`** -- for text and number inputs that fire native change events
+- **`watch()` + `setValue()`** -- for select fields and other custom components
+- **`handleSubmit(onSuccess, onError)`** -- validates, filters to editable fields, calls the API; never call `bdo.create()` manually
+- **Validation errors** -- `errors.FieldName.message` shows constraint violations automatically

package/docs/examples/bdo/edit-product-dialog.md

@@ -0,0 +1,95 @@
+# Edit Product Dialog
+
+> Click a table row to open an edit form in a dialog, save, and refetch the table.
+
+```tsx
+import { useState, useMemo } from "react";
+import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
+import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
+import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
+import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
+import { BuyerProduct } from "@/bdo/buyer/Product";
+import type { BuyerProductEntityType } from "@/bdo/buyer/Product";
+import type { FieldErrors } from "react-hook-form";
+
+export default function ProductPage() {
+  const [showForm, setShowForm] = useState(false);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const product = useMemo(() => new BuyerProduct(), []);
+
+  // ── Table ────────────────────────────────────────────────────
+  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({
+    bdo: product,
+    initialState: { sort: [{ Title: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
+  });
+
+  // ── Form (create when selectedId is null, edit when string) ──
+  const { register, handleSubmit, errors, isLoading: formLoading, isSubmitting, watch, setValue, isDirty }: UseBDOFormReturnType<BuyerProduct> =
+    useBDOForm({ bdo: product, recordId: selectedId ?? undefined });
+
+  const handleCreate = () => { setSelectedId(null); setShowForm(true); };
+  const handleEdit = (id: string) => { setSelectedId(id); setShowForm(true); };
+  const onSuccess = () => { setShowForm(false); setSelectedId(null); table.refetch(); };
+  const onError = (err: FieldErrors<BuyerProductEntityType> | Error) => {
+    if (err instanceof Error) console.error(err.message);
+  };
+
+  if (table.isLoading) return <p>Loading...</p>;
+
+  return (
+    <div>
+      <button onClick={handleCreate}>Add Product</button>
+
+      <table>
+        <thead>
+          <tr>
+            <th>{product.Title.label}</th>
+            <th>{product.Price.label}</th>
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row) => (
+            <tr key={row._id} onClick={() => handleEdit(row._id)} style={{ cursor: "pointer" }}>
+              <td>{row.Title.get()}</td>
+              <td>${row.Price.get()?.toFixed(2)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Dialog form */}
+      {showForm && (
+        <dialog open>
+          <h2>{selectedId ? "Edit Product" : "Add Product"}</h2>
+          {formLoading ? (
+            <p>Loading form...</p>
+          ) : (
+            <form onSubmit={handleSubmit(onSuccess, onError)}>
+              <label>{product.Title.label}</label>
+              <input {...register(product.Title.id)} />
+              {errors.Title && <p>{errors.Title.message}</p>}
+
+              <label>{product.Price.label}</label>
+              <input type="number" step="0.01" {...register(product.Price.id)} />
+              {errors.Price && <p>{errors.Price.message}</p>}
+
+              <button type="button" onClick={() => setShowForm(false)}>Cancel</button>
+              <button type="submit" disabled={isSubmitting || (!!selectedId && !isDirty)}>
+                {isSubmitting ? "Saving..." : selectedId ? "Save Changes" : "Add Product"}
+              </button>
+            </form>
+          )}
+        </dialog>
+      )}
+    </div>
+  );
+}
+```
+
+## Key Patterns
+
+- **Shared BDO instance** -- `useMemo(() => new BuyerProduct(), [])` is passed to both `useBDOTable` and `useBDOForm`
+- **Create vs edit mode** -- `selectedId` is `null` for create (no `recordId`), or a string for edit
+- **`table.refetch()` after save** -- called in `onSuccess` to refresh the table data
+- **`isDirty` guard** -- disables the submit button in edit mode when no changes have been made