@ketrics/sdk-backend 0.7.0 → 0.8.0

package/README.md

@@ -1,1513 +1,720 @@
-# @ketrics/sdk-backend
-
-TypeScript type definitions for building tenant applications on the Ketrics platform.
-
-## Installation
-
-```bash
-npm install @ketrics/sdk-backend
-```
+# Ketrics SDK for Backend (@ketrics/sdk-backend)
 
 ## Overview
 
-The SDK provides TypeScript types for the global `ketrics` object that is automatically injected into your tenant application code at runtime. Everything is accessible via the `ketrics` object:
-
-- **Context**: `ketrics.tenant`, `ketrics.application`, `ketrics.user`, `ketrics.env`, `ketrics.environment`
-- **Utilities**: `ketrics.console`, `ketrics.http`
-- **Volume**: `ketrics.Volume.connect()` for S3-backed storage
-- **Database**: `ketrics.DatabaseConnection.connect()` for external database access
-- **Secrets**: `ketrics.Secret.get()` for encrypted secrets
-- **Excel**: `ketrics.Excel.read()` and `ketrics.Excel.create()` for Excel files
-- **PDF**: `ketrics.Pdf.read()` and `ketrics.Pdf.create()` for PDF files
-- **Error classes**: `ketrics.VolumeNotFoundError`, `ketrics.DatabaseError`, etc. for `instanceof` checks
-
----
-
-## Quick Start
-
-```typescript
-// Import types only if needed for type annotations
-import type { FileContent, IVolume, IDatabaseConnection } from '@ketrics/sdk-backend';
-
-export async function handler() {
-  // Context is always available
-  console.log('Tenant:', ketrics.tenant.name);
-  console.log('User:', ketrics.user.email);
-  console.log('App:', ketrics.application.code);
-
-  // Access S3 volumes
-  const volume = await ketrics.Volume.connect('uploads');
-  const file = await volume.get('report.pdf');
-
-  // Access external databases
-  const db = await ketrics.DatabaseConnection.connect('main-db');
-  const result = await db.query('SELECT * FROM users');
-  await db.close();
-
-  // Access encrypted secrets
-  const apiKey = await ketrics.Secret.get('stripe-api-key');
-
-  // Read/write Excel files
-  const workbook = await ketrics.Excel.read(file.content);
-  const sheet = workbook.getWorksheet('Sheet1');
-
-  return { success: true };
-}
-```
-
----
-
-## Context Properties (Read-only)
-
-### Tenant Context
-
-Access information about the current tenant:
-
-```typescript
-ketrics.tenant.id       // Tenant UUID (e.g., "550e8400-e29b-41d4-a716-446655440000")
-ketrics.tenant.code     // Tenant code/slug (e.g., "acme-corp")
-ketrics.tenant.name     // Tenant display name (e.g., "ACME Corporation")
-```
-
-### Application Context
-
-Access information about the current application:
-
-```typescript
-ketrics.application.id           // Application UUID
-ketrics.application.code         // Application code (e.g., "inventory")
-ketrics.application.name         // Application display name (e.g., "Inventory Manager")
-ketrics.application.version      // Application version (optional)
-ketrics.application.deploymentId // Current deployment ID
-```
-
-### User Context
-
-Access information about the user making the request:
-
-```typescript
-ketrics.user.id       // User UUID
-ketrics.user.email    // User email (e.g., "john@example.com")
-ketrics.user.name     // User full name (e.g., "John Doe")
-ketrics.user.isAdmin  // Whether user is tenant admin (boolean)
-```
-
-### Environment Context
-
-Access runtime environment information:
-
-```typescript
-ketrics.env.nodeVersion  // Node.js version (e.g., "v18.17.0")
-ketrics.env.runtime      // Runtime platform ("ecs-fargate")
-ketrics.env.region       // AWS region (e.g., "us-east-1")
-```
-
-### Environment Variables
-
-Access application-level environment variables configured in the Ketrics portal:
-
-```typescript
-// Access custom environment variables set for your application
-const apiEndpoint = ketrics.environment['API_ENDPOINT'];
-const debugMode = ketrics.environment['DEBUG_MODE'];
-const maxRetries = ketrics.environment['MAX_RETRIES'];
-
-// Example: Configure behavior based on env vars
-if (ketrics.environment['FEATURE_FLAG_NEW_UI'] === 'true') {
-  // Use new UI logic
-}
-```
-
----
-
-## Console Logging
-
-Logs are automatically forwarded to CloudWatch with proper context (tenant, application, user, request ID):
-
-```typescript
-ketrics.console.log('Processing order...');
-ketrics.console.info('Order received', { orderId: 123 });
-ketrics.console.warn('Rate limit approaching');
-ketrics.console.error('Failed to process order', { error: err.message });
-ketrics.console.debug('Debug info', { state: currentState });
-```
-
-All log levels are supported:
-- `log()` - General logging
-- `info()` - Informational messages
-- `warn()` - Warning messages
-- `error()` - Error messages
-- `debug()` - Debug messages (may be filtered in production)
-
----
-
-## HTTP Client
-
-Make external API requests with built-in timeout and user agent:
+The Ketrics SDK for Backend is a TypeScript type definition library that provides the complete interface for building tenant applications on the Ketrics platform. This SDK defines the `ketrics` global object—a comprehensive runtime API that tenant code uses to access platform features including storage, databases, secrets management, document generation, background jobs, and messaging.
+
+**Purpose**: This package serves as the type contract between tenant application code and the Ketrics runtime execution environment. It is published as an npm package and consumed by tenant developers building applications that run in isolated VM sandboxes.
+
+**Architecture Context**:
+- Tenant applications run in ECS Fargate containers with Node.js 24+
+- The global `ketrics` object is injected at runtime by the Ketrics platform
+- This SDK provides TypeScript definitions so tenant code has IDE support and type safety
+- The SDK is a pure type definition library (no implementation)
+
+**Key Responsibilities**:
+1. Define all TypeScript interfaces and types for the `ketrics` global object
+2. Provide comprehensive error classes for all SDK operations
+3. Establish the contract between tenant code and the Ketrics runtime
+4. Enable type-safe access to platform capabilities (storage, databases, secrets, etc.)
+
+## Business Logic
+
+### What Problem Does This Solve?
+
+Tenant applications need standardized, type-safe access to platform infrastructure without direct access to underlying services. This SDK enables developers to:
+
+- Read/write files to S3-backed volumes with permission controls
+- Query external databases with transaction support
+- Retrieve encrypted secrets via KMS
+- Generate PDF and Excel documents programmatically
+- Execute long-running tasks asynchronously
+- Send messages to users with multiple channels (inbox, push notifications)
+- Make external API calls with a standardized HTTP client
+- Access tenant and application metadata
+- Log to CloudWatch with proper context
+
+### Core Workflows and Processes
+
+**1. Storage Access (Volumes)**
+- Connect to an S3-backed volume by code
+- Get files (with content, metadata, etag)
+- Put files (with metadata and conditional create)
+- Delete files (single or by prefix)
+- List files with pagination and filtering
+- Copy/move files within volumes
+- Generate presigned URLs for direct browser access
+
+**2. Database Operations**
+- Connect to external databases by code
+- Execute SELECT queries with typed results
+- Execute INSERT/UPDATE/DELETE with affected row counts
+- Run queries within transactions (auto-commit on success, auto-rollback on error)
+- Connection pooling and lifecycle management
+
+**3. Secrets Management**
+- Retrieve encrypted secrets by code
+- Check if a secret exists before accessing
+- Secrets are decrypted using tenant-specific KMS keys
+- Subject to application access grants
+
+**4. Document Generation**
+- **Excel**: Read/parse existing Excel files, create new workbooks, add worksheets, format cells, write files
+- **PDF**: Read/parse existing PDFs, create new documents, draw text/shapes/images, embed fonts, write files
+
+**5. Background Jobs**
+- Queue async function execution with payloads
+- Support cross-app jobs with permission validation
+- Track job status (pending, running, completed, failed)
+- Idempotency keys to prevent duplicate execution
+- Configurable timeouts (default 5min, max 15min)
+
+**6. User Messaging**
+- Send messages to individual users
+- Bulk send to multiple users
+- Send to group members (requires IAM-data permissions)
+- Support for multiple channels: inbox (always) + push notifications (optional)
+- Priority levels: LOW, MEDIUM, HIGH
+- Custom action URLs for deep linking
+
+### Business Rules Implemented
+
+**Access Control**:
+- Volume access requires an access grant to the specific volume
+- Database access requires an access grant with specific permissions
+- Secrets access requires an access grant with decrypt permission
+- Messages to groups require IAM-data tenant permissions (via application role)
+- Cross-app jobs require application grants with background job permission
+
+**Data Boundaries**:
+- Requestor context distinguishes between users (type: "USER") and service accounts (type: "SERVICE_ACCOUNT")
+- Requestor's application permissions determine what operations are allowed
+- Each tenant's secrets are encrypted with tenant-specific KMS keys
+
+**Input/Output Expectations**:
+- File operations support streams, buffers, and strings
+- Database queries return generic typed result objects
+- Job operations return UUID job identifiers
+- List operations support pagination with cursors
+- All timestamps are ISO 8601 strings
+
+**Edge Cases Handled**:
+- File already exists with `ifNotExists` option
+- File size limits enforced on put operations
+- Content type restrictions on volumes
+- Invalid path characters and path traversal detection
+- Connection timeouts with retry semantics
+- Null/undefined secret values
+- Transaction rollback on error
+- Job timeout after max execution time
+- Bulk messaging with partial failures
+
+## Technical Details
+
+### Technology Stack and Dependencies
+
+**Runtime Environment**:
+- Node.js 24.0.0+ (specified in package.json engines)
+- TypeScript 5.0.0+ for compilation
+- ES2020 target with CommonJS module format
+
+**Package Dependencies**:
+- `@types/node@^24.10.2` - Node.js type definitions for stream types (Readable)
+- `typescript@^5.0.0` - TypeScript compiler (dev dependency)
+
+**Key Type System Features**:
+- Strict mode enabled for type safety
+- Declaration maps for source map debugging
+- Module resolution set to "node" for standard npm resolution
+- Force consistent casing for file imports
+
+### File Structure with Purpose
+
+```
+src/
+├── index.ts                    # Main entry point, exports all public types and interfaces
+├── context.ts                  # Runtime context types (tenant, app, requestor, environment)
+├── console.ts                  # Console logger interface
+├── http.ts                     # HTTP client interface for external API calls
+├── databases.ts                # Database connection interfaces and types
+├── database-errors.ts          # Database error class hierarchy
+├── volumes.ts                  # Volume storage interfaces and types
+├── errors.ts                   # Volume error class hierarchy
+├── secrets.ts                  # Secret retrieval interfaces
+├── secret-errors.ts            # Secret error classes
+├── excel.ts                    # Excel workbook interfaces and types
+├── excel-errors.ts             # Excel error classes
+├── pdf.ts                      # PDF document interfaces and types
+├── pdf-errors.ts               # PDF error classes
+├── job.ts                      # Background job types and interfaces
+├── job-errors.ts               # Job execution error classes
+├── messages.ts                 # Message sending interfaces and types
+├── messages-errors.ts          # Message error classes
+└── dist/                       # Compiled JavaScript and .d.ts files (generated)
+```
+
+### Key Functions/Classes and Their Purposes
+
+**Context Interfaces** (`context.ts`):
+- `TenantContext`: Tenant ID, code, and name
+- `ApplicationContext`: Application ID, code, name, version, deployment ID
+- `RequestorContext`: Identifies if request is from USER or SERVICE_ACCOUNT with permissions
+- `RuntimeContext`: Node.js version, AWS region, runtime platform
+- `EnvironmentVariables`: Tenant application environment variables
+
+**SDK Manager Classes** (defined in index.ts as static interfaces):
+
+1. **Volume** - S3-backed file storage
+   - `connect(volumeCode: string): Promise<IVolume>`
+   - Methods: get, put, delete, deleteByPrefix, list, copy, move, downloadUrl, uploadUrl
+
+2. **DatabaseConnection** - External database access
+   - `connect(databaseCode: string): Promise<IDatabaseConnection>`
+   - Methods: query<T>(), execute(), transaction(), close()
+
+3. **Secret** - Encrypted secret retrieval
+   - `get(secretCode: string): Promise<string>`
+   - `exists(secretCode: string): Promise<boolean>`
+
+4. **Excel** - Excel file operations
+   - `read(buffer: Buffer): Promise<IExcelWorkbook>`
+   - `create(): IExcelWorkbook`
+   - Workbook methods: getWorksheet, addWorksheet, writeFile
+
+5. **Pdf** - PDF document operations
+   - `read(buffer: Buffer): Promise<IPdfDocument>`
+   - `create(): Promise<IPdfDocument>`
+   - `rgb(r, g, b): PdfRgbColor`
+   - Document methods: page manipulation, drawing, embedding
+
+6. **Job** - Background job execution
+   - `runInBackground(params: RunInBackgroundParams): Promise<string>` - Returns job ID
+   - `getStatus(jobId: string): Promise<JobStatus>`
+   - `list(params?: JobListParams): Promise<JobListResult>`
+
+7. **Messages** - User messaging
+   - `send(params: SendMessageParams): Promise<SendMessageResult>`
+   - `sendBulk(params: SendBulkMessageParams): Promise<SendBulkMessageResult>`
+   - `sendToGroup(params: SendGroupMessageParams): Promise<SendBulkMessageResult>`
+
+**Error Class Hierarchy**:
+Each feature domain (Volume, Database, Secret, Excel, PDF, Job, Messages) defines:
+- Abstract base error class (extends Error)
+- Specific error subclasses for different failure scenarios
+- Type guards: `is[Feature]Error()`, `is[Feature]ErrorType()`
+
+Example Volume errors:
+- `VolumeError` (abstract base)
+- `VolumeNotFoundError`, `VolumeAccessDeniedError`, `VolumePermissionDeniedError`
+- `FileNotFoundError`, `FileAlreadyExistsError`, `InvalidPathError`
+- `FileSizeLimitError`, `ContentTypeNotAllowedError`
+
+### Configuration Options and Environment Variables
+
+**Tenant Environment Variables** (via `ketrics.environment`):
+- Application-defined key-value pairs passed at deployment time
+- All keys are uppercase with letters, numbers, underscores only
+- Accessed at runtime for configuration (API keys, feature flags, etc.)
+
+**Volume Configuration**:
+- Volume codes define which S3 bucket is accessed
+- Permissions defined per volume: ReadObject, CreateObject, UpdateObject, DeleteObject, ListObjects
+- Content-type restrictions enforced on put operations
+- File size limits enforced per volume
+
+**Database Configuration**:
+- Database codes identify external database servers (PostgreSQL, MySQL, etc.)
+- Permissions per database: read, write, admin
+- Connection pooling managed by runtime
+- Query timeouts configurable
+
+**Excel Configuration**:
+- Tab colors, default row height, default column width configurable per worksheet
+- Column definitions with header, key, width
+
+**PDF Configuration**:
+- Standard page sizes: A4, Letter, Legal, Tabloid, A3, A5
+- Standard fonts: Courier variants, Helvetica variants, TimesRoman variants, Symbol, ZapfDingbats
+- RGB color values (0-1 range)
+- Drawing options: size, opacity, rotation, line height, max width
+
+**Job Configuration**:
+- Timeout range: 1ms to 900,000ms (15 minutes), default 300,000ms (5 minutes)
+- Idempotency keys prevent duplicate job creation
+- Cross-app execution requires application grants
+
+**Message Configuration**:
+- Subject max length: 200 chars
+- Body max length: 10,000 chars (markdown supported)
+- Priority levels: LOW, MEDIUM, HIGH
+- Channels: inbox (always enabled) + push notifications (optional per message)
+
+### External Integrations
+
+**AWS S3** (Volumes):
+- S3 buckets mapped to volume codes
+- Presigned URLs for direct browser download/upload
+- Versioning support via version IDs
+- ETag support for content hashing
+
+**External Databases**:
+- PostgreSQL, MySQL, and other JDBC-compatible databases
+- Connection strings and credentials never exposed to tenant code
+- Parameterized queries to prevent SQL injection
+- Transaction support with automatic rollback
+
+**AWS KMS** (Secrets):
+- Tenant-specific KMS keys for secret encryption
+- Secrets decrypted at request time
+- Decryption errors surface as SecretDecryptionError
+
+**CloudWatch** (Logging):
+- Console logs forwarded to CloudWatch with tenant/app/requestor context
+- Proper log grouping and filtering capabilities
+
+**Application Job Queue**:
+- Background job execution in same or different applications
+- Status tracking in centralized job store
+- Timeout enforcement and error capture
+
+**User Messaging Platform**:
+- Inbox storage for messages
+- Push notification delivery
+- Group membership resolution via IAM service
+
+## Data Flow
+
+### How Data Enters the Component
+
+1. **Context Injection**: At runtime, the Ketrics platform injects a global `ketrics` object with:
+   - Tenant metadata (ID, code, name)
+   - Application metadata (ID, code, version, deploymentId)
+   - Requestor information (type, ID, permissions)
+   - Runtime environment (Node.js version, AWS region)
+   - Environment variables (key-value pairs)
+
+2. **Function Parameters**: Tenant code receives:
+   - HTTP request payloads (JSON, form data, etc.)
+   - File uploads to volumes
+   - Database query parameters
+   - Job payloads
+   - Message content from users
+
+3. **External Services**: Data retrieved from:
+   - S3 via volume.get()
+   - Database queries via db.query()
+   - Secrets via Secret.get()
+   - Uploaded Excel/PDF files via Excel.read(), Pdf.read()
+
+### Transformations Applied
+
+**Volume Operations**:
+- Raw S3 objects → FileContent (buffer + metadata)
+- List operations → Paginated FileInfo arrays with cursors
+- Put operations → PutResult with etag and optional versionId
+- Copy/move → CopyResult/MoveResult with operation status
+
+**Database Operations**:
+- Raw SQL results → DatabaseQueryResult<T> with typed rows
+- Execute operations → DatabaseExecuteResult with affectedRows and insertId
+- Transactions → Implicit begin/commit/rollback with error handling
+
+**Document Operations**:
+- Raw file buffers → IExcelWorkbook/IPdfDocument with method interfaces
+- Workbook operations → Cells, rows, worksheets with formatting
+- PDF drawing → Rendered text, shapes, images on pages
+
+**Job Operations**:
+- RunInBackgroundParams → Job ID string
+- Job polling → JobStatus with timestamps and error details
+- Job listing → Paginated JobStatus arrays with cursor
+
+**Message Operations**:
+- SendMessageParams → SendMessageResult with messageId and status
+- Bulk operations → Aggregated counts (sent, failed) + per-user results
+- Group operations → Member resolution + bulk message delivery
+
+### How Data Exits or Is Persisted
+
+**Persistent Storage**:
+- Volume.put() → Data stored in S3 (encrypted at rest)
+- Database execute() → Data persisted in external database
+- Excel workbook → Buffer written to volume or returned to caller
+- PDF document → Buffer written to volume or returned to caller
+- Message → Stored in user inbox, push notification sent
+
+**Return Values**:
+- Query results → Returned synchronously to caller
+- File content → Streamed or buffered to caller
+- Generated documents → Returned as buffers
+- Job IDs → Returned immediately, execution async
+- Operation results → Status objects with metadata
+
+**External API Calls**:
+- ketrics.http → External API responses via HttpResponse<T>
+- Logging → CloudWatch via ketrics.console
+- Notifications → Push delivery platform
+- Messages → Inbox storage + notification delivery
 
-```typescript
-// GET request
-const response = await ketrics.http.get<MyData>('https://api.example.com/data');
-console.log(response.data, response.status);
-
-// POST request with body
-const result = await ketrics.http.post('https://api.example.com/orders', {
-  product: 'Widget',
-  quantity: 5,
-});
-
-// PUT request
-await ketrics.http.put('https://api.example.com/orders/123', {
-  status: 'shipped',
-});
-
-// DELETE request
-await ketrics.http.delete('https://api.example.com/orders/123');
-
-// With configuration options
-const configured = await ketrics.http.get('https://api.example.com/data', {
-  headers: {
-    'Authorization': 'Bearer token123',
-    'X-Custom-Header': 'value',
-  },
-  timeout: 5000,  // 5 seconds
-  params: { page: 1, limit: 10 },
-  maxRedirects: 3,
-});
-```
-
-### Response Structure
-
-```typescript
-interface HttpResponse<T> {
-  data: T;                          // Response body
-  status: number;                   // HTTP status code (e.g., 200)
-  statusText: string;               // Status text (e.g., "OK")
-  headers: Record<string, string>;  // Response headers
-}
-```
-
----
-
-## Volume Storage (S3-backed)
-
-Access S3-backed file storage with granular permissions:
-
-### Connecting to a Volume
-
-```typescript
-import type { IVolume, FileContent, PutResult, ListResult } from '@ketrics/sdk-backend';
-
-// Connect to a volume by code
-const volume = await ketrics.Volume.connect('uploads');
-
-// Check volume info
-console.log(volume.code);        // 'uploads'
-console.log(volume.permissions); // Set { 'ReadObject', 'CreateObject', ... }
-```
-
-### Reading Files
-
-```typescript
-// Get file content
-const file: FileContent = await volume.get('documents/report.pdf');
-console.log(file.content);        // Buffer containing file data
-console.log(file.contentType);    // 'application/pdf'
-console.log(file.contentLength);  // 12345 (bytes)
-console.log(file.lastModified);   // Date object
-console.log(file.etag);           // '"abc123..."'
-console.log(file.metadata);       // { author: 'john@example.com' }
-
-// Check if file exists (without downloading)
-const exists = await volume.exists('config.json');
-
-// Get file metadata only (no content download)
-const meta = await volume.getMetadata('large-file.zip');
-console.log(meta.size, meta.contentType, meta.lastModified);
-```
-
-### Writing Files
-
-```typescript
-// Write text/JSON content
-const result = await volume.put('output/data.json', JSON.stringify(data), {
-  contentType: 'application/json',
-});
-console.log(result.key, result.etag, result.size);
-
-// Write binary content
-const buffer = Buffer.from('Hello World');
-await volume.put('files/hello.txt', buffer);
-
-// Write with metadata
-await volume.put('documents/report.pdf', pdfBuffer, {
-  contentType: 'application/pdf',
-  metadata: {
-    author: ketrics.user.email,
-    version: '1.0',
-  },
-});
+## Error Handling
 
-// Create only if file doesn't exist
-try {
-  await volume.put('config.json', defaultConfig, { ifNotExists: true });
-} catch (error) {
-  if (error instanceof ketrics.FileAlreadyExistsError) {
-    console.log('Config already exists, skipping');
+### Error Scenarios Considered
+
+Each feature domain handles specific error scenarios:
+
+**Volume Errors**:
+- `VolumeNotFoundError`: Volume code doesn't exist in tenant's namespace
+- `VolumeAccessDeniedError`: Application lacks access grant
+- `VolumePermissionDeniedError`: Specific operation (read/write/delete/list) not permitted
+- `FileNotFoundError`: Requested file doesn't exist
+- `FileAlreadyExistsError`: File exists when `ifNotExists: true`
+- `InvalidPathError`: Path contains invalid characters or traversal attempts (../)
+- `FileSizeLimitError`: File exceeds volume's size limit
+- `ContentTypeNotAllowedError`: MIME type not allowed for volume
+
+**Database Errors**:
+- `DatabaseNotFoundError`: Database code doesn't exist
+- `DatabaseAccessDeniedError`: No access grant to database
+- `DatabaseConnectionError`: Cannot establish connection (network, credentials, server down)
+- `DatabaseQueryError`: SQL syntax error, constraint violation, etc.
+- `DatabaseTransactionError`: Transaction commit/rollback failed
+
+**Secret Errors**:
+- `SecretNotFoundError`: Secret code doesn't exist
+- `SecretAccessDeniedError`: Application lacks access grant
+- `SecretDecryptionError`: KMS decryption failed (corrupted value, key revoked)
+
+**Excel Errors**:
+- `ExcelParseError`: Provided buffer is not valid Excel format
+- `ExcelWriteError`: File write operation failed
+
+**PDF Errors**:
+- `PdfParseError`: Provided buffer is not valid PDF format
+- `PdfWriteError`: File write operation failed
+
+**Job Errors**:
+- `JobNotFoundError`: Job ID doesn't exist
+- `InvalidFunctionError`: Target function name invalid or missing
+- `CrossAppPermissionError`: Application lacks permission for cross-app job
+- `EltJobExecutionError`: Job failed during execution (timeout, runtime error)
+
+**Message Errors**:
+- `MessageValidationError`: Subject/body too long, invalid parameters
+- `GroupNotFoundError`: Group code doesn't exist
+- `TenantGrantPermissionDeniedError`: Application lacks IAM-data permissions for group access
+
+### Retry Logic or Fallback Mechanisms
+
+**Built-in Retry Behaviors**:
+- Database connection pooling automatically handles connection reuse
+- Connection timeouts trigger error rather than unlimited retries (tenant responsibility to retry)
+- Failed bulk messages don't prevent other messages in batch (partial success tracked)
+
+**Tenant-Implemented Retry Patterns**:
+```typescript
+// Retry with exponential backoff
+async function retryWithBackoff(fn, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) throw error;
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
   }
 }
-```
-
-### Listing Files
-
-```typescript
-// List all files
-const list = await volume.list();
-for (const file of list.files) {
-  console.log(file.key, file.size, file.lastModified);
-}
-
-// List with prefix filter
-const docs = await volume.list({ prefix: 'documents/' });
-
-// Paginated listing
-const page1 = await volume.list({ maxResults: 100 });
-if (page1.isTruncated) {
-  const page2 = await volume.list({
-    maxResults: 100,
-    continuationToken: page1.continuationToken,
-  });
-}
-
-// Hierarchical listing with delimiter
-const folders = await volume.list({ delimiter: '/' });
-console.log(folders.folders); // ['documents/', 'images/', 'uploads/']
-```
-
-### Deleting Files
-
-```typescript
-// Delete single file
-await volume.delete('temp/file.txt');
 
-// Delete by prefix (batch delete)
-const result = await volume.deleteByPrefix('temp/');
-console.log(`Deleted ${result.deletedCount} files`);
-console.log('Deleted keys:', result.deletedKeys);
-```
-
-### Copying and Moving Files
-
-```typescript
-// Copy a file
-await volume.copy('source.pdf', 'backup/source.pdf');
-
-// Copy with metadata replacement
-await volume.copy('source.pdf', 'archive/source.pdf', {
-  metadataDirective: 'REPLACE',
-  metadata: { archived: 'true', archivedBy: ketrics.user.email },
-});
-
-// Move a file (copy + delete)
-await volume.move('temp/upload.pdf', 'documents/final.pdf');
-```
-
-### Generating Presigned URLs
-
-```typescript
-// Generate download URL (for sharing)
-const downloadUrl = await volume.generateDownloadUrl('report.pdf', {
-  expiresIn: 3600, // 1 hour
-  responseContentDisposition: 'attachment; filename="report.pdf"',
-});
-console.log(downloadUrl.url);       // Presigned S3 URL
-console.log(downloadUrl.expiresAt); // Expiration Date
-
-// Generate upload URL (for direct client uploads)
-const uploadUrl = await volume.generateUploadUrl('uploads/new-file.pdf', {
-  expiresIn: 3600,
-  contentType: 'application/pdf',
-  maxSize: 10 * 1024 * 1024, // 10MB limit
+// Idempotency keys prevent duplicate job execution
+const jobId = await ketrics.Job.runInBackground({
+  function: 'processPayment',
+  payload: { orderId: '123' },
+  options: { idempotencyKey: 'order-123-payment' }
 });
-// Client can PUT directly to uploadUrl.url
 ```
 
----
-
-## Database Connections
-
-Access external databases (PostgreSQL, MySQL, MSSQL) with connection pooling:
-
-### Connecting to a Database
-
-```typescript
-import type { IDatabaseConnection, DatabaseQueryResult } from '@ketrics/sdk-backend';
-
-// Connect to a database by code
-const db = await ketrics.DatabaseConnection.connect('main-db');
-
-// Check connection info
-console.log(db.code);        // 'main-db'
-console.log(db.permissions); // Set { 'query', 'execute', ... }
-```
-
-### Querying Data
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  created_at: Date;
-}
-
-// Simple query
-const result = await db.query<User>('SELECT * FROM users');
-console.log(result.rows);     // [{ id: 1, name: 'John', ... }, ...]
-console.log(result.rowCount); // 10
-
-// Query with parameters (prevents SQL injection)
-const users = await db.query<User>(
-  'SELECT * FROM users WHERE age > ? AND status = ?',
-  [18, 'active']
-);
-
-// Query single record
-const user = await db.query<User>(
-  'SELECT * FROM users WHERE id = ?',
-  [userId]
-);
-if (user.rows.length > 0) {
-  console.log('Found user:', user.rows[0].name);
-}
-```
-
-### Executing Statements
-
-```typescript
-// INSERT
-const insertResult = await db.execute(
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['John Doe', 'john@example.com']
-);
-console.log(insertResult.affectedRows); // 1
-console.log(insertResult.insertId);     // 123 (auto-increment ID)
-
-// UPDATE
-const updateResult = await db.execute(
-  'UPDATE users SET status = ? WHERE id = ?',
-  ['inactive', userId]
-);
-console.log(updateResult.affectedRows); // Number of rows updated
-
-// DELETE
-const deleteResult = await db.execute(
-  'DELETE FROM users WHERE status = ?',
-  ['deleted']
-);
-console.log(deleteResult.affectedRows); // Number of rows deleted
-```
-
-### Transactions
-
-```typescript
-// Automatic commit on success, rollback on error
-const result = await db.transaction(async (tx) => {
-  // Debit from account
-  await tx.execute(
-    'UPDATE accounts SET balance = balance - ? WHERE id = ?',
-    [100, fromAccountId]
-  );
-
-  // Credit to account
-  await tx.execute(
-    'UPDATE accounts SET balance = balance + ? WHERE id = ?',
-    [100, toAccountId]
-  );
-
-  // Record transfer
-  const transfer = await tx.execute(
-    'INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)',
-    [fromAccountId, toAccountId, 100]
-  );
-
-  return { transferId: transfer.insertId };
-});
+### Logging Approach
 
-console.log('Transfer completed:', result.transferId);
-```
+**Console Logging** (ketrics.console):
+- Methods: log(), error(), warn(), info(), debug()
+- Forwarded to CloudWatch with context:
+  - Tenant ID and code
+  - Application ID and code
+  - Requestor information (user ID or service account ID)
+  - Timestamp
+  - Log level
 
-### Closing Connections
+**Error Logging**:
+- Error classes implement toJSON() for serialization
+- Error properties: name, message, code (operation), timestamp, resource code
+- Security note: Error messages never expose credentials, connection strings, or internal IDs
 
+**Example Logging Pattern**:
 ```typescript
-// Always close when done to return connection to pool
-const db = await ketrics.DatabaseConnection.connect('main-db');
 try {
+  const db = await ketrics.DatabaseConnection.connect('main-db');
+  ketrics.console.log('Connected to database');
   const result = await db.query('SELECT * FROM users');
-  return result.rows;
-} finally {
-  await db.close();
-}
-```
-
----
-
-## Secrets
-
-Access encrypted secrets stored with tenant-specific KMS encryption:
-
-### Getting Secrets
-
-```typescript
-// Get a secret value
-const apiKey = await ketrics.Secret.get('stripe-api-key');
-
-// Use the secret (value is decrypted automatically)
-const response = await ketrics.http.post('https://api.stripe.com/v1/charges', data, {
-  headers: { 'Authorization': `Bearer ${apiKey}` },
-});
-```
-
-### Checking Secret Existence
-
-```typescript
-// Check if a secret exists before using it
-if (await ketrics.Secret.exists('optional-webhook-secret')) {
-  const secret = await ketrics.Secret.get('optional-webhook-secret');
-  // Use the optional secret
-} else {
-  // Use default behavior
-}
-```
-
-### Common Patterns
-
-```typescript
-// Database password from secret
-const dbPassword = await ketrics.Secret.get('db-password');
-
-// API keys
-const stripeKey = await ketrics.Secret.get('stripe-api-key');
-const sendgridKey = await ketrics.Secret.get('sendgrid-api-key');
-
-// OAuth credentials
-const clientId = await ketrics.Secret.get('oauth-client-id');
-const clientSecret = await ketrics.Secret.get('oauth-client-secret');
-```
-
----
-
-## Excel Files
-
-Read and write Excel files (.xlsx) using a simple API:
-
-### Reading Excel Files
-
-```typescript
-import type { IExcelWorkbook, IExcelWorksheet, IExcelRow } from '@ketrics/sdk-backend';
-
-// Read from volume
-const volume = await ketrics.Volume.connect('uploads');
-const file = await volume.get('data/report.xlsx');
-
-// Parse Excel file
-const workbook = await ketrics.Excel.read(file.content);
-
-// Get worksheet by name
-const sheet = workbook.getWorksheet('Sheet1');
-if (!sheet) {
-  throw new Error('Sheet not found');
-}
-
-// Get worksheet by index (1-indexed)
-const firstSheet = workbook.getWorksheet(1);
-
-// List all worksheets
-console.log(`Workbook has ${workbook.worksheetCount} sheets`);
-for (const ws of workbook.worksheets) {
-  console.log(`- ${ws.name}: ${ws.actualRowCount} rows`);
-}
-```
-
-### Reading Rows and Cells
-
-```typescript
-// Get all rows with values
-const rows = sheet.getRows();
-for (const row of rows) {
-  console.log('Row', row.number, ':', row.values);
+  ketrics.console.log(`Retrieved ${result.rowCount} users`);
+} catch (error) {
+  if (error instanceof ketrics.DatabaseQueryError) {
+    ketrics.console.error('Database query failed', error.toJSON());
+  } else {
+    ketrics.console.error('Unexpected error', { message: error.message });
+  }
 }
-
-// Get a specific row (1-indexed)
-const headerRow = sheet.getRow(1);
-console.log('Headers:', headerRow.values);
-
-// Get a specific cell
-const cell = sheet.getCell('A1');
-console.log(cell.value, cell.text, cell.address);
-
-// Get cell by coordinates
-const cellB2 = sheet.getCell(2, 2);
-
-// Iterate over rows
-sheet.eachRow((row, rowNumber) => {
-  console.log(`Row ${rowNumber}:`, row.values);
-});
-
-// Include empty rows
-sheet.eachRow((row, rowNumber) => {
-  console.log(`Row ${rowNumber}:`, row.values);
-}, { includeEmpty: true });
-
-// Get all values as 2D array
-const allValues = sheet.getSheetValues();
-// allValues[1] = first row, allValues[1][1] = cell A1
-```
-
-### Working with Cells
-
-```typescript
-// Get cell properties
-const cell = sheet.getCell('B5');
-console.log(cell.value);    // Cell value (number, string, Date, etc.)
-console.log(cell.text);     // Text representation
-console.log(cell.address);  // 'B5'
-console.log(cell.row);      // 5
-console.log(cell.col);      // 2
-console.log(cell.formula);  // Formula if present (e.g., '=SUM(A1:A10)')
-console.log(cell.type);     // Cell type
-
-// Iterate over cells in a row
-const row = sheet.getRow(1);
-row.eachCell((cell, colNumber) => {
-  console.log(`Column ${colNumber}:`, cell.value);
-});
-```
-
-### Creating Excel Files
-
-```typescript
-// Create new workbook
-const workbook = ketrics.Excel.create();
-
-// Add worksheet
-const sheet = workbook.addWorksheet('Sales Report', {
-  tabColor: 'FF0000', // Red tab
-  defaultRowHeight: 20,
-  defaultColWidth: 15,
-});
-
-// Define columns (optional)
-sheet.columns = [
-  { header: 'ID', key: 'id', width: 10 },
-  { header: 'Product', key: 'product', width: 30 },
-  { header: 'Price', key: 'price', width: 15 },
-  { header: 'Quantity', key: 'qty', width: 10 },
-];
-
-// Add rows
-sheet.addRow(['1', 'Widget A', 9.99, 100]);
-sheet.addRow(['2', 'Widget B', 19.99, 50]);
-sheet.addRow(['3', 'Widget C', 29.99, 25]);
-
-// Add multiple rows at once
-sheet.addRows([
-  ['4', 'Widget D', 39.99, 10],
-  ['5', 'Widget E', 49.99, 5],
-]);
-
-// Insert row at position
-sheet.insertRow(2, ['INSERTED', 'Row', 0, 0]);
-
-// Merge cells
-sheet.mergeCells('A1', 'D1'); // Merge A1:D1
-sheet.mergeCells(5, 1, 5, 4); // Merge row 5, columns 1-4
-
-// Write to buffer
-const buffer = await workbook.toBuffer();
-
-// Save to volume
-await volume.put('output/report.xlsx', buffer, {
-  contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-});
 ```
 
-### Converting to CSV
-
-```typescript
-// Convert worksheet to CSV
-const csvContent = await workbook.toCsv('Sheet1');
+## Usage
 
-// Save as CSV
-await volume.put('output/data.csv', csvContent, {
-  contentType: 'text/csv',
-});
-```
+### How to Run/Deploy This Component
 
-### Managing Worksheets
+This is a type definition library. It does not run standalone but is consumed by tenant applications.
 
-```typescript
-// Remove worksheet
-workbook.removeWorksheet('TempSheet');
-workbook.removeWorksheet(2); // By index
-
-// Rename worksheet
-const sheet = workbook.getWorksheet('OldName');
-if (sheet) {
-  sheet.name = 'NewName';
-}
+**Installation in Tenant Application**:
+```bash
+npm install @ketrics/sdk-backend
 ```
 
----
-
-## PDF Files
-
-Read, create, and modify PDF files using the pdf-lib wrapper:
-
-### Reading PDF Files
-
-```typescript
-import type { IPdfDocument, IPdfPage } from '@ketrics/sdk-backend';
-
-// Read from volume
-const volume = await ketrics.Volume.connect('uploads');
-const file = await volume.get('documents/report.pdf');
-
-// Parse PDF file
-const doc = await ketrics.Pdf.read(file.content);
-
-// Get document info
-console.log('Page count:', doc.getPageCount());
-console.log('Title:', doc.getTitle());
-console.log('Author:', doc.getAuthor());
-
-// Get all pages
-const pages = doc.getPages();
-for (const page of pages) {
-  console.log(`Page size: ${page.width}x${page.height}`);
+**TypeScript Configuration** (tsconfig.json):
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "lib": ["ES2020"],
+    "types": ["@ketrics/sdk-backend"]
+  }
 }
-
-// Get specific page (0-indexed)
-const firstPage = doc.getPage(0);
-console.log('First page size:', firstPage.getSize());
-```
-
-### Creating PDF Files
-
-```typescript
-// Create new empty document
-const doc = await ketrics.Pdf.create();
-
-// Set document metadata
-doc.setTitle('Sales Report Q4 2024');
-doc.setAuthor(ketrics.user.name);
-doc.setSubject('Quarterly sales data');
-doc.setKeywords(['sales', 'report', 'Q4', '2024']);
-doc.setCreator('Ketrics Application');
-
-// Add pages with different sizes
-const pageA4 = doc.addPage('A4');        // Standard A4
-const pageLetter = doc.addPage('Letter'); // US Letter
-const pageCustom = doc.addPage([600, 400]); // Custom size in points
-
-// Insert page at specific position (0-indexed)
-const insertedPage = doc.insertPage(1, 'A4');
-
-// Remove a page
-doc.removePage(2);
-
-// Write to buffer
-const buffer = await doc.toBuffer();
-
-// Save to volume
-await volume.put('output/report.pdf', buffer, {
-  contentType: 'application/pdf',
-});
-```
-
-### Drawing Text
-
-```typescript
-const doc = await ketrics.Pdf.create();
-const page = doc.addPage('A4');
-
-// Simple text (default: Helvetica, 12pt, black)
-await page.drawText('Hello, World!', { x: 50, y: 700 });
-
-// Styled text
-await page.drawText('Large Red Title', {
-  x: 50,
-  y: 750,
-  size: 32,
-  color: ketrics.Pdf.rgb(1, 0, 0), // Red (RGB values 0-1)
-});
-
-// Text with custom font
-const boldFont = await doc.embedStandardFont('HelveticaBold');
-await page.drawText('Bold Text', {
-  x: 50,
-  y: 650,
-  size: 16,
-  font: boldFont,
-});
-
-// Rotated text
-await page.drawText('Rotated', {
-  x: 200,
-  y: 500,
-  size: 14,
-  rotate: 45, // degrees
-});
-
-// Text with opacity
-await page.drawText('Semi-transparent', {
-  x: 50,
-  y: 600,
-  size: 14,
-  opacity: 0.5,
-});
-
-// Multiline text with wrapping
-await page.drawText('This is a long paragraph that will wrap to multiple lines when it exceeds the maximum width.', {
-  x: 50,
-  y: 550,
-  size: 12,
-  maxWidth: 200,
-  lineHeight: 16,
-});
 ```
 
-### Drawing Shapes
-
-```typescript
-const doc = await ketrics.Pdf.create();
-const page = doc.addPage('A4');
-
-// Rectangle (filled)
-page.drawRectangle({
-  x: 50,
-  y: 600,
-  width: 200,
-  height: 100,
-  color: ketrics.Pdf.rgb(0.2, 0.4, 0.8), // Blue fill
-});
-
-// Rectangle (outlined)
-page.drawRectangle({
-  x: 50,
-  y: 480,
-  width: 200,
-  height: 100,
-  borderColor: ketrics.Pdf.rgb(0, 0, 0),
-  borderWidth: 2,
-});
-
-// Rectangle (filled with border)
-page.drawRectangle({
-  x: 50,
-  y: 360,
-  width: 200,
-  height: 100,
-  color: ketrics.Pdf.rgb(0.9, 0.9, 0.9), // Light gray fill
-  borderColor: ketrics.Pdf.rgb(0, 0, 0),
-  borderWidth: 1,
-  opacity: 0.8,
-});
-
-// Line
-page.drawLine({
-  start: { x: 50, y: 340 },
-  end: { x: 250, y: 340 },
-  thickness: 2,
-  color: ketrics.Pdf.rgb(0, 0, 0),
-});
-
-// Circle
-page.drawCircle({
-  x: 150,
-  y: 250,
-  radius: 50,
-  color: ketrics.Pdf.rgb(0.8, 0.2, 0.2), // Red fill
-  borderColor: ketrics.Pdf.rgb(0, 0, 0),
-  borderWidth: 2,
-});
-```
-
-### Embedding Images
-
-```typescript
-const doc = await ketrics.Pdf.create();
-const page = doc.addPage('A4');
-
-// Read image from volume
-const volume = await ketrics.Volume.connect('uploads');
-const logoFile = await volume.get('images/logo.png');
-const photoFile = await volume.get('images/photo.jpg');
-
-// Embed PNG image
-const pngImage = await doc.embedPng(logoFile.content);
-console.log('PNG dimensions:', pngImage.width, 'x', pngImage.height);
-
-// Embed JPG image
-const jpgImage = await doc.embedJpg(photoFile.content);
-
-// Draw image at original size
-page.drawImage(pngImage, { x: 50, y: 700 });
-
-// Draw image at specific size
-page.drawImage(jpgImage, {
-  x: 50,
-  y: 500,
-  width: 200,
-  height: 150,
-});
-
-// Draw image with opacity
-page.drawImage(pngImage, {
-  x: 300,
-  y: 700,
-  opacity: 0.5,
-});
+**Building the SDK Package**:
+```bash
+# Install dependencies
+npm install
 
-// Scale image to fit within bounds
-const scaled = pngImage.scaleToFit(150, 100);
-page.drawImage(pngImage, {
-  x: 50,
-  y: 350,
-  width: scaled.width,
-  height: scaled.height,
-});
+# Compile TypeScript to JavaScript
+npm run build
 
-// Scale image by factor
-const factor = pngImage.scale(0.5);
-page.drawImage(pngImage, {
-  x: 250,
-  y: 350,
-  width: factor.width,
-  height: factor.height,
-});
+# Output: dist/ folder with .js, .d.ts, .map files
 ```
 
-### Working with Fonts
-
-```typescript
-const doc = await ketrics.Pdf.create();
-const page = doc.addPage('A4');
-
-// Embed standard fonts (14 built-in fonts available)
-const helvetica = await doc.embedStandardFont('Helvetica');
-const helveticaBold = await doc.embedStandardFont('HelveticaBold');
-const timesRoman = await doc.embedStandardFont('TimesRoman');
-const courier = await doc.embedStandardFont('Courier');
-
-// Use different fonts
-await page.drawText('Helvetica Regular', { x: 50, y: 750, font: helvetica, size: 14 });
-await page.drawText('Helvetica Bold', { x: 50, y: 720, font: helveticaBold, size: 14 });
-await page.drawText('Times Roman', { x: 50, y: 690, font: timesRoman, size: 14 });
-await page.drawText('Courier', { x: 50, y: 660, font: courier, size: 14 });
-
-// Calculate text width for positioning
-const text = 'Right-aligned text';
-const textWidth = helvetica.widthOfTextAtSize(text, 14);
-await page.drawText(text, {
-  x: page.width - 50 - textWidth, // Right-align with 50pt margin
-  y: 600,
-  font: helvetica,
-  size: 14,
-});
-
-// Get font height
-const lineHeight = helvetica.heightAtSize(14);
-console.log('Line height:', lineHeight);
-
-// Embed custom font from file
-const customFontFile = await volume.get('fonts/OpenSans-Regular.ttf');
-const customFont = await doc.embedFont(customFontFile.content);
-await page.drawText('Custom Font', { x: 50, y: 550, font: customFont, size: 14 });
+**Publishing**:
+```bash
+npm publish
 ```
 
-### Available Standard Fonts
-
-| Font Name | Description |
-|-----------|-------------|
-| `Helvetica` | Sans-serif regular |
-| `HelveticaBold` | Sans-serif bold |
-| `HelveticaOblique` | Sans-serif italic |
-| `HelveticaBoldOblique` | Sans-serif bold italic |
-| `TimesRoman` | Serif regular |
-| `TimesRomanBold` | Serif bold |
-| `TimesRomanItalic` | Serif italic |
-| `TimesRomanBoldItalic` | Serif bold italic |
-| `Courier` | Monospace regular |
-| `CourierBold` | Monospace bold |
-| `CourierOblique` | Monospace italic |
-| `CourierBoldOblique` | Monospace bold italic |
-| `Symbol` | Symbol characters |
-| `ZapfDingbats` | Decorative symbols |
-
-### Page Sizes
-
-| Size | Dimensions (points) |
-|------|---------------------|
-| `A4` | 595 x 842 |
-| `A3` | 842 x 1191 |
-| `A5` | 420 x 595 |
-| `Letter` | 612 x 792 |
-| `Legal` | 612 x 1008 |
-| `Tabloid` | 792 x 1224 |
-
-### Merging PDF Documents
+This publishes to npm registry at https://www.npmjs.com/package/@ketrics/sdk-backend
 
-```typescript
-// Read source documents
-const volume = await ketrics.Volume.connect('uploads');
-const file1 = await volume.get('doc1.pdf');
-const file2 = await volume.get('doc2.pdf');
-
-const doc1 = await ketrics.Pdf.read(file1.content);
-const doc2 = await ketrics.Pdf.read(file2.content);
-
-// Create merged document
-const mergedDoc = await ketrics.Pdf.create();
-mergedDoc.setTitle('Merged Document');
-
-// Copy all pages from doc1
-const doc1Pages = await mergedDoc.copyPages(doc1,
-  Array.from({ length: doc1.getPageCount() }, (_, i) => i)
-);
-
-// Copy specific pages from doc2 (pages 0 and 2)
-const doc2Pages = await mergedDoc.copyPages(doc2, [0, 2]);
-
-// Save merged document
-const buffer = await mergedDoc.toBuffer();
-await volume.put('merged.pdf', buffer, {
-  contentType: 'application/pdf',
-});
-```
-
-### Modifying Existing PDFs
+### Example Invocations
 
+**Complete Tenant Application Example**:
 ```typescript
-// Read existing PDF
-const volume = await ketrics.Volume.connect('uploads');
-const file = await volume.get('template.pdf');
-const doc = await ketrics.Pdf.read(file.content);
-
-// Get first page and add watermark
-const page = doc.getPage(0);
-await page.drawText('CONFIDENTIAL', {
-  x: page.width / 2 - 100,
-  y: page.height / 2,
-  size: 48,
-  color: ketrics.Pdf.rgb(0.9, 0.1, 0.1),
-  opacity: 0.3,
-  rotate: 45,
-});
-
-// Add footer to all pages
-const pages = doc.getPages();
-for (let i = 0; i < pages.length; i++) {
-  const p = pages[i];
-  await p.drawText(`Page ${i + 1} of ${pages.length}`, {
-    x: p.width / 2 - 30,
-    y: 30,
-    size: 10,
-    color: ketrics.Pdf.rgb(0.5, 0.5, 0.5),
-  });
-}
-
-// Save modified document
-const buffer = await doc.toBuffer();
-await volume.put('modified.pdf', buffer, {
-  contentType: 'application/pdf',
-});
-```
-
-### Complete PDF Generation Example
+// handler.ts - Tenant application code
 
-```typescript
-export async function generateInvoice(orderId: string) {
-  // Get order data from database
-  const db = await ketrics.DatabaseConnection.connect('orders-db');
-  const orderResult = await db.query(
-    'SELECT * FROM orders WHERE id = ?',
-    [orderId]
-  );
-  const order = orderResult.rows[0];
-  await db.close();
-
-  // Create PDF
-  const doc = await ketrics.Pdf.create();
-  doc.setTitle(`Invoice #${order.invoice_number}`);
-  doc.setAuthor(ketrics.tenant.name);
-
-  const page = doc.addPage('A4');
-  const { width, height } = page.getSize();
-
-  // Embed fonts
-  const boldFont = await doc.embedStandardFont('HelveticaBold');
-  const regularFont = await doc.embedStandardFont('Helvetica');
-
-  // Header
-  await page.drawText(ketrics.tenant.name, {
-    x: 50,
-    y: height - 50,
-    size: 24,
-    font: boldFont,
-  });
-
-  await page.drawText(`Invoice #${order.invoice_number}`, {
-    x: 50,
-    y: height - 90,
-    size: 18,
-    font: regularFont,
-    color: ketrics.Pdf.rgb(0.4, 0.4, 0.4),
-  });
-
-  // Customer info
-  await page.drawText('Bill To:', {
-    x: 50,
-    y: height - 150,
-    size: 12,
-    font: boldFont,
-  });
-
-  await page.drawText(order.customer_name, {
-    x: 50,
-    y: height - 170,
-    size: 12,
-    font: regularFont,
-  });
-
-  // Line items header
-  const tableTop = height - 250;
-  page.drawRectangle({
-    x: 50,
-    y: tableTop - 5,
-    width: width - 100,
-    height: 25,
-    color: ketrics.Pdf.rgb(0.9, 0.9, 0.9),
-  });
-
-  await page.drawText('Item', { x: 55, y: tableTop, size: 10, font: boldFont });
-  await page.drawText('Qty', { x: 300, y: tableTop, size: 10, font: boldFont });
-  await page.drawText('Price', { x: 380, y: tableTop, size: 10, font: boldFont });
-  await page.drawText('Total', { x: 460, y: tableTop, size: 10, font: boldFont });
-
-  // Line items (simplified example)
-  let yPos = tableTop - 30;
-  for (const item of order.items) {
-    await page.drawText(item.name, { x: 55, y: yPos, size: 10, font: regularFont });
-    await page.drawText(String(item.quantity), { x: 300, y: yPos, size: 10, font: regularFont });
-    await page.drawText(`$${item.price.toFixed(2)}`, { x: 380, y: yPos, size: 10, font: regularFont });
-    await page.drawText(`$${(item.quantity * item.price).toFixed(2)}`, { x: 460, y: yPos, size: 10, font: regularFont });
-    yPos -= 20;
+export async function processOrder(payload: { orderId: string }) {
+  try {
+    // Access context
+    ketrics.console.log(`Processing for tenant: ${ketrics.tenant.name}`);
+    ketrics.console.log(`Requestor: ${ketrics.requestor.name} (${ketrics.requestor.type})`);
+
+    // Get secret
+    const apiKey = await ketrics.Secret.get('stripe-api-key');
+
+    // Query database
+    const db = await ketrics.DatabaseConnection.connect('orders-db');
+    try {
+      const result = await db.query<Order>(
+        'SELECT * FROM orders WHERE id = ?',
+        [payload.orderId]
+      );
+      if (result.rowCount === 0) {
+        return { error: 'Order not found' };
+      }
+      const order = result.rows[0];
+
+      // Make external API call
+      const response = await ketrics.http.post<ShipmentResponse>(
+        'https://shipping-api.example.com/create-shipment',
+        { orderId: order.id, address: order.shippingAddress },
+        { headers: { 'Authorization': `Bearer ${apiKey}` } }
+      );
+
+      // Store file in volume
+      const volume = await ketrics.Volume.connect('orders');
+      const result = await volume.put(
+        `shipments/${order.id}/label.pdf`,
+        response.data.labelPdf,
+        { contentType: 'application/pdf' }
+      );
+
+      // Update database in transaction
+      await db.transaction(async (tx) => {
+        await tx.execute(
+          'UPDATE orders SET status = ?, shipment_id = ? WHERE id = ?',
+          ['shipped', response.data.shipmentId, order.id]
+        );
+      });
+
+      // Send message to user
+      await ketrics.Messages.send({
+        userId: order.userId,
+        type: 'ORDER_SHIPPED',
+        subject: 'Your order has shipped!',
+        body: `Track your package at: ${response.data.trackingUrl}`,
+        priority: 'HIGH',
+        actionUrl: response.data.trackingUrl
+      });
+
+      // Queue async job
+      const jobId = await ketrics.Job.runInBackground({
+        function: 'sendShipmentNotifications',
+        payload: { orderId: order.id },
+        options: { timeout: 60000 }
+      });
+
+      return {
+        success: true,
+        shipmentId: response.data.shipmentId,
+        jobId: jobId
+      };
+    } finally {
+      await db.close();
+    }
+  } catch (error) {
+    ketrics.console.error('Order processing failed', { error: error.message });
+    throw error;
   }
-
-  // Total line
-  page.drawLine({
-    start: { x: 380, y: yPos + 5 },
-    end: { x: width - 50, y: yPos + 5 },
-    thickness: 1,
-    color: ketrics.Pdf.rgb(0, 0, 0),
-  });
-
-  await page.drawText('Total:', { x: 380, y: yPos - 15, size: 12, font: boldFont });
-  await page.drawText(`$${order.total.toFixed(2)}`, { x: 460, y: yPos - 15, size: 12, font: boldFont });
-
-  // Footer
-  await page.drawText(`Generated on ${new Date().toLocaleDateString()}`, {
-    x: 50,
-    y: 30,
-    size: 8,
-    color: ketrics.Pdf.rgb(0.6, 0.6, 0.6),
-  });
-
-  // Save to volume
-  const volume = await ketrics.Volume.connect('invoices');
-  const buffer = await doc.toBuffer();
-  await volume.put(`${order.invoice_number}.pdf`, buffer, {
-    contentType: 'application/pdf',
-    metadata: {
-      orderId: order.id,
-      generatedBy: ketrics.user.email,
-    },
-  });
-
-  return {
-    success: true,
-    invoiceNumber: order.invoice_number,
-  };
 }
-```
-
----
-
-## Error Handling
 
-All error classes are available on the `ketrics` object for `instanceof` checks:
-
-### Volume Errors
-
-```typescript
-try {
-  const volume = await ketrics.Volume.connect('uploads');
-  const file = await volume.get('missing.txt');
-} catch (error) {
-  if (error instanceof ketrics.VolumeNotFoundError) {
-    console.log(`Volume '${error.volumeCode}' not found`);
-  } else if (error instanceof ketrics.VolumeAccessDeniedError) {
-    console.log(`No access to volume '${error.volumeCode}'`);
-  } else if (error instanceof ketrics.VolumePermissionDeniedError) {
-    console.log(`Missing permission: ${error.requiredPermission}`);
-  } else if (error instanceof ketrics.FileNotFoundError) {
-    console.log(`File '${error.key}' not found`);
-  } else if (error instanceof ketrics.FileAlreadyExistsError) {
-    console.log(`File '${error.key}' already exists`);
-  } else if (error instanceof ketrics.FileSizeLimitError) {
-    console.log(`File too large: ${error.size} > ${error.maxSize}`);
-  } else if (error instanceof ketrics.ContentTypeNotAllowedError) {
-    console.log(`Type '${error.contentType}' not allowed. Use: ${error.allowedTypes.join(', ')}`);
-  } else if (error instanceof ketrics.InvalidPathError) {
-    console.log(`Invalid path '${error.path}': ${error.reason}`);
-  } else if (error instanceof ketrics.VolumeError) {
-    // Base class catches all volume errors
-    console.log(`Volume error: ${error.message}`);
-    console.log(error.toJSON());
-  } else {
-    throw error;
+export async function generateMonthlyReport() {
+  try {
+    // Create Excel workbook
+    const workbook = ketrics.Excel.create();
+    const sheet = workbook.addWorksheet('Sales Report');
+
+    // Query all transactions
+    const db = await ketrics.DatabaseConnection.connect('analytics-db');
+    try {
+      const result = await db.query<Transaction>(
+        'SELECT * FROM transactions WHERE month = MONTH(NOW())'
+      );
+
+      // Populate worksheet
+      sheet.addRow(['Date', 'Amount', 'Category']);
+      for (const tx of result.rows) {
+        sheet.addRow([new Date(tx.date), tx.amount, tx.category]);
+      }
+
+      // Write to volume
+      const buffer = await workbook.writeFile();
+      const volume = await ketrics.Volume.connect('reports');
+      await volume.put(`monthly/${new Date().toISOString().split('T')[0]}.xlsx`, buffer);
+
+      // Send to group (requires IAM-data permissions)
+      await ketrics.Messages.sendToGroup({
+        groupCode: 'finance-team',
+        type: 'REPORT_READY',
+        subject: 'Monthly Sales Report',
+        body: 'Your monthly sales report is ready',
+        priority: 'MEDIUM'
+      });
+
+      return { success: true };
+    } finally {
+      await db.close();
+    }
+  } catch (error) {
+    if (error instanceof ketrics.GroupNotFoundError) {
+      ketrics.console.error(`Group not found: ${error.message}`);
+    } else if (error instanceof ketrics.ExcelWriteError) {
+      ketrics.console.error('Failed to write Excel file');
+    } else {
+      throw error;
+    }
   }
 }
 ```
 
-### Database Errors
-
+**Error Handling Patterns**:
 ```typescript
+// Type guards for error handling
 try {
   const db = await ketrics.DatabaseConnection.connect('main-db');
-  await db.query('SELECT * FROM users');
 } catch (error) {
-  if (error instanceof ketrics.DatabaseNotFoundError) {
-    console.log(`Database '${error.databaseCode}' not found`);
-  } else if (error instanceof ketrics.DatabaseAccessDeniedError) {
-    console.log(`No access to database '${error.databaseCode}'`);
-  } else if (error instanceof ketrics.DatabaseConnectionError) {
-    console.log(`Connection failed: ${error.reason}`);
-  } else if (error instanceof ketrics.DatabaseQueryError) {
-    console.log(`Query failed: ${error.reason}`);
-    if (error.sql) console.log(`SQL: ${error.sql}`);
-  } else if (error instanceof ketrics.DatabaseTransactionError) {
-    console.log(`Transaction failed: ${error.reason}`);
-    console.log(`Rolled back: ${error.rolledBack}`);
-  } else if (error instanceof ketrics.DatabaseError) {
-    // Base class catches all database errors
+  if (ketrics.isDatabaseError(error)) {
+    // Specific database error
     console.log(`Database error: ${error.message}`);
-  } else {
-    throw error;
-  }
-}
-```
-
-### Secret Errors
-
-```typescript
-try {
-  const secret = await ketrics.Secret.get('api-key');
-} catch (error) {
-  if (error instanceof ketrics.SecretNotFoundError) {
-    console.log(`Secret '${error.secretCode}' not found`);
-  } else if (error instanceof ketrics.SecretAccessDeniedError) {
-    console.log(`No access to secret '${error.secretCode}'`);
-  } else if (error instanceof ketrics.SecretDecryptionError) {
-    console.log(`Decryption failed: ${error.reason}`);
-  } else if (error instanceof ketrics.SecretError) {
-    // Base class catches all secret errors
-    console.log(`Secret error: ${error.message}`);
-  } else {
-    throw error;
   }
-}
-```
-
-### Excel Errors
-
-```typescript
-try {
-  const workbook = await ketrics.Excel.read(buffer);
-  const outputBuffer = await workbook.toBuffer();
-} catch (error) {
-  if (error instanceof ketrics.ExcelParseError) {
-    console.log(`Failed to parse Excel: ${error.reason}`);
-  } else if (error instanceof ketrics.ExcelWriteError) {
-    console.log(`Failed to write Excel: ${error.reason}`);
-  } else if (error instanceof ketrics.ExcelError) {
-    // Base class catches all Excel errors
-    console.log(`Excel error: ${error.message}`);
-  } else {
-    throw error;
-  }
-}
-```
-
-### PDF Errors
 
-```typescript
-try {
-  const doc = await ketrics.Pdf.read(buffer);
-  const page = doc.addPage('A4');
-  await page.drawText('Hello');
-  const outputBuffer = await doc.toBuffer();
-} catch (error) {
-  if (error instanceof ketrics.PdfParseError) {
-    console.log(`Failed to parse PDF: ${error.reason}`);
-  } else if (error instanceof ketrics.PdfWriteError) {
-    console.log(`Failed to write PDF: ${error.reason}`);
-  } else if (error instanceof ketrics.PdfError) {
-    // Base class catches all PDF errors
-    console.log(`PDF error: ${error.message}`);
-  } else {
-    throw error;
+  if (ketrics.isDatabaseErrorType(error, 'DatabaseNotFoundError')) {
+    // Exact error type check
+    console.log(`Database not found: ${error.databaseCode}`);
   }
-}
-```
-
----
-
-## Error Class Reference
-
-### Volume Errors
-
-| Error Class | When Thrown |
-|-------------|-------------|
-| `VolumeError` | Base class for all volume errors |
-| `VolumeNotFoundError` | Volume doesn't exist |
-| `VolumeAccessDeniedError` | Application has no access grant |
-| `VolumePermissionDeniedError` | Missing required permission (Read, Create, Update, Delete, List) |
-| `FileNotFoundError` | File doesn't exist |
-| `FileAlreadyExistsError` | File exists (with `ifNotExists` option) |
-| `InvalidPathError` | Invalid file path (e.g., path traversal attempt) |
-| `FileSizeLimitError` | File exceeds volume size limit |
-| `ContentTypeNotAllowedError` | Content type not allowed by volume |
-
-### Database Errors
-
-| Error Class | When Thrown |
-|-------------|-------------|
-| `DatabaseError` | Base class for all database errors |
-| `DatabaseNotFoundError` | Database doesn't exist |
-| `DatabaseAccessDeniedError` | Application has no access grant |
-| `DatabaseConnectionError` | Connection cannot be established |
-| `DatabaseQueryError` | SQL query fails |
-| `DatabaseTransactionError` | Transaction fails (automatically rolled back) |
-
-### Secret Errors
-
-| Error Class | When Thrown |
-|-------------|-------------|
-| `SecretError` | Base class for all secret errors |
-| `SecretNotFoundError` | Secret doesn't exist |
-| `SecretAccessDeniedError` | Application has no access grant |
-| `SecretDecryptionError` | KMS decryption fails |
-
-### Excel Errors
-
-| Error Class | When Thrown |
-|-------------|-------------|
-| `ExcelError` | Base class for all Excel errors |
-| `ExcelParseError` | File cannot be parsed (invalid/corrupted) |
-| `ExcelWriteError` | File cannot be written |
-
-### PDF Errors
-
-| Error Class | When Thrown |
-|-------------|-------------|
-| `PdfError` | Base class for all PDF errors |
-| `PdfParseError` | PDF file cannot be parsed (invalid/corrupted) |
-| `PdfWriteError` | PDF file cannot be written |
-
----
-
-## Type Exports
-
-All types are exported for use in your application:
 
-```typescript
-import type {
-  // Context
-  TenantContext,
-  ApplicationContext,
-  UserContext,
-  EnvironmentContext,
-
-  // Console
-  ConsoleLogger,
-
-  // HTTP
-  HttpRequestConfig,
-  HttpResponse,
-  HttpClient,
-
-  // Volumes
-  IVolume,
-  PutContent,
-  FileContent,
-  FileMetadata,
-  FileInfo,
-  PutOptions,
-  PutResult,
-  DeleteResult,
-  DeleteByPrefixResult,
-  ListOptions,
-  ListResult,
-  CopyOptions,
-  CopyResult,
-  MoveOptions,
-  MoveResult,
-  DownloadUrlOptions,
-  UploadUrlOptions,
-  PresignedUrl,
-
-  // Databases
-  IDatabaseConnection,
-  DatabaseQueryResult,
-  DatabaseExecuteResult,
-  DatabaseManager,
-
-  // Secrets
-  ISecret,
-
-  // Excel
-  IExcelWorkbook,
-  IExcelWorksheet,
-  IExcelRow,
-  IExcelCell,
-  ExcelCellValue,
-  ExcelRowValues,
-  ExcelColumnDefinition,
-  AddWorksheetOptions,
-  ExcelManager,
-
-  // PDF
-  IPdfDocument,
-  IPdfPage,
-  PdfPageSize,
-  PdfStandardFont,
-  PdfRgbColor,
-  PdfDrawTextOptions,
-  PdfDrawRectOptions,
-  PdfDrawLineOptions,
-  PdfDrawCircleOptions,
-  PdfDrawImageOptions,
-  PdfEmbeddedImage,
-  PdfEmbeddedFont,
-  PdfManager,
-
-  // Main SDK
-  KetricsSdkV1,
-} from '@ketrics/sdk-backend';
-```
-
----
-
-## Complete Example
-
-Here's a complete example showing multiple SDK features working together:
-
-```typescript
-import type { IVolume, IDatabaseConnection, FileContent } from '@ketrics/sdk-backend';
-
-interface Order {
-  id: number;
-  customer_name: string;
-  total: number;
-  status: string;
-}
-
-export async function generateReport() {
-  ketrics.console.log('Starting report generation', {
-    tenant: ketrics.tenant.code,
-    user: ketrics.user.email,
-  });
-
-  // Get API key from secrets
-  const emailApiKey = await ketrics.Secret.get('sendgrid-api-key');
-
-  // Connect to database
-  const db = await ketrics.DatabaseConnection.connect('orders-db');
-
-  try {
-    // Query orders from database
-    const orders = await db.query<Order>(
-      'SELECT * FROM orders WHERE status = ? AND created_at > ?',
-      ['completed', '2024-01-01']
-    );
-
-    ketrics.console.info(`Found ${orders.rowCount} orders`);
-
-    // Create Excel report
-    const workbook = ketrics.Excel.create();
-    const sheet = workbook.addWorksheet('Orders Report');
-
-    // Add header row
-    sheet.addRow(['Order ID', 'Customer', 'Total', 'Status']);
-
-    // Add data rows
-    for (const order of orders.rows) {
-      sheet.addRow([order.id, order.customer_name, order.total, order.status]);
-    }
-
-    // Calculate total
-    const total = orders.rows.reduce((sum, o) => sum + o.total, 0);
-    sheet.addRow(['', 'TOTAL', total, '']);
-
-    // Generate buffer
-    const buffer = await workbook.toBuffer();
-
-    // Save to volume
-    const volume = await ketrics.Volume.connect('reports');
-    const fileName = `orders-${new Date().toISOString().split('T')[0]}.xlsx`;
-
-    await volume.put(`monthly/${fileName}`, buffer, {
-      contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-      metadata: {
-        generatedBy: ketrics.user.email,
-        orderCount: String(orders.rowCount),
-      },
-    });
-
-    // Generate download URL
-    const downloadUrl = await volume.generateDownloadUrl(`monthly/${fileName}`, {
-      expiresIn: 86400, // 24 hours
-    });
-
-    // Send email notification via external API
-    await ketrics.http.post('https://api.sendgrid.com/v3/mail/send', {
-      to: ketrics.user.email,
-      subject: 'Your report is ready',
-      body: `Download your report: ${downloadUrl.url}`,
-    }, {
-      headers: { 'Authorization': `Bearer ${emailApiKey}` },
-    });
-
-    ketrics.console.log('Report generated successfully', { fileName });
-
-    return {
-      success: true,
-      fileName,
-      downloadUrl: downloadUrl.url,
-      orderCount: orders.rowCount,
-      total,
-    };
-
-  } finally {
-    await db.close();
+  if (error instanceof ketrics.DatabaseAccessDeniedError) {
+    // Direct instanceof check
+    console.log('Application lacks database access grant');
   }
 }
 ```
 
----
+### Testing Approach
 
-## License
-
-MIT
+**Unit Testing Tenant Code**:
+```bash
+# Tenant applications test their handlers without running in Ketrics platform
+npm install --save-dev jest @types/jest ts-jest
+
+# Mock the global ketrics object for tests
+jest.mock('@ketrics/sdk-backend', () => ({
+  // Provide mock implementations
+}));
+```
+
+**Integration Testing** (in Ketrics platform):
+- Deploy application to staging environment
+- Ketrics platform verifies type compatibility at build time
+- Runtime validates against actual service permissions
+- Test tenant isolation and error scenarios
+
+**Type Safety**:
+- TypeScript compilation enforces correct API usage at build time
+- No runtime type checking (SDK is pure types)
+- Type definitions include JSDoc comments with usage examples
+
+## Architecture Patterns
+
+### API Design Patterns
+
+**Static Factory Pattern**:
+- Volume.connect(), DatabaseConnection.connect(), Secret.get()
+- No constructor calls, explicit factory methods
+- Enables lazy connection pooling and resource management
+
+**Error Type Guards**:
+- `isVolumeError(error)` - Checks if error is any VolumeError
+- `isVolumeErrorType(error, 'VolumeNotFoundError')` - Checks specific type
+- Enables type-safe error narrowing without instanceof
+
+**Transaction Scope**:
+- `db.transaction(async (tx) => { ... })`
+- Callback receives transaction connection
+- Automatic commit on success, rollback on error
+
+**Pagination with Cursors**:
+- List operations return cursor for next page
+- Enables efficient large result set handling
+- Stateless pagination without offset/limit complexity
+
+### File Export Strategy
+
+The index.ts file re-exports all types from feature modules:
+1. Interfaces and types for tenant usage
+2. Error classes for instanceof checking
+3. Type guards for runtime error discrimination
+4. Global KetricsSdkV1 interface defining the complete ketrics object
+
+This central export point ensures:
+- Single source of truth for SDK surface
+- Complete type definitions for IDE autocomplete
+- Proper TypeScript declaration file generation