@ram_28/kf-ai-sdk 1.0.0

package/sdk/api/client.ts

@@ -0,0 +1,447 @@
+// ============================================================
+// API Client - Simple CRUD Operations
+// ============================================================
+
+import type {
+  ListOptions,
+  ListResponse,
+  ReadResponse,
+  CreateUpdateResponse,
+  DeleteResponse,
+  CountResponse,
+  DateTimeEncoded,
+  DateEncoded,
+  MetricOptions,
+  MetricResponse,
+  PivotOptions,
+  PivotResponse,
+  DraftResponse,
+  FieldsResponse,
+  FetchFieldOption,
+  FetchFieldResponse,
+} from "../types/common";
+
+/**
+ * API client interface for a specific Business Object
+ */
+export interface ResourceClient<T = any> {
+  // ============================================================
+  // BASIC CRUD OPERATIONS
+  // ============================================================
+
+  /** Get single record by ID */
+  get(id: string): Promise<T>;
+
+  /** Create new record */
+  create(data: Partial<T> & { _id?: string }): Promise<CreateUpdateResponse>;
+
+  /** Update existing record */
+  update(id: string, data: Partial<T>): Promise<CreateUpdateResponse>;
+
+  /** Delete record by ID */
+  delete(id: string): Promise<DeleteResponse>;
+
+  /** List records with optional filtering, sorting, and pagination */
+  list(options?: ListOptions): Promise<ListResponse<T>>;
+
+  /** Get count of records matching the same criteria as list */
+  count(options?: ListOptions): Promise<CountResponse>;
+
+  // ============================================================
+  // DRAFT/INTERACTIVE OPERATIONS
+  // ============================================================
+
+  /**
+   * Create draft - compute fields without persisting
+   * POST /{bo_id}/draft
+   */
+  draft(data: Partial<T>): Promise<DraftResponse>;
+
+  /**
+   * Update draft (commit) - compute and prepare for update
+   * POST /{bo_id}/{instance_id}/draft
+   */
+  draftUpdate(id: string, data: Partial<T>): Promise<CreateUpdateResponse>;
+
+  /**
+   * Update draft (patch) - compute fields during editing
+   * PATCH /{bo_id}/{instance_id}/draft
+   */
+  draftPatch(id: string, data: Partial<T>): Promise<DraftResponse>;
+
+  // ============================================================
+  // QUERY OPERATIONS
+  // ============================================================
+
+  /**
+   * Get aggregated metrics grouped by dimensions
+   * POST /{bo_id}/metric
+   */
+  metric(options: Omit<MetricOptions, "Type">): Promise<MetricResponse>;
+
+  /**
+   * Get pivot table data
+   * POST /{bo_id}/pivot
+   */
+  pivot(options: Omit<PivotOptions, "Type">): Promise<PivotResponse>;
+
+  // ============================================================
+  // METADATA OPERATIONS
+  // ============================================================
+
+  /**
+   * Get field definitions for this Business Object
+   * GET /{bo_id}/fields
+   */
+  fields(): Promise<FieldsResponse>;
+
+  /**
+   * Fetch reference data for a specific field (for lookup and dropdown fields)
+   * GET /{bo_id}/{instance_id}/field/{field_id}/fetch
+   */
+  fetchField(instanceId: string, fieldId: string): Promise<FetchFieldOption[]>;
+}
+
+/**
+ * Configuration options for the API client
+ */
+interface ApiConfig {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Global API configuration
+ */
+let apiConfig: ApiConfig = {
+  baseUrl: "",
+  headers: {
+    "Content-Type": "application/json",
+  },
+};
+
+/**
+ * Set the base URL for all API requests
+ */
+export function setApiBaseUrl(baseUrl: string): void {
+  apiConfig.baseUrl = baseUrl;
+}
+
+/**
+ * Set default headers for all requests
+ */
+export function setDefaultHeaders(headers: Record<string, string>): void {
+  apiConfig.headers = { ...apiConfig.headers, ...headers };
+}
+
+/**
+ * Get current default headers
+ */
+export function getDefaultHeaders(): Record<string, string> {
+  return { ...apiConfig.headers };
+}
+
+/**
+ * Get current base URL
+ */
+export function getApiBaseUrl(): string {
+  return apiConfig.baseUrl || "";
+}
+
+/**
+ * Recursively process an object to decode datetime fields
+ */
+function decodeResponseData<T>(data: any): T {
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  if (Array.isArray(data)) {
+    return data.map((item) => decodeResponseData(item)) as T;
+  }
+
+  if (typeof data === "object") {
+    // Check for datetime encoding
+    if ("$__dt__" in data) {
+      return new Date((data as DateTimeEncoded).$__dt__ * 1000) as T;
+    }
+
+    // Check for date encoding
+    if ("$__d__" in data) {
+      return new Date((data as DateEncoded).$__d__) as T;
+    }
+
+    // Recursively process object properties
+    const result: any = {};
+    for (const [key, value] of Object.entries(data)) {
+      result[key] = decodeResponseData(value);
+    }
+    return result as T;
+  }
+
+  return data as T;
+}
+
+/**
+ * Create a resource client for the specified Business Object
+ * @param bo_id - Business Object identifier (e.g., "user", "leave", "vendor")
+ * @returns Resource client with CRUD operations matching API spec
+ */
+export function api<T = any>(bo_id: string): ResourceClient<T> {
+  const baseUrl = apiConfig.baseUrl;
+  const defaultHeaders = apiConfig.headers;
+
+  return {
+    async get(id: string): Promise<T> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/read`, {
+        method: "GET",
+        headers: defaultHeaders,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to get ${bo_id} ${id}: ${response.statusText}`);
+      }
+
+      const responseData: ReadResponse<T> = await response.json();
+      return decodeResponseData<T>(responseData.Data);
+    },
+
+    async create(
+      data: Partial<T> & { _id?: string }
+    ): Promise<CreateUpdateResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/create`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to create ${bo_id}: ${response.statusText}`);
+      }
+
+      return response.json();
+    },
+
+    async update(id: string, data: Partial<T>): Promise<CreateUpdateResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/update`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to update ${bo_id} ${id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async delete(id: string): Promise<DeleteResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/delete`, {
+        method: "DELETE",
+        headers: defaultHeaders,
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to delete ${bo_id} ${id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async list(options?: ListOptions): Promise<ListResponse<T>> {
+      const requestBody: ListOptions = {
+        Type: "List",
+        ...options,
+      };
+
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/list`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to list ${bo_id}: ${response.statusText}`);
+      }
+
+      const responseData: ListResponse<any> = await response.json();
+      return {
+        Data: responseData.Data.map((item) => decodeResponseData<T>(item)),
+      };
+    },
+
+    async count(options?: ListOptions): Promise<CountResponse> {
+      // Note: Count uses metric endpoint with Count aggregation
+      const requestBody = {
+        Type: "Metric",
+        GroupBy: [],
+        Metric: [{ Field: "_id", Type: "Count" }],
+        ...(options?.Filter && { Filter: options.Filter }),
+      };
+
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/metric`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to count ${bo_id}: ${response.statusText}`);
+      }
+
+      const result = await response.json();
+      // Extract count from metric response
+      const count = result.Data?.[0]?.count__id ?? 0;
+      return { Count: count };
+    },
+
+    // ============================================================
+    // DRAFT/INTERACTIVE OPERATIONS
+    // ============================================================
+
+    async draft(data: Partial<T>): Promise<DraftResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/draft`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to create draft for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async draftUpdate(
+      id: string,
+      data: Partial<T>
+    ): Promise<CreateUpdateResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/draft`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to update draft for ${bo_id} ${id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async draftPatch(id: string, data: Partial<T>): Promise<DraftResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/${id}/draft`, {
+        method: "PATCH",
+        headers: defaultHeaders,
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to patch draft for ${bo_id} ${id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    // ============================================================
+    // QUERY OPERATIONS
+    // ============================================================
+
+    async metric(
+      options: Omit<MetricOptions, "Type">
+    ): Promise<MetricResponse> {
+      const requestBody: MetricOptions = {
+        Type: "Metric",
+        ...options,
+      };
+
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/metric`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get metrics for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async pivot(options: Omit<PivotOptions, "Type">): Promise<PivotResponse> {
+      const requestBody: PivotOptions = {
+        Type: "Pivot",
+        ...options,
+      };
+
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/pivot`, {
+        method: "POST",
+        headers: defaultHeaders,
+        body: JSON.stringify(requestBody),
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get pivot data for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    // ============================================================
+    // METADATA OPERATIONS
+    // ============================================================
+
+    async fields(): Promise<FieldsResponse> {
+      const response = await fetch(`${baseUrl}/api/app/${bo_id}/fields`, {
+        method: "GET",
+        headers: defaultHeaders,
+      });
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to get fields for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      return response.json();
+    },
+
+    async fetchField(
+      instanceId: string,
+      fieldId: string
+    ): Promise<FetchFieldOption[]> {
+      const response = await fetch(
+        `${baseUrl}/api/app/${bo_id}/${instanceId}/field/${fieldId}/fetch`,
+        {
+          method: "GET",
+          headers: defaultHeaders,
+        }
+      );
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch field ${fieldId} for ${bo_id}: ${response.statusText}`
+        );
+      }
+
+      const responseData: FetchFieldResponse = await response.json();
+      return responseData.Data;
+    },
+  };
+}

package/sdk/api/datetime.ts

@@ -0,0 +1,33 @@
+import type { DateTimeEncoded, DateEncoded } from '../types/common';
+
+/**
+ * Utility functions for datetime encoding/decoding
+ */
+
+/**
+ * Encode a Date object to API datetime format
+ */
+export function encodeDatetime(date: Date): DateTimeEncoded {
+  return { $__dt__: date.getTime() / 1000 };
+}
+
+/**
+ * Decode API datetime format to Date object
+ */
+export function decodeDatetime(encoded: DateTimeEncoded): Date {
+  return new Date(encoded.$__dt__ * 1000);
+}
+
+/**
+ * Encode a Date object to API date format (YYYY-MM-DD)
+ */
+export function encodeDate(date: Date): DateEncoded {
+  return { $__d__: date.toISOString().split('T')[0] };
+}
+
+/**
+ * Decode API date format to Date object
+ */
+export function decodeDate(encoded: DateEncoded): Date {
+  return new Date(encoded.$__d__);
+}

package/sdk/api/index.ts

@@ -0,0 +1,61 @@
+// Main API client
+export {
+  api,
+  setApiBaseUrl,
+  setDefaultHeaders,
+  getDefaultHeaders,
+  getApiBaseUrl,
+} from "./client";
+export type { ResourceClient } from "./client";
+
+// DateTime utilities
+export {
+  encodeDatetime,
+  decodeDatetime,
+  encodeDate,
+  decodeDate,
+} from "./datetime";
+
+// Metadata API client
+export { getBdoSchema, listMetadata } from "./metadata";
+export type { BackendSchema, MetadataItem, FieldMetadata } from "./metadata";
+
+// Re-export common types for convenience
+export type {
+  // Sort types
+  SortDirection,
+  SortOption,
+  Sort,
+  // Filter types
+  Filter,
+  FilterCondition,
+  FilterOperator,
+  FilterRHSType,
+  LogicalOperator,
+  FilterLogical,
+  FilterNode,
+  // List types
+  ListOptions,
+  ListResponse,
+  ReadResponse,
+  CreateUpdateResponse,
+  DeleteResponse,
+  CountResponse,
+  // DateTime types
+  DateTimeEncoded,
+  DateEncoded,
+  // Metric types
+  MetricType,
+  MetricField,
+  MetricOptions,
+  MetricResponse,
+  // Pivot types
+  PivotHeaderItem,
+  PivotResponseData,
+  PivotOptions,
+  PivotResponse,
+  // Draft types
+  DraftResponse,
+  // Fields types
+  FieldsResponse,
+} from "../types/common";

package/sdk/api/metadata.ts

@@ -0,0 +1,148 @@
+// ============================================================
+// METADATA API CLIENT
+// ============================================================
+// Handles metadata/schema fetching operations for Business Objects
+
+import type { ListOptions, ListResponse } from "../types/common";
+import { getApiBaseUrl, getDefaultHeaders } from "./client";
+
+// ============================================================
+// METADATA API OPERATIONS
+// ============================================================
+
+/**
+ * BDO Schema Structure (Business Object Metadata)
+ */
+export interface BackendSchema {
+  [fieldName: string]: any;
+}
+
+/**
+ * Get BDO schema/metadata by ID
+ *
+ * Endpoint: GET //api/app/meta/bdo/${metaId}
+ *
+ * @param metaId - The Business Object metadata ID (e.g., "Product", "Order")
+ * @returns Promise resolving to the BDO schema
+ *
+ * @example
+ * ```typescript
+ * const schema = await getBdoSchema("Product");
+ * console.log(schema.Fields); // Access field definitions
+ * ```
+ */
+export async function getBdoSchema(metaId: string): Promise<BackendSchema> {
+  try {
+    const baseUrl = getApiBaseUrl();
+    const headers = getDefaultHeaders();
+
+    const response = await fetch(`${baseUrl}/api/app/meta/bdo/${metaId}`, {
+      method: "GET",
+      headers,
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch schema for ${metaId}: ${response.statusText}`
+      );
+    }
+
+    const bdoSchema = await response.json();
+
+    // Validate that response is a valid BDO schema object
+    if (!bdoSchema || typeof bdoSchema !== "object") {
+      throw new Error(`Invalid BDO schema response for ${metaId}`);
+    }
+
+    return bdoSchema as BackendSchema;
+  } catch (error) {
+    console.error(`Schema fetch error for ${metaId}:`, error);
+    throw new Error(
+      `Failed to load BDO schema: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+  }
+}
+
+/**
+ * Metadata item structure
+ */
+export interface MetadataItem {
+  _id: string;
+  Name: string;
+  Kind: string;
+  Description?: string;
+  [key: string]: any;
+}
+
+/**
+ * List all metadata items with optional filtering and pagination
+ *
+ * Endpoint: GET or POST /api/app/metadata/list
+ *
+ * @param options - Optional list options (filters, sorting, pagination)
+ * @returns Promise resolving to list of metadata items
+ *
+ * @example
+ * ```typescript
+ * // List all metadata
+ * const all = await listMetadata();
+ *
+ * // List with filters
+ * const businessObjects = await listMetadata({
+ *   Filter: {
+ *     Operator: "AND",
+ *     Condition: [{ LhsField: "Kind", Operator: "eq", RhsValue: "BusinessObject" }]
+ *   }
+ * });
+ * ```
+ */
+export async function listMetadata(
+  options?: ListOptions
+): Promise<ListResponse<MetadataItem>> {
+  try {
+    const baseUrl = getApiBaseUrl();
+    const headers = getDefaultHeaders();
+
+    // Use GET for simple requests, POST for complex filters
+    const method = options?.Filter || options?.Sort ? "POST" : "GET";
+
+    const response = await fetch(`${baseUrl}/api/app/metadata/list`, {
+      method,
+      headers,
+      ...(method === "POST" &&
+        options && {
+          body: JSON.stringify(options),
+        }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to list metadata: ${response.statusText}`);
+    }
+
+    const result = await response.json();
+
+    return result as ListResponse<MetadataItem>;
+  } catch (error) {
+    console.error("Metadata list error:", error);
+    throw new Error(
+      `Failed to list metadata: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+  }
+}
+
+/**
+ * Field metadata structure
+ */
+export interface FieldMetadata {
+  Id: string;
+  Name: string;
+  Type: string;
+  Required?: boolean;
+  Unique?: boolean;
+  Computed?: boolean;
+  Values?: {
+    Mode: "Static" | "Dynamic";
+    Items?: Array<{ Value: string; Label: string }>;
+  };
+  [key: string]: any;
+}