@magentrix-corp/magentrix-sdk 1.1.5 → 1.1.7

package/README.md

@@ -21,36 +21,70 @@ npm install @magentrix-corp/magentrix-sdk
 
 ## Quick Start
 
+### Vue 3 Project Template (Recommended)
+
+The fastest way to start a new Vue.js project with Magentrix SDK:
+
+```bash
+npm create @magentrix-corp/iris-app-template@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+**Learn more**: [Create Iris App Template](https://www.npmjs.com/package/@magentrix-corp/create-iris-app-template?activeTab=readme)
+
+---
+
 ### JavaScript/TypeScript
 
 ```typescript
-import { MagentrixClient, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixClient, MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://dev.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: '<your-refresh-token>',
-  isDevMode: true, // Use token-based auth
-  onSessionExpired: async () => {
-    console.log('Session expired!')
-  },
-  onError: (error) => {
-    console.error('API Error:', error)
-  }
+  isDevMode: true // Use token-based auth
 }
 
-const client = new MagentrixClient(config)
+const dataService = new MagentrixClient(config)
 
-// Create a session
-const session = await client.createSession()
-console.log('Token:', session.token)
+// Get current user information
+try {
+  const userInfo = await dataService.getUserInfo()
+  console.log('Logged in as:', userInfo.name)
+  console.log('Role:', userInfo.roleType)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Failed to get user info:', error.message)
+  }
+}
 
-// Query data
-const results = await client.query('SELECT Id, Name FROM Account')
-console.log(results)
+// Query data - session is automatically created when needed
+try {
+  const result = await dataService.query('SELECT Id, Name FROM Account')
+  console.log(result.data) // Array of account objects
+
+  // Access individual records
+  result.data.forEach(account => {
+    console.log(account.Id, account.Name)
+  })
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 
 // Retrieve by ID
-const record = await client.retrieve('account-id-123')
-console.log(record)
+try {
+  const result = await dataService.retrieve('account-id-123')
+  console.log(result.record) // The account object
+  console.log('Name:', result.record.Name)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Retrieve failed:', error.message)
+  }
+}
 ```
 
 ### Vue 3
@@ -58,32 +92,40 @@ console.log(record)
 ```vue
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
-import { type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 import { useMagentrixSdk } from '@magentrix-corp/magentrix-sdk/vue'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://dev.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: '<your-refresh-token>',
-  isDevMode: true,
-  onError: (error: any) => {
-    console.error('API Error:', error)
-  }
+  isDevMode: true
 }
 
-const client = useMagentrixSdk().getInstance(config)
+const dataService = useMagentrixSdk().getInstance(config)
 const account = ref<any>(null)
+const error = ref<string | null>(null)
 
 onMounted(async () => {
-  await client.createSession()
-  account.value = (await client.retrieve('006000000LJIxF70000')).record
-  console.log(account.value)
+  try {
+    // Session is automatically created when needed
+    account.value = (await dataService.retrieve('006000000LJIxF70000')).record
+    console.log(account.value)
+  } catch (err) {
+    if (err instanceof MagentrixError) {
+      error.value = err.message
+      console.error('Failed to retrieve account:', err.message)
+    }
+  }
 })
 </script>
 
 <template>
-  <div v-if="account">
-    <h1>{{ account.Name }}</h1>
-    <p>{{ account.Email }}</p>
+  <div>
+    <div v-if="error" class="error">{{ error }}</div>
+    <div v-else-if="account">
+      <h1>{{ account.Name }}</h1>
+      <p>{{ account.Email }}</p>
+    </div>
   </div>
 </template>
 ```
@@ -94,11 +136,9 @@ onMounted(async () => {
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| `baseUrl` | `string` | Yes | Base URL of your Magentrix instance (e.g., 'https://your-instance.magentrix.com') |
+| `baseUrl` | `string` | Yes | Base URL of your Magentrix instance (e.g., 'https://your-portal-domain.com') |
 | `refreshToken` | `string` | No | Refresh token for authentication. Required when `isDevMode: true` |
 | `isDevMode` | `boolean` | No | Enable token-based authentication (default: `false`). See [Authentication Modes](#authentication-modes) |
-| `onSessionExpired` | `() => Promise<void> \| void` | No | Callback invoked when session expires |
-| `onError` | `(error: any) => void` | No | Global error handler for all API errors |
 
 ## Authentication Modes
 
@@ -118,12 +158,12 @@ The SDK supports two authentication modes controlled by the `isDevMode` flag:
 import { MagentrixClient, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://dev.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: '<your-refresh-token>',
   isDevMode: true
 }
 
-const client = new MagentrixClient(config)
+const dataService = new MagentrixClient(config)
 ```
 
 ### Production Mode (`isDevMode: false` or not set)
@@ -141,11 +181,11 @@ const client = new MagentrixClient(config)
 import { MagentrixClient, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://your-instance.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   isDevMode: false // or omit this property
 }
 
-const client = new MagentrixClient(config)
+const dataService = new MagentrixClient(config)
 ```
 
 ## API Reference
@@ -156,10 +196,29 @@ const client = new MagentrixClient(config)
 
 Creates a new session using the refresh token.
 
+**Note**: You typically don't need to call this method directly. The SDK automatically creates and refreshes sessions when needed.
+
 ```typescript
-const session = await client.createSession()
-console.log(session.token)      // Bearer token
-console.log(session.expires_in) // Seconds until expiration
+import { MagentrixClient, MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-portal-domain.com',
+  refreshToken: '<your-refresh-token>',
+  isDevMode: true
+}
+
+const dataService = new MagentrixClient(config)
+
+// Optional: Manually create session if needed
+try {
+  const session = await dataService.createSession()
+  console.log(session.token)      // Bearer token
+  console.log(session.expires_in) // Seconds until expiration
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Session creation failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -177,14 +236,58 @@ console.log(session.expires_in) // Seconds until expiration
 Execute a custom query using Magentrix query language.
 
 ```typescript
-const results = await client.query('SELECT Id, Name, Email FROM Contact WHERE Status = "Active"')
-console.log(results)
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  // Standard query - returns object with 'data' property containing array of records
+  const result = await dataService.query('SELECT Id, Name, Email FROM Contact WHERE Status = "Active"')
+  console.log(result.data) // Array of contact objects
+
+  // Access individual records
+  result.data.forEach(contact => {
+    console.log(contact.Id, contact.Name, contact.Email)
+  })
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
+
+try {
+  // Aggregate query - returns object with 'data' property containing aggregate results
+  const result = await dataService.query('SELECT COUNT(Id) as TotalAccounts FROM Account')
+  console.log(result.data.TotalAccounts) // Number value
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
+
+try {
+  // Multiple aggregates
+  const result = await dataService.query(`
+    SELECT
+      COUNT(Id) as TotalAccounts,
+      SUM(AnnualRevenue) as TotalRevenue,
+      AVG(AnnualRevenue) as AverageRevenue
+    FROM Account
+  `)
+  console.log('Total:', result.data.TotalAccounts)
+  console.log('Sum:', result.data.TotalRevenue)
+  console.log('Average:', result.data.AverageRevenue)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
 - `query`: Query string in Magentrix query language
 
-**Returns**: Query results
+**Returns**: Object with the following structure:
+- For standard queries: `{ data: Array<Object> }` - Array of records with selected fields
+- For aggregate queries: `{ data: Object }` - Object with aggregate field names as properties
 
 **Throws**: `MagentrixError` if query is empty or invalid
 
@@ -195,14 +298,32 @@ console.log(results)
 Retrieve a single record by ID.
 
 ```typescript
-const account = await client.retrieve('account-id-123')
-console.log(account.Name)
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  // Retrieve returns an object with a 'record' property
+  const result = await dataService.retrieve('account-id-123')
+  const account = result.record
+
+  console.log('Account Name:', account.Name)
+  console.log('Account Email:', account.Email)
+  console.log('Account Status:', account.Status)
+
+  // Or destructure directly
+  const { record } = await dataService.retrieve('contact-id-456')
+  console.log('Contact:', record.Name)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Retrieve failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
 - `id`: Record ID to retrieve
 
-**Returns**: Record object
+**Returns**: Object with the following structure:
+- `{ record: Object }` - The record property contains the full record data with all fields
 
 **Throws**: `MagentrixError` if ID is not provided
 
@@ -215,12 +336,25 @@ console.log(account.Name)
 Create a new record.
 
 ```typescript
-const newAccount = await client.create('Account', {
-  Name: 'Acme Corporation',
-  Email: 'contact@acme.com',
-  Status: 'Active'
-})
-console.log('Created ID:', newAccount.Id)
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  const newAccount = await dataService.create('Account', {
+    Name: 'Acme Corporation',
+    Email: 'contact@acme.com',
+    Status: 'Active'
+  })
+  console.log('Created ID:', newAccount.Id)
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Database error:', error.message)
+    error.getErrors().forEach(err => {
+      console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+    })
+  } else if (error instanceof MagentrixError) {
+    console.error('Create failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -229,7 +363,7 @@ console.log('Created ID:', newAccount.Id)
 
 **Returns**: Created record with ID
 
-**Throws**: `MagentrixError` if entityName or data is missing
+**Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
 ---
 
@@ -238,11 +372,25 @@ console.log('Created ID:', newAccount.Id)
 Update an existing record (requires `Id` in data).
 
 ```typescript
-const updated = await client.edit('Account', {
-  Id: 'account-id-123',
-  Name: 'Updated Name',
-  Status: 'Inactive'
-})
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  const updated = await dataService.edit('Account', {
+    Id: 'account-id-123',
+    Name: 'Updated Name',
+    Status: 'Inactive'
+  })
+  console.log('Updated successfully')
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Database error:', error.message)
+    error.getErrors().forEach(err => {
+      console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+    })
+  } else if (error instanceof MagentrixError) {
+    console.error('Edit failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -251,7 +399,7 @@ const updated = await client.edit('Account', {
 
 **Returns**: Updated record
 
-**Throws**: `MagentrixError` if entityName or data is missing
+**Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
 ---
 
@@ -260,11 +408,25 @@ const updated = await client.edit('Account', {
 Create or update a record. If `Id` is provided and exists, updates the record; otherwise creates a new one.
 
 ```typescript
-const record = await client.upsert('Contact', {
-  Id: 'contact-id-456', // Optional
-  Name: 'John Doe',
-  Email: 'john@example.com'
-})
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  const record = await dataService.upsert('Contact', {
+    Id: 'contact-id-456', // Optional
+    Name: 'John Doe',
+    Email: 'john@example.com'
+  })
+  console.log('Upsert successful:', record.Id)
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Database error:', error.message)
+    error.getErrors().forEach(err => {
+      console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+    })
+  } else if (error instanceof MagentrixError) {
+    console.error('Upsert failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -273,7 +435,7 @@ const record = await client.upsert('Contact', {
 
 **Returns**: Created or updated record
 
-**Throws**: `MagentrixError` if entityName or data is missing
+**Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
 ---
 
@@ -282,11 +444,27 @@ const record = await client.upsert('Contact', {
 Delete a record by ID.
 
 ```typescript
-// Soft delete (default)
-await client.delete('Account', 'account-id-123')
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  // Soft delete (default)
+  await dataService.delete('Account', 'account-id-123')
+  console.log('Account deleted successfully')
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Delete failed:', error.message)
+  }
+}
 
-// Permanent delete
-await client.delete('Account', 'account-id-123', true)
+try {
+  // Permanent delete
+  await dataService.delete('Account', 'account-id-123', true)
+  console.log('Account permanently deleted')
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Delete failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -305,7 +483,16 @@ await client.delete('Account', 'account-id-123', true)
 Delete multiple records by IDs.
 
 ```typescript
-await client.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  await dataService.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
+  console.log('Contacts deleted successfully')
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Delete many failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -319,6 +506,52 @@ await client.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
 
 ---
 
+### User Information
+
+#### `getUserInfo(): Promise<UserInfo>`
+
+Get information about the currently authenticated user.
+
+```typescript
+import { MagentrixError, type UserInfo } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  const userInfo: UserInfo = await dataService.getUserInfo()
+  console.log('User Name:', userInfo.name)
+  console.log('Username:', userInfo.userName)
+  console.log('User ID:', userInfo.id)
+  console.log('Role Type:', userInfo.roleType)
+  console.log('Locale:', userInfo.locale)
+  console.log('Preferred Currency:', userInfo.preferred_currency)
+  console.log('Currency Symbol:', userInfo.userCurrencySymbol)
+  console.log('Timezone Offset:', userInfo.user_timezone)
+  console.log('Is Guest:', userInfo.guest)
+  console.log('Is Impersonating:', userInfo.impr)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Failed to get user info:', error.message)
+  }
+}
+```
+
+**Returns**: `UserInfo` object containing:
+- `name`: Full name of the user
+- `userName`: Username of the user
+- `id`: User ID
+- `guest`: Whether the user is a guest
+- `impr`: Whether the user is using delegated access (impersonation)
+- `preferred_currency`: User's preferred currency ISO code
+- `user_timezone`: User's timezone offset
+- `userCurrencySymbol`: User's currency symbol
+- `lang`: User's language code
+- `roleType`: User's role type (`'guest'`, `'employee'`, `'customer'`, `'partner'`, or `'admin'`)
+- `locale`: User's locale
+- `display_user_currency`: Whether to display amounts in user's currency
+
+**Throws**: `MagentrixError` if the request fails
+
+---
+
 ### Custom Endpoints
 
 #### `execute(path: string, model?: any, method?: RequestMethod): Promise<any>`
@@ -326,16 +559,30 @@ await client.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
 Execute a custom API endpoint.
 
 ```typescript
-import { RequestMethod } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixError, RequestMethod } from '@magentrix-corp/magentrix-sdk'
 
-// GET request
-const data = await client.execute('/custom/endpoint', null, RequestMethod.get)
+try {
+  // GET request
+  const data = await dataService.execute('/custom/endpoint', null, RequestMethod.get)
+  console.log('GET result:', data)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('GET request failed:', error.message)
+  }
+}
 
-// POST request
-const result = await client.execute('/custom/action', {
-  param1: 'value1',
-  param2: 'value2'
-}, RequestMethod.post)
+try {
+  // POST request
+  const result = await dataService.execute('/custom/action', {
+    param1: 'value1',
+    param2: 'value2'
+  }, RequestMethod.post)
+  console.log('POST result:', result)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('POST request failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
@@ -361,7 +608,8 @@ General SDK errors (authentication, validation, API errors).
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  await client.createSession()
+  const result = await dataService.query('SELECT Id FROM Account')
+  console.log(result.data) // Array of account objects
 } catch (error) {
   if (error instanceof MagentrixError) {
     console.error('Magentrix Error:', error.message)
@@ -377,7 +625,7 @@ Database-specific errors with detailed error information.
 import { DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  await client.create('Account', invalidData)
+  await dataService.create('Account', invalidData)
 } catch (error) {
   if (error instanceof DatabaseError) {
     console.error('Database Error:', error.message)
@@ -390,21 +638,209 @@ try {
 }
 ```
 
-### Global Error Handler
+### Common Error Codes
+
+The API returns specific error codes for different scenarios. Here are the most common ones:
+
+#### Create Operation Errors
+
+**HTTP 406 Not Acceptable** - Validation errors
+
+```json
+{
+  "errors": [
+    {
+      "code": "Missing_Field",
+      "fieldName": "Name",
+      "message": "You must enter a value."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+**HTTP 413 Request Entity Too Large** - Payload exceeds size limit
 
-Set a global error handler in the configuration:
+```json
+{
+  "errors": [
+    {
+      "code": "PAYLOAD_TOO_LARGE",
+      "message": "The payload size exceeds the 20MB size limit."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+**HTTP 400 Bad Request** - Missing or invalid payload
+
+```json
+{
+  "errors": [
+    {
+      "code": "PAYLOAD_MISSING",
+      "message": "Request body is empty. A valid JSON/XML payload is required."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+#### Update Operation Errors
+
+**HTTP 406 Not Acceptable** - Validation errors
+
+```json
+{
+  "errors": [
+    {
+      "code": "Missing_Field",
+      "fieldName": "LastName",
+      "message": "You must enter a value."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+**HTTP 404 Not Found** - Record not found
+
+```json
+{
+  "errors": [
+    {
+      "code": "MISSING_ENTITY",
+      "message": "Record no longer exists."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+**HTTP 400 Bad Request** - ID mismatch
+
+```json
+{
+  "errors": [
+    {
+      "code": "ENTITY_ID_MISMATCH",
+      "message": "The ID in the request body does not match the record ID in the URL."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+#### Delete Operation Errors
+
+**HTTP 406 Not Acceptable** - Resource not found
+
+```json
+{
+  "message": "Resource not found",
+  "success": false
+}
+```
+
+**HTTP 404 Not Found** - Record not found
+
+```json
+{
+  "errors": [
+    {
+      "code": "ENTITY_NOT_FOUND",
+      "message": "Record was not found or you may not have access."
+    }
+  ],
+  "id": "Not found",
+  "success": false
+}
+```
+
+#### Authentication Errors
+
+**HTTP 401 Unauthorized** - Invalid or expired session
+
+```json
+{
+  "message": "Session expired. Please authenticate again.",
+  "success": false
+}
+```
+
+**HTTP 403 Forbidden** - Invalid token or too many failed attempts
+
+```json
+{
+  "errors": [
+    {
+      "code": "403",
+      "message": "Invalid Token"
+    }
+  ],
+  "success": false
+}
+```
+
+#### General Errors
+
+**HTTP 404 Not Found** - Invalid entity or resource
+
+```json
+{
+  "errors": [
+    {
+      "code": "INVALID_ENTITY",
+      "message": "Entity 'InvalidEntity' does not exist."
+    }
+  ],
+  "id": null,
+  "success": false
+}
+```
+
+**HTTP 500 Internal Server Error** - Unexpected server error
+
+```json
+{
+  "message": "An unexpected error occurred.",
+  "success": false
+}
+```
+
+### Error Handling Example
 
 ```typescript
-const client = new MagentrixClient({
-  baseUrl: 'https://your-instance.magentrix.com',
-  onError: (error) => {
-    // Log to monitoring service
-    console.error('Global error handler:', error)
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
-    // Show user notification
-    showNotification('An error occurred', 'error')
+try {
+  const newAccount = await dataService.create('Account', {
+    Name: 'Acme Corporation',
+    Email: 'contact@acme.com'
+  })
+  console.log('Created:', newAccount.Id)
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    // Handle validation errors with field-level details
+    console.error('Validation failed:', error.message)
+    error.getErrors().forEach(err => {
+      console.error(`- ${err.fieldName}: ${err.message} (Code: ${err.code})`)
+    })
+  } else if (error instanceof MagentrixError) {
+    // Handle general API errors
+    console.error('API Error:', error.message)
+  } else {
+    // Handle unexpected errors
+    console.error('Unexpected error:', error)
   }
-})
+}
 ```
 
 
@@ -412,21 +848,30 @@ const client = new MagentrixClient({
 
 ## Advanced Usage
 
-### Session Expiration Handling
+### Automatic Session Management
 
-Handle session expiration gracefully:
+The SDK automatically handles session creation and refresh:
 
 ```typescript
-const client = new MagentrixClient({
-  baseUrl: 'https://your-instance.magentrix.com',
+import { MagentrixClient, MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: 'your-refresh-token',
-  isDevMode: true,
-  onSessionExpired: async () => {
-    console.log('Session expired, refreshing...')
-    // The SDK will automatically refresh the session
-    // You can add custom logic here (e.g., show notification)
+  isDevMode: true
+}
+
+const dataService = new MagentrixClient(config)
+
+// No need to call createSession() - the SDK handles it automatically
+try {
+  const result = await dataService.query('SELECT Id FROM Account')
+  console.log(result.data) // Array of account objects
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
   }
-})
+}
 ```
 
 ### TypeScript Types
@@ -438,6 +883,7 @@ import {
   MagentrixClient,
   MagentrixConfig,
   SessionInfo,
+  UserInfo,
   MagentrixError,
   DatabaseError,
   RequestMethod,
@@ -445,12 +891,16 @@ import {
 } from '@magentrix-corp/magentrix-sdk'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://your-instance.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: 'your-refresh-token',
   isDevMode: true
 }
 
-const client = new MagentrixClient(config)
+const dataService = new MagentrixClient(config)
+
+// Use UserInfo type for type safety
+const userInfo: UserInfo = await dataService.getUserInfo()
+console.log(`Welcome ${userInfo.name}!`)
 ```
 
 ### Batch Operations
@@ -458,6 +908,8 @@ const client = new MagentrixClient(config)
 Perform multiple operations efficiently:
 
 ```typescript
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
 // Create multiple records
 const accounts = [
   { Name: 'Account 1', Status: 'Active' },
@@ -465,40 +917,136 @@ const accounts = [
   { Name: 'Account 3', Status: 'Active' }
 ]
 
-const created = await Promise.all(
-  accounts.map(account => client.create('Account', account))
-)
-
-console.log('Created IDs:', created.map(a => a.Id))
+try {
+  const created = await Promise.all(
+    accounts.map(account => dataService.create('Account', account))
+  )
+  console.log('Created IDs:', created.map(a => a.Id))
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Batch create failed:', error.message)
+  }
+}
 
 // Delete multiple records
-const idsToDelete = ['id-1', 'id-2', 'id-3']
-await client.deleteMany('Account', idsToDelete)
+try {
+  const idsToDelete = ['id-1', 'id-2', 'id-3']
+  await dataService.deleteMany('Account', idsToDelete)
+  console.log('Batch delete successful')
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Batch delete failed:', error.message)
+  }
+}
 ```
 
 ### Custom Query Examples
 
 ```typescript
-// Simple query
-const activeContacts = await client.query(
-  'SELECT Id, Name, Email FROM Contact WHERE Status = "Active"'
-)
+import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+
+try {
+  // Simple query - returns array of records in 'data' property
+  const result = await dataService.query(
+    'SELECT Id, Name, Email FROM Contact WHERE Status = "Active"'
+  )
+  console.log('Active contacts:', result.data)
+
+  // Iterate through results
+  result.data.forEach(contact => {
+    console.log(`${contact.Name} - ${contact.Email}`)
+  })
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
+
+try {
+  // Query with sorting
+  const result = await dataService.query(
+    'SELECT Id, Name FROM Account ORDER BY Name ASC'
+  )
+  console.log('Sorted accounts:', result.data)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
+
+try {
+  // Query with limit
+  const result = await dataService.query(
+    'SELECT Id, Name FROM Account LIMIT 10'
+  )
+  console.log('Recent records:', result.data)
+  console.log('Total records returned:', result.data.length)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 
-// Query with sorting
-const sortedAccounts = await client.query(
-  'SELECT Id, Name FROM Account ORDER BY Name ASC'
-)
+try {
+  // Aggregate query - returns object with aggregate values
+  const result = await dataService.query(
+    'SELECT COUNT(Id) as TotalAccounts FROM Account'
+  )
+  console.log('Total accounts:', result.data.TotalAccounts)
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 
-// Query with limit
-const recentRecords = await client.query(
-  'SELECT Id, Name FROM Account LIMIT 10'
-)
+try {
+  // Multiple aggregates
+  const result = await dataService.query(`
+    SELECT
+      COUNT(Id) as Total,
+      SUM(AnnualRevenue) as Revenue,
+      AVG(NumberOfEmployees) as AvgEmployees
+    FROM Account
+    WHERE Status = "Active"
+  `)
+  console.log('Statistics:', {
+    total: result.data.Total,
+    revenue: result.data.Revenue,
+    avgEmployees: result.data.AvgEmployees
+  })
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 ```
 
 ---
 
 ## Vue 3 Integration
 
+### Quick Start with Project Template
+
+The fastest way to get started with a Vue.js project using the Magentrix SDK is to use the official project template:
+
+```bash
+npm create @magentrix-corp/iris-app-template@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+This template provides:
+- ✅ Pre-configured Magentrix SDK integration
+- ✅ Vue 3 + TypeScript setup
+- ✅ Vite for fast development
+- ✅ Example components and best practices
+- ✅ Ready-to-use authentication flow
+
+**Learn more**: [https://www.npmjs.com/package/@magentrix-corp/create-iris-app-template](https://www.npmjs.com/package/@magentrix-corp/create-iris-app-template?activeTab=readme)
+
+---
+
 ### Composable Usage
 
 The SDK provides a dedicated Vue 3 composable:
@@ -506,16 +1054,16 @@ The SDK provides a dedicated Vue 3 composable:
 ```vue
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
-import { type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 import { useMagentrixSdk } from '@magentrix-corp/magentrix-sdk/vue'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://dev.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: '<your-refresh-token>',
   isDevMode: true
 }
 
-const client = useMagentrixSdk().getInstance(config)
+const dataService = useMagentrixSdk().getInstance(config)
 const accounts = ref<any[]>([])
 const loading = ref(false)
 const error = ref<string | null>(null)
@@ -525,11 +1073,14 @@ const loadAccounts = async () => {
   error.value = null
 
   try {
-    await client.createSession()
-    const results = await client.query('SELECT Id, Name FROM Account')
-    accounts.value = results
-  } catch (err: any) {
-    error.value = err.message
+    // Session is automatically created when needed
+    const result = await dataService.query('SELECT Id, Name FROM Account')
+    accounts.value = result.data // Extract the data array
+  } catch (err) {
+    if (err instanceof MagentrixError) {
+      error.value = err.message
+      console.error('Failed to load accounts:', err.message)
+    }
   } finally {
     loading.value = false
   }
@@ -558,16 +1109,16 @@ onMounted(() => {
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue'
-import { type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixError, DatabaseError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
 import { useMagentrixSdk } from '@magentrix-corp/magentrix-sdk/vue'
 
 const config: MagentrixConfig = {
-  baseUrl: 'https://dev.magentrix.com',
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: '<your-refresh-token>',
   isDevMode: true
 }
 
-const client = useMagentrixSdk().getInstance(config)
+const dataService = useMagentrixSdk().getInstance(config)
 
 const formData = ref({
   Name: 'Company Name',
@@ -577,34 +1128,50 @@ const formData = ref({
 
 const createAccount = async () => {
   try {
-    const created = await client.create('Account', formData.value)
+    const created = await dataService.create('Account', formData.value)
     console.log('Created:', created)
 
     // Reset form
     formData.value = { Name: '', Type: '', Status: 'Active' }
   } catch (error) {
-    console.error('Failed to create account:', error)
+    if (error instanceof DatabaseError) {
+      console.error('Database error:', error.message)
+      error.getErrors().forEach(err => {
+        console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+      })
+    } else if (error instanceof MagentrixError) {
+      console.error('Failed to create account:', error.message)
+    }
   }
 }
 
 const updateAccount = async (id: string) => {
   try {
-    await client.edit('Account', {
+    await dataService.edit('Account', {
       Id: id,
       ...formData.value
     })
     console.log('Updated successfully')
   } catch (error) {
-    console.error('Failed to update account:', error)
+    if (error instanceof DatabaseError) {
+      console.error('Database error:', error.message)
+      error.getErrors().forEach(err => {
+        console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+      })
+    } else if (error instanceof MagentrixError) {
+      console.error('Failed to update account:', error.message)
+    }
   }
 }
 
 const deleteAccount = async (id: string) => {
   try {
-    await client.delete('Account', id)
+    await dataService.delete('Account', id)
     console.log('Deleted successfully')
   } catch (error) {
-    console.error('Failed to delete account:', error)
+    if (error instanceof MagentrixError) {
+      console.error('Failed to delete account:', error.message)
+    }
   }
 }
 </script>
@@ -619,8 +1186,8 @@ const deleteAccount = async (id: string) => {
 Use environment variables for configuration:
 
 ```typescript
-const client = new MagentrixClient({
-  baseUrl: process.env.MAGENTRIX_BASE_URL || 'https://default.magentrix.com',
+const dataService = new MagentrixClient({
+  baseUrl: process.env.MAGENTRIX_BASE_URL || 'https://your-portal-domain.com',
   refreshToken: process.env.MAGENTRIX_REFRESH_TOKEN,
   isDevMode: process.env.NODE_ENV === 'development'
 })
@@ -631,12 +1198,15 @@ const client = new MagentrixClient({
 Always handle errors appropriately:
 
 ```typescript
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
+
 try {
-  const result = await client.create('Account', data)
-  // Handle success
+  const result = await dataService.create('Account', data)
+  console.log('Account created:', result.Id)
 } catch (error) {
   if (error instanceof DatabaseError) {
     // Handle database validation errors
+    console.error('Database Error:', error.message)
     error.getErrors().forEach(err => {
       console.error(`${err.fieldName}: ${err.message}`)
     })
@@ -652,21 +1222,23 @@ try {
 
 ### 3. Session Management
 
-For development mode, create session once at app initialization:
+The SDK automatically manages sessions - no manual initialization needed:
 
 ```typescript
 // app.ts or main.ts
-const client = new MagentrixClient({
-  baseUrl: 'https://your-instance.magentrix.com',
+import { MagentrixClient, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: 'your-refresh-token',
   isDevMode: true
-})
+}
 
-// Initialize session
-await client.createSession()
+const dataService = new MagentrixClient(config)
 
+// No need to call createSession() - it's handled automatically
 // Export for use throughout the app
-export { client }
+export { dataService }
 ```
 
 ### 4. Production Deployment
@@ -674,14 +1246,25 @@ export { client }
 For production (cookie-based auth), no session creation needed:
 
 ```typescript
-const client = new MagentrixClient({
-  baseUrl: 'https://your-instance.magentrix.com',
+import { MagentrixClient, MagentrixError, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-portal-domain.com',
   isDevMode: false // Uses ASP.NET session cookies
-})
+}
+
+const dataService = new MagentrixClient(config)
 
 // No need to call createSession()
-// Just use the client directly
-const data = await client.query('SELECT Id FROM Account')
+// Just use the dataService directly
+try {
+  const result = await dataService.query('SELECT Id FROM Account')
+  console.log(result.data) // Array of account objects
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Query failed:', error.message)
+  }
+}
 ```
 
 ---
@@ -695,11 +1278,15 @@ const data = await client.query('SELECT Id FROM Account')
 **Solution**: Ensure `refreshToken` is provided in config when using `isDevMode: true`
 
 ```typescript
-const client = new MagentrixClient({
-  baseUrl: 'https://your-instance.magentrix.com',
+import { MagentrixClient, type MagentrixConfig } from '@magentrix-corp/magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-portal-domain.com',
   refreshToken: 'your-refresh-token', // Required for dev mode
   isDevMode: true
-})
+}
+
+const dataService = new MagentrixClient(config)
 ```
 
 ---
@@ -723,8 +1310,8 @@ Proprietary
 ## Support
 
 For issues and questions:
-- GitHub Issues: [Create an issue](https://github.com/your-repo/magentrix-sdk/issues)
-- Documentation: [Magentrix Developer Portal](https://your-instance.magentrix.com/docs)
+- Documentation: [Magentrix Help Center]https://help.magentrix.com/
+- Website: [Magentrix.com](https://www.magentrix.com/)
 
 ---