@smartsides/oracle-ebs-sdk 1.0.7 → 1.0.10

package/README.md

@@ -5,7 +5,8 @@ TypeScript SDK for Oracle EBS API - Optimized for Next.js 15+
 ## Features
 
 - ✅ **Full TypeScript Support** - Complete type safety with autocomplete
-- ✅ **All API Endpoints** - 9 modules covering all Oracle EBS functionality
+- ✅ **All API Endpoints** - 10 modules covering all Oracle EBS functionality
+- ✅ **AI Assistant** - ChatGPT-style chat with voice support ⭐ NEW
 - ✅ **Auto User Context** - Stores full user object from login automatically
 - ✅ **Smart Defaults** - Employee number auto-extracted for payslip/leave requests
 - ✅ **Error Handling** - Typed errors with automatic retry logic
@@ -178,22 +179,67 @@ const preview = await client.sitRequests.saveAndPreview(data);
 const result = await client.sitRequests.submit(data);
 ```
 
+### Segments
+
+```typescript
+// Get SIT segments metadata
+const segments = await client.segments.getSitSegments({ 
+  idFlexNum: '50496' 
+});
+
+// Returns array of segment metadata:
+// - segmentNumber, segmentName, segmentPrompt
+// - applicationColumnName, requiredFlag
+// - defaultValue, valueSetName, validationType
+// - enabledFlag, displayedFlag, executionStatus
+```
+
+
 ### Notifications
 
 ```typescript
-// Get notifications
+// Get notification list (USER_ID auto-extracted from login)
 const notifications = await client.notifications.getList();
 
-// Get details
-const details = await client.notifications.getDetails({ notificationId: '123' });
+// Get notification details
+const details = await client.notifications.getDetails({ 
+  notificationId: '9341634' 
+});
 
-// Process approval
+// Get all details (SSHR_SIT_REQDTLS)
+const allDetails = await client.notifications.getAllDetails({
+  notificationId: '9288875',
+  itemKey: '756840',
+  analysisCriteriaId: '3643761',
+  idFlexNum: '50310'
+});
+
+// Get absence details (for FYI notifications)
+const absenceDetails = await client.notifications.getAbsenceDetails({
+  itemKey: '760206'
+});
+
+// Get action history
+const history = await client.notifications.getActionHistory({
+  notificationId: '9330566'
+});
+
+// Process approval (APPROVE or DECLINE)
 await client.notifications.processApproval({
-  notificationId: '123',
+  notificationId: '9341634',
   action: 'APPROVE',
+  comments: 'Approved for processing',
+  responderUserName: 'optional'
+});
+
+// Close FYI notification (USER_ID auto-extracted)
+await client.notifications.closeFyi({
+  notificationId: '9336582'
 });
 ```
 
+**Auto User ID**: Notification methods automatically use USER_ID from the logged-in user where needed.
+
 ### Payslip
 
 ```typescript
@@ -264,6 +310,101 @@ const health = await client.health.check();
 const message = await client.health.ping();
 ```
 
+### AI Assistant 🆕
+
+The AI module provides ChatGPT-style conversational AI with persistent chat history.
+
+```typescript
+import { MessageRole } from '@smartsides/oracle-ebs-sdk';
+
+// Send a chat message
+const response = await client.ai.sendMessage({
+  message: 'Show my latest payslip',
+  language: 'en',
+  history: [
+    { role: MessageRole.USER, content: 'Hello' },
+    { role: MessageRole.ASSISTANT, content: 'Hi! How can I help?' }
+  ],
+  threadId: 'optional-thread-id' // For continuing existing conversation
+});
+
+// Response includes:
+// - message: AI response text
+// - ctas: Call-to-action buttons (if any)
+// - metadata: Intent, tokens used, etc.
+// - threadId: Thread ID for conversation persistence
+
+// Voice message with thread continuity ⭐ NEW
+// First voice message - creates new thread
+const voiceResponse1 = await client.ai.sendVoice(audioBlob, {
+  language: 'en'
+});
+const threadId = voiceResponse1.response.threadId;
+
+// Second voice message - continues same thread
+const voiceResponse2 = await client.ai.sendVoice(audioBlob, {
+  language: 'en',
+  threadId: threadId  // Maintains conversation context!
+});
+
+// Arabic voice with thread continuity
+const arabicResponse = await client.ai.sendVoice(audioBlob, {
+  language: 'ar',
+  threadId: threadId  // Works with Arabic too!
+});
+
+// Thread management
+const threads = await client.ai.getChatThreads();
+const messages = await client.ai.getThreadMessages(threadId);
+await client.ai.deleteThread(threadId);
+```
+
+**Voice Thread Continuity Benefits:**
+- ✅ Multi-turn voice conversations (request → confirmation → submission)
+- ✅ Maintains full conversation context across voice messages
+- ✅ Works with both English and Arabic
+- ✅ Automatic leave type mapping and date extraction
+- ✅ Seamless voice-based leave request submission
+
+// Transcribe voice to text
+const transcription = await client.ai.transcribeVoice(audioBlob);
+
+// Get all chat threads for current user
+const threads = await client.ai.getChatThreads();
+// Returns: Array of ChatThread objects with id, title, messageCount, etc.
+
+// Get messages for a specific thread
+const { thread, messages } = await client.ai.getThreadMessages(threadId);
+// Returns: Thread metadata + array of ThreadMessage objects
+
+// Create a new chat thread
+const newThread = await client.ai.createThread();
+// Returns: ChatThread object with new thread ID
+
+// Delete a chat thread
+await client.ai.deleteThread(threadId);
+// Deletes thread and all associated messages
+```
+
+**Chat History Features:**
+- ✅ **Persistent Threads**: All conversations saved to PostgreSQL
+- ✅ **Auto-Title Generation**: Thread titles generated from first message
+- ✅ **Message History**: Complete conversation history with timestamps
+- ✅ **User-Scoped**: Each user only sees their own threads
+- ✅ **Secure**: JWT authentication + ownership validation
+
+**Available Types:**
+```typescript
+import {
+  MessageRole,      // USER | ASSISTANT
+  ActionType,       // Enum for action types
+  UserIntent,       // Enum for user intents
+  ChatThread,       // Thread metadata type
+  ThreadMessage,    // Message type
+  CallToAction,     // CTA button type
+} from '@smartsides/oracle-ebs-sdk';
+```
+
 ## Error Handling
 
 ```typescript
@@ -311,6 +452,69 @@ const client = new OracleEBSClient({
 });
 ```
 
+## 🔒 Security Best Practices
+
+### CRITICAL: Never Decode JWT Tokens
+
+**❌ NEVER do this in your application:**
+
+```typescript
+// DON'T decode JWT on the client side
+const token = localStorage.getItem('token');
+const payload = JSON.parse(atob(token.split('.')[1]));
+const employeeNumber = payload.EMPLOYEE_NUMBER;
+
+// DON'T pass user context to SDK methods
+await client.payslip.getHeader({ periodName, employeeNumber });
+```
+
+**✅ ALWAYS do this instead:**
+
+```typescript
+// Just set the token and pass business parameters
+client.setToken(token);
+await client.payslip.getHeader({ periodName });
+// Backend extracts employeeNumber from JWT automatically
+```
+
+### Why This Matters
+
+1. **Security**: JWT payload is base64 encoded, NOT encrypted - anyone can read it
+2. **Single Source of Truth**: Backend validates and extracts user context
+3. **Prevents Tampering**: Users cannot access other users' data
+4. **Maintainability**: JWT structure changes don't affect your code
+5. **Consistency**: All endpoints follow the same pattern
+
+### How It Works
+
+The SDK sends the JWT token in the Authorization header. The backend:
+1. Validates the token signature
+2. Checks token expiration
+3. Extracts user context (employeeNumber, userId, personId, etc.)
+4. Uses this context to fetch user-specific data
+
+### Affected Methods
+
+All user-specific methods automatically use JWT context:
+- ✅ `payslip.getHeader()` - Uses EMPLOYEE_NUMBER from JWT
+- ✅ `payslip.getDetails()` - Uses EMPLOYEE_NUMBER from JWT
+- ✅ `leaves.getRestrictedTypes()` - Uses USER_ID, PERSON_ID from JWT
+- ✅ `leaves.createRequest()` - Uses PERSON_ID, USER_ID from JWT
+- ✅ `notifications.getList()` - Uses USER_ID from JWT
+- ✅ `notifications.closeFyi()` - Uses USER_ID from JWT
+- ✅ `employee.getPersonalInfo()` - Uses context from JWT
+- ✅ `accrualBalances.getBalances()` - Uses context from JWT
+
+**You only pass business parameters** (periodName, dates, etc.) - never user context.
+
+### Reference
+
+For complete security documentation, see:
+- [Backend JWT Security Pattern](../docs/JWT_SECURITY_PATTERN.md)
+- [Backend Documentation](../docs/index.md#-core-security-principles)
+
+---
+
 ## React Query Hooks
 
 All hooks are available from `@smartsides/oracle-ebs-sdk/hooks`:

package/dist/{OracleEBSClient-C2zQ1MaD.d.mts → OracleEBSClient-DFGpQFfQ.d.mts}

@@ -173,16 +173,16 @@ declare class LeavesModule extends BaseClient {
     createRequest(input: CreateLeaveRequestInput): Promise<CreateLeaveRequestResponse>;
 }
 
-interface SitSegment {
+interface SitSegment$1 {
     segmentName: string;
     segmentValue: string;
     displayValue?: string;
 }
-interface GetSitSegmentsParams {
+interface GetSitSegmentsParams$1 {
     idFlexNum: string;
 }
-interface GetSitSegmentsResponse {
-    segments: SitSegment[];
+interface GetSitSegmentsResponse$1 {
+    segments: SitSegment$1[];
 }
 interface SaveAndPreviewSitRequestInput {
     itemType: string;
@@ -216,6 +216,8 @@ interface SubmitSitRequestResponse {
     itemKey: string;
 }
 interface GetSitHistoryParams {
+    sitName: string;
+    transactionId?: string;
     startDate?: string;
     endDate?: string;
 }
@@ -231,10 +233,10 @@ interface GetSitHistoryResponse {
 }
 
 declare class SitRequestsModule extends BaseClient {
-    getSegments(params: GetSitSegmentsParams): Promise<GetSitSegmentsResponse>;
+    getSegments(params: GetSitSegmentsParams$1): Promise<GetSitSegmentsResponse$1>;
     saveAndPreview(input: SaveAndPreviewSitRequestInput): Promise<SaveAndPreviewSitRequestResponse>;
     submit(input: SubmitSitRequestInput): Promise<SubmitSitRequestResponse>;
-    getHistory(params?: GetSitHistoryParams): Promise<GetSitHistoryResponse>;
+    getHistory(params: GetSitHistoryParams): Promise<GetSitHistoryResponse>;
 }
 
 interface Notification {
@@ -448,7 +450,6 @@ interface GetPayslipRunBalancesResponse {
 }
 
 declare class PayslipModule extends BaseClient {
-    private getEmployeeNumberFromContext;
     getHeader(params: GetPayslipHeaderParams): Promise<PayslipHeader>;
     getDetails(params: GetPayslipDetailsParams): Promise<GetPayslipDetailsResponse>;
     getLeaveDetails(params: GetPayslipLeaveDetailsParams): Promise<GetPayslipLeaveDetailsResponse>;
@@ -559,6 +560,169 @@ declare class HealthModule extends BaseClient {
     ping(): Promise<string>;
 }
 
+declare enum MessageRole {
+    USER = "user",
+    ASSISTANT = "assistant",
+    SYSTEM = "system"
+}
+declare enum ActionType {
+    NAVIGATE = "navigate",
+    API_CALL = "api_call",
+    DOWNLOAD = "download",
+    CLOSE_NOTIFICATION = "close_notification",
+    SUBMIT_LEAVE = "submit_leave",
+    APPROVE_NOTIFICATION = "approve_notification",
+    DECLINE_NOTIFICATION = "decline_notification"
+}
+declare enum UserIntent {
+    NOTIFICATIONS_SUMMARY = "notifications_summary",
+    NOTIFICATION_CLOSE = "notification_close",
+    NOTIFICATION_ACTION = "notification_action",
+    PAYSLIP_QUERY = "payslip_query",
+    PAYSLIP_RETRIEVAL = "payslip_retrieval",
+    SALARY_DEDUCTION = "salary_deduction",
+    LEAVE_BALANCE = "leave_balance",
+    LEAVE_REQUEST = "leave_request",
+    PROFILE_INFO = "profile_info",
+    HIRING_DATE = "hiring_date",
+    POSITION_INFO = "position_info",
+    GENERAL_QUERY = "general_query",
+    OUT_OF_SCOPE = "out_of_scope"
+}
+interface ChatMessage {
+    role: MessageRole;
+    content: string;
+}
+interface CallToAction {
+    id: string;
+    label: string;
+    type: ActionType;
+    params?: Record<string, any>;
+    path?: string;
+    icon?: string;
+    variant?: 'default' | 'outline' | 'ghost' | 'destructive';
+}
+interface AiResponse {
+    message: string;
+    ctas?: CallToAction[];
+    metadata?: {
+        intent?: UserIntent;
+        model?: string;
+        tokensUsed?: number;
+        [key: string]: any;
+    };
+    requiresAction?: boolean;
+    chartData?: any;
+    threadId?: string;
+}
+interface ChatRequest {
+    message: string;
+    language?: 'en' | 'ar';
+    history?: ChatMessage[];
+    threadId?: string;
+}
+interface VoiceTranscription {
+    text: string;
+    language: string;
+    confidence?: number;
+    duration?: number;
+}
+interface VoiceResponse {
+    transcription: VoiceTranscription;
+    response: AiResponse;
+}
+interface ChatHistory {
+    id: string;
+    messages: Array<ChatMessage & {
+        timestamp: Date;
+    }>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface ChatThread {
+    id: string;
+    userId: string;
+    username: string;
+    title: string | null;
+    status: string;
+    intent: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    lastMessageAt: Date;
+    messageCount: number;
+}
+interface ThreadMessage {
+    id: string;
+    threadId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    metadata?: {
+        intent?: string;
+        ctas?: CallToAction[];
+        tokensUsed?: number;
+        [key: string]: any;
+    };
+    createdAt: Date;
+}
+interface GetThreadMessagesResponse {
+    thread: ChatThread;
+    messages: ThreadMessage[];
+}
+interface GetThreadsResponse {
+    threads: ChatThread[];
+}
+interface CreateThreadResponse {
+    thread: ChatThread;
+}
+interface DeleteThreadResponse {
+    success: boolean;
+    message: string;
+}
+
+declare class AiModule extends BaseClient {
+    sendMessage(request: ChatRequest): Promise<AiResponse>;
+    sendVoice(audioBlob: Blob, options?: {
+        language?: 'en' | 'ar';
+        threadId?: string;
+    }): Promise<VoiceResponse>;
+    saveChatMessage(message: ChatMessage): void;
+    getLocalChatHistory(): Array<ChatMessage & {
+        timestamp: Date;
+    }>;
+    clearChatHistory(): void;
+    getChatThreads(): Promise<ChatThread[]>;
+    getThreadMessages(threadId: string): Promise<GetThreadMessagesResponse>;
+    createThread(): Promise<ChatThread>;
+    deleteThread(threadId: string): Promise<void>;
+}
+
+interface GetSitSegmentsParams {
+    idFlexNum: string;
+}
+interface SitSegment {
+    segmentNumber?: string;
+    segmentName?: string;
+    segmentPrompt?: string;
+    applicationColumnName?: string;
+    requiredFlag?: string;
+    defaultType?: string;
+    originalDefaultValue?: string;
+    executedDefaultValue?: string;
+    valueSetId?: string;
+    flexValueSetName?: string;
+    validationType?: string;
+    enabledFlag?: string;
+    displayedFlag?: string;
+    updatableFlag?: string;
+    insertableFlag?: string;
+    executionStatus?: string;
+}
+type GetSitSegmentsResponse = SitSegment[];
+
+declare class SegmentsModule extends BaseClient {
+    getSitSegments(params: GetSitSegmentsParams): Promise<GetSitSegmentsResponse>;
+}
+
 declare class OracleEBSClient {
     readonly auth: AuthModule;
     readonly leaves: LeavesModule;
@@ -569,6 +733,8 @@ declare class OracleEBSClient {
     readonly accrualBalances: AccrualBalancesModule;
     readonly forms: FormsModule;
     readonly health: HealthModule;
+    readonly ai: AiModule;
+    readonly segments: SegmentsModule;
     constructor(config: OracleEBSConfig);
     setToken(token: string, user?: {
         userName?: string;
@@ -581,4 +747,4 @@ declare class OracleEBSClient {
     clearToken(): void;
 }
 
-export { type APIResponse as A, type GetPayslipDetailsParams as B, type CacheOptions as C, type PayslipDetail as D, type GetPayslipDetailsResponse as E, type PersonalInformation as F, type GetAbsenceTypesParams as G, type EmployeeHierarchyNode as H, type GetEmployeeHierarchyResponse as I, type GetTableColumnsParams as J, type GetTableColumnsResponse as K, type LoginCredentials as L, type DffSegment as M, type Notification as N, OracleEBSClient as O, type ProcessApprovalInput as P, type GetDffSegmentsParams as Q, type RetryOptions as R, type SitSegment as S, type TableColumn as T, type UserContext as U, type GetDffSegmentsResponse as V, type HealthCheckResponse as W, type AccrualBalance as X, type GetAccrualBalancesParams as Y, type GetAccrualBalancesResponse as Z, type OracleEBSConfig as a, type LoginResponse as b, type Responsibility as c, type AbsenceType as d, type GetAbsenceTypesResponse as e, type LeaveHistoryRecord as f, type GetLeaveHistoryResponse as g, type CreateLeaveRequestInput as h, type CreateLeaveRequestResponse as i, type GetSitSegmentsParams as j, type GetSitSegmentsResponse as k, type SaveAndPreviewSitRequestInput as l, type SaveAndPreviewSitRequestResponse as m, type SubmitSitRequestInput as n, type SubmitSitRequestResponse as o, type GetSitHistoryParams as p, type SitHistoryRecord as q, type GetSitHistoryResponse as r, type GetNotificationsResponse as s, type NotificationDetails as t, type GetNotificationDetailsParams as u, type ProcessApprovalResponse as v, type CloseFyiParams as w, type CloseFyiResponse as x, type GetPayslipHeaderParams as y, type PayslipHeader as z };
+export { type GetAccrualBalancesParams as $, type APIResponse as A, type CloseFyiResponse as B, type CacheOptions as C, type GetPayslipHeaderParams as D, type PayslipHeader as E, type GetPayslipDetailsParams as F, type GetAbsenceTypesParams as G, type PayslipDetail as H, type GetPayslipDetailsResponse as I, type PersonalInformation as J, type EmployeeHierarchyNode as K, type LoginCredentials as L, type GetEmployeeHierarchyResponse as M, type Notification as N, OracleEBSClient as O, type ProcessApprovalInput as P, type GetTableColumnsParams as Q, type RetryOptions as R, type SitSegment$1 as S, type TableColumn as T, type UserContext as U, type GetTableColumnsResponse as V, type DffSegment as W, type GetDffSegmentsParams as X, type GetDffSegmentsResponse as Y, type HealthCheckResponse as Z, type AccrualBalance as _, type OracleEBSConfig as a, type GetAccrualBalancesResponse as a0, MessageRole as a1, ActionType as a2, UserIntent as a3, type ChatMessage as a4, type CallToAction as a5, type AiResponse as a6, type ChatRequest as a7, type VoiceTranscription as a8, type VoiceResponse as a9, type ChatHistory as aa, type ChatThread as ab, type ThreadMessage as ac, type GetThreadMessagesResponse as ad, type GetThreadsResponse as ae, type CreateThreadResponse as af, type DeleteThreadResponse as ag, type LoginResponse as b, type Responsibility as c, type AbsenceType as d, type GetAbsenceTypesResponse as e, type LeaveHistoryRecord as f, type GetLeaveHistoryResponse as g, type CreateLeaveRequestInput as h, type CreateLeaveRequestResponse as i, type GetSitSegmentsParams$1 as j, type GetSitSegmentsResponse$1 as k, type SaveAndPreviewSitRequestInput as l, type SaveAndPreviewSitRequestResponse as m, type SubmitSitRequestInput as n, type SubmitSitRequestResponse as o, type GetSitHistoryParams as p, type SitHistoryRecord as q, type GetSitHistoryResponse as r, type SitSegment as s, type GetSitSegmentsParams as t, type GetSitSegmentsResponse as u, type GetNotificationsResponse as v, type NotificationDetails as w, type GetNotificationDetailsParams as x, type ProcessApprovalResponse as y, type CloseFyiParams as z };