@magentrix-corp/magentrix-sdk 1.1.6 → 1.1.7

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('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)
@@ -218,8 +239,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 +285,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 +301,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('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)
@@ -256,7 +322,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
 
@@ -541,8 +608,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 +865,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)
@@ -879,11 +946,16 @@ try {
 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 +964,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 +976,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 +1025,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 +1074,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 +1258,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.7",
   "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",