@magentrix-corp/magentrix-sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,92 +1,57 @@
 # Magentrix SDK for JavaScript
 
-A standalone, framework-agnostic TypeScript library that provides a clean interface for interacting with the Magentrix REST API v3.
-
-[![npm version](https://img.shields.io/npm/v/magentrix-sdk.svg)](https://www.npmjs.com/package/magentrix-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+A TypeScript-based SDK for seamless integration with Magentrix APIs. This SDK provides a convenient interface for authentication, CRUD operations, and custom queries with built-in session management and error handling.
 
 ## Features
 
-### Core Functionality
-
-- ✅ **Full REST API v3 support** - Complete coverage of Magentrix REST API endpoints
-- ✅ **CRUD operations** - Create, Read, Update, Delete operations made simple
-- ✅ **Query execution** - Execute queries using IRIS query language
-- ✅ **Custom MVC actions** - Execute custom MVC actions seamlessly
-- ✅ **Session management** - Built-in authentication and session handling
-- ✅ **Automatic token refresh** - Handles token refresh automatically
-- ✅ **IRIS data extensions** - Support for metadata and permissions
-
-### Developer Experience
-
-- ✅ **TypeScript-first** - Full type definitions for enhanced IDE support
-- ✅ **Promise-based API** - Modern async/await syntax
-- ✅ **Vue.js 3 plugin** - Seamless integration with Vue.js applications
-- ✅ **Composable pattern** - Vue composables for reactive data management
-- ✅ **Comprehensive error handling** - Robust error handling with custom callbacks
-- ✅ **Zero external dependencies** - Only uses native Fetch API
-
-### Package Quality
-
-- ✅ **Modern build system** - Built with Rollup for optimal bundling
-- ✅ **Multiple module formats** - CommonJS and ES Module outputs
-- ✅ **Tree-shakeable** - Import only what you need
-- ✅ **Source maps included** - Easy debugging in development
-- ✅ **Full documentation** - Complete examples and API reference
+- ✅ **Dual Authentication Modes**: Token-based (dev) and cookie-based (production) authentication
+- ✅ **Automatic Session Management**: Token refresh with configurable expiration handling
+- ✅ **CRUD Operations**: Create, read, update, delete operations for entities
+- ✅ **Custom Queries**: Execute custom queries and retrieve data by ID
+- ✅ **Vue 3 Integration**: Dedicated composable for Vue.js applications
+- ✅ **TypeScript Support**: Full type definitions included
+- ✅ **Error Handling**: Custom error classes with optional global error callbacks
+- ✅ **ESM & CommonJS**: Supports both module formats
 
 ## Installation
 
 ```bash
-npm install magentrix-sdk
-```
-
-or
-
-```bash
-yarn add magentrix-sdk
-```
-
-or
-
-```bash
-pnpm add magentrix-sdk
+npm install @magentrix-corp/magentrix-sdk
 ```
 
 ## Quick Start
 
-### Vanilla JavaScript/TypeScript
+### JavaScript/TypeScript
 
-```javascript
+```typescript
 import { MagentrixClient } from 'magentrix-sdk'
 
 const client = new MagentrixClient({
-  baseUrl: '{your-portal-domain}',
-  token: '',
-  refreshToken: '{refresh-token}',
-  antiForgeryToken: '',
-  onSessionExpired: () => {
-    // Handle session expiration
-    console.log('Session expired, redirecting to login...')
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token',
+  isDevMode: true, // Use token-based auth
+  onSessionExpired: async () => {
+    console.log('Session expired!')
   },
   onError: (error) => {
-    // Handle errors globally
     console.error('API Error:', error)
   }
 })
 
-// Create a session and retrieve data
-async function fetchData() {
-  const sessionInfo = await client.createSession()
-  console.log('Session Token:', sessionInfo.token)
+// Create a session
+const session = await client.createSession()
+console.log('Token:', session.token)
 
-  const data = await client.retrieve('xyz')
-  console.log('Retrieved Data:', data)
-}
+// Query data
+const results = await client.query('SELECT Id, Name FROM Account')
+console.log(results)
 
-fetchData()
+// Retrieve by ID
+const record = await client.retrieve('account-id-123')
+console.log(record)
 ```
 
-### Vue.js 3
+### Vue 3
 
 ```vue
 <script setup>
@@ -94,143 +59,663 @@ import { ref, onMounted } from 'vue'
 import { useMagentrixSdk } from 'magentrix-sdk/vue'
 
 const client = useMagentrixSdk({
-  baseUrl: 'https://your-portal.magentrix.com',
-  token: '',
+  baseUrl: 'https://your-instance.magentrix.com',
   refreshToken: 'your-refresh-token',
-  antiForgeryToken: '',
-  onSessionExpired: () => {
-    // Handle session expiration
-    console.log('Session expired')
-  },
+  isDevMode: true,
   onError: (error) => {
-    // Handle errors
-    console.error('Error:', error)
+    console.error('API Error:', error)
   }
 })
 
-const model = ref()
+const account = ref(null)
 
 onMounted(async () => {
-  const sessionInfo = await client.createSession()
-  console.log('Session Token:', sessionInfo.token)
-
-  const data = await client.retrieve('xyz')
-  console.log('Retrieved Data:', data)
-  model.value = data
+  await client.createSession()
+  account.value = await client.retrieve('account-id-123')
 })
 </script>
 
 <template>
-  <div>
-    <p v-if="model">{{ model.Id }}</p>
+  <div v-if="account">
+    <h1>{{ account.Name }}</h1>
+    <p>ID: {{ account.Id }}</p>
   </div>
 </template>
 ```
 
-## API Reference
+## Configuration
+
+### MagentrixConfig
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `baseUrl` | `string` | Yes | Base URL of your Magentrix instance (e.g., 'https://your-instance.magentrix.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
+
+The SDK supports two authentication modes controlled by the `isDevMode` flag:
+
+### Development Mode (`isDevMode: true`)
+
+**Use Case**: External applications, mobile apps, or development environments
+
+**Behavior**:
+- Uses **token-based authentication** with Bearer tokens
+- Automatically refreshes tokens before they expire (30-second buffer)
+- Validates session on every API call
+- Requires `refreshToken` in configuration
+
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token',
+  isDevMode: true
+})
+```
+
+### Production Mode (`isDevMode: false` or not set)
+
+**Use Case**: Web applications using ASP.NET Forms Authentication
+
+**Behavior**:
+- Uses **cookie-based authentication** (ASP.NET session cookies)
+- No bearer tokens sent in requests
+- No automatic session validation
+- Automatically redirects to login page when session expires
+- No `refreshToken` required
+
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  isDevMode: false // or omit this property
+})
+```
 
-### Configuration Options
+## API Reference
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `baseUrl` | `string` | Yes | Your Magentrix portal domain |
-| `token` | `string` | No | Initial authentication token |
-| `refreshToken` | `string` | No | Token used for refreshing sessions |
-| `antiForgeryToken` | `string` | No | Anti-forgery token for security |
-| `onSessionExpired` | `() => Promise<void> \| void` | No | Callback when session expires |
-| `onError` | `(error: any) => void` | No | Global error handler |
+### Session Management
 
-### Core Methods
+#### `createSession(refreshToken?: string): Promise<SessionInfo>`
 
-#### `createSession()`
-Creates a new session and returns session information.
+Creates a new session using the refresh token.
 
-```javascript
-const sessionInfo = await client.createSession()
-console.log(sessionInfo.token)
+```typescript
+const session = await client.createSession()
+console.log(session.token)      // Bearer token
+console.log(session.expires_in) // Seconds until expiration
 ```
 
-#### `retrieve(id: string)`
-Retrieves a record by ID.
+**Parameters**:
+- `refreshToken` (optional): Override the refresh token from config
+
+**Returns**: `SessionInfo` object with `token` and `expires_in`
+
+**Throws**: `MagentrixError` if token is invalid or expired
+
 
-```javascript
-const record = await client.retrieve('record-id')
+### Query Operations
+
+#### `query(query: string): Promise<any>`
+
+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)
 ```
 
-#### `execute(action: string, params?: object)`
-Executes a custom MVC action.
+**Parameters**:
+- `query`: Query string in Magentrix query language
+
+**Returns**: Query results
+
+**Throws**: `MagentrixError` if query is empty or invalid
+
+---
+
+#### `retrieve(id: string): Promise<any>`
 
-```javascript
-const result = await client.execute('customAction', { param1: 'value' })
+Retrieve a single record by ID.
+
+```typescript
+const account = await client.retrieve('account-id-123')
+console.log(account.Name)
 ```
 
-## Examples
+**Parameters**:
+- `id`: Record ID to retrieve
+
+**Returns**: Record object
+
+**Throws**: `MagentrixError` if ID is not provided
+
+---
 
 ### CRUD Operations
 
-```javascript
-// Create
-const newRecord = await client.create({
-  Name: 'New Record',
-  Description: 'Record description'
+#### `create(entityName: string, data: any): Promise<any>`
+
+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)
+```
+
+**Parameters**:
+- `entityName`: Name of the entity (e.g., 'Account', 'Contact')
+- `data`: Object containing the record data
+
+**Returns**: Created record with ID
+
+**Throws**: `MagentrixError` if entityName or data is missing
+
+---
+
+#### `edit(entityName: string, data: any): Promise<any>`
+
+Update an existing record (requires `Id` in data).
+
+```typescript
+const updated = await client.edit('Account', {
+  Id: 'account-id-123',
+  Name: 'Updated Name',
+  Status: 'Inactive'
+})
+```
+
+**Parameters**:
+- `entityName`: Name of the entity
+- `data`: Object containing the record data with `Id`
+
+**Returns**: Updated record
+
+**Throws**: `MagentrixError` if entityName or data is missing
+
+---
+
+#### `upsert(entityName: string, data: any): Promise<any>`
+
+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'
+})
+```
+
+**Parameters**:
+- `entityName`: Name of the entity
+- `data`: Object containing the record data
+
+**Returns**: Created or updated record
+
+**Throws**: `MagentrixError` if entityName or data is missing
+
+---
+
+#### `delete(entityName: string, id: string, permanent?: boolean): Promise<any>`
+
+Delete a record by ID.
+
+```typescript
+// Soft delete (default)
+await client.delete('Account', 'account-id-123')
+
+// Permanent delete
+await client.delete('Account', 'account-id-123', true)
+```
+
+**Parameters**:
+- `entityName`: Name of the entity
+- `id`: Record ID to delete
+- `permanent` (optional): If `true`, permanently deletes the record (default: `false`)
+
+**Returns**: Deletion result
+
+**Throws**: `MagentrixError` if entityName or id is missing
+
+---
+
+#### `deleteMany(entityName: string, ids: string[], permanent?: boolean): Promise<any>`
+
+Delete multiple records by IDs.
+
+```typescript
+await client.deleteMany('Contact', ['id-1', 'id-2', 'id-3'])
+```
+
+**Parameters**:
+- `entityName`: Name of the entity
+- `ids`: Array of record IDs to delete
+- `permanent` (optional): If `true`, permanently deletes the records (default: `false`)
+
+**Returns**: Deletion result
+
+**Throws**: `MagentrixError` if entityName or ids is missing/empty
+
+---
+
+### Custom Endpoints
+
+#### `execute(path: string, model?: any, method?: RequestMethod): Promise<any>`
+
+Execute a custom API endpoint.
+
+```typescript
+import { RequestMethod } from 'magentrix-sdk'
+
+// GET request
+const data = await client.execute('/custom/endpoint', null, RequestMethod.get)
+
+// POST request
+const result = await client.execute('/custom/action', {
+  param1: 'value1',
+  param2: 'value2'
+}, RequestMethod.post)
+```
+
+**Parameters**:
+- `path`: API endpoint path
+- `model` (optional): Request body data
+- `method` (optional): HTTP method (default: `RequestMethod.post`)
+
+**Returns**: API response
+
+**Throws**: `MagentrixError` if path is missing or GET request has a body
+
+---
+
+## Error Handling
+
+The SDK provides two custom error classes:
+
+### MagentrixError
+
+General SDK errors (authentication, validation, API errors).
+
+```typescript
+import { MagentrixError } from 'magentrix-sdk'
+
+try {
+  await client.createSession()
+} catch (error) {
+  if (error instanceof MagentrixError) {
+    console.error('Magentrix Error:', error.message)
+  }
+}
+```
+
+### DatabaseError
+
+Database-specific errors with detailed error information.
+
+```typescript
+import { DatabaseError } from 'magentrix-sdk'
+
+try {
+  await client.create('Account', invalidData)
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    console.error('Database Error:', error.message)
+    if (error.hasErrors()) {
+      error.getErrors().forEach(err => {
+        console.error(`Field: ${err.fieldName}, Message: ${err.message}`)
+      })
+    }
+  }
+}
+```
+
+### Global Error Handler
+
+Set a global error handler in the configuration:
+
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  onError: (error) => {
+    // Log to monitoring service
+    console.error('Global error handler:', error)
+
+    // Show user notification
+    showNotification('An error occurred', 'error')
+  }
 })
+```
+
+
+---
+
+## Advanced Usage
+
+### Session Expiration Handling
 
-// Read
-const record = await client.retrieve('record-id')
+Handle session expiration gracefully:
 
-// Update
-const updated = await client.update('record-id', {
-  Name: 'Updated Name'
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.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)
+  }
 })
+```
+
+### TypeScript Types
+
+Import types for better type safety:
+
+```typescript
+import {
+  MagentrixClient,
+  MagentrixConfig,
+  SessionInfo,
+  MagentrixError,
+  DatabaseError,
+  RequestMethod,
+  ContentType
+} from 'magentrix-sdk'
+
+const config: MagentrixConfig = {
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token',
+  isDevMode: true
+}
+
+const client = new MagentrixClient(config)
+```
+
+### Batch Operations
+
+Perform multiple operations efficiently:
+
+```typescript
+// Create multiple records
+const accounts = [
+  { Name: 'Account 1', Status: 'Active' },
+  { Name: 'Account 2', Status: 'Active' },
+  { 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))
+
+// Delete multiple records
+const idsToDelete = ['id-1', 'id-2', 'id-3']
+await client.deleteMany('Account', idsToDelete)
+```
 
-// Delete
-await client.delete('record-id')
+### Custom Query Examples
+
+```typescript
+// Simple query
+const activeContacts = await client.query(
+  'SELECT Id, Name, Email FROM Contact WHERE Status = "Active"'
+)
+
+// Query with sorting
+const sortedAccounts = await client.query(
+  'SELECT Id, Name FROM Account ORDER BY Name ASC'
+)
+
+// Query with limit
+const recentRecords = await client.query(
+  'SELECT Id, Name FROM Account LIMIT 10'
+)
 ```
 
-### Query Execution
+---
+
+## Vue 3 Integration
+
+### Composable Usage
+
+The SDK provides a dedicated Vue 3 composable:
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue'
+import { useMagentrixSdk } from 'magentrix-sdk/vue'
+
+const client = useMagentrixSdk({
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token',
+  isDevMode: true
+})
 
-```javascript
-const results = await client.query({
-  entity: 'Account',
-  filter: 'Status eq "Active"',
-  select: ['Id', 'Name', 'Email']
+const accounts = ref([])
+const loading = ref(false)
+const error = ref(null)
+
+const loadAccounts = async () => {
+  loading.value = true
+  error.value = null
+
+  try {
+    await client.createSession()
+    const results = await client.query('SELECT Id, Name FROM Account')
+    accounts.value = results
+  } catch (err) {
+    error.value = err.message
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => {
+  loadAccounts()
 })
+</script>
+
+<template>
+  <div>
+    <div v-if="loading">Loading...</div>
+    <div v-else-if="error">Error: {{ error }}</div>
+    <ul v-else>
+      <li v-for="account in accounts" :key="account.Id">
+        {{ account.Name }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+### Reactive CRUD Operations
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useMagentrixSdk } from 'magentrix-sdk/vue'
+
+const client = useMagentrixSdk({
+  baseUrl: 'https://your-instance.magentrix.com',
+  isDevMode: true
+})
+
+const formData = ref({
+  Name: '',
+  Email: '',
+  Status: 'Active'
+})
+
+const createAccount = async () => {
+  try {
+    const created = await client.create('Account', formData.value)
+    console.log('Created:', created)
+
+    // Reset form
+    formData.value = { Name: '', Email: '', Status: 'Active' }
+  } catch (error) {
+    console.error('Failed to create account:', error)
+  }
+}
+
+const updateAccount = async (id) => {
+  try {
+    await client.edit('Account', {
+      Id: id,
+      ...formData.value
+    })
+    console.log('Updated successfully')
+  } catch (error) {
+    console.error('Failed to update account:', error)
+  }
+}
+
+const deleteAccount = async (id) => {
+  try {
+    await client.delete('Account', id)
+    console.log('Deleted successfully')
+  } catch (error) {
+    console.error('Failed to delete account:', error)
+  }
+}
+</script>
 ```
 
-## TypeScript Support
+---
+
+## Best Practices
 
-The SDK is written in TypeScript and provides full type definitions out of the box:
+### 1. Environment-Specific Configuration
+
+Use environment variables for configuration:
 
 ```typescript
-import { MagentrixClient, SessionInfo } from 'magentrix-sdk'
+const client = new MagentrixClient({
+  baseUrl: process.env.MAGENTRIX_BASE_URL || 'https://default.magentrix.com',
+  refreshToken: process.env.MAGENTRIX_REFRESH_TOKEN,
+  isDevMode: process.env.NODE_ENV === 'development'
+})
+```
 
-const client: MagentrixClient = new MagentrixClient({
-  baseUrl: 'https://your-portal.magentrix.com',
-  refreshToken: 'your-token'
+### 2. Error Handling
+
+Always handle errors appropriately:
+
+```typescript
+try {
+  const result = await client.create('Account', data)
+  // Handle success
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    // Handle database validation errors
+    error.getErrors().forEach(err => {
+      console.error(`${err.fieldName}: ${err.message}`)
+    })
+  } else if (error instanceof MagentrixError) {
+    // Handle general SDK errors
+    console.error('SDK Error:', error.message)
+  } else {
+    // Handle unexpected errors
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+### 3. Session Management
+
+For development mode, create session once at app initialization:
+
+```typescript
+// app.ts or main.ts
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token',
+  isDevMode: true
 })
 
-const sessionInfo: SessionInfo = await client.createSession()
+// Initialize session
+await client.createSession()
+
+// Export for use throughout the app
+export { client }
 ```
 
-## Browser Support
+### 4. Production Deployment
+
+For production (cookie-based auth), no session creation needed:
+
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  isDevMode: false // Uses ASP.NET session cookies
+})
+
+// No need to call createSession()
+// Just use the client directly
+const data = await client.query('SELECT Id FROM Account')
+```
 
-The SDK uses the native Fetch API and supports all modern browsers:
+---
 
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
+## Troubleshooting
 
-For older browsers, you may need to include a fetch polyfill.
+### Common Issues
 
-## Contributing
+**Issue**: `Session expired and no refresh token available`
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+**Solution**: Ensure `refreshToken` is provided in config when using `isDevMode: true`
+
+```typescript
+const client = new MagentrixClient({
+  baseUrl: 'https://your-instance.magentrix.com',
+  refreshToken: 'your-refresh-token', // Required for dev mode
+  isDevMode: true
+})
+```
+
+---
+
+**Issue**: `Login failed` error when creating session
+
+**Solution**: Verify that your refresh token is valid and not expired. Refresh tokens can be obtained from your Magentrix instance.
+
+---
+
+**Issue**: Redirected to login page in production
+
+**Solution**: This is expected behavior when using `isDevMode: false`. The SDK automatically detects session expiration and redirects to the login page. Ensure users are authenticated via ASP.NET Forms Authentication.
+
+---
 
 ## License
 
-MIT
+Proprietary
 
 ## Support
 
-For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/your-org/magentrix-sdk).
+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)
+
+---
+
+## Changelog
+
+### 1.0.0
+- Initial release
+- Token-based and cookie-based authentication
+- CRUD operations
+- Custom queries
+- Vue 3 composable
+- TypeScript support
+- Automatic session management