@ram_28/kf-ai-sdk 2.0.1 → 2.0.2

package/sdk/bdo/core/types.ts

@@ -18,64 +18,166 @@ export interface ValidationResultType {
   errors: string[];
 }
 
-/**
- * Base field metadata — only id, label, and isEditable.
- * Specialized fields (SelectField, ReferenceField) extend this with their own properties.
- */
-export interface FieldMetaType {
-  readonly id: string;
-  readonly label: string;
-  readonly isEditable: boolean;
+// ============================================================
+// RAW BACKEND META TYPES
+// These represent the exact JSON shape from the backend,
+// with _id injected by the generator.
+// ============================================================
+
+/** Base constraint shape shared by all field types */
+export interface BaseConstraintType {
+  Required?: boolean;
+  PrimaryKey?: boolean;
+  DefaultValue?: unknown;
 }
 
-/**
- * SelectField meta — extends FieldMetaType with static options
- */
-export interface SelectFieldMetaType<T extends string | number = string> extends FieldMetaType {
-  readonly options: readonly SelectOptionType<T>[];
+/** Base field meta — raw backend shape + injected _id */
+export interface BaseFieldMetaType {
+  _id: string;
+  Name: string;
+  Type: string;
+  ReadOnly?: boolean;
+  Required?: boolean;
+  Constraint?: BaseConstraintType;
+  DefaultValue?: unknown;
 }
 
-/**
- * ReferenceField meta — extends FieldMetaType with reference info
- */
-export interface ReferenceFieldMetaType extends FieldMetaType {
-  readonly reference: { bdo: string; fields: string[] };
+export interface StringFieldMetaType extends BaseFieldMetaType {
+  Type: "String";
+  Constraint?: BaseConstraintType & {
+    Length?: number;
+    Enum?: string[];
+  };
+  DefaultValue?: string;
+  View?: {
+    DataObject?: { Type: string; Id: string };
+    Fields?: string[];
+    Search?: string[];
+    Filter?: Record<string, unknown>;
+    Sort?: unknown[];
+  };
 }
 
+export interface TextFieldMetaType extends BaseFieldMetaType {
+  Type: "Text";
+  Constraint?: BaseConstraintType & {
+    Format?: "Plain" | "Markdown";
+  };
+  DefaultValue?: string;
+}
 
-/**
- * Option for select fields
- */
-export interface SelectOptionType<T = string> {
-  value: T;
-  label: string;
-  disabled?: boolean;
+export interface NumberFieldMetaType extends BaseFieldMetaType {
+  Type: "Number";
+  Constraint?: BaseConstraintType & {
+    IntegerPart?: number;
+    FractionPart?: number;
+  };
+  DefaultValue?: number;
 }
 
-/**
- * Base configuration for all fields
- */
-export interface FieldConfigType {
-  id: string;
-  label: string;
-  editable?: boolean;
+export interface BooleanFieldMetaType extends BaseFieldMetaType {
+  Type: "Boolean";
+  Constraint?: BaseConstraintType;
+  DefaultValue?: boolean;
 }
 
-/**
- * Configuration for select fields with predefined options
- */
-export interface SelectFieldConfigType<T extends string | number = string> extends FieldConfigType {
-  options: readonly SelectOptionType<T>[];
+export interface DateFieldMetaType extends BaseFieldMetaType {
+  Type: "Date";
+  Constraint?: BaseConstraintType;
+  DefaultValue?: string;
+}
+
+export interface DateTimeFieldMetaType extends BaseFieldMetaType {
+  Type: "DateTime";
+  Constraint?: BaseConstraintType & {
+    Precision?: "Second" | "Millisecond";
+  };
+  DefaultValue?: string;
+}
+
+export interface SelectFieldMetaType extends BaseFieldMetaType {
+  Type: "String";
+  Constraint?: BaseConstraintType & {
+    Enum: string[];
+  };
+  DefaultValue?: string;
+}
+
+export interface ReferenceFieldMetaType extends BaseFieldMetaType {
+  Type: "Reference";
+  Constraint?: BaseConstraintType;
+  View?: {
+    DataObject: { Type: string; Id: string };
+    Fields?: string[];
+    Search?: string[];
+    Filter?: Record<string, unknown>;
+    Sort?: unknown[];
+  };
+}
+
+export interface UserFieldMetaType extends BaseFieldMetaType {
+  Type: "User";
+  Constraint?: BaseConstraintType;
+  View?: {
+    Filter?: Record<string, unknown>;
+    Sort?: unknown[];
+    BusinessEntity?: string;
+  };
+}
+
+export interface ArrayFieldMetaType extends BaseFieldMetaType {
+  Type: "Array";
+  Constraint?: BaseConstraintType;
+  Property?: BaseFieldMetaType;
+}
+
+export interface ObjectFieldMetaType extends BaseFieldMetaType {
+  Type: "Object";
+  Constraint?: BaseConstraintType;
+  Property?: Record<string, BaseFieldMetaType>;
+}
+
+export interface FileFieldMetaType extends BaseFieldMetaType {
+  Type: "File";
+  Constraint?: BaseConstraintType;
+}
+
+// ============================================================
+// RUNTIME ACCESSOR TYPES
+// These represent what item.Title looks like at runtime
+// ============================================================
+
+/** Base runtime accessor — every field accessor has these */
+export interface BaseFieldAccessorType<T> {
+  readonly label: string;
+  readonly required: boolean;
+  readonly readOnly: boolean;
+  readonly defaultValue: unknown;
+  readonly meta: BaseFieldMetaType;
+  get(): T | undefined;
+  validate(): ValidationResultType;
+}
+
+/** Editable accessor adds set() */
+export interface EditableFieldAccessorType<T> extends BaseFieldAccessorType<T> {
+  set(value: T): void;
 }
 
+/** Readonly accessor has no set() */
+export type ReadonlyFieldAccessorType<T> = BaseFieldAccessorType<T>;
+
+/** Union of editable or readonly accessor */
+export type FieldAccessorType<T> = EditableFieldAccessorType<T> | ReadonlyFieldAccessorType<T>;
+
+// ============================================================
+// SELECT FIELD OPTIONS
+// ============================================================
+
 /**
- * Configuration for reference fields that link to other BDOs
+ * Option for select fields
  */
-export interface ReferenceFieldConfigType<
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  _TRef = unknown,
-> extends FieldConfigType {
-  referenceBdo: string;
-  referenceFields?: readonly string[];
+export interface SelectOptionType<T = string> {
+  value: T;
+  label: string;
+  disabled?: boolean;
 }
-

package/sdk/bdo/fields/ArrayField.ts

@@ -4,7 +4,7 @@
 // ============================================================
 
 import type { ArrayFieldType } from "../../types/base-fields";
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { ArrayFieldMetaType, BaseFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -15,14 +15,18 @@ import { BaseField } from "./BaseField";
  * @example
  * ```typescript
  * readonly Tags = new ArrayField<string>({
- *   id: "Tags",
- *   label: "Tags"
+ *   _id: "Tags", Name: "Tags", Type: "Array",
  * });
  * ```
  */
 export class ArrayField<T = unknown> extends BaseField<ArrayFieldType<T>> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: ArrayFieldMetaType) {
+    super(meta);
+  }
+
+  /** Element type descriptor for array items */
+  get elementType(): BaseFieldMetaType | undefined {
+    return (this._meta as ArrayFieldMetaType).Property;
   }
 
   validate(value: ArrayFieldType<T> | undefined): ValidationResultType {

package/sdk/bdo/fields/BaseField.ts

@@ -3,48 +3,38 @@
 // Abstract base class for all field types
 // ============================================================
 
-import type { FieldConfigType, ValidationResultType, FieldMetaType } from "../core/types";
+import type { BaseFieldMetaType, ValidationResultType } from "../core/types";
 
 /**
- * Abstract base class for all field definitions
+ * Abstract base class for all field definitions.
+ * Stores the raw backend meta JSON and exposes convenience getters.
  *
  * @template T - The TypeScript type of the field value
- *
- * @example
- * ```typescript
- * class CustomField extends BaseField<MyType> {
- *   validate(value: MyType | undefined): ValidationResult {
- *     // Custom validation logic
- *   }
- * }
- * ```
  */
 export abstract class BaseField<T> {
-  protected readonly id: string;
-  protected readonly label: string;
-  protected readonly editable: boolean;
+  /** Full raw backend meta */
+  protected readonly _meta: BaseFieldMetaType;
   protected _parentBoId?: string;
 
-  constructor(config: FieldConfigType) {
-    this.id = config.id;
-    this.label = config.label;
-    this.editable = config.editable ?? true;
+  constructor(meta: BaseFieldMetaType) {
+    this._meta = meta;
   }
 
+  // === Convenience getters (transform backend naming → SDK naming) ===
+
+  get id(): string { return this._meta._id; }
+  get label(): string { return this._meta.Name || this._meta._id; }
+  get readOnly(): boolean { return this._meta.ReadOnly ?? false; }
+  get required(): boolean { return this._meta.Constraint?.Required ?? this._meta.Required ?? false; }
+  get defaultValue(): unknown { return this._meta.DefaultValue ?? this._meta.Constraint?.DefaultValue; }
+  get primaryKey(): boolean { return this._meta.Constraint?.PrimaryKey ?? false; }
+
+  /** Full raw meta (the exact JSON passed to constructor) */
+  get meta(): BaseFieldMetaType { return this._meta; }
+
   /**
    * Validate a value for this field
    * Override in subclasses for custom validation
    */
   abstract validate(value: T | undefined): ValidationResultType;
-
-  /**
-   * Get field metadata (id, label, and field-specific info)
-   */
-  get meta(): FieldMetaType {
-    return {
-      id: this.id,
-      label: this.label,
-      isEditable: this.editable,
-    };
-  }
 }

package/sdk/bdo/fields/BooleanField.ts

@@ -4,7 +4,7 @@
 // ============================================================
 
 import type { BooleanFieldType } from "../../types/base-fields";
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { BooleanFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -13,14 +13,13 @@ import { BaseField } from "./BaseField";
  * @example
  * ```typescript
  * readonly IsActive = new BooleanField({
- *   id: "IsActive",
- *   label: "Is Active"
+ *   _id: "IsActive", Name: "Is Active", Type: "Boolean",
  * });
  * ```
  */
 export class BooleanField extends BaseField<BooleanFieldType> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: BooleanFieldMetaType) {
+    super(meta);
   }
 
   validate(value: BooleanFieldType | undefined): ValidationResultType {

package/sdk/bdo/fields/DateField.ts

@@ -4,7 +4,7 @@
 // ============================================================
 
 import type { DateFieldType } from "../../types/base-fields";
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { DateFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -13,14 +13,13 @@ import { BaseField } from "./BaseField";
  * @example
  * ```typescript
  * readonly BirthDate = new DateField({
- *   id: "BirthDate",
- *   label: "Birth Date"
+ *   _id: "BirthDate", Name: "Birth Date", Type: "Date",
  * });
  * ```
  */
 export class DateField extends BaseField<DateFieldType> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: DateFieldMetaType) {
+    super(meta);
   }
 
   validate(value: DateFieldType | undefined): ValidationResultType {

package/sdk/bdo/fields/DateTimeField.ts

@@ -3,7 +3,7 @@
 // Field for date and datetime values
 // ============================================================
 
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { DateTimeFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -17,14 +17,18 @@ type DateTimeValue = string;
  * @example
  * ```typescript
  * readonly CreatedAt = new DateTimeField({
- *   id: "_created_at",
- *   label: "Created At"
+ *   _id: "_created_at", Name: "Created At", Type: "DateTime", ReadOnly: true,
  * });
  * ```
  */
 export class DateTimeField extends BaseField<DateTimeValue> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: DateTimeFieldMetaType) {
+    super(meta);
+  }
+
+  /** DateTime-specific: precision */
+  get precision(): "Second" | "Millisecond" {
+    return (this._meta as DateTimeFieldMetaType).Constraint?.Precision ?? "Second";
   }
 
   validate(value: DateTimeValue | undefined): ValidationResultType {

package/sdk/bdo/fields/FileField.ts

@@ -0,0 +1,39 @@
+// ============================================================
+// FILE FIELD
+// Field for file attachments
+// ============================================================
+
+import type { FileFieldType } from "../../types/base-fields";
+import type { FileFieldMetaType, ValidationResultType } from "../core/types";
+import { BaseField } from "./BaseField";
+
+/**
+ * Field definition for file attachment fields
+ *
+ * @example
+ * ```typescript
+ * readonly Attachment = new FileField({
+ *   _id: "Attachment", Name: "Attachment", Type: "File",
+ * });
+ * ```
+ */
+export class FileField extends BaseField<FileFieldType> {
+  constructor(meta: FileFieldMetaType) {
+    super(meta);
+  }
+
+  validate(value: FileFieldType | 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 file object`],
+      };
+    }
+
+    return { valid: true, errors: [] };
+  }
+}

package/sdk/bdo/fields/NumberField.ts

@@ -4,7 +4,7 @@
 // ============================================================
 
 import type { NumberFieldType } from "../../types/base-fields";
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { NumberFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -13,16 +13,19 @@ import { BaseField } from "./BaseField";
  * @example
  * ```typescript
  * readonly Price = new NumberField({
- *   id: "Price",
- *   label: "Price"
+ *   _id: "Price", Name: "Price", Type: "Number",
+ *   Constraint: { IntegerPart: 9, FractionPart: 2 },
  * });
  * ```
  */
 export class NumberField extends BaseField<NumberFieldType> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: NumberFieldMetaType) {
+    super(meta);
   }
 
+  get integerPart(): number { return (this._meta as NumberFieldMetaType).Constraint?.IntegerPart ?? 9; }
+  get fractionPart(): number | undefined { return (this._meta as NumberFieldMetaType).Constraint?.FractionPart; }
+
   validate(value: NumberFieldType | undefined): ValidationResultType {
     if (value !== undefined && value !== null && (typeof value !== "number" || isNaN(value))) {
       return {

package/sdk/bdo/fields/ObjectField.ts

@@ -4,7 +4,7 @@
 // ============================================================
 
 import type { ObjectFieldType } from "../../types/base-fields";
-import type { FieldConfigType, ValidationResultType } from "../core/types";
+import type { ObjectFieldMetaType, ValidationResultType } from "../core/types";
 import { BaseField } from "./BaseField";
 
 /**
@@ -13,16 +13,20 @@ import { BaseField } from "./BaseField";
  * @example
  * ```typescript
  * readonly Config = new ObjectField({
- *   id: "Config",
- *   label: "Configuration"
+ *   _id: "Config", Name: "Configuration", Type: "Object",
  * });
  * ```
  */
 export class ObjectField<
   T extends Record<string, unknown> = Record<string, unknown>,
 > extends BaseField<ObjectFieldType<T>> {
-  constructor(config: FieldConfigType) {
-    super(config);
+  constructor(meta: ObjectFieldMetaType) {
+    super(meta);
+  }
+
+  /** Nested property definitions */
+  get properties(): Record<string, unknown> | undefined {
+    return (this._meta as ObjectFieldMetaType).Property;
   }
 
   validate(value: ObjectFieldType<T> | undefined): ValidationResultType {

package/sdk/bdo/fields/ReferenceField.ts

@@ -4,35 +4,44 @@
 // ============================================================
 
 import type { ReferenceFieldType } from "../../types/base-fields";
-import type { ReferenceFieldConfigType, ValidationResultType, ReferenceFieldMetaType } from "../core/types";
+import type { ReferenceFieldMetaType as ReferenceFieldMetaRawType, ValidationResultType } from "../core/types";
 import { api } from "../../api/client";
 import { BaseField } from "./BaseField";
 
 /**
- * Field definition for reference/lookup fields
+ * Field definition for reference/lookup fields.
+ * Config is derived from View.DataObject in the raw meta.
  *
  * @template TRef - The type of the referenced record
  *
  * @example
  * ```typescript
- * readonly SupplierInfo = new ReferenceField<SupplierType>({
- *   id: "SupplierInfo",
- *   label: "Supplier",
- *   referenceBdo: "BDO_Supplier",
- *   referenceFields: ["_id", "SupplierName", "Email"]
+ * readonly SupplierInfo = new ReferenceField<SupplierRefType>({
+ *   _id: "SupplierInfo", Name: "Supplier", Type: "Reference",
+ *   View: {
+ *     DataObject: { Type: "BO", Id: "BDO_Supplier" },
+ *     Fields: ["_id", "SupplierName", "Email"],
+ *   },
  * });
  * ```
  */
 export class ReferenceField<TRef = unknown> extends BaseField<
   ReferenceFieldType<TRef>
 > {
-  protected readonly referenceBdo: string;
-  protected readonly referenceFields: readonly string[];
+  constructor(meta: ReferenceFieldMetaRawType) {
+    super(meta);
+  }
+
+  get referenceBdo(): string {
+    return (this._meta as ReferenceFieldMetaRawType).View?.DataObject?.Id ?? "";
+  }
+
+  get referenceFields(): readonly string[] {
+    return (this._meta as ReferenceFieldMetaRawType).View?.Fields ?? ["_id"];
+  }
 
-  constructor(config: ReferenceFieldConfigType<TRef>) {
-    super(config);
-    this.referenceBdo = config.referenceBdo;
-    this.referenceFields = config.referenceFields ?? ["_id"];
+  get searchFields(): readonly string[] {
+    return (this._meta as ReferenceFieldMetaRawType).View?.Search ?? [];
   }
 
   validate(value: ReferenceFieldType<TRef> | undefined): ValidationResultType {
@@ -69,19 +78,4 @@ export class ReferenceField<TRef = unknown> extends BaseField<
     }
     return api(this._parentBoId).fetchField<TRef>(instanceId ?? "new", this.id);
   }
-
-  /**
-   * Get field metadata including reference info
-   */
-  override get meta(): ReferenceFieldMetaType {
-    return {
-      id: this.id,
-      label: this.label,
-      isEditable: this.editable,
-      reference: {
-        bdo: this.referenceBdo,
-        fields: [...this.referenceFields],
-      },
-    };
-  }
 }

package/sdk/bdo/fields/SelectField.ts

@@ -3,35 +3,34 @@
 // Field for single selection from predefined options
 // ============================================================
 
-import type { SelectFieldConfigType, SelectOptionType, ValidationResultType, SelectFieldMetaType } from "../core/types";
+import type { SelectFieldMetaType as SelectFieldMetaRawType, SelectOptionType, ValidationResultType } from "../core/types";
 import type { FetchFieldOptionType } from "../../types/common";
 import { api } from "../../api/client";
 import { BaseField } from "./BaseField";
 
 /**
- * Field definition for select fields with predefined options
+ * Field definition for select fields.
+ * Options are derived from Constraint.Enum in the raw meta.
  *
  * @template T - Union type of allowed option values
  *
  * @example
  * ```typescript
- * readonly Status = new SelectField<"active" | "inactive" | "pending">({
- *   id: "Status",
- *   label: "Status",
- *   options: [
- *     { value: "active", label: "Active" },
- *     { value: "inactive", label: "Inactive" },
- *     { value: "pending", label: "Pending" }
- *   ]
+ * readonly Status = new SelectField<"active" | "inactive">({
+ *   _id: "Status", Name: "Status", Type: "String",
+ *   Constraint: { Enum: ["active", "inactive"] },
  * });
  * ```
  */
 export class SelectField<T extends string | number = string> extends BaseField<T> {
-  protected readonly options: readonly SelectOptionType<T>[];
+  constructor(meta: SelectFieldMetaRawType) {
+    super(meta);
+  }
 
-  constructor(config: SelectFieldConfigType<T>) {
-    super(config);
-    this.options = config.options;
+  /** Static options derived from Constraint.Enum */
+  get options(): readonly SelectOptionType<T>[] {
+    const enumValues = (this._meta as SelectFieldMetaRawType).Constraint?.Enum ?? [];
+    return enumValues.map(v => ({ value: v as T, label: v }));
   }
 
   validate(value: T | undefined): ValidationResultType {
@@ -73,16 +72,4 @@ export class SelectField<T extends string | number = string> extends BaseField<T
       label: item.Label,
     }));
   }
-
-  /**
-   * Get field metadata including static options
-   */
-  override get meta(): SelectFieldMetaType<T> {
-    return {
-      id: this.id,
-      label: this.label,
-      isEditable: this.editable,
-      options: this.options,
-    };
-  }
 }