@ram_28/kf-ai-sdk 2.0.6 → 2.0.9

package/docs/useForm.md

@@ -174,6 +174,63 @@ interface ReadonlyFormFieldAccessorType<T> {
 }
 ```
 
+### File & Image Value Types
+
+```typescript
+// Metadata for an uploaded file or image
+interface FileType {
+  _id: string;
+  _name: string;
+  FileName: string;
+  FileExtension: string;
+  Size: number;
+  ContentType: string;
+}
+
+type ImageFieldType = FileType | null;  // Single image, nullable
+type FileFieldType = FileType[];        // Array of files
+
+// Request a thumbnail or preview variant from the backend
+type AttachmentViewType = "thumbnail" | "preview";
+```
+
+### File & Image Accessor Types
+
+Image and File fields extend the base accessor with attachment operations.
+Editable accessors get `upload` and `deleteAttachment`; readonly accessors only get download.
+
+```typescript
+// Editable Image — single file
+interface EditableImageFieldAccessorType
+  extends EditableFormFieldAccessorType<ImageFieldType> {
+  upload(file: File): Promise<FileType>;
+  getDownloadUrl(viewType?: AttachmentViewType): Promise<FileDownloadResponseType>;
+  deleteAttachment(): Promise<void>;
+}
+
+// Readonly Image — download only
+interface ReadonlyImageFieldAccessorType
+  extends ReadonlyFormFieldAccessorType<ImageFieldType> {
+  getDownloadUrl(viewType?: AttachmentViewType): Promise<FileDownloadResponseType>;
+}
+
+// Editable File — multi-file
+interface EditableFileFieldAccessorType
+  extends EditableFormFieldAccessorType<FileFieldType> {
+  upload(files: File[]): Promise<FileType[]>;
+  getDownloadUrl(attachmentId: string, viewType?: AttachmentViewType): Promise<FileDownloadResponseType>;
+  getDownloadUrls(viewType?: AttachmentViewType): Promise<FileDownloadResponseType[]>;
+  deleteAttachment(attachmentId: string): Promise<void>;
+}
+
+// Readonly File — download only
+interface ReadonlyFileFieldAccessorType
+  extends ReadonlyFormFieldAccessorType<FileFieldType> {
+  getDownloadUrl(attachmentId: string, viewType?: AttachmentViewType): Promise<FileDownloadResponseType>;
+  getDownloadUrls(viewType?: AttachmentViewType): Promise<FileDownloadResponseType[]>;
+}
+```
+
 ---
 
 ## Basic Example
@@ -720,6 +777,123 @@ function ProductForm({ productId, onSuccess }: ProductFormProps) {
 
 ---
 
+## File & Image Attachments in Forms
+
+Image and File fields get attachment methods on the `item` accessor automatically.
+`upload()` updates local field state only — the form's `handleSubmit` persists everything to the backend.
+`deleteAttachment()` is atomic — it removes the file from storage and the backend record immediately.
+
+```tsx
+// Assuming SellerProduct BDO has:
+//   readonly ProductImage = new ImageField({ _id: "ProductImage", Name: "Product Image", Type: "Image" });
+//   readonly Attachments = new FileField({ _id: "Attachments", Name: "Attachments", Type: "File" });
+
+function ProductFormWithAttachments({ productId }: { productId?: string }) {
+  const product = useMemo(() => new SellerProduct(), []);
+
+  const { register, handleSubmit, item, errors, isSubmitting, watch } = useForm({
+    bdo: product,
+    recordId: productId,
+    mode: ValidationMode.OnBlur,
+  });
+
+  // --- Image field (single file) ---
+
+  const handleImageUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    // Uploads to storage, sets local value (FileType)
+    // Validates extension client-side before uploading
+    const metadata = await item.ProductImage.upload(file);
+    console.log("Uploaded image:", metadata.FileName);
+  };
+
+  const handleImageDelete = async () => {
+    // Atomic — deletes from storage + backend immediately
+    await item.ProductImage.deleteAttachment();
+  };
+
+  const handleImagePreview = async () => {
+    // Get a thumbnail URL (backend-generated variant)
+    const { DownloadUrl } = await item.ProductImage.getDownloadUrl("thumbnail");
+    window.open(DownloadUrl);
+  };
+
+  // --- File field (multi-file) ---
+
+  const handleFilesUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(e.target.files ?? []);
+    if (!files.length) return;
+
+    // Uploads all files in parallel, appends to existing array
+    const uploaded = await item.Attachments.upload(files);
+    console.log(`Uploaded ${uploaded.length} files`);
+  };
+
+  const handleFileDelete = async (attachmentId: string) => {
+    // Removes single file from storage + backend + local array
+    await item.Attachments.deleteAttachment(attachmentId);
+  };
+
+  const handleFileDownload = async (attachmentId: string) => {
+    const { DownloadUrl } = await item.Attachments.getDownloadUrl(attachmentId);
+    window.open(DownloadUrl);
+  };
+
+  // Current field values
+  const currentImage = item.ProductImage.get();         // FileType | null
+  const currentFiles = item.Attachments.get() ?? [];    // FileType[]
+
+  return (
+    <form onSubmit={handleSubmit((data) => console.log("Saved:", data._id))}>
+      {/* ... other fields with register() ... */}
+
+      {/* Image field */}
+      <div className="field">
+        <label>{product.ProductImage.label}</label>
+        {currentImage ? (
+          <div>
+            <span>{currentImage.FileName}</span>
+            <button type="button" onClick={handleImagePreview}>Preview</button>
+            <button type="button" onClick={handleImageDelete}>Remove</button>
+          </div>
+        ) : (
+          <input type="file" accept="image/*" onChange={handleImageUpload} />
+        )}
+      </div>
+
+      {/* File field */}
+      <div className="field">
+        <label>{product.Attachments.label}</label>
+        <input type="file" multiple onChange={handleFilesUpload} />
+        <ul>
+          {currentFiles.map((file) => (
+            <li key={file._id}>
+              {file.FileName} ({file.Size} bytes)
+              <button type="button" onClick={() => handleFileDownload(file._id)}>Download</button>
+              <button type="button" onClick={() => handleFileDelete(file._id)}>Delete</button>
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+**Key points:**
+- `upload()` validates file extensions client-side (throws on unsupported types)
+- Image upload replaces the current value; File upload appends to the array
+- `getDownloadUrl("thumbnail")` / `getDownloadUrl("preview")` request backend-generated variants
+- Readonly Image/File fields only have `getDownloadUrl` — no `upload` or `deleteAttachment`
+
+---
+
 ## Constants Reference
 
 ```typescript

package/docs/workflow.md

@@ -27,6 +27,7 @@ import {
   StringField,
   NumberField,
   BooleanField,
+  DateField,
   DateTimeField,
   SelectField,
   ReferenceField,
@@ -52,8 +53,9 @@ import type {
 
 ```typescript
 interface WorkflowStartResponseType {
-  activityId: string;          // First activity ID in the workflow
-  activityInstanceId: string;  // Instance ID for the started activity
+  BPInstanceId: string;  // Business process instance ID
+  ActivityId: string;    // First activity ID in the workflow
+  _id: string;           // Activity instance ID
 }
 ```
 
@@ -170,17 +172,13 @@ export class EmployeeInputActivity extends Activity<
     activityId: "EMPLOYEE_INPUT",
   };
 
-  readonly StartDate = new DateTimeField({ id: "StartDate", label: "Start Date" });
-  readonly EndDate = new DateTimeField({ id: "EndDate", label: "End Date" });
+  readonly StartDate = new DateField({ "_id": "StartDate", "Name": "Start Date", "Type": "Date" });
+  readonly EndDate = new DateField({ "_id": "EndDate", "Name": "End Date", "Type": "Date" });
   readonly LeaveType = new SelectField<"PTO" | "Sick" | "Parental">({
-    id: "LeaveType", label: "Leave Type",
-    options: [
-      { value: "PTO", label: "PTO" },
-      { value: "Sick", label: "Sick" },
-      { value: "Parental", label: "Parental" },
-    ],
+    "_id": "LeaveType", "Name": "Leave Type", "Type": "String",
+    "Constraint": { "Enum": ["PTO", "Sick", "Parental"] },
   });
-  readonly LeaveDays = new NumberField({ id: "LeaveDays", label: "Leave Days", editable: false });
+  readonly LeaveDays = new NumberField({ "_id": "LeaveDays", "Name": "Leave Days", "Type": "Number", "ReadOnly": true });
 }
 
 export type ManagerApprovalEntityType = {
@@ -198,14 +196,15 @@ export class ManagerApprovalActivity extends Activity<
     activityId: "MANAGER_APPROVAL",
   };
 
-  readonly ManagerApproved = new BooleanField({ id: "ManagerApproved", label: "Manager Approved" });
-  readonly ManagerReason = new StringField({ id: "ManagerReason", label: "Manager's Reason" });
+  readonly ManagerApproved = new BooleanField({ "_id": "ManagerApproved", "Name": "Manager Approved", "Type": "Boolean" });
+  readonly ManagerReason = new StringField({ "_id": "ManagerReason", "Name": "Manager's Reason", "Type": "String" });
 }
 
 // --- Workflow class ---
 
 export class SimpleLeaveProcess {
   async start(): Promise<WorkflowStartResponseType>;
+  async progress(instance_id: string): Promise<ActivityProgressType[]>;
 
   employeeInputActivity(): EmployeeInputActivity;
   managerApprovalActivity(): ManagerApprovalActivity;
@@ -222,23 +221,24 @@ Start a new workflow instance.
 
 ```typescript
 const wf = new SimpleLeaveProcess();
-const { activityId, activityInstanceId } = await wf.start();
+const { BPInstanceId, ActivityId, _id } = await wf.start();
 ```
 
-### progress()
+### progress(instance_id)
 
-Get global progress across the entire business process. Returns a list of progress entries for each stage/activity.
+Get progress for a specific process instance. Returns a list of progress entries for each stage/activity.
 
 ```typescript
 const wf = new SimpleLeaveProcess();
-const progressList = await wf.progress();
+const { BPInstanceId } = await wf.start();
+const progressList = await wf.progress(BPInstanceId);
 // progressList: ActivityProgressType[]
 for (const entry of progressList) {
   console.log(entry._name, entry.Status, entry.CompletedAt);
 }
 ```
 
-**Endpoint:** `GET /api/app/process/{bp_id}/progress`
+**Endpoint:** `GET /api/app/process/{bp_id}/{instance_id}/progress`
 
 ---
 
@@ -250,54 +250,44 @@ Each Activity class provides methods to query and access activity instances. Lis
 const activity = wf.employeeInputActivity();
 ```
 
-### getInProgressList(options?)
+### getInProgressList()
 
-List in-progress activity instances with optional filtering and pagination.
+List in-progress activity instances. Filtering and pagination are handled server-side automatically.
 
 ```typescript
-const result = await activity.getInProgressList({
-  Page: 1,
-  PageSize: 20,
-});
+const result = await activity.getInProgressList();
 
 for (const item of result.Data) {
   console.log(item._id, item.Status, item.StartDate);
 }
 ```
 
-### getCompletedList(options?)
+### getCompletedList()
 
-List completed activity instances with optional filtering and pagination.
+List completed activity instances. Filtering and pagination are handled server-side automatically.
 
 ```typescript
-const result = await activity.getCompletedList({
-  Page: 1,
-  PageSize: 20,
-});
+const result = await activity.getCompletedList();
 
 for (const item of result.Data) {
   console.log(item._id, item.CompletedAt, item.StartDate);
 }
 ```
 
-### inProgressMetrics(options)
+### inProgressMetrics()
 
 Get aggregated metrics for in-progress activity instances.
 
 ```typescript
-const metrics = await activity.inProgressMetrics({
-  Metric: [{ Field: "Status", Function: "Count" }],
-});
+const metrics = await activity.inProgressMetrics();
 ```
 
-### completedMetrics(options)
+### completedMetrics()
 
 Get aggregated metrics for completed activity instances.
 
 ```typescript
-const metrics = await activity.completedMetrics({
-  Metric: [{ Field: "Status", Function: "Count" }],
-});
+const metrics = await activity.completedMetrics();
 ```
 
 ### getInstance(instanceId)
@@ -311,7 +301,7 @@ const instance = await activity.getInstance("inst_abc123");
 instance._id;                          // "inst_abc123"
 instance.StartDate.get();              // read value (typed)
 instance.StartDate.set("2026-03-01");  // set value (editable fields only)
-instance.StartDate.meta;               // { id: "StartDate", label: "Start Date", ... }
+instance.StartDate.meta;               // { _id: "StartDate", Name: "Start Date", Type: "Date" }
 instance.LeaveDays.get();              // read computed/readonly field
 // instance.LeaveDays.set(...)         // NOT available — readonly, no set()
 
@@ -401,10 +391,10 @@ import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
 import type { WorkflowStartResponseType } from "@ram_28/kf-ai-sdk/workflow";
 
 const wf = new SimpleLeaveProcess();
-const { activityId, activityInstanceId }: WorkflowStartResponseType = await wf.start();
+const { BPInstanceId, ActivityId, _id }: WorkflowStartResponseType = await wf.start();
 
-// Check global progress at any time
-const progress = await wf.progress();
+// Check progress at any time
+const progress = await wf.progress(BPInstanceId);
 ```
 
 ### Step 2 — React component with useActivityForm
@@ -532,7 +522,7 @@ function LeaveRequestPage() {
   const startLeaveRequest = async () => {
     const wf = new SimpleLeaveProcess();
     const result: WorkflowStartResponseType = await wf.start();
-    setInstanceId(result.activityInstanceId);
+    setInstanceId(result._id);
   };
 
   if (!instanceId) {
@@ -560,10 +550,7 @@ import { SimpleLeaveProcess } from "@/bdo/workflows/SimpleLeaveProcess";
 const wf = new SimpleLeaveProcess();
 const activity = wf.managerApprovalActivity();
 
-const result = await activity.getInProgressList({
-  Page: 1,
-  PageSize: 20,
-});
+const result = await activity.getInProgressList();
 
 for (const item of result.Data) {
   console.log(item._id, item.Status, item.AssignedTo.username);
@@ -685,7 +672,7 @@ const progress = await instance.progress();
 
 ## Filtering Reference
 
-Status filtering is built into the method names (`getInProgressList` / `getCompletedList`), so you no longer need a Status filter condition.
+Status filtering is built into the method names (`getInProgressList` / `getCompletedList`). All filtering (by current user, activity status, and activity ID) and pagination are handled server-side automatically — no client-side options are needed.
 
 ### In-progress items
 
@@ -699,37 +686,12 @@ const result = await activity.getInProgressList();
 const result = await activity.getCompletedList();
 ```
 
-### Assigned to a specific user (in-progress)
-
-```typescript
-const result = await activity.getInProgressList({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "AssignedTo._id", Operator: "EQ", RHSValue: userId, RHSType: "Constant" },
-    ],
-  },
-});
-```
-
-### Assigned to a specific user (completed)
-
-```typescript
-const result = await activity.getCompletedList({
-  Filter: {
-    Operator: "And",
-    Condition: [
-      { LHSField: "AssignedTo._id", Operator: "EQ", RHSValue: userId, RHSType: "Constant" },
-    ],
-  },
-});
-```
-
-### Global process progress
+### Process progress
 
 ```typescript
 const wf = new SimpleLeaveProcess();
-const progressList = await wf.progress();
+const { BPInstanceId } = await wf.start();
+const progressList = await wf.progress(BPInstanceId);
 // Returns ActivityProgressType[] — one entry per activity in the process
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "2.0.6",
+  "version": "2.0.9",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",

package/sdk/api/client.ts

@@ -16,6 +16,10 @@ import type {
   DraftResponseType,
   FieldsResponseType,
   FetchFieldOptionType,
+  FileUploadRequestType,
+  FileUploadResponseType,
+  FileDownloadResponseType,
+  AttachmentViewType,
 } from "../types/common";
 
 /**
@@ -115,6 +119,51 @@ export interface ResourceClientType<T = any> {
     instanceId: string,
     fieldId: string,
   ): Promise<TResult[]>;
+
+  // ============================================================
+  // ATTACHMENT OPERATIONS
+  // ============================================================
+
+  /**
+   * Get signed upload URLs for file attachments
+   * POST /{bo_id}/{instance_id}/field/{field_id}/attachment/upload
+   */
+  getUploadUrl(
+    instanceId: string,
+    fieldId: string,
+    files: FileUploadRequestType[],
+  ): Promise<FileUploadResponseType[]>;
+
+  /**
+   * Get signed download URL for a single attachment
+   * GET /{bo_id}/{instance_id}/field/{field_id}/attachment/{attachment_id}/read
+   */
+  getDownloadUrl(
+    instanceId: string,
+    fieldId: string,
+    attachmentId: string,
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType>;
+
+  /**
+   * Get signed download URLs for all attachments on a field
+   * GET /{bo_id}/{instance_id}/field/{field_id}/attachment/read
+   */
+  getDownloadUrls(
+    instanceId: string,
+    fieldId: string,
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType[]>;
+
+  /**
+   * Delete an attachment
+   * DELETE /{bo_id}/{instance_id}/field/{field_id}/attachment/{attachment_id}/delete
+   */
+  deleteAttachment(
+    instanceId: string,
+    fieldId: string,
+    attachmentId: string,
+  ): Promise<void>;
 }
 
 /**
@@ -455,6 +504,102 @@ export function createResourceClient<T = any>(
       const responseData: { Data: TResult[] } = await response.json();
       return responseData.Data;
     },
+
+    // ============================================================
+    // ATTACHMENT OPERATIONS
+    // ============================================================
+
+    async getUploadUrl(
+      instanceId: string,
+      fieldId: string,
+      files: FileUploadRequestType[],
+    ): Promise<FileUploadResponseType[]> {
+      const response = await fetch(
+        `${baseUrl}${basePath}/${instanceId}/field/${fieldId}/attachment/upload`,
+        {
+          method: "POST",
+          headers: getDefaultHeaders(),
+          body: JSON.stringify(files),
+        },
+      );
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get upload URL for ${basePath}/${fieldId}: ${response.statusText}`,
+        );
+      }
+
+      const responseData: { Data: FileUploadResponseType[] } =
+        await response.json();
+      return responseData.Data;
+    },
+
+    async getDownloadUrl(
+      instanceId: string,
+      fieldId: string,
+      attachmentId: string,
+      viewType?: AttachmentViewType,
+    ): Promise<FileDownloadResponseType> {
+      let url = `${baseUrl}${basePath}/${instanceId}/field/${fieldId}/attachment/${attachmentId}/read`;
+      if (viewType) url += `?view_type=${viewType}`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: getDefaultHeaders(),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get download URL for ${basePath}/${fieldId}/${attachmentId}: ${response.statusText}`,
+        );
+      }
+
+      const responseData: { Data: FileDownloadResponseType } =
+        await response.json();
+      return responseData.Data;
+    },
+
+    async getDownloadUrls(
+      instanceId: string,
+      fieldId: string,
+      viewType?: AttachmentViewType,
+    ): Promise<FileDownloadResponseType[]> {
+      let url = `${baseUrl}${basePath}/${instanceId}/field/${fieldId}/attachment/read`;
+      if (viewType) url += `?view_type=${viewType}`;
+      const response = await fetch(url, {
+        method: "GET",
+        headers: getDefaultHeaders(),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get download URLs for ${basePath}/${fieldId}: ${response.statusText}`,
+        );
+      }
+
+      const responseData: { Data: FileDownloadResponseType[] } =
+        await response.json();
+      return responseData.Data;
+    },
+
+    async deleteAttachment(
+      instanceId: string,
+      fieldId: string,
+      attachmentId: string,
+    ): Promise<void> {
+      const response = await fetch(
+        `${baseUrl}${basePath}/${instanceId}/field/${fieldId}/attachment/${attachmentId}/delete`,
+        {
+          method: "DELETE",
+          headers: getDefaultHeaders(),
+        },
+      );
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to delete attachment ${attachmentId} for ${basePath}/${fieldId}: ${response.statusText}`,
+        );
+      }
+    },
   };
 }
 

package/sdk/api/index.ts

@@ -58,6 +58,10 @@ export type {
   DraftResponseType,
   // Fields types
   FieldsResponseType,
+  // Attachment types
+  FileUploadRequestType,
+  FileUploadResponseType,
+  FileDownloadResponseType,
 } from "../types/common";
 
 // Re-export date types from base-fields

package/sdk/api.types.ts

@@ -54,4 +54,9 @@ export type {
   FieldsResponseType,
   FetchFieldOptionType,
   FetchFieldResponseType,
+
+  // Attachment types
+  FileUploadRequestType,
+  FileUploadResponseType,
+  FileDownloadResponseType,
 } from './types/common';