@ram_28/kf-ai-sdk 1.0.19 → 1.0.21

package/sdk/index.ts

@@ -1,16 +1,163 @@
-// Core SDK exports
+// ============================================================
+// @ram_28/kf-ai-sdk - Main Entry Point
+// ============================================================
+// This is the primary export file for the SDK, providing a unified
+// interface to all hooks, types, utilities, and API functions.
 
-// Type system
-export * from './types';
+// ============================================================
+// HOOKS - Core functionality for building applications
+// ============================================================
 
-// API client
-export * from './api';
+// Table hook - Data tables with sorting, pagination, and filtering
+export { useTable } from './components/hooks/useTable';
+export type {
+  UseTableOptionsType,
+  UseTableReturnType,
+} from './components/hooks/useTable';
 
-// Utilities
-export * from './utils';
+// Form hook - Schema-driven forms with validation
+export { useForm } from './components/hooks/useForm';
+export type {
+  UseFormOptionsType,
+  UseFormReturnType,
+  FormFieldConfigType,
+  FormSchemaConfigType,
+} from './components/hooks/useForm';
 
-// Components
-export * from './components';
+// Kanban hook - Kanban board state management
+export { useKanban } from './components/hooks/useKanban';
+export type {
+  UseKanbanOptionsType,
+  UseKanbanReturnType,
+  KanbanCardType,
+  KanbanColumnType,
+  ColumnConfigType,
+} from './components/hooks/useKanban';
+
+// Filter hook - Advanced filtering with logical operators
+export { useFilter, isCondition, isConditionGroup } from './components/hooks/useFilter';
+export type {
+  UseFilterOptionsType,
+  UseFilterReturnType,
+} from './components/hooks/useFilter';
+
+// ============================================================
+// AUTHENTICATION - User authentication and authorization
+// ============================================================
+
+export { AuthProvider, useAuth } from './auth';
+export type {
+  UseAuthReturnType,
+  UserDetailsType,
+  AuthStatusType,
+  AuthProviderPropsType,
+} from './auth/types';
+
+// ============================================================
+// API CLIENT - Type-safe CRUD operations
+// ============================================================
+
+export { api, setApiBaseUrl, getApiBaseUrl, getBdoSchema } from './api';
+
+// ============================================================
+// TYPES - Core type definitions
+// ============================================================
+
+// Common types
+export type {
+  SortType,
+  SortDirectionType,
+  FilterType,
+  ConditionType,
+  ConditionGroupType,
+  ConditionOperatorType,
+  ConditionGroupOperatorType,
+  ListResponseType,
+  ListOptionsType,
+  ColumnDefinitionType,
+} from './types/common';
+
+// Base field types
+export type {
+  IdFieldType,
+  StringFieldType,
+  TextAreaFieldType,
+  NumberFieldType,
+  LongFieldType,
+  BooleanFieldType,
+  DateFieldType,
+  DateTimeFieldType,
+  CurrencyFieldType,
+  SelectFieldType,
+  LookupFieldType,
+  ArrayFieldType,
+  JSONFieldType,
+  ReferenceFieldType,
+  ExtractReferenceType,
+  ExtractFetchFieldType,
+} from './types/base-fields';
 
-// Authentication
+// ============================================================
+// UTILITIES - Helper functions
+// ============================================================
+
+// Formatting utilities
+export {
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatBoolean,
+  formatArray,
+  formatJSON,
+  formatFieldValue,
+} from './utils/formatting';
+
+// Class name utility
+export { cn } from './utils/cn';
+
+// Error handling utilities
+export {
+  toError,
+  isError,
+  getErrorMessage,
+  isNetworkError,
+  isTimeoutError,
+  isAbortError,
+  tryCatch,
+  wrapError,
+} from './utils/error-handling';
+
+// API utilities
+export {
+  buildListOptions,
+  buildCountOptions,
+  combineFilters,
+} from './utils/api';
+
+// ============================================================
+// UI COMPONENTS - Pre-built React components
+// ============================================================
+
+export {
+  Kanban,
+  KanbanColumn,
+  KanbanColumnHeader,
+  KanbanColumnTitle,
+  KanbanColumnContent,
+  KanbanCard,
+  KanbanCardTitle,
+  KanbanCardDescription,
+  KanbanColumnFooter,
+} from './components/ui';
+
+// ============================================================
+// LEGACY EXPORTS - For backwards compatibility
+// ============================================================
+
+// Re-export everything from submodules for backwards compatibility
+export * from './types';
+export * from './api';
+export * from './utils';
+export * from './components';
 export * from './auth';

package/sdk/table.types.ts

@@ -10,4 +10,7 @@ export type {
 
   // Column definition
   ColumnDefinitionType,
+
+  // State types
+  PaginationStateType,
 } from './components/hooks/useTable/types';

package/sdk/types/base-fields.ts

@@ -67,27 +67,47 @@ export type LongFieldType = number;
  */
 export type BooleanFieldType = boolean;
 
+/**
+ * Encoded date format from API response
+ * API returns: { "$__d__": "YYYY-MM-DD" }
+ */
+export interface DateEncodedType {
+  $__d__: string;
+}
+
+/**
+ * Encoded datetime format from API response
+ * API returns: { "$__dt__": unix_timestamp_seconds }
+ */
+export interface DateTimeEncodedType {
+  $__dt__: number;
+}
+
 /**
  * Date field (date only, no time)
- * Resolves to: Date
+ * API Response Format: { "$__d__": "YYYY-MM-DD" }
+ * API Request Format: "YYYY-MM-DD"
  * Storage: DATE in database
  * Use this for birth dates, due dates, calendar events
  *
  * @example
- * DateFieldType // => Date (date only)
+ * // Response from API:
+ * { "$__d__": "2025-03-15" }
  */
-export type DateFieldType = Date;
+export type DateFieldType = DateEncodedType;
 
 /**
  * DateTime field (date and time)
- * Resolves to: Date
+ * API Response Format: { "$__dt__": unix_timestamp_seconds }
+ * API Request Format: "YYYY-MM-DD HH:MM:SS"
  * Storage: DATETIME/TIMESTAMP in database
  * Use this for created_at, updated_at, event timestamps
  *
  * @example
- * DateTimeFieldType // => Date (with time)
+ * // Response from API:
+ * { "$__dt__": 1769110463 }
  */
-export type DateTimeFieldType = Date;
+export type DateTimeFieldType = DateTimeEncodedType;
 
 // ============================================================
 // COMPLEX FIELD TYPES
@@ -124,7 +144,47 @@ export type CurrencyValueType =
  */
 export type JSONFieldType<T = JSONValueType> = T;
 
-export type ReferenceFieldType = string;
+/**
+ * Reference/Lookup field for relationships to other Business Data Objects
+ *
+ * @template TReferencedType - The full type of the referenced BDO record
+ *
+ * Runtime behavior:
+ * - The field stores the full referenced record (e.g., full supplier object)
+ * - API returns the complete record from the referenced BDO
+ * - On save, the full object is sent in the payload
+ *
+ * @example
+ * SupplierInfo: ReferenceFieldType<BaseSupplierType>;
+ * // At runtime: { _id: "...", SupplierId: "...", SupplierName: "...", ... }
+ */
+export type ReferenceFieldType<TReferencedType = unknown> = TReferencedType;
+
+/**
+ * Extract the referenced type from a ReferenceFieldType
+ * Note: Since ReferenceFieldType<T> = T, this just returns T if it has _id
+ */
+export type ExtractReferenceType<T> = T extends { _id: string } ? T : never;
+
+/**
+ * Extract the type that fetchField should return for a given field type
+ * - For Reference fields (objects with _id) → the full referenced record type
+ * - For other field types → { Value: string; Label: string } (static dropdown)
+ *
+ * Detection: All BDO types have _id: string, so we check for that property
+ * to distinguish reference fields from primitive fields like StringFieldType.
+ *
+ * @example
+ * type SupplierOptions = ExtractFetchFieldType<BaseProductType["SupplierInfo"]>;
+ * // Result: BaseSupplierType (has _id)
+ *
+ * type CategoryOptions = ExtractFetchFieldType<BaseProductType["Category"]>;
+ * // Result: { Value: string; Label: string } (string has no _id)
+ */
+export type ExtractFetchFieldType<T> =
+  T extends { _id: string }
+    ? T
+    : { Value: string; Label: string };
 
 /**
  * Valid JSON value types
@@ -156,17 +216,11 @@ export interface JSONArrayType extends Array<JSONValueType> {}
 export type SelectFieldType<T extends string> = T;
 
 /**
- * Lookup field for references to other records
- * @template T - Type of the referenced record ID (defaults to string)
- * Resolves to: T
- * Storage: VARCHAR in database (stores the ID)
- * Use this for foreign keys, relationships, references
- *
- * @example
- * LookupFieldType // => string (referenced record ID)
- * LookupFieldType<IdFieldType> // => string (typed as IdFieldType)
+ * Alias for ReferenceFieldType (Lookup = Reference in the backend)
+ * @template TReferencedType - The full type of the referenced BDO record
+ * @deprecated Use ReferenceFieldType instead
  */
-export type LookupFieldType<T extends string = string> = T;
+export type LookupFieldType<TReferencedType = unknown> = ReferenceFieldType<TReferencedType>;
 
 // ============================================================
 // CONTAINER AND UTILITY TYPES

package/sdk/types/common.ts

@@ -37,14 +37,15 @@ export type FilterRHSTypeType = "Constant" | "BOField" | "AppVariable";
 
 /**
  * Leaf condition (actual field comparison)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface ConditionType {
+export interface ConditionType<T = any> {
   /** Optional ID for hook state management (omitted in API payload) */
   id?: string;
   /** Condition operator */
   Operator: ConditionOperatorType;
-  /** Left-hand side field name */
-  LHSField: string;
+  /** Left-hand side field name (keyof T when generic is provided) */
+  LHSField: T extends any ? keyof T | string : string;
   /** Right-hand side value */
   RHSValue: any;
   /** Right-hand side type (optional, defaults to Constant) */
@@ -53,34 +54,25 @@ export interface ConditionType {
 
 /**
  * Group combining conditions (recursive structure)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export interface ConditionGroupType {
+export interface ConditionGroupType<T = any> {
   /** Optional ID for hook state management (omitted in API payload) */
   id?: string;
   /** Group operator (And, Or, Not) */
   Operator: ConditionGroupOperatorType;
   /** Nested conditions (can be Condition or ConditionGroup) */
-  Condition: Array<ConditionType | ConditionGroupType>;
+  Condition: Array<ConditionType<T> | ConditionGroupType<T>>;
 }
 
 /**
  * Root filter type (alias for ConditionGroup)
+ * @template T - Data type for type-safe field names (defaults to any)
  */
-export type FilterType = ConditionGroupType;
+export type FilterType<T = any> = ConditionGroupType<T>;
 
-/**
- * DateTime encoding format used by the API
- */
-export interface DateTimeEncodedType {
-  $__dt__: number;
-}
-
-/**
- * Date encoding format used by the API
- */
-export interface DateEncodedType {
-  $__d__: string;
-}
+// Note: DateTimeEncodedType and DateEncodedType are now defined in base-fields.ts
+// They are re-exported from api/index.ts for convenience
 
 /**
  * Standard paginated list response
@@ -296,3 +288,25 @@ export interface FetchFieldResponseType {
   /** Array of field options */
   Data: FetchFieldOptionType[];
 }
+
+// ============================================================
+// SHARED COMPONENT TYPES
+// ============================================================
+
+/**
+ * Column definition for data display and behavior
+ * Used by useTable and useKanban for defining field configurations
+ * @template T - Data type for type-safe field names
+ */
+export interface ColumnDefinitionType<T> {
+  /** Field name from the data type */
+  fieldId: keyof T;
+  /** Display label (optional, defaults to fieldId) */
+  label?: string;
+  /** Enable sorting for this field */
+  enableSorting?: boolean;
+  /** Enable filtering for this field */
+  enableFiltering?: boolean;
+  /** Custom transform function (overrides auto-formatting) */
+  transform?: (value: any, item: T) => React.ReactNode;
+}

package/sdk/utils/api/buildListOptions.ts

@@ -0,0 +1,120 @@
+// ============================================================
+// BUILD LIST OPTIONS UTILITY
+// ============================================================
+// Shared utility for building API list options across hooks
+
+import type { ListOptionsType, FilterType, SortType } from "../../types/common";
+
+/**
+ * Options for building list API request options
+ */
+export interface BuildListOptionsParams<T = any> {
+  /** Search query string */
+  search?: string;
+  /** Filter payload */
+  filter?: FilterType<T>;
+  /** Sort configuration */
+  sort?: {
+    field: keyof T | null;
+    direction: "asc" | "desc" | null;
+  };
+  /** Sort array in API format */
+  sortArray?: SortType;
+  /** Pagination settings */
+  pagination?: {
+    pageNo: number;
+    pageSize: number;
+  };
+}
+
+/**
+ * Build list options for count queries
+ * Excludes pagination and sorting (they don't affect count)
+ */
+export function buildCountOptions<T = any>(
+  params: Pick<BuildListOptionsParams<T>, "search" | "filter">
+): ListOptionsType {
+  const opts: ListOptionsType = {};
+
+  if (params.search) {
+    opts.Search = params.search;
+  }
+
+  if (params.filter) {
+    opts.Filter = params.filter;
+  }
+
+  return opts;
+}
+
+/**
+ * Build list options for data queries
+ * Includes all options: search, filter, sort, pagination
+ */
+export function buildListOptions<T = any>(
+  params: BuildListOptionsParams<T>
+): ListOptionsType {
+  const opts: ListOptionsType = buildCountOptions({
+    search: params.search,
+    filter: params.filter,
+  });
+
+  // Add sorting - convert internal format to API format
+  if (params.sort?.field && params.sort?.direction) {
+    opts.Sort = [
+      {
+        [String(params.sort.field)]:
+          params.sort.direction === "asc" ? "ASC" : "DESC",
+      },
+    ];
+  } else if (params.sortArray) {
+    opts.Sort = params.sortArray;
+  }
+
+  // Add pagination
+  if (params.pagination) {
+    opts.Page = params.pagination.pageNo;
+    opts.PageSize = params.pagination.pageSize;
+  }
+
+  return opts;
+}
+
+/**
+ * Combine filter payload with additional column filter
+ * Used for kanban column-specific queries
+ */
+export function combineFilters<T = any>(
+  baseFilter: FilterType<T> | undefined,
+  additionalCondition: {
+    LHSField: string;
+    Operator: string;
+    RHSValue: any;
+    RHSType?: string;
+  }
+): FilterType<T> {
+  const columnFilterObject = {
+    ...additionalCondition,
+    RHSType: additionalCondition.RHSType || "Constant",
+  };
+
+  if (!baseFilter) {
+    return {
+      Operator: "And",
+      Condition: [columnFilterObject],
+    } as FilterType<T>;
+  }
+
+  // If base is And, append. If base is Or/Not, wrap in new And.
+  if (baseFilter.Operator === "And") {
+    return {
+      ...baseFilter,
+      Condition: [...(baseFilter.Condition || []), columnFilterObject],
+    } as FilterType<T>;
+  }
+
+  return {
+    Operator: "And",
+    Condition: [baseFilter, columnFilterObject],
+  } as FilterType<T>;
+}

package/sdk/utils/api/index.ts

@@ -0,0 +1,2 @@
+// API utilities
+export * from "./buildListOptions";

package/sdk/utils/error-handling.ts

@@ -0,0 +1,150 @@
+// ============================================================
+// ERROR HANDLING UTILITIES
+// ============================================================
+// Type-safe error handling utilities for the SDK
+
+/**
+ * Safely convert unknown error to Error object
+ * Handles all possible error types that could be thrown
+ */
+export function toError(err: unknown): Error {
+  // Already an Error instance
+  if (err instanceof Error) {
+    return err;
+  }
+
+  // String error
+  if (typeof err === "string") {
+    return new Error(err);
+  }
+
+  // Object with message property
+  if (
+    err !== null &&
+    typeof err === "object" &&
+    "message" in err &&
+    typeof (err as { message: unknown }).message === "string"
+  ) {
+    const error = new Error((err as { message: string }).message);
+    // Preserve any additional properties
+    Object.assign(error, err);
+    return error;
+  }
+
+  // Fallback: convert to string
+  return new Error(String(err));
+}
+
+/**
+ * Type guard to check if a value is an Error
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}
+
+/**
+ * Type guard to check if error has a specific code
+ */
+export function hasErrorCode(
+  err: unknown,
+  code: string
+): err is Error & { code: string } {
+  return (
+    err instanceof Error &&
+    "code" in err &&
+    (err as Error & { code: unknown }).code === code
+  );
+}
+
+/**
+ * Type guard to check if error is a network error
+ */
+export function isNetworkError(err: unknown): boolean {
+  if (!isError(err)) return false;
+
+  const message = err.message.toLowerCase();
+  return (
+    message.includes("network") ||
+    message.includes("fetch") ||
+    message.includes("connection") ||
+    hasErrorCode(err, "NETWORK_ERROR") ||
+    hasErrorCode(err, "ENOTFOUND") ||
+    hasErrorCode(err, "ECONNREFUSED")
+  );
+}
+
+/**
+ * Type guard to check if error is a timeout error
+ */
+export function isTimeoutError(err: unknown): boolean {
+  if (!isError(err)) return false;
+
+  return (
+    err.message.toLowerCase().includes("timeout") ||
+    hasErrorCode(err, "TIMEOUT") ||
+    hasErrorCode(err, "ETIMEDOUT")
+  );
+}
+
+/**
+ * Type guard to check if error is an abort error
+ */
+export function isAbortError(err: unknown): boolean {
+  if (!isError(err)) return false;
+
+  return err.name === "AbortError" || hasErrorCode(err, "ABORT_ERR");
+}
+
+/**
+ * Extract error message from unknown error
+ */
+export function getErrorMessage(err: unknown): string {
+  if (isError(err)) {
+    return err.message;
+  }
+
+  if (typeof err === "string") {
+    return err;
+  }
+
+  if (
+    err !== null &&
+    typeof err === "object" &&
+    "message" in err &&
+    typeof (err as { message: unknown }).message === "string"
+  ) {
+    return (err as { message: string }).message;
+  }
+
+  return String(err);
+}
+
+/**
+ * Safe error handler wrapper for async functions
+ * Returns a tuple of [result, error]
+ */
+export async function tryCatch<T>(
+  fn: () => Promise<T>
+): Promise<[T, null] | [null, Error]> {
+  try {
+    const result = await fn();
+    return [result, null];
+  } catch (err) {
+    return [null, toError(err)];
+  }
+}
+
+/**
+ * Create a wrapped error with original error as cause
+ */
+export function wrapError(message: string, cause: unknown): Error {
+  const error = new Error(message);
+  // Use Object.defineProperty for broader compatibility
+  Object.defineProperty(error, 'cause', {
+    value: toError(cause),
+    writable: true,
+    enumerable: false,
+    configurable: true,
+  });
+  return error;
+}

package/sdk/utils/index.ts

@@ -3,3 +3,9 @@ export * from "./formatting";
 
 // Class name utilities
 export * from "./cn";
+
+// Error handling utilities
+export * from "./error-handling";
+
+// API utilities
+export * from "./api";

package/dist/client-DgtkT50N.cjs

@@ -1 +0,0 @@
-"use strict";let o={baseUrl:"",headers:{"Content-Type":"application/json"}};function u(e){o.baseUrl=e}function h(e){o.headers={...o.headers,...e}}function d(){return{...o.headers}}function l(){return o.baseUrl||""}function i(e){if(e==null)return e;if(Array.isArray(e))return e.map(s=>i(s));if(typeof e=="object"){if("$__dt__"in e)return new Date(e.$__dt__*1e3);if("$__d__"in e)return new Date(e.$__d__);const s={};for(const[n,t]of Object.entries(e))s[n]=i(t);return s}return e}function w(e){const s=o.baseUrl,n=o.headers;return{async get(t){const r=await fetch(`${s}/api/app/${e}/${t}/read`,{method:"GET",headers:n});if(!r.ok)throw new Error(`Failed to get ${e} ${t}: ${r.statusText}`);const a=await r.json();return i(a.Data)},async create(t){const r=await fetch(`${s}/api/app/${e}/create`,{method:"POST",headers:n,body:JSON.stringify(t)});if(!r.ok)throw new Error(`Failed to create ${e}: ${r.statusText}`);return r.json()},async update(t,r){const a=await fetch(`${s}/api/app/${e}/${t}/update`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to update ${e} ${t}: ${a.statusText}`);return a.json()},async delete(t){const r=await fetch(`${s}/api/app/${e}/${t}/delete`,{method:"DELETE",headers:n});if(!r.ok)throw new Error(`Failed to delete ${e} ${t}: ${r.statusText}`);return r.json()},async list(t){const r={Type:"List",...t},a=await fetch(`${s}/api/app/${e}/list`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to list ${e}: ${a.statusText}`);return{Data:(await a.json()).Data.map(f=>i(f))}},async count(t){var p,$;const r={Type:"Metric",GroupBy:[],Metric:[{Field:"_id",Type:"Count"}],...(t==null?void 0:t.Filter)&&{Filter:t.Filter}},a=await fetch(`${s}/api/app/${e}/metric`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to count ${e}: ${a.statusText}`);return{Count:(($=(p=(await a.json()).Data)==null?void 0:p[0])==null?void 0:$.count__id)??0}},async draft(t){const r=await fetch(`${s}/api/app/${e}/draft`,{method:"POST",headers:n,body:JSON.stringify(t)});if(!r.ok)throw new Error(`Failed to create draft for ${e}: ${r.statusText}`);return r.json()},async draftUpdate(t,r){const a=await fetch(`${s}/api/app/${e}/${t}/draft`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to update draft for ${e} ${t}: ${a.statusText}`);return a.json()},async draftPatch(t,r){const a=await fetch(`${s}/api/app/${e}/${t}/draft`,{method:"PATCH",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to patch draft for ${e} ${t}: ${a.statusText}`);return a.json()},async draftInteraction(t){const r=await fetch(`${s}/api/app/${e}/draft`,{method:"PATCH",headers:n,body:JSON.stringify(t)});if(!r.ok)throw new Error(`Failed to create interactive draft for ${e}: ${r.statusText}`);const a=await r.json();return{...a.Data,_id:a.Data._id}},async metric(t){const r={Type:"Metric",...t},a=await fetch(`${s}/api/app/${e}/metric`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to get metrics for ${e}: ${a.statusText}`);return a.json()},async pivot(t){const r={Type:"Pivot",...t},a=await fetch(`${s}/api/app/${e}/pivot`,{method:"POST",headers:n,body:JSON.stringify(r)});if(!a.ok)throw new Error(`Failed to get pivot data for ${e}: ${a.statusText}`);return a.json()},async fields(){const t=await fetch(`${s}/api/app/${e}/fields`,{method:"GET",headers:n});if(!t.ok)throw new Error(`Failed to get fields for ${e}: ${t.statusText}`);return t.json()},async fetchField(t,r){const a=await fetch(`${s}/api/app/${e}/${t}/field/${r}/fetch`,{method:"GET",headers:n});if(!a.ok)throw new Error(`Failed to fetch field ${r} for ${e}: ${a.statusText}`);return(await a.json()).Data}}}exports.api=w;exports.getApiBaseUrl=l;exports.getDefaultHeaders=d;exports.setApiBaseUrl=u;exports.setDefaultHeaders=h;