@ram_28/kf-ai-sdk 1.0.0

package/sdk/types/base-fields.ts

@@ -0,0 +1,221 @@
+/**
+ * Base field type for ID fields
+ * Resolves to: string
+ * Use this for all ID-type fields (user IDs, order IDs, etc.)
+ */
+export type IdField = string;
+
+/**
+ * String field with optional literal type constraint and length limits
+ * @template T - Literal string type (e.g., 'pending' | 'completed')
+ * @template MinLength - Minimum string length (optional)
+ * @template MaxLength - Maximum string length (optional)
+ * Resolves to: T or string
+ * Storage: VARCHAR in database
+ *
+ * @example
+ * StringField // => string
+ * StringField<'active' | 'inactive'> // => 'active' | 'inactive'
+ * StringField<string, 1, 100> // => string with length constraints
+ */
+export type StringField<
+  T extends string = string,
+  _MinLength extends number = never,
+  _MaxLength extends number = never,
+> = T;
+
+/**
+ * Multi-line text field for longer content
+ * Resolves to: string
+ * Storage: TEXT in database
+ * Use this for descriptions, comments, rich text content
+ *
+ * @example
+ * TextAreaField // => string (multi-line)
+ */
+export type TextAreaField = string;
+
+/**
+ * Numeric field with optional precision constraints
+ * @template Precision - Number of decimal places (optional)
+ * Resolves to: number
+ * Storage: DECIMAL/FLOAT in database
+ * Use this for quantities, measurements, calculations
+ *
+ * @example
+ * NumberField // => number
+ * NumberField<2> // => number with 2 decimal places
+ */
+export type NumberField<_Precision extends number = never> = number;
+
+/**
+ * Large integer field for big numbers
+ * Resolves to: number
+ * Storage: BIGINT in database
+ * Use this for large counters, timestamps, file sizes
+ *
+ * @example
+ * LongField // => number (large integer)
+ */
+export type LongField = number;
+
+/**
+ * Boolean field
+ * Resolves to: boolean
+ * Storage: BOOLEAN in database
+ * Use this for true/false values, flags, toggles
+ */
+export type BooleanField = boolean;
+
+/**
+ * Date field (date only, no time)
+ * Resolves to: Date
+ * Storage: DATE in database
+ * Use this for birth dates, due dates, calendar events
+ *
+ * @example
+ * DateField // => Date (date only)
+ */
+export type DateField = Date;
+
+/**
+ * DateTime field (date and time)
+ * Resolves to: Date
+ * Storage: DATETIME/TIMESTAMP in database
+ * Use this for created_at, updated_at, event timestamps
+ *
+ * @example
+ * DateTimeField // => Date (with time)
+ */
+export type DateTimeField = Date;
+
+// ============================================================
+// COMPLEX FIELD TYPES
+// ============================================================
+
+/**
+ * Currency field supporting multiple value formats
+ * Resolves to: CurrencyValue
+ * Storage: JSON/VARCHAR in database
+ * Use this for prices, monetary amounts, financial data
+ *
+ * @example
+ * CurrencyField // => {value: number, currency: string} | string
+ */
+export type CurrencyField = CurrencyValue;
+
+/**
+ * Currency value format - supports both object and string representations
+ */
+export type CurrencyValue =
+  | { value: number; currency: string } // Object format: {value: 100.50, currency: "USD"}
+  | string; // String format: "100.50 USD" or "USD 100.50"
+
+/**
+ * JSON field for structured data
+ * @template T - Expected JSON structure (optional)
+ * Resolves to: T or JSONValue
+ * Storage: JSON/TEXT in database
+ * Use this for configurations, metadata, flexible schemas
+ *
+ * @example
+ * JSONField // => JSONValue (any valid JSON)
+ * JSONField<{settings: {theme: string}}> // => {settings: {theme: string}}
+ */
+export type JSONField<T = JSONValue> = T;
+
+export type ReferenceField = string;
+
+/**
+ * Valid JSON value types
+ */
+export type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONObject
+  | JSONArray;
+
+export interface JSONObject {
+  [key: string]: JSONValue;
+}
+
+export interface JSONArray extends Array<JSONValue> {}
+
+/**
+ * Select field for single choice from predefined options
+ * @template T - Union of allowed option values
+ * Resolves to: T
+ * Storage: VARCHAR in database
+ * Use this for status fields, categories, enum-like values
+ *
+ * @example
+ * SelectField<'active' | 'inactive' | 'pending'> // => 'active' | 'inactive' | 'pending'
+ */
+export type SelectField<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
+ * LookupField // => string (referenced record ID)
+ * LookupField<IdField> // => string (typed as IdField)
+ */
+export type LookupField<T extends string = string> = T;
+
+// ============================================================
+// CONTAINER AND UTILITY TYPES
+// ============================================================
+
+/**
+ * Array field with MultiValue support
+ * @template T - Type of array elements
+ * Resolves to: T[]
+ * Storage: JSON in database
+ * Use this for tags, categories, multiple selections
+ *
+ * @example
+ * ArrayField<string> // => string[]
+ * ArrayField<IdField> // => string[]
+ * ArrayField<SelectField<'tag1' | 'tag2'>> // => ('tag1' | 'tag2')[]
+ */
+export type ArrayField<T> = T[];
+
+/**
+ * Nested object field
+ * @template T - Shape of nested object
+ * Resolves to: T
+ * Storage: JSON in database
+ * Use this for complex nested structures, embedded documents
+ *
+ * @example
+ * ObjectField<{ name: string; age: number }> // => { name: string; age: number }
+ */
+export type ObjectField<T extends Record<string, any>> = T;
+
+/**
+ * Optional field wrapper
+ * @template T - Base field type
+ * Resolves to: T | undefined
+ * Use this for fields that may not have values
+ *
+ * @example
+ * OptionalField<StringField> // => string | undefined
+ * OptionalField<NumberField> // => number | undefined
+ */
+export type OptionalField<T> = T | undefined;
+
+// ============================================================
+// UTILITY TYPES FOR FIELD VALIDATION
+// ============================================================
+
+/**
+ * Utility type to extract the base type from a field type
+ * Useful for runtime validation and type guards
+ */
+export type ExtractFieldType<T> = T extends OptionalField<infer U> ? U : T;

package/sdk/types/common.ts

@@ -0,0 +1,306 @@
+/**
+ * Sort direction for API queries (matching API spec)
+ */
+export type SortDirection = "ASC" | "DESC";
+
+/**
+ * Sort configuration: array of field-direction mappings
+ * Format: [{ "fieldName": "ASC" }, { "anotherField": "DESC" }]
+ */
+export type SortOption = Record<string, SortDirection>;
+
+/**
+ * Sort configuration: array of sort options
+ */
+export type Sort = SortOption[];
+
+/**
+ * Filter operators for individual conditions (leaf nodes)
+ */
+export type FilterOperator =
+  | "EQ" | "NE" | "GT" | "GTE" | "LT" | "LTE"
+  | "Between" | "NotBetween" | "IN" | "NIN"
+  | "Empty" | "NotEmpty" | "Contains" | "NotContains"
+  | "MinLength" | "MaxLength";
+
+/**
+ * Logical operators for combining filter conditions (tree nodes)
+ */
+export type LogicalOperator = "And" | "Or" | "Not";
+
+/**
+ * RHS value type for filter conditions
+ */
+export type FilterRHSType = "Constant" | "BOField" | "AppVariable";
+
+/**
+ * Base interface for all filter nodes
+ */
+interface FilterNodeBase {
+  /** Operator type */
+  Operator: FilterOperator | LogicalOperator;
+}
+
+/**
+ * Leaf filter condition (actual field comparison)
+ */
+export interface FilterCondition extends FilterNodeBase {
+  /** Condition operator */
+  Operator: FilterOperator;
+  /** Left-hand side field name */
+  LHSField: string;
+  /** Right-hand side value */
+  RHSValue: any;
+  /** Right-hand side type (optional, defaults to Constant) */
+  RHSType?: FilterRHSType;
+}
+
+/**
+ * Logical filter node (combines multiple conditions)
+ */
+export interface FilterLogical extends FilterNodeBase {
+  /** Logical operator */
+  Operator: LogicalOperator;
+  /** Nested conditions (can be FilterCondition or FilterLogical) */
+  Condition: Array<FilterCondition | FilterLogical>;
+}
+
+/**
+ * Filter structure matching API specification (root level)
+ * This is a discriminated union - a filter is either a logical node or a condition
+ */
+export type Filter = FilterLogical;
+
+/**
+ * Convenience type for any filter node (leaf or logical)
+ */
+export type FilterNode = FilterCondition | FilterLogical;
+
+/**
+ * DateTime encoding format used by the API
+ */
+export interface DateTimeEncoded {
+  $__dt__: number;
+}
+
+/**
+ * Date encoding format used by the API  
+ */
+export interface DateEncoded {
+  $__d__: string;
+}
+
+/**
+ * Standard paginated list response
+ * @template T - Type of items in the list
+ */
+export interface ListResponse<T> {
+  /** Array of items for current page */
+  Data: T[];
+}
+
+/**
+ * Read API response wrapper
+ * @template T - Type of the data object
+ */
+export interface ReadResponse<T> {
+  /** The data object */
+  Data: T;
+}
+
+/**
+ * Create/Update API response
+ */
+export interface CreateUpdateResponse {
+  /** ID of the created/updated record */
+  _id: string;
+}
+
+/**
+ * Delete API response
+ */
+export interface DeleteResponse {
+  /** Status of the delete operation */
+  status: "success";
+}
+
+/**
+ * Count API response
+ */
+export interface CountResponse {
+  /** Total count of matching records */
+  Count: number;
+}
+
+/**
+ * Options for list queries (API request format)
+ */
+export interface ListOptions {
+  /** Query type (defaults to "List") */
+  Type?: "List";
+
+  /** Specific fields to return */
+  Field?: string[];
+
+  /** Filter criteria */
+  Filter?: Filter;
+
+  /** Sort configuration */
+  Sort?: Sort;
+
+  /** Search query (separate from filters) */
+  Search?: string;
+
+  /** Page number (1-indexed) */
+  Page?: number;
+
+  /** Records per page */
+  PageSize?: number;
+}
+
+// ============================================================
+// METRIC/AGGREGATE TYPES
+// ============================================================
+
+/**
+ * Metric aggregation function types
+ */
+export type MetricType =
+  | "Sum"
+  | "Avg"
+  | "Count"
+  | "Max"
+  | "Min"
+  | "DistinctCount"
+  | "BlankCount"
+  | "NotBlankCount"
+  | "Concat"
+  | "DistinctConcat";
+
+/**
+ * Metric field configuration
+ */
+export interface MetricField {
+  /** Field to aggregate */
+  Field: string;
+  /** Aggregation function type */
+  Type: MetricType;
+}
+
+/**
+ * Options for metric/aggregate queries
+ */
+export interface MetricOptions {
+  /** Query type (always "Metric") */
+  Type: "Metric";
+  /** Fields to group by */
+  GroupBy: string[];
+  /** Metric definitions */
+  Metric: MetricField[];
+  /** Optional filter criteria */
+  Filter?: Filter;
+}
+
+/**
+ * Response from metric endpoint
+ */
+export interface MetricResponse {
+  /** Aggregated data rows */
+  Data: Record<string, any>[];
+}
+
+// ============================================================
+// PIVOT TYPES
+// ============================================================
+
+/**
+ * Pivot table header item (hierarchical)
+ */
+export interface PivotHeaderItem {
+  /** Header key/label */
+  Key: string;
+  /** Child headers for nested grouping */
+  Children?: PivotHeaderItem[] | null;
+}
+
+/**
+ * Pivot response data structure
+ */
+export interface PivotResponseData {
+  /** Row headers */
+  RowHeader: PivotHeaderItem[];
+  /** Column headers */
+  ColumnHeader: PivotHeaderItem[];
+  /** Value matrix [row][column] */
+  Value: (number | string | null)[][];
+}
+
+/**
+ * Options for pivot queries
+ */
+export interface PivotOptions {
+  /** Query type (always "Pivot") */
+  Type: "Pivot";
+  /** Row dimension fields */
+  Row: string[];
+  /** Column dimension fields */
+  Column: string[];
+  /** Metric definitions */
+  Metric: MetricField[];
+  /** Optional filter criteria */
+  Filter?: Filter;
+}
+
+/**
+ * Response from pivot endpoint
+ */
+export interface PivotResponse {
+  /** Pivot data including headers and values */
+  Data: PivotResponseData;
+}
+
+// ============================================================
+// DRAFT/INTERACTIVE TYPES
+// ============================================================
+
+/**
+ * Response from draft operations
+ */
+export interface DraftResponse {
+  /** Computed field values */
+  [fieldName: string]: any;
+}
+
+// ============================================================
+// FIELDS METADATA TYPES
+// ============================================================
+
+/**
+ * Response from fields endpoint
+ */
+export interface FieldsResponse {
+  /** Field metadata */
+  Data: Record<string, any>[];
+}
+
+// ============================================================
+// FETCH FIELD TYPES
+// ============================================================
+
+/**
+ * Single option returned from fetch field endpoint
+ */
+export interface FetchFieldOption {
+  /** The value to be stored */
+  Value: string;
+  /** The display label */
+  Label: string;
+}
+
+/**
+ * Response from fetch field endpoint
+ */
+export interface FetchFieldResponse {
+  /** Array of field options */
+  Data: FetchFieldOption[];
+}

package/sdk/types/index.ts

@@ -0,0 +1,5 @@
+// Base field types
+export * from './base-fields';
+
+// Common API types
+export * from './common';

package/sdk/utils/cn.ts

@@ -0,0 +1,10 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Utility for merging Tailwind CSS classes
+ * Combines clsx for conditional classes and tailwind-merge for deduplication
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}