@ram_28/kf-ai-sdk 2.0.6 → 2.0.9

package/sdk/bdo/core/BaseBdo.ts

@@ -12,6 +12,10 @@ import type {
   PivotOptionsType,
   PivotResponseType,
   DraftResponseType,
+  FileUploadRequestType,
+  FileUploadResponseType,
+  FileDownloadResponseType,
+  AttachmentViewType,
 } from "../../types/common";
 import type { SystemFields } from "../../types/base-fields";
 import { api } from "../../api/client";
@@ -62,6 +66,13 @@ export abstract class BaseBdo<
   // FIELD DEFINITIONS (auto-discovered)
   // ============================================================
 
+  /**
+   * Get the Business Object ID for API calls
+   */
+  getBoId(): string {
+    return this.meta._id;
+  }
+
   /**
    * Whether fields have been bound to this BDO
    */
@@ -299,4 +310,53 @@ export abstract class BaseBdo<
   ): Promise<PivotResponseType> {
     return api<TEntity>(this.meta._id).pivot(options);
   }
+
+  // ============================================================
+  // ATTACHMENT OPERATIONS
+  // ============================================================
+
+  /**
+   * Get signed upload URLs for file/image attachments
+   */
+  protected async getUploadUrl(
+    instanceId: string,
+    fieldId: string,
+    files: FileUploadRequestType[],
+  ): Promise<FileUploadResponseType[]> {
+    return api<TEntity>(this.meta._id).getUploadUrl(instanceId, fieldId, files);
+  }
+
+  /**
+   * Get signed download URL for a single attachment
+   */
+  protected async getDownloadUrl(
+    instanceId: string,
+    fieldId: string,
+    attachmentId: string,
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType> {
+    return api<TEntity>(this.meta._id).getDownloadUrl(instanceId, fieldId, attachmentId, viewType);
+  }
+
+  /**
+   * Get signed download URLs for all attachments on a field
+   */
+  protected async getDownloadUrls(
+    instanceId: string,
+    fieldId: string,
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType[]> {
+    return api<TEntity>(this.meta._id).getDownloadUrls(instanceId, fieldId, viewType);
+  }
+
+  /**
+   * Delete an attachment
+   */
+  protected async deleteAttachment(
+    instanceId: string,
+    fieldId: string,
+    attachmentId: string,
+  ): Promise<void> {
+    return api<TEntity>(this.meta._id).deleteAttachment(instanceId, fieldId, attachmentId);
+  }
 }

package/sdk/bdo/core/Item.ts

@@ -9,8 +9,27 @@ import type {
   EditableFieldAccessorType,
   ReadonlyFieldAccessorType,
   FieldAccessorType,
+  EditableImageFieldAccessorType,
+  ReadonlyImageFieldAccessorType,
+  EditableFileFieldAccessorType,
+  ReadonlyFileFieldAccessorType,
 } from "./types";
 import type { BaseField } from "../fields/BaseField";
+import type {
+  FileType,
+  ImageFieldType,
+  FileFieldType,
+} from "../../types/base-fields";
+import type {
+  FileUploadRequestType,
+  FileDownloadResponseType,
+  AttachmentViewType,
+} from "../../types/common";
+import {
+  validateFileExtension,
+  extractFileExtension,
+} from "../fields/attachment-constants";
+import { api } from "../../api/client";
 
 /**
  * Interface for BDO that Item needs
@@ -23,23 +42,44 @@ interface BdoLike {
     value: unknown,
     allValues: Record<string, unknown>
   ): ValidationResultType;
+  getBoId(): string;
 }
 
 // Re-export accessor types for convenience
 export type { EditableFieldAccessorType, ReadonlyFieldAccessorType, FieldAccessorType, BaseFieldMetaType };
 
+/**
+ * Resolve editable accessor type — specialized for File/Image fields
+ */
+type ResolveEditableAccessor<T> =
+  [T] extends [ImageFieldType]
+    ? EditableImageFieldAccessorType
+    : [T] extends [FileFieldType]
+      ? EditableFileFieldAccessorType
+      : EditableFieldAccessorType<T>;
+
+/**
+ * Resolve readonly accessor type — specialized for File/Image fields
+ */
+type ResolveReadonlyAccessor<T> =
+  [T] extends [ImageFieldType]
+    ? ReadonlyImageFieldAccessorType
+    : [T] extends [FileFieldType]
+      ? ReadonlyFileFieldAccessorType
+      : ReadonlyFieldAccessorType<T>;
+
 /**
  * Create editable accessor type for each field in TEditable
  */
 type EditableAccessors<T> = {
-  [K in keyof T as K extends "_id" ? never : K]: EditableFieldAccessorType<T[K]>;
+  [K in keyof T as K extends "_id" ? never : K]: ResolveEditableAccessor<T[K]>;
 };
 
 /**
  * Create readonly accessor type for each field in TReadonly
  */
 type ReadonlyAccessors<T> = {
-  [K in keyof T as K extends "_id" ? never : K]: ReadonlyFieldAccessorType<T[K]>;
+  [K in keyof T as K extends "_id" ? never : K]: ResolveReadonlyAccessor<T[K]>;
 };
 
 /**
@@ -90,7 +130,8 @@ export class Item<T extends Record<string, unknown>> {
           prop === "_bdo" ||
           prop === "_data" ||
           prop === "_accessorCache" ||
-          prop === "_getAccessor"
+          prop === "_getAccessor" ||
+          prop === "_requireInstanceId"
         ) {
           return Reflect.get(target, prop, receiver);
         }
@@ -155,6 +196,20 @@ export class Item<T extends Record<string, unknown>> {
     }) as Item<T>;
   }
 
+  /**
+   * Require instanceId or throw.
+   * TODO: Support create flow via draftInteraction to get temp _id
+   */
+  private _requireInstanceId(): string {
+    const id = this._data._id as string | undefined;
+    if (!id) {
+      throw new Error(
+        "Cannot perform attachment operation: item has no _id. Save the item first.",
+      );
+    }
+    return id;
+  }
+
   /**
    * Get or create a field accessor for the given field.
    * Editable fields get set(), readonly fields do not.
@@ -234,6 +289,179 @@ export class Item<T extends Record<string, unknown>> {
       };
     }
 
+    // Enrich File/Image field accessors with attachment methods
+    if (meta.Type === "Image" || meta.Type === "File") {
+      const boId = this._bdo.getBoId();
+      const acc = accessor as unknown as Record<string, unknown>;
+
+      if (meta.Type === "Image") {
+        // Image field — single file
+
+        // getDownloadUrl — always available (editable + readonly)
+        acc.getDownloadUrl = async (
+          viewType?: AttachmentViewType,
+        ): Promise<FileDownloadResponseType> => {
+          const instanceId = this._requireInstanceId();
+          const value = this._data[fieldId as keyof T] as
+            | FileType
+            | null
+            | undefined;
+          if (!value?._id) {
+            throw new Error(`${fieldId} has no image to download`);
+          }
+          return api(boId).getDownloadUrl(
+            instanceId,
+            fieldId,
+            value._id,
+            viewType,
+          );
+        };
+
+        // upload + deleteAttachment — editable only
+        if (!isReadOnly) {
+          /**
+           * Upload to storage and update local field value.
+           * Does NOT persist to backend — call save()/update() after uploading.
+           */
+          acc.upload = async (file: File): Promise<FileType> => {
+            validateFileExtension(file.name, "Image");
+            const instanceId = this._requireInstanceId();
+            const request: FileUploadRequestType = {
+              FileName: file.name,
+              Size: file.size,
+              FileExtension: extractFileExtension(file.name),
+            };
+            const [uploadInfo] = await api(boId).getUploadUrl(
+              instanceId,
+              fieldId,
+              [request],
+            );
+
+            await fetch(uploadInfo.UploadUrl.URL, {
+              method: "PUT",
+              headers: { "Content-Type": uploadInfo.ContentType },
+              body: file,
+            });
+
+            const metadata: FileType = {
+              _id: uploadInfo._id,
+              _name: uploadInfo._name,
+              FileName: uploadInfo.FileName,
+              FileExtension: uploadInfo.FileExtension,
+              Size: uploadInfo.Size,
+              ContentType: uploadInfo.ContentType,
+            };
+
+            this._data[fieldId as keyof T] = metadata as T[keyof T];
+            return metadata;
+          };
+
+          acc.deleteAttachment = async (): Promise<void> => {
+            const instanceId = this._requireInstanceId();
+            const value = this._data[fieldId as keyof T] as
+              | FileType
+              | null
+              | undefined;
+            if (!value?._id) {
+              throw new Error(`${fieldId} has no image to delete`);
+            }
+            await api(boId).deleteAttachment(instanceId, fieldId, value._id);
+            this._data[fieldId as keyof T] = null as T[keyof T];
+          };
+        }
+      } else {
+        // File field — multi-file
+
+        // getDownloadUrl + getDownloadUrls — always available (editable + readonly)
+        acc.getDownloadUrl = async (
+          attachmentId: string,
+          viewType?: AttachmentViewType,
+        ): Promise<FileDownloadResponseType> => {
+          const instanceId = this._requireInstanceId();
+          return api(boId).getDownloadUrl(
+            instanceId,
+            fieldId,
+            attachmentId,
+            viewType,
+          );
+        };
+
+        acc.getDownloadUrls = async (
+          viewType?: AttachmentViewType,
+        ): Promise<FileDownloadResponseType[]> => {
+          const instanceId = this._requireInstanceId();
+          return api(boId).getDownloadUrls(instanceId, fieldId, viewType);
+        };
+
+        // upload + deleteAttachment — editable only
+        if (!isReadOnly) {
+          /**
+           * Upload to storage and update local field value.
+           * Does NOT persist to backend — call save()/update() after uploading.
+           * (deleteAttachment is atomic — backend handles storage + DB in one call)
+           */
+          acc.upload = async (files: File[]): Promise<FileType[]> => {
+            for (const file of files) {
+              validateFileExtension(file.name, "File");
+            }
+            const instanceId = this._requireInstanceId();
+            const requests: FileUploadRequestType[] = files.map((file) => ({
+              FileName: file.name,
+              Size: file.size,
+              FileExtension: extractFileExtension(file.name),
+            }));
+            const uploadInfos = await api(boId).getUploadUrl(
+              instanceId,
+              fieldId,
+              requests,
+            );
+
+            const uploaded: FileType[] = await Promise.all(
+              files.map(async (file, i) => {
+                await fetch(uploadInfos[i].UploadUrl.URL, {
+                  method: "PUT",
+                  headers: { "Content-Type": uploadInfos[i].ContentType },
+                  body: file,
+                });
+                return {
+                  _id: uploadInfos[i]._id,
+                  _name: uploadInfos[i]._name,
+                  FileName: uploadInfos[i].FileName,
+                  FileExtension: uploadInfos[i].FileExtension,
+                  Size: uploadInfos[i].Size,
+                  ContentType: uploadInfos[i].ContentType,
+                };
+              }),
+            );
+
+            const current =
+              (this._data[fieldId as keyof T] as FileType[] | undefined) ?? [];
+            this._data[fieldId as keyof T] = [
+              ...current,
+              ...uploaded,
+            ] as T[keyof T];
+            return uploaded;
+          };
+
+          acc.deleteAttachment = async (
+            attachmentId: string,
+          ): Promise<void> => {
+            const instanceId = this._requireInstanceId();
+            await api(boId).deleteAttachment(
+              instanceId,
+              fieldId,
+              attachmentId,
+            );
+            const current =
+              (this._data[fieldId as keyof T] as FileType[] | undefined) ?? [];
+            this._data[fieldId as keyof T] = current.filter(
+              (f) => f._id !== attachmentId,
+            ) as T[keyof T];
+          };
+        }
+      }
+    }
+
     // Cache and return
     this._accessorCache.set(fieldId, accessor);
     return accessor;

package/sdk/bdo/core/types.ts

@@ -142,6 +142,11 @@ export interface FileFieldMetaType extends BaseFieldMetaType {
   Constraint?: BaseConstraintType;
 }
 
+export interface ImageFieldMetaType extends BaseFieldMetaType {
+  Type: "Image";
+  Constraint?: BaseConstraintType;
+}
+
 // ============================================================
 // RUNTIME ACCESSOR TYPES
 // These represent what item.Title looks like at runtime
@@ -170,6 +175,64 @@ export type ReadonlyFieldAccessorType<T> = BaseFieldAccessorType<T>;
 /** Union of editable or readonly accessor */
 export type FieldAccessorType<T> = EditableFieldAccessorType<T> | ReadonlyFieldAccessorType<T>;
 
+// ============================================================
+// FILE/IMAGE FIELD ACCESSOR TYPES
+// ============================================================
+
+import type {
+  FileType,
+  ImageFieldType,
+  FileFieldType,
+} from "../../types/base-fields";
+import type {
+  FileDownloadResponseType,
+  AttachmentViewType,
+} from "../../types/common";
+
+/** Editable Image field accessor — adds upload, download, delete */
+export interface EditableImageFieldAccessorType
+  extends EditableFieldAccessorType<ImageFieldType> {
+  upload(file: File): Promise<FileType>;
+  getDownloadUrl(
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType>;
+  deleteAttachment(): Promise<void>;
+}
+
+/** Readonly Image field accessor — download only */
+export interface ReadonlyImageFieldAccessorType
+  extends ReadonlyFieldAccessorType<ImageFieldType> {
+  getDownloadUrl(
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType>;
+}
+
+/** Editable File field accessor — adds upload, download, delete */
+export interface EditableFileFieldAccessorType
+  extends EditableFieldAccessorType<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 field accessor — download only */
+export interface ReadonlyFileFieldAccessorType
+  extends ReadonlyFieldAccessorType<FileFieldType> {
+  getDownloadUrl(
+    attachmentId: string,
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType>;
+  getDownloadUrls(
+    viewType?: AttachmentViewType,
+  ): Promise<FileDownloadResponseType[]>;
+}
+
 // ============================================================
 // SELECT FIELD OPTIONS
 // ============================================================

package/sdk/bdo/fields/FileField.ts

@@ -1,6 +1,6 @@
 // ============================================================
 // FILE FIELD
-// Field for file attachments
+// Field for file attachments (array of files)
 // ============================================================
 
 import type { FileFieldType } from "../../types/base-fields";
@@ -12,8 +12,8 @@ import { BaseField } from "./BaseField";
  *
  * @example
  * ```typescript
- * readonly Attachment = new FileField({
- *   _id: "Attachment", Name: "Attachment", Type: "File",
+ * readonly Attachments = new FileField({
+ *   _id: "Attachments", Name: "Attachments", Type: "File",
  * });
  * ```
  */
@@ -27,13 +27,22 @@ export class FileField extends BaseField<FileFieldType> {
       return { valid: true, errors: [] };
     }
 
-    if (typeof value !== "object" || Array.isArray(value)) {
+    if (!Array.isArray(value)) {
       return {
         valid: false,
-        errors: [`${this.label} must be a valid file object`],
+        errors: [`${this.label} must be an array of file objects`],
       };
     }
 
+    for (const item of value) {
+      if (!item || typeof item !== "object" || !item._id) {
+        return {
+          valid: false,
+          errors: [`Each file in ${this.label} must have an _id`],
+        };
+      }
+    }
+
     return { valid: true, errors: [] };
   }
 }

package/sdk/bdo/fields/ImageField.ts

@@ -0,0 +1,46 @@
+// ============================================================
+// IMAGE FIELD
+// Field for single image attachments (nullable)
+// ============================================================
+
+import type { ImageFieldType } from "../../types/base-fields";
+import type { ImageFieldMetaType, ValidationResultType } from "../core/types";
+import { BaseField } from "./BaseField";
+
+/**
+ * Field definition for single image attachment fields
+ *
+ * @example
+ * ```typescript
+ * readonly Avatar = new ImageField({
+ *   _id: "Avatar", Name: "Avatar", Type: "Image",
+ * });
+ * ```
+ */
+export class ImageField extends BaseField<ImageFieldType> {
+  constructor(meta: ImageFieldMetaType) {
+    super(meta);
+  }
+
+  validate(value: ImageFieldType | undefined): ValidationResultType {
+    if (value === undefined || value === null) {
+      return { valid: true, errors: [] };
+    }
+
+    if (typeof value !== "object" || Array.isArray(value)) {
+      return {
+        valid: false,
+        errors: [`${this.label} must be a valid image object`],
+      };
+    }
+
+    if (!value._id || !value.FileName) {
+      return {
+        valid: false,
+        errors: [`${this.label} must have _id and FileName`],
+      };
+    }
+
+    return { valid: true, errors: [] };
+  }
+}

package/sdk/bdo/fields/attachment-constants.ts

@@ -0,0 +1,72 @@
+/** Supported image extensions — matches backend SupportFileExtensions.IMAGE_EXTENSIONS */
+export const IMAGE_EXTENSIONS = new Set([
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "webp",
+  "bmp",
+  "tiff",
+  "tif",
+  "heic",
+  "heif",
+]);
+
+/** Supported file extensions — matches backend SupportFileExtensions.FILE_EXTENSIONS */
+export const FILE_EXTENSIONS = new Set([
+  // Images
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "webp",
+  "bmp",
+  "tiff",
+  "tif",
+  "heic",
+  "heif",
+  // Videos
+  "mp4",
+  "mov",
+  "avi",
+  "webm",
+  "mkv",
+  "m4v",
+  "wmv",
+  "flv",
+  // Documents
+  "pdf",
+  "doc",
+  "docx",
+  "xls",
+  "xlsx",
+  "ppt",
+  "pptx",
+  // Other
+  "txt",
+  "csv",
+  "zip",
+]);
+
+/** Extract and normalize file extension from a filename. Returns lowercase without dot. */
+export function extractFileExtension(fileName: string): string {
+  if (!fileName.includes(".")) return "";
+  const parts = fileName.split(".");
+  return (parts[parts.length - 1] ?? "").toLowerCase();
+}
+
+/** Validate file extension against backend whitelist. Throws on invalid. */
+export function validateFileExtension(
+  fileName: string,
+  fieldType: "File" | "Image",
+): void {
+  const ext = extractFileExtension(fileName);
+  const allowed = fieldType === "Image" ? IMAGE_EXTENSIONS : FILE_EXTENSIONS;
+  if (!ext || !allowed.has(ext)) {
+    const types = [...allowed].sort().join(", ");
+    throw new Error(
+      `File "${fileName}" has unsupported extension "${ext || "(none)"}". ` +
+        `Supported for ${fieldType} fields: ${types}`,
+    );
+  }
+}

package/sdk/bdo/fields/index.ts

@@ -15,4 +15,5 @@ export { ObjectField } from "./ObjectField";
 export { TextField } from "./TextField";
 export { UserField } from "./UserField";
 export { FileField } from "./FileField";
+export { ImageField } from "./ImageField";
 export { TextAreaField } from "./TextAreaField";

package/sdk/bdo/index.ts

@@ -32,7 +32,12 @@ export type {
   ArrayFieldMetaType,
   ObjectFieldMetaType,
   FileFieldMetaType,
+  ImageFieldMetaType,
   BaseFieldAccessorType,
+  EditableImageFieldAccessorType,
+  ReadonlyImageFieldAccessorType,
+  EditableFileFieldAccessorType,
+  ReadonlyFileFieldAccessorType,
 } from "./core/types";
 
 // Field classes
@@ -51,4 +56,5 @@ export {
   ObjectField,
   UserField,
   FileField,
+  ImageField,
 } from "./fields";

package/sdk/bdo.ts

@@ -22,6 +22,7 @@ export {
   ObjectField,
   UserField,
   FileField,
+  ImageField,
 } from "./bdo/fields";
 
 // Constants

package/sdk/bdo.types.ts

@@ -23,10 +23,15 @@ export type {
   ArrayFieldMetaType,
   ObjectFieldMetaType,
   FileFieldMetaType,
+  ImageFieldMetaType,
   BaseFieldAccessorType,
   EditableFieldAccessorType,
   ReadonlyFieldAccessorType,
   FieldAccessorType,
+  EditableImageFieldAccessorType,
+  ReadonlyImageFieldAccessorType,
+  EditableFileFieldAccessorType,
+  ReadonlyFileFieldAccessorType,
 } from "./bdo/core/types";
 
 // Re-export SDK field types
@@ -43,6 +48,8 @@ export type {
   ArrayFieldType,
   ObjectFieldType,
   UserFieldType,
+  FileType,
+  ImageFieldType,
   FileFieldType,
   SystemFieldsType,
   UserRefType,

package/sdk/components/hooks/useForm/createResolver.ts

@@ -10,7 +10,7 @@ export function validateConstraints(field: BaseField<unknown>, value: unknown):
   const errors: string[] = [];
 
   // Required
-  if (field.required && (value === undefined || value === null || value === "")) {
+  if (field.required && (value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0))) {
     errors.push(`${field.label} is required`);
     return { valid: false, errors };
   }