@smartsides/oracle-ebs-sdk 1.0.6 → 1.0.9

package/README.md

@@ -5,7 +5,10 @@ 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
 - ✅ **React Query Integration** - Built-in hooks for Next.js
 - ✅ **Server Components** - Optimized for Next.js App Router
@@ -34,16 +37,17 @@ const client = new OracleEBSClient({
   logging: { enabled: true },
 });
 
-// Login
-const { access_token } = await client.auth.login({
+// Login - automatically stores user object
+const response = await client.auth.login({
   username: 'your-username',
   password: 'your-password',
 });
+// User info (EMPLOYEE_NUMBER, USER_ID, etc.) now available to all modules
 
 // Get leave types
 const types = await client.leaves.getRestrictedTypes();
 
-// Create leave request
+// Create leave request - employee number auto-extracted
 const request = await client.leaves.createRequest({
   absenceTypeId: '71',
   startDate: '2026-01-20',
@@ -51,6 +55,11 @@ const request = await client.leaves.createRequest({
   days: 3,
   comments: 'Family vacation',
 });
+
+// Get payslip - employee number auto-extracted
+const header = await client.payslip.getHeader({ 
+  periodName: '6 2025' 
+});
 ```
 
 ### Next.js App Router (Client Component)
@@ -123,8 +132,12 @@ export default async function Page() {
 ### Authentication
 
 ```typescript
-// Login
-await client.auth.login({ username, password });
+// Login - automatically stores full user object
+const response = await client.auth.login({ username, password });
+// User object now available to all modules:
+// - userName, ebsVersion
+// - USER_ID, PERSON_ID, EMPLOYEE_NUMBER
+// - responsibilities
 
 // Get user context
 const user = await client.auth.getUserContext();
@@ -133,6 +146,8 @@ const user = await client.auth.getUserContext();
 await client.auth.logout();
 ```
 
+**User Storage**: The SDK automatically stores the complete user object from the login response, making user information available to all modules without additional API calls.
+
 ### Leaves & Absences
 
 ```typescript
@@ -167,29 +182,85 @@ const result = await client.sitRequests.submit(data);
 ### 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' 
+});
+
+// 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
+// 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
-// Get header
-const header = await client.payslip.getHeader({ periodName: '6 2025' });
+// Get header - employee number auto-extracted from login
+const header = await client.payslip.getHeader({ 
+  periodName: '6 2025' 
+});
+
+// Get details (earnings/deductions)
+const details = await client.payslip.getDetails({ 
+  periodName: '6 2025' 
+});
+
+// Get leave details
+const leaveDetails = await client.payslip.getLeaveDetails({ 
+  periodName: '6 2025' 
+});
+
+// Get run balances
+const runBalances = await client.payslip.getRunBalances({ 
+  periodName: '6 2025' 
+});
 
-// Get details
-const details = await client.payslip.getDetails({ periodName: '6 2025' });
+// Get accrual balances
+const accrualBalances = await client.accrualBalances.getBalances({
+  calculationDate: '2025-06-30'
+});
+
+// Optional: Override employee number (for admin/HR use)
+const header = await client.payslip.getHeader({ 
+  employeeNumber: '12345',
+  periodName: '6 2025' 
+});
 ```
 
+**Auto Employee Number**: All payslip methods automatically use the employee number from the logged-in user. No need to pass it explicitly unless you're querying for a different employee.
+
 ### Employee
 
 ```typescript
@@ -223,6 +294,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
@@ -270,6 +436,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`:
@@ -282,6 +511,10 @@ All hooks are available from `@smartsides/oracle-ebs-sdk/hooks`:
 - `useSitSegments(client, params, options)`
 - `useNotifications(client, options)`
 - `usePayslipHeader(client, params, options)`
+- `usePayslipDetails(client, params, options)`
+- `usePayslipLeaveDetails(client, params, options)`
+- `usePayslipRunBalances(client, params, options)`
+- `useAccrualBalances(client, params, options)`
 - `usePersonalInfo(client, options)`
 - `useHealthCheck(client, options)`
 - And more...
@@ -305,6 +538,38 @@ const client = createServerClientFromCookies(cookies());
 const client = createServerClientFromHeaders(headers());
 ```
 
+## Key Improvements (v1.0.6)
+
+### Automatic User Context Storage
+The SDK now automatically stores the complete user object from the login response, eliminating the need to:
+- Make additional API calls for user information
+- Pass employee number to every payslip/leave request
+- Manually manage user context in your application
+
+### Smart Employee Number Extraction
+All payslip and leave methods automatically use the employee number from the logged-in user:
+```typescript
+// Before (v1.0.2)
+await client.payslip.getHeader({ 
+  employeeNumber: '4446',  // Had to pass manually
+  periodName: '6 2025' 
+});
+
+// After (v1.0.6)
+await client.payslip.getHeader({ 
+  periodName: '6 2025'  // Employee number auto-extracted!
+});
+```
+
+### Full User Object Access
+All modules can now access the complete user object:
+- `userName` - Username
+- `ebsVersion` - Oracle EBS version
+- `USER_ID` - User ID
+- `PERSON_ID` - Person ID  
+- `EMPLOYEE_NUMBER` - Employee number
+- `responsibilities` - User responsibilities
+
 ## License
 
 PROPRIETARY - SmartSides Development Team