@magentrix-corp/magentrix-sdk 1.1.7 → 1.1.8

package/README.md

@@ -77,7 +77,7 @@ try {
 
 // Retrieve by ID
 try {
-  const result = await dataService.retrieve('account-id-123')
+  const result = await dataService.retrieve('00I00000000003x0001')
   console.log(result.record) // The account object
   console.log('Name:', result.record.Name)
 } catch (error) {
@@ -108,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) {
@@ -188,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
@@ -302,7 +329,7 @@ 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 result = await dataService.retrieve('00I00000000003x0001')
   const account = result.record
 
   console.log('Account Name:', account.Name)
@@ -310,7 +337,7 @@ try {
   console.log('Account Status:', account.Status)
 
   // Or destructure directly
-  const { record } = await dataService.retrieve('contact-id-456')
+  const { record } = await dataService.retrieve('00300000000001A0001')
   console.log('Contact:', record.Name)
 } catch (error) {
   if (error instanceof MagentrixError) {
@@ -331,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',
@@ -355,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'
   })
@@ -391,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'
   })
@@ -427,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>`
@@ -448,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) {
@@ -458,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) {
@@ -486,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) {
@@ -905,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) {
@@ -940,6 +1080,25 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magentrix-corp/magentrix-sdk",
-  "version": "1.1.7",
+  "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",