@magentrix-corp/magentrix-sdk 1.1.6 → 1.1.8

package/README.md

@@ -21,6 +21,21 @@ 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
@@ -47,8 +62,13 @@ try {
 
 // Query data - session is automatically created when needed
 try {
-  const results = await dataService.query('SELECT Id, Name FROM Account')
-  console.log(results)
+  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)
@@ -57,8 +77,9 @@ try {
 
 // Retrieve by ID
 try {
-  const record = await dataService.retrieve('account-id-123')
-  console.log(record)
+  const result = await dataService.retrieve('00I00000000003x0001')
+  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)
@@ -87,7 +108,7 @@ const error = ref<string | null>(null)
 onMounted(async () => {
   try {
     // Session is automatically created when needed
-    account.value = (await dataService.retrieve('006000000LJIxF70000')).record
+    account.value = (await dataService.retrieve('00I00000000003x0001')).record
     console.log(account.value)
   } catch (err) {
     if (err instanceof MagentrixError) {
@@ -167,6 +188,33 @@ const config: MagentrixConfig = {
 const dataService = new MagentrixClient(config)
 ```
 
+## Magentrix ID Format
+
+Magentrix uses a unique 19-character base-62 identifier format that is case-sensitive.
+
+### ID Structure
+
+A Magentrix ID consists of three parts:
+
+1. **First 3 characters**: Key Prefix - Identifies the entity type (e.g., "001" for Account, "003" for Contact)
+2. **Middle 12 characters**: Sequential base-62 number - Unique record identifier
+3. **Last 4 characters**: Organization ID - Unique identifier for the specific client
+
+### Example IDs
+
+```
+00I00000000003x0001  // Account record
+00300000000001A0001  // Contact record
+00500000000002B0001  // Opportunity record
+```
+
+**Important**:
+- IDs are case-sensitive
+- Always use the full 19-character ID when referencing records
+- The key prefix determines the entity type
+
+---
+
 ## API Reference
 
 ### Session Management
@@ -218,8 +266,42 @@ Execute a custom query using Magentrix query language.
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  const results = await dataService.query('SELECT Id, Name, Email FROM Contact WHERE Status = "Active"')
-  console.log(results)
+  // 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)
@@ -230,7 +312,9 @@ try {
 **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
 
@@ -244,8 +328,17 @@ Retrieve a single record by ID.
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  const account = await dataService.retrieve('account-id-123')
-  console.log(account.Name)
+  // Retrieve returns an object with a 'record' property
+  const result = await dataService.retrieve('00I00000000003x0001')
+  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('00300000000001A0001')
+  console.log('Contact:', record.Name)
 } catch (error) {
   if (error instanceof MagentrixError) {
     console.error('Retrieve failed:', error.message)
@@ -256,7 +349,8 @@ try {
 **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
 
@@ -264,13 +358,14 @@ try {
 
 ### CRUD Operations
 
-#### `create(entityName: string, data: any): Promise<any>`
+#### `create(entityName: string, data: any | any[]): Promise<any>`
 
-Create a new record.
+Create a new record or multiple records in a single API call.
 
 ```typescript
 import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
+// Create a single record
 try {
   const newAccount = await dataService.create('Account', {
     Name: 'Acme Corporation',
@@ -288,28 +383,52 @@ try {
     console.error('Create failed:', error.message)
   }
 }
+
+// Create multiple records in a single API call (RECOMMENDED for batch operations)
+try {
+  const newAccounts = await dataService.create('Account', [
+    { Name: 'Account 1', Email: 'account1@example.com', Status: 'Active' },
+    { Name: 'Account 2', Email: 'account2@example.com', Status: 'Active' },
+    { Name: 'Account 3', Email: 'account3@example.com', Status: 'Active' }
+  ])
+  console.log('Created IDs:', newAccounts.map(a => a.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('Batch create failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
 - `entityName`: Name of the entity (e.g., 'Account', 'Contact')
-- `data`: Object containing the record data
+- `data`: Single object or array of objects containing the record data
 
-**Returns**: Created record with ID
+**Returns**:
+- Single object: Created record with ID
+- Array: Array of created records with IDs
 
 **Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
+**Note**: When creating multiple records, pass an array to make a single optimized API call instead of multiple calls.
+
 ---
 
-#### `edit(entityName: string, data: any): Promise<any>`
+#### `edit(entityName: string, data: any | any[]): Promise<any>`
 
-Update an existing record (requires `Id` in data).
+Update an existing record or multiple records in a single API call (requires `Id` in data).
 
 ```typescript
 import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
+// Update a single record
 try {
   const updated = await dataService.edit('Account', {
-    Id: 'account-id-123',
+    Id: '00I00000000003x0001',
     Name: 'Updated Name',
     Status: 'Inactive'
   })
@@ -324,28 +443,52 @@ try {
     console.error('Edit failed:', error.message)
   }
 }
+
+// Update multiple records in a single API call (RECOMMENDED for batch operations)
+try {
+  const updated = await dataService.edit('Account', [
+    { Id: '00I00000000003x0001', Name: 'Updated Account 1', Status: 'Active' },
+    { Id: '00I00000000003y0001', Name: 'Updated Account 2', Status: 'Inactive' },
+    { Id: '00I00000000003z0001', Name: 'Updated Account 3', Status: 'Active' }
+  ])
+  console.log('Updated successfully:', updated.length, 'records')
+} 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('Batch edit failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
 - `entityName`: Name of the entity
-- `data`: Object containing the record data with `Id`
+- `data`: Single object or array of objects containing the record data with `Id`
 
-**Returns**: Updated record
+**Returns**:
+- Single object: Updated record
+- Array: Array of updated records
 
 **Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
+**Note**: When updating multiple records, pass an array to make a single optimized API call instead of multiple calls.
+
 ---
 
-#### `upsert(entityName: string, data: any): Promise<any>`
+#### `upsert(entityName: string, data: any | any[]): Promise<any>`
 
-Create or update a record. If `Id` is provided and exists, updates the record; otherwise creates a new one.
+Create or update a record or multiple records in a single API call. If `Id` is provided and exists, updates the record; otherwise creates a new one.
 
 ```typescript
 import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
+// Upsert a single record
 try {
   const record = await dataService.upsert('Contact', {
-    Id: 'contact-id-456', // Optional
+    Id: '00300000000001A0001', // Optional
     Name: 'John Doe',
     Email: 'john@example.com'
   })
@@ -360,16 +503,39 @@ try {
     console.error('Upsert failed:', error.message)
   }
 }
+
+// Upsert multiple records in a single API call (RECOMMENDED for batch operations)
+try {
+  const records = await dataService.upsert('Contact', [
+    { Id: '00300000000001A0001', Name: 'John Doe', Email: 'john@example.com' }, // Will update
+    { Name: 'Jane Smith', Email: 'jane@example.com' }, // Will create (no Id)
+    { Id: '00300000000001B0001', Name: 'Bob Johnson', Email: 'bob@example.com' } // Will update
+  ])
+  console.log('Upsert successful:', records.length, 'records')
+} 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('Batch upsert failed:', error.message)
+  }
+}
 ```
 
 **Parameters**:
 - `entityName`: Name of the entity
-- `data`: Object containing the record data
+- `data`: Single object or array of objects containing the record data (Id is optional)
 
-**Returns**: Created or updated record
+**Returns**:
+- Single object: Created or updated record
+- Array: Array of created or updated records
 
 **Throws**: `MagentrixError` if entityName or data is missing, `DatabaseError` for validation errors
 
+**Note**: When upserting multiple records, pass an array to make a single optimized API call instead of multiple calls.
+
 ---
 
 #### `delete(entityName: string, id: string, permanent?: boolean): Promise<any>`
@@ -381,7 +547,7 @@ import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
   // Soft delete (default)
-  await dataService.delete('Account', 'account-id-123')
+  await dataService.delete('Account', '00I00000000003x0001')
   console.log('Account deleted successfully')
 } catch (error) {
   if (error instanceof MagentrixError) {
@@ -391,7 +557,7 @@ try {
 
 try {
   // Permanent delete
-  await dataService.delete('Account', 'account-id-123', true)
+  await dataService.delete('Account', '00I00000000003x0001', true)
   console.log('Account permanently deleted')
 } catch (error) {
   if (error instanceof MagentrixError) {
@@ -419,7 +585,11 @@ Delete multiple records by IDs.
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  await dataService.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
+  await dataService.deleteMany('Contact', [
+    '00300000000001A0001',
+    '00300000000001B0001',
+    '00300000000001C0001'
+  ])
   console.log('Contacts deleted successfully')
 } catch (error) {
   if (error instanceof MagentrixError) {
@@ -541,8 +711,8 @@ General SDK errors (authentication, validation, API errors).
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  const results = await dataService.query('SELECT Id FROM Account')
-  console.log(results)
+  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)
@@ -798,8 +968,8 @@ const dataService = new MagentrixClient(config)
 
 // No need to call createSession() - the SDK handles it automatically
 try {
-  const results = await dataService.query('SELECT Id FROM Account')
-  console.log(results)
+  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)
@@ -838,32 +1008,69 @@ console.log(`Welcome ${userInfo.name}!`)
 
 ### Batch Operations
 
-Perform multiple operations efficiently:
+The `create()`, `edit()`, and `upsert()` methods accept arrays for efficient batch operations in a single API call.
+
+**✅ RECOMMENDED: Single API call with array**
 
 ```typescript
-import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
+import { MagentrixError, DatabaseError } from '@magentrix-corp/magentrix-sdk'
 
-// Create multiple records
+// Create multiple records in a single API call (OPTIMIZED)
 const accounts = [
-  { Name: 'Account 1', Status: 'Active' },
-  { Name: 'Account 2', Status: 'Active' },
-  { Name: 'Account 3', Status: 'Active' }
+  { Name: 'Account 1', Email: 'account1@example.com', Status: 'Active' },
+  { Name: 'Account 2', Email: 'account2@example.com', Status: 'Active' },
+  { Name: 'Account 3', Email: 'account3@example.com', Status: 'Active' }
 ]
 
 try {
-  const created = await Promise.all(
-    accounts.map(account => dataService.create('Account', account))
-  )
+  const created = await dataService.create('Account', accounts)
   console.log('Created IDs:', created.map(a => a.Id))
 } catch (error) {
-  if (error instanceof MagentrixError) {
+  if (error instanceof DatabaseError) {
     console.error('Batch create failed:', error.message)
+    error.getErrors().forEach(err => {
+      console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+    })
+  }
+}
+
+// Update multiple records in a single API call (OPTIMIZED)
+try {
+  const updates = [
+    { Id: '00I00000000003x0001', Name: 'Updated Account 1', Status: 'Active' },
+    { Id: '00I00000000003y0001', Name: 'Updated Account 2', Status: 'Inactive' },
+    { Id: '00I00000000003z0001', Name: 'Updated Account 3', Status: 'Active' }
+  ]
+  const updated = await dataService.edit('Account', updates)
+  console.log('Updated:', updated.length, 'records')
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Batch update failed:', error.message)
+  }
+}
+
+// Upsert multiple records in a single API call (OPTIMIZED)
+try {
+  const records = [
+    { Id: '00300000000001A0001', Name: 'John Doe', Email: 'john@example.com' }, // Updates
+    { Name: 'Jane Smith', Email: 'jane@example.com' }, // Creates (no Id)
+    { Id: '00300000000001B0001', Name: 'Bob Johnson', Email: 'bob@example.com' } // Updates
+  ]
+  const results = await dataService.upsert('Contact', records)
+  console.log('Upserted:', results.length, 'records')
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Batch upsert failed:', error.message)
   }
 }
 
 // Delete multiple records
 try {
-  const idsToDelete = ['id-1', 'id-2', 'id-3']
+  const idsToDelete = [
+    '00I00000000003x0001',
+    '00I00000000003y0001',
+    '00I00000000003z0001'
+  ]
   await dataService.deleteMany('Account', idsToDelete)
   console.log('Batch delete successful')
 } catch (error) {
@@ -873,17 +1080,41 @@ try {
 }
 ```
 
+**❌ NOT RECOMMENDED: Multiple API calls**
+
+```typescript
+// This makes multiple API calls - NOT optimized!
+const accounts = [
+  { Name: 'Account 1', Status: 'Active' },
+  { Name: 'Account 2', Status: 'Active' },
+  { Name: 'Account 3', Status: 'Active' }
+]
+
+// DON'T DO THIS - makes 3 separate API calls
+const created = await Promise.all(
+  accounts.map(account => dataService.create('Account', account))
+)
+
+// INSTEAD DO THIS - makes 1 API call
+const created = await dataService.create('Account', accounts)
+```
+
 ### Custom Query Examples
 
 ```typescript
 import { MagentrixError } from '@magentrix-corp/magentrix-sdk'
 
 try {
-  // Simple query
-  const activeContacts = await dataService.query(
+  // 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:', activeContacts)
+  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)
@@ -892,10 +1123,10 @@ try {
 
 try {
   // Query with sorting
-  const sortedAccounts = await dataService.query(
+  const result = await dataService.query(
     'SELECT Id, Name FROM Account ORDER BY Name ASC'
   )
-  console.log('Sorted accounts:', sortedAccounts)
+  console.log('Sorted accounts:', result.data)
 } catch (error) {
   if (error instanceof MagentrixError) {
     console.error('Query failed:', error.message)
@@ -904,10 +1135,44 @@ try {
 
 try {
   // Query with limit
-  const recentRecords = await dataService.query(
+  const result = await dataService.query(
     'SELECT Id, Name FROM Account LIMIT 10'
   )
-  console.log('Recent records:', recentRecords)
+  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)
+  }
+}
+
+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)
+  }
+}
+
+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)
@@ -919,6 +1184,28 @@ try {
 
 ## 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:
@@ -946,8 +1233,8 @@ const loadAccounts = async () => {
 
   try {
     // Session is automatically created when needed
-    const results = await dataService.query('SELECT Id, Name FROM Account')
-    accounts.value = results
+    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
@@ -1130,8 +1417,8 @@ const dataService = new MagentrixClient(config)
 // No need to call createSession()
 // Just use the dataService directly
 try {
-  const data = await dataService.query('SELECT Id FROM Account')
-  console.log(data)
+  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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magentrix-corp/magentrix-sdk",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "TypeScript SDK for Magentrix APIs with dual authentication modes, automatic session management, CRUD operations, and Vue 3 integration",
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",