@ram_28/kf-ai-sdk 1.0.23 → 1.0.25

package/docs/QUICK_REFERENCE.md

@@ -230,6 +230,30 @@ function ProtectedRoute({ children }) {
 
 ---
 
+## Date Handling
+
+### Display Encoded Date
+```typescript
+import { decodeDate } from "@ram_28/kf-ai-sdk/api";
+import { formatDate } from "@ram_28/kf-ai-sdk/utils";
+
+const readable = formatDate(decodeDate(record.OrderDate), 'medium');
+// => "Mar 15, 2025"
+```
+
+### Display Timestamp
+```typescript
+import { decodeDateTime } from "@ram_28/kf-ai-sdk/api";
+import { formatDateTime } from "@ram_28/kf-ai-sdk/utils";
+
+const readable = formatDateTime(decodeDateTime(record._created_at), 'medium');
+// => "Mar 15, 2025, 10:30:45 AM"
+```
+
+[Full Documentation](./datetime.md)
+
+---
+
 ## Type Imports
 
 ```typescript

package/docs/api.md

@@ -5,10 +5,11 @@ Direct API methods for CRUD operations, drafts, metrics, and metadata.
 ## Setup
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 ```
@@ -200,10 +201,11 @@ const response = await product.list(options?: ListOptionsType): Promise<ListResp
 **Example:** Fetch paginated products with filter
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -244,10 +246,11 @@ const record = await product.get(id: string): Promise<T>
 **Example:** Fetch single product
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -271,10 +274,11 @@ const response = await product.create(data: Partial<T>): Promise<CreateUpdateRes
 **Example:** Create new product
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -302,10 +306,11 @@ const response = await product.update(id: string, data: Partial<T>): Promise<Cre
 **Example:** Update product price
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -330,10 +335,11 @@ const response = await product.delete(id: string): Promise<DeleteResponseType>
 **Example:** Delete product
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -357,10 +363,11 @@ const response = await product.draft(data: Partial<T>): Promise<DraftResponseTyp
 **Example:** Preview computed discount
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -387,10 +394,11 @@ const response = await product.draftPatch(id: string, data: Partial<T>): Promise
 **Example:** Update draft during editing
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -417,10 +425,11 @@ const response = await product.metric(options: MetricOptionsType): Promise<Metri
 **Example 1:** Total count
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -436,10 +445,11 @@ console.log("Total products:", response.Data[0]["count__id"]);
 **Example 2:** Sum with filter (low stock count)
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -466,10 +476,11 @@ console.log("Low stock products:", response.Data[0]["count__id"]);
 **Example 3:** Group by field (products by category)
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -491,10 +502,11 @@ response.Data.forEach((row) => {
 **Example 4:** Multiple metrics (stock sum and average by category)
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -528,10 +540,11 @@ const response = await product.pivot(options: PivotOptionsType): Promise<PivotRe
 **Example:** Sales pivot by region and quarter
 
 ```typescript
-import { Order, OrderType } from "../sources";
+import { Order } from "../sources";
+import type { OrderForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type AdminOrder = OrderType<typeof Roles.Admin>;
+type AdminOrder = OrderForRole<typeof Roles.Admin>;
 
 const order = new Order(Roles.Admin);
 
@@ -587,10 +600,11 @@ const response = await product.fields(): Promise<FieldsResponseType>
 **Example:** Get field metadata
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 
@@ -625,10 +639,11 @@ const options = await product.fetchField(instanceId: string, fieldId: keyof T):
 **Example:** Fetch supplier options for dropdown
 
 ```typescript
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 const product = new Product(Roles.Buyer);
 

package/docs/datetime.md

@@ -0,0 +1,144 @@
+# Date & DateTime Handling
+
+Working with Date and DateTime fields in the SDK.
+
+## API Response Format
+
+The backend returns dates in encoded format:
+- **Date**: `{ "$__d__": "YYYY-MM-DD" }`
+- **DateTime**: `{ "$__dt__": unix_timestamp_seconds }`
+
+## Imports
+
+```typescript
+// Decoding & formatting for API
+import {
+  decodeDate,
+  decodeDateTime,
+  formatDate,
+  formatDateTime,
+  parseDate,
+  parseDateTime,
+} from "@ram_28/kf-ai-sdk/api";
+
+// UI display formatting
+import {
+  formatDate,
+  formatDateTime
+} from "@ram_28/kf-ai-sdk/utils";
+```
+
+## Decoding API Responses
+
+Convert encoded dates to JavaScript Date objects.
+
+### decodeDate
+```typescript
+const apiResponse = { "$__d__": "2025-03-15" };
+const date = decodeDate(apiResponse);
+// => Date object for March 15, 2025
+```
+
+### decodeDateTime
+```typescript
+const apiResponse = { "$__dt__": 1769110463 };
+const date = decodeDateTime(apiResponse);
+// => Date object with full timestamp
+```
+
+## Formatting for API Requests
+
+Convert Date objects to strings the API expects.
+
+### formatDate (API)
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/api";
+
+const date = new Date(2025, 2, 15);
+formatDate(date); // => "2025-03-15"
+```
+
+### formatDateTime (API)
+```typescript
+import { formatDateTime } from "@ram_28/kf-ai-sdk/api";
+
+const date = new Date(2025, 2, 15, 10, 30, 45);
+formatDateTime(date); // => "2025-03-15 10:30:45"
+```
+
+## Formatting for UI Display
+
+Convert Date objects to human-readable strings.
+
+### formatDate (UI)
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/utils";
+
+const date = new Date(2025, 2, 15);
+formatDate(date, 'short');  // => "3/15/25"
+formatDate(date, 'medium'); // => "Mar 15, 2025"
+formatDate(date, 'long');   // => "March 15, 2025"
+```
+
+### formatDateTime (UI)
+```typescript
+import { formatDateTime } from "@ram_28/kf-ai-sdk/utils";
+
+const date = new Date(2025, 2, 15, 10, 30, 45);
+formatDateTime(date, 'short');  // => "3/15/25, 10:30 AM"
+formatDateTime(date, 'medium'); // => "Mar 15, 2025, 10:30:45 AM"
+formatDateTime(date, 'long');   // => "March 15, 2025 at 10:30:45 AM"
+```
+
+## Common Patterns
+
+### Display a date from API response
+```typescript
+import { decodeDate } from "@ram_28/kf-ai-sdk/api";
+import { formatDate } from "@ram_28/kf-ai-sdk/utils";
+
+function displayDate(encodedDate: { $__d__: string }) {
+  const date = decodeDate(encodedDate);
+  return formatDate(date, 'medium');
+}
+
+// Usage in component
+<span>{displayDate(record.OrderDate)}</span>
+```
+
+### Display created/modified timestamps
+```typescript
+import { decodeDateTime } from "@ram_28/kf-ai-sdk/api";
+import { formatDateTime } from "@ram_28/kf-ai-sdk/utils";
+
+function displayTimestamp(encodedDateTime: { $__dt__: number }) {
+  const date = decodeDateTime(encodedDateTime);
+  return formatDateTime(date, 'medium');
+}
+
+// Usage
+<span>Created: {displayTimestamp(record._created_at)}</span>
+<span>Modified: {displayTimestamp(record._modified_at)}</span>
+```
+
+### Submit a date to the API
+```typescript
+import { formatDate } from "@ram_28/kf-ai-sdk/api";
+
+// From a date picker value
+const datePickerValue = "2025-03-15"; // HTML date input value
+// Already in correct format, use directly
+
+// From a Date object
+const dateObj = new Date();
+const apiValue = formatDate(dateObj); // => "2025-03-15"
+```
+
+## Type Definitions
+
+```typescript
+import type {
+  DateEncodedType,      // { $__d__: string }
+  DateTimeEncodedType,  // { $__dt__: number }
+} from "@ram_28/kf-ai-sdk/api";
+```

package/docs/useFilter.md

@@ -173,10 +173,11 @@ Use the generic type parameter to get TypeScript validation on field names.
 
 ```tsx
 import { useFilter } from "@ram_28/kf-ai-sdk/filter";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function TypeSafeFilter() {
   // Pass the type parameter for type-safe LHSField
@@ -216,10 +217,11 @@ function TypeSafeFilter() {
 ```tsx
 import { useFilter } from "@ram_28/kf-ai-sdk/filter";
 import type { UseFilterOptionsType } from "@ram_28/kf-ai-sdk/filter/types";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 // Type-safe filter options
 const initialFilter: UseFilterOptionsType<BuyerProduct> = {

package/docs/useForm.md

@@ -227,10 +227,11 @@ interface FormFieldConfigType {
 
 ```tsx
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function CreateProductForm() {
   const product = new Product(Roles.Buyer);
@@ -283,10 +284,11 @@ Create form with validation and success handling.
 import { useForm } from "@ram_28/kf-ai-sdk/form";
 import type { FieldErrors } from "@ram_28/kf-ai-sdk/form/types";
 import { useNavigate } from "react-router-dom";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function ProductListingForm() {
   const product = new Product(Roles.Buyer);
@@ -362,10 +364,11 @@ Update mode with record loading state.
 
 ```tsx
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function EditProductForm({ productId }: { productId: string }) {
   const product = new Product(Roles.Buyer);
@@ -428,10 +431,11 @@ Working with computed fields and the watch function.
 
 ```tsx
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function PricingForm() {
   const product = new Product(Roles.Buyer);
@@ -483,10 +487,11 @@ Static fields return options with `Value` and `Label`.
 ```tsx
 import { useState } from "react";
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function ProductCategoryForm({ recordId }: { recordId: string }) {
   const product = new Product(Roles.Buyer);
@@ -558,10 +563,11 @@ Reference fields return the full object structure. Use a custom dropdown to disp
 ```tsx
 import { useState } from "react";
 import { useForm } from "@ram_28/kf-ai-sdk/form";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 type SupplierOption = {
   _id: string;

package/docs/useTable.md

@@ -221,10 +221,11 @@ A minimal table displaying data with loading and error states.
 ```tsx
 import { useTable } from "@ram_28/kf-ai-sdk/table";
 import type { ColumnDefinitionType } from "@ram_28/kf-ai-sdk/table/types";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function ProductsTable() {
   const product = new Product(Roles.Buyer);
@@ -282,10 +283,11 @@ import type {
   UseTableReturnType,
   ColumnDefinitionType,
 } from "@ram_28/kf-ai-sdk/table/types";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function MyItemsTable() {
   const product = new Product(Roles.Buyer);
@@ -858,10 +860,11 @@ import type {
   UseTableReturnType,
   ColumnDefinitionType,
 } from "@ram_28/kf-ai-sdk/table/types";
-import { Product, ProductType } from "../sources";
+import { Product } from "../sources";
+import type { ProductForRole } from "../sources";
 import { Roles } from "../sources/roles";
 
-type BuyerProduct = ProductType<typeof Roles.Buyer>;
+type BuyerProduct = ProductForRole<typeof Roles.Buyer>;
 
 function ProductListPage() {
   const product = new Product(Roles.Buyer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ram_28/kf-ai-sdk",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Type-safe, AI-driven SDK for building modern web applications with role-based access control",
   "author": "Ramprasad",
   "license": "MIT",