@ketrics/sdk-backend 0.7.1 → 0.9.0

package/README.md

@@ -1,760 +1,720 @@
-# @ketrics/sdk-backend
-
-TypeScript type definitions and runtime interfaces for building tenant applications on the Ketrics platform.
-
-## 1. Overview
-
-### Purpose
-
-The `@ketrics/sdk-backend` package provides TypeScript type definitions for the Ketrics backend SDK. It defines the contract between tenant application code and the Ketrics Data Plane runtime environment. Tenant developers install this package to get full TypeScript intellisense and type safety when writing application code that runs inside Ketrics' sandboxed JavaScript VM.
-
-### Role in the Architecture
+# Ketrics SDK for Backend (@ketrics/sdk-backend)
+
+## Overview
+
+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
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                           Ketrics Platform                                   │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                              │
-│  ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐  │
-│  │  Tenant API   │      │   Data Plane     │      │ ketrics-sdk-     │  │
-│  │      API         │      │      API         │      │   backend        │  │
-│  │                  │      │                  │      │   (this pkg)     │  │
-│  │  - Tenant mgmt   │      │  - VM Sandbox    │◄─────│                  │  │
-│  │  - App deploy    │      │  - Request exec  │      │  Type defs for   │  │
-│  │  - User mgmt     │      │  - SDK injection │      │  global `ketrics`│  │
-│  └──────────────────┘      └──────────────────┘      └──────────────────┘  │
-│           │                         │                         ▲             │
-│           │                         │                         │             │
-│           ▼                         ▼                         │             │
-│  ┌──────────────────────────────────────────────────┐        │             │
-│  │              Tenant Applications                  │────────┘             │
-│  │                                                   │                      │
-│  │  import type { IVolume } from '@ketrics/sdk-backend'                    │
-│  │                                                   │                      │
-│  │  export async function handler() {                │                      │
-│  │    const volume = await ketrics.Volume.connect('uploads');              │
-│  │    // Full TypeScript support via this SDK       │                      │
-│  │  }                                                │                      │
-│  └───────────────────────────────────────────────────┘                      │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-The SDK sits between the Data Plane runtime (which injects the actual `ketrics` global object) and tenant application code. It provides:
-
-1. **Type definitions** for the global `ketrics` object
-2. **Interface contracts** for all SDK modules (Volume, Database, Secret, Excel, PDF, Job, Messages)
-3. **Error class hierarchies** for type-safe error handling
-4. **Type guards** for runtime error checking
-
-### Key Responsibilities
-
-- Define the shape of the `ketrics` global object available in tenant code
-- Provide TypeScript types for context objects (tenant, application, requestor, runtime)
-- Define interfaces for all platform services (storage, database, secrets, file processing)
-- Export error classes for `instanceof` checks in catch blocks
-- Export type guards (`isVolumeError`, `isDatabaseError`, etc.) for safe error handling
-
-### Boundaries
-
-This package is **types only** at development time. It contains:
-- TypeScript interfaces and type definitions
-- Abstract error base classes and concrete error implementations
-- Type guard functions
-
-It does **not** contain:
-- Actual SDK implementations (those are in the Data Plane API)
-- Runtime logic (the Data Plane injects the real `ketrics` object)
-- API clients or network code
-
-## 2. Business Logic
-
-### Problem Solved
-
-Tenant developers need to write application code that runs inside Ketrics' sandboxed VM. Without this SDK, they would have no TypeScript support, leading to:
-- No autocomplete or intellisense in their IDE
-- No compile-time type checking
-- No documentation for available methods and their signatures
-- Difficulty understanding error types for proper handling
-
-### Core Workflows
-
-#### 1. Context Access
-Tenant code accesses execution context through `ketrics.tenant`, `ketrics.application`, `ketrics.requestor`, and `ketrics.runtime`. The SDK defines the exact shape of these objects.
-
-```typescript
-// TenantContext: id, code, name
-// ApplicationContext: id, code, name, version, deploymentId
-// RequestorContext: type ('USER' | 'SERVICE_ACCOUNT'), userId?, serviceAccountId?, name, email?, applicationPermissions
-// RuntimeContext: nodeVersion, runtime ('ecs-fargate'), region
+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)
 ```
 
-#### 2. Resource Access Pattern
-All resources (volumes, databases, secrets) follow a consistent pattern:
+### 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)
 
-1. **Connect/Get** - Obtain a handle to the resource by code
-2. **Perform Operations** - Use methods on the returned interface
-3. **Handle Errors** - Catch typed errors using `instanceof`
+### 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
+
+## Error Handling
+
+### 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
-try {
-  const volume = await ketrics.Volume.connect('uploads');  // Step 1
-  const file = await volume.get('report.pdf');             // Step 2
-} catch (error) {
-  if (error instanceof ketrics.FileNotFoundError) {        // Step 3
-    // Handle specific error
+// 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));
+    }
   }
 }
-```
-
-#### 3. File Processing
-Excel and PDF modules follow a factory pattern:
-- `ketrics.Excel.read(buffer)` - Parse existing file
-- `ketrics.Excel.create()` - Create new file
-- `ketrics.Pdf.read(buffer)` - Parse existing PDF
-- `ketrics.Pdf.create()` - Create new PDF
-
-### Business Rules
-
-1. **Permission-Based Access**: All resource access is gated by application grants. The SDK types reflect this with `permissions` properties on connection interfaces.
-
-2. **Tenant Isolation**: The SDK's context types (`TenantContext`, `ApplicationContext`) ensure tenant code always knows its execution context.
-
-3. **Requestor Types**: The `RequestorContext` distinguishes between human users (`type: 'USER'`) and service accounts (`type: 'SERVICE_ACCOUNT'`) for audit and access control.
-
-4. **Error Hierarchy**: Each module has a base error class (e.g., `VolumeError`) with specific subclasses. This allows catching all errors from a module or specific error types.
-
-### Input/Output Expectations
-
-| Module | Input | Output |
-|--------|-------|--------|
-| Volume.connect | Volume code (string) | IVolume interface |
-| volume.get | File key (string) | FileContent (content, contentType, size, etag) |
-| volume.put | Key, content, options | PutResult (key, etag, size) |
-| DatabaseConnection.connect | Database code (string) | IDatabaseConnection interface |
-| db.query | SQL string, params array | DatabaseQueryResult (rows, rowCount) |
-| Secret.get | Secret code (string) | Decrypted string value |
-| Excel.read | Buffer | IExcelWorkbook |
-| Pdf.create | (none) | IPdfDocument |
-| Job.runInBackground | RunInBackgroundParams | Job ID (string) |
-| Messages.send | SendMessageParams | SendMessageResult |
-
-### Edge Cases Handled
-
-1. **File Not Found**: `FileNotFoundError` with the key that wasn't found
-2. **Permission Denied**: Separate errors for "no grant" vs "missing specific permission"
-3. **Path Traversal**: `InvalidPathError` for attempts like `../../../etc/passwd`
-4. **Size Limits**: `FileSizeLimitError` includes both actual and max size
-5. **Content Type Restrictions**: `ContentTypeNotAllowedError` includes allowed types
-6. **Cross-App Jobs**: `CrossAppPermissionError` for background jobs targeting other apps
-7. **Transaction Failures**: `DatabaseTransactionError` includes whether rollback occurred
-
-## 3. Technical Details
-
-### Technology Stack
-
-- **Language**: TypeScript 5.x
-- **Target**: ES2020
-- **Module System**: CommonJS
-- **Node Version**: 24.x (required for `@types/node` peer dependency)
-- **Build**: TypeScript compiler (`tsc`)
-- **Output**: JavaScript + Declaration files (`.d.ts`)
-
-### File Structure
-
-```
-ketrics-sdk-backend/
-├── package.json           # NPM package configuration
-├── tsconfig.json          # TypeScript compiler options
-├── src/
-│   ├── index.ts           # Main entry: exports all types, defines KetricsSdkV1 interface
-│   ├── context.ts         # TenantContext, ApplicationContext, RequestorContext, RuntimeContext
-│   ├── console.ts         # ConsoleLogger interface (log, error, warn, info, debug)
-│   ├── http.ts            # HttpClient, HttpRequestConfig, HttpResponse
-│   ├── volumes.ts         # IVolume, FileContent, PutOptions, ListResult, etc.
-│   ├── errors.ts          # VolumeError hierarchy (VolumeNotFoundError, FileNotFoundError, etc.)
-│   ├── databases.ts       # IDatabaseConnection, DatabaseQueryResult, transaction support
-│   ├── database-errors.ts # DatabaseError hierarchy
-│   ├── secrets.ts         # ISecret interface (get, exists)
-│   ├── secret-errors.ts   # SecretError hierarchy
-│   ├── excel.ts           # IExcelWorkbook, IExcelWorksheet, IExcelRow, IExcelCell
-│   ├── excel-errors.ts    # ExcelError, ExcelParseError, ExcelWriteError
-│   ├── pdf.ts             # IPdfDocument, IPdfPage, drawing options, embedded resources
-│   ├── pdf-errors.ts      # PdfError, PdfParseError, PdfWriteError
-│   ├── job.ts             # RunInBackgroundParams, JobStatus, JobListResult
-│   ├── job-errors.ts      # JobError hierarchy
-│   ├── messages.ts        # SendMessageParams, MessagesManager, bulk/group messaging
-│   └── messages-errors.ts # MessageError hierarchy
-└── dist/                  # Compiled output (generated)
-    ├── index.js           # Compiled JavaScript
-    ├── index.d.ts         # Type declarations
-    └── ...
-```
-
-### Key Interfaces
-
-#### KetricsSdkV1 (Main SDK Interface)
-
-The primary interface defining the global `ketrics` object:
-
-```typescript
-interface KetricsSdkV1 {
-  // Context (read-only)
-  tenant: TenantContext;
-  application: ApplicationContext;
-  requestor: RequestorContext;
-  runtime: RuntimeContext;
-  environment: EnvironmentVariables;
-
-  // Utilities
-  console: ConsoleLogger;
-  http: HttpClient;
-
-  // Resource Factories
-  Volume: { connect(code: string): Promise<IVolume> };
-  DatabaseConnection: { connect(code: string): Promise<IDatabaseConnection> };
-  Secret: { get(code: string): Promise<string>; exists(code: string): Promise<boolean> };
-  Excel: { read(buffer: Buffer): Promise<IExcelWorkbook>; create(): IExcelWorkbook };
-  Pdf: { read(buffer: Buffer): Promise<IPdfDocument>; create(): Promise<IPdfDocument>; rgb(r, g, b): PdfRgbColor };
-  Job: { runInBackground(params): Promise<string>; getStatus(id): Promise<JobStatus>; list(params?): Promise<JobListResult> };
-  Messages: MessagesManager;
-
-  // Error Classes (for instanceof checks)
-  VolumeError, VolumeNotFoundError, FileNotFoundError, ...
-  DatabaseError, DatabaseNotFoundError, DatabaseQueryError, ...
-  SecretError, SecretNotFoundError, ...
-  ExcelError, PdfError, JobError, MessageError, ...
-
-  // Type Guards
-  isVolumeError, isVolumeErrorType, isDatabaseError, ...
-}
-```
-
-#### IVolume (S3-Backed Storage)
-
-```typescript
-interface IVolume {
-  readonly code: string;
-  readonly permissions: ReadonlySet<string>;
-
-  // Read
-  get(key: string): Promise<FileContent>;
-  exists(key: string): Promise<boolean>;
-  getMetadata(key: string): Promise<FileMetadata>;
-
-  // Write
-  put(key: string, content: PutContent, options?: PutOptions): Promise<PutResult>;
-
-  // Delete
-  delete(key: string): Promise<DeleteResult>;
-  deleteByPrefix(prefix: string): Promise<DeleteByPrefixResult>;
-
-  // List
-  list(options?: ListOptions): Promise<ListResult>;
-
-  // File Management
-  copy(src: string, dest: string, options?: CopyOptions): Promise<CopyResult>;
-  move(src: string, dest: string, options?: MoveOptions): Promise<MoveResult>;
-
-  // URL Generation
-  generateDownloadUrl(key: string, options?: DownloadUrlOptions): Promise<PresignedUrl>;
-  generateUploadUrl(key: string, options?: UploadUrlOptions): Promise<PresignedUrl>;
-}
-```
-
-#### IDatabaseConnection (External Database Access)
-
-```typescript
-interface IDatabaseConnection {
-  readonly code: string;
-  readonly permissions: ReadonlySet<string>;
-
-  query<T>(sql: string, params?: unknown[]): Promise<DatabaseQueryResult<T>>;
-  execute(sql: string, params?: unknown[]): Promise<DatabaseExecuteResult>;
-  transaction<T>(fn: (tx: IDatabaseConnection) => Promise<T>): Promise<T>;
-  close(): Promise<void>;
-}
-```
-
-### Configuration
-
-**tsconfig.json settings:**
-- `target: "ES2020"` - Modern JavaScript output
-- `module: "commonjs"` - Node.js compatible modules
-- `declaration: true` - Generate `.d.ts` files
-- `declarationMap: true` - Enable declaration sourcemaps
-- `strict: true` - Full TypeScript strictness
-- `outDir: "./dist"` - Output directory
-
-**No environment variables** - This is a pure type definition package.
-
-### External Integrations
-
-This package has **no runtime dependencies**. It only requires `@types/node` as a peer dependency for Node.js built-in types like `Buffer` and `stream.Readable`.
 
-The types it defines correspond to these Data Plane integrations:
-- **AWS S3** (via Volume interface)
-- **PostgreSQL/MySQL/MSSQL** (via DatabaseConnection interface)
-- **AWS KMS** (via Secret interface, for decryption)
-- **ExcelJS** (via Excel interface)
-- **pdf-lib** (via Pdf interface)
-- **AWS CloudWatch Logs** (via ConsoleLogger interface)
-
-## 4. Data Flow
-
-### Type Definition Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         Development Time                                     │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                              │
-│  Tenant Developer's IDE                                                      │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │                                                                      │   │
-│  │  import type { IVolume } from '@ketrics/sdk-backend';               │   │
-│  │                           ▲                                          │   │
-│  │                           │                                          │   │
-│  │  // TypeScript uses the   │                                          │   │
-│  │  // SDK types for:        │                                          │   │
-│  │  //  - Autocomplete       │                                          │   │
-│  │  //  - Type checking      │                                          │   │
-│  │  //  - Error detection    │                                          │   │
-│  │                           │                                          │   │
-│  │  const volume = await ketrics.Volume.connect('uploads');            │   │
-│  │  //    ▲                                                             │   │
-│  │  //    │ TypeScript knows this is IVolume                           │   │
-│  │  //    │                                                             │   │
-│  │  const file = await volume.get('doc.pdf');                          │   │
-│  │  //                        ▲                                         │   │
-│  │  //                        │ TypeScript knows this is FileContent   │   │
-│  │                                                                      │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                          Runtime (Data Plane)                                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                              │
-│  VM Sandbox                                                                  │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │                                                                      │   │
-│  │  global.ketrics = {                                                 │   │
-│  │    tenant: { id: '...', code: 'acme', name: 'ACME Corp' },         │   │
-│  │    Volume: {                                                        │   │
-│  │      connect: async (code) => { /* actual S3 implementation */ }   │   │
-│  │    },                                                               │   │
-│  │    // ... all other SDK modules injected by Data Plane             │   │
-│  │  };                                                                 │   │
-│  │                                                                      │   │
-│  │  // Tenant code executes with real implementations                  │   │
-│  │  await handler();                                                   │   │
-│  │                                                                      │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-│                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Error Flow
-
-```
-Operation Fails in Data Plane
-            │
-            ▼
-┌─────────────────────────────────────┐
-│ Data Plane throws typed error       │
-│ e.g., new FileNotFoundError(...)    │
-└─────────────────────────────────────┘
-            │
-            ▼
-┌─────────────────────────────────────┐
-│ Error propagates to tenant code     │
-└─────────────────────────────────────┘
-            │
-            ▼
-┌─────────────────────────────────────┐
-│ Tenant catch block                  │
-│                                     │
-│ catch (error) {                     │
-│   if (error instanceof ketrics.     │
-│       FileNotFoundError) {          │
-│     // TypeScript knows error.key   │
-│     // exists on this type          │
-│   }                                 │
-│ }                                   │
-└─────────────────────────────────────┘
-```
-
-### Module Dependency Graph
-
-```
-index.ts (main entry)
-    │
-    ├── context.ts (no dependencies)
-    ├── console.ts (no dependencies)
-    ├── http.ts (no dependencies)
-    │
-    ├── volumes.ts
-    │       └── uses: stream.Readable from Node.js
-    │
-    ├── errors.ts (volume errors)
-    │       └── no dependencies
-    │
-    ├── databases.ts
-    │       └── no dependencies
-    │
-    ├── database-errors.ts
-    │       └── no dependencies
-    │
-    ├── secrets.ts
-    │       └── no dependencies
-    │
-    ├── secret-errors.ts
-    │       └── no dependencies
-    │
-    ├── excel.ts
-    │       └── no dependencies
-    │
-    ├── excel-errors.ts
-    │       └── no dependencies
-    │
-    ├── pdf.ts
-    │       └── no dependencies
-    │
-    ├── pdf-errors.ts
-    │       └── no dependencies
-    │
-    ├── job.ts
-    │       └── no dependencies
-    │
-    ├── job-errors.ts
-    │       └── no dependencies
-    │
-    ├── messages.ts
-    │       └── no dependencies
-    │
-    └── messages-errors.ts
-            └── no dependencies
+// Idempotency keys prevent duplicate job execution
+const jobId = await ketrics.Job.runInBackground({
+  function: 'processPayment',
+  payload: { orderId: '123' },
+  options: { idempotencyKey: 'order-123-payment' }
+});
 ```
 
-## 5. Error Handling
+### Logging Approach
 
-### Error Hierarchy Design
+**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
 
-Each SDK module follows a consistent error hierarchy pattern:
-
-```
-Error (built-in)
-└── ModuleError (abstract base)
-    ├── ModuleNotFoundError
-    ├── ModuleAccessDeniedError
-    └── ModuleSpecificError1
-    └── ModuleSpecificError2
-    └── ...
-```
-
-### Volume Errors
-
-| Error Class | Code | Description |
-|-------------|------|-------------|
-| `VolumeError` | - | Abstract base class |
-| `VolumeNotFoundError` | - | Volume code doesn't exist in tenant |
-| `VolumeAccessDeniedError` | - | Application lacks grant to volume |
-| `VolumePermissionDeniedError` | - | Operation requires missing permission (ReadObject, CreateObject, etc.) |
-| `FileNotFoundError` | - | File key doesn't exist |
-| `FileAlreadyExistsError` | - | File exists when using `ifNotExists: true` |
-| `InvalidPathError` | - | Path contains invalid characters or traversal attempt |
-| `FileSizeLimitError` | - | File exceeds volume's configured limit |
-| `ContentTypeNotAllowedError` | - | MIME type not in volume's allowlist |
-
-### Database Errors
-
-| Error Class | Description |
-|-------------|-------------|
-| `DatabaseError` | Abstract base class |
-| `DatabaseNotFoundError` | Database code doesn't exist |
-| `DatabaseAccessDeniedError` | Application lacks grant |
-| `DatabaseConnectionError` | Cannot establish connection (network, auth, etc.) |
-| `DatabaseQueryError` | SQL execution failed (syntax, constraint violation) |
-| `DatabaseTransactionError` | Transaction failed (includes `rolledBack` property) |
-
-### Secret Errors
-
-| Error Class | Description |
-|-------------|-------------|
-| `SecretError` | Abstract base class |
-| `SecretNotFoundError` | Secret code doesn't exist |
-| `SecretAccessDeniedError` | Application lacks grant |
-| `SecretDecryptionError` | KMS decryption failed (key issue, corrupted data) |
-
-### File Processing Errors
-
-| Error Class | Description |
-|-------------|-------------|
-| `ExcelError` | Abstract base class |
-| `ExcelParseError` | Cannot parse .xlsx file (invalid format, corrupted) |
-| `ExcelWriteError` | Cannot write .xlsx file |
-| `PdfError` | Abstract base class |
-| `PdfParseError` | Cannot parse PDF file |
-| `PdfWriteError` | Cannot write PDF file |
-
-### Job Errors
-
-| Error Class | Description |
-|-------------|-------------|
-| `JobError` | Abstract base class |
-| `JobNotFoundError` | Job ID doesn't exist |
-| `InvalidFunctionError` | Function name is empty or invalid |
-| `CrossAppPermissionError` | Missing permission for cross-app job execution |
-| `JobExecutionError` | Job failed during execution |
-
-### Message Errors
-
-| Error Class | Description |
-|-------------|-------------|
-| `MessageError` | Base class |
-| `MessageValidationError` | Invalid message parameters |
-| `GroupNotFoundError` | Group code doesn't exist |
-| `TenantGrantPermissionDeniedError` | Missing IAM-data permissions for group messaging |
-
-### Type Guards
-
-Each module provides type guard functions:
+**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
-// Check if any error from module
-if (isVolumeError(error)) { /* error is VolumeError */ }
-if (isDatabaseError(error)) { /* error is DatabaseError */ }
-if (isSecretError(error)) { /* error is SecretError */ }
-
-// Check for specific error type
-if (isVolumeErrorType(error, FileNotFoundError)) {
-  console.log(error.key); // TypeScript knows error.key exists
+try {
+  const db = await ketrics.DatabaseConnection.connect('main-db');
+  ketrics.console.log('Connected to database');
+  const result = await db.query('SELECT * FROM users');
+  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 });
+  }
 }
 ```
 
-### Error Properties
-
-All error classes include:
-- `name`: Error class name (e.g., `"FileNotFoundError"`)
-- `message`: Human-readable description
-- `timestamp`: When the error occurred
-- `toJSON()`: Serializes error for logging (no stack trace, no internal details)
-
-Module-specific properties:
-- Volume errors: `volumeCode`, `operation`
-- Database errors: `databaseCode`, `operation`
-- Secret errors: `secretCode`, `operation`
-- File errors: `key` (the file path)
-- Permission errors: `requiredPermission`
-
-### Security Considerations
-
-Error messages are designed to avoid leaking sensitive information:
-- No connection strings or credentials
-- No internal tenant IDs
-- No AWS account information
-- SQL limited to 200 characters in `DatabaseQueryError`
+## Usage
 
-## 6. Usage
+### How to Run/Deploy This Component
 
-### Installation
+This is a type definition library. It does not run standalone but is consumed by tenant applications.
 
+**Installation in Tenant Application**:
 ```bash
 npm install @ketrics/sdk-backend
 ```
 
-### Development Requirements
-
-- Node.js 24.x or higher
-- TypeScript 5.x
-
-### Build Commands
+**TypeScript Configuration** (tsconfig.json):
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "lib": ["ES2020"],
+    "types": ["@ketrics/sdk-backend"]
+  }
+}
+```
 
+**Building the SDK Package**:
 ```bash
 # Install dependencies
 npm install
 
-# Build TypeScript to JavaScript + declarations
+# Compile TypeScript to JavaScript
 npm run build
 
-# Clean build output
-npm run clean
+# Output: dist/ folder with .js, .d.ts, .map files
+```
 
-# Build and publish to npm
-npm run prepublishOnly  # Runs build automatically
+**Publishing**:
+```bash
+npm publish
 ```
 
-### Using in Tenant Applications
+This publishes to npm registry at https://www.npmjs.com/package/@ketrics/sdk-backend
 
-The SDK is designed for **type imports only** in tenant code:
+### Example Invocations
 
+**Complete Tenant Application Example**:
 ```typescript
-// Import types for type annotations
-import type {
-  IVolume,
-  FileContent,
-  IDatabaseConnection,
-  DatabaseQueryResult
-} from '@ketrics/sdk-backend';
-
-// The global `ketrics` object is automatically available at runtime
-export async function processOrder(orderId: string) {
-  // Access tenant context
-  console.log(`Processing for tenant: ${ketrics.tenant.name}`);
-
-  // Log to CloudWatch
-  ketrics.console.log('Starting order processing', { orderId });
-
-  // Access S3 volume
-  const volume: IVolume = await ketrics.Volume.connect('orders');
-  const orderFile: FileContent = await volume.get(`${orderId}.json`);
-
-  // Query database
-  const db = await ketrics.DatabaseConnection.connect('orders-db');
-  const result = await db.query<{ status: string }>(
-    'UPDATE orders SET status = ? WHERE id = ? RETURNING status',
-    ['processed', orderId]
-  );
-  await db.close();
-
-  return { success: true, newStatus: result.rows[0].status };
-}
-```
+// handler.ts - Tenant application code
 
-### Error Handling Pattern
-
-```typescript
-export async function safeVolumeRead(volumeCode: string, key: string) {
+export async function processOrder(payload: { orderId: string }) {
   try {
-    const volume = await ketrics.Volume.connect(volumeCode);
-    return await volume.get(key);
-  } catch (error) {
-    // Check specific error types first
-    if (error instanceof ketrics.VolumeNotFoundError) {
-      return { error: 'VOLUME_NOT_FOUND', volumeCode: error.volumeCode };
-    }
-    if (error instanceof ketrics.FileNotFoundError) {
-      return { error: 'FILE_NOT_FOUND', key: error.key };
-    }
-    if (error instanceof ketrics.VolumePermissionDeniedError) {
-      return { error: 'PERMISSION_DENIED', permission: error.requiredPermission };
+    // 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;
+  }
+}
 
-    // Fallback for any other volume error
-    if (ketrics.isVolumeError(error)) {
-      return { error: 'VOLUME_ERROR', message: error.message };
+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;
     }
-
-    // Re-throw unexpected errors
-    throw error;
   }
 }
 ```
 
-### Complete Example: Report Generation
-
+**Error Handling Patterns**:
 ```typescript
-import type { IExcelWorkbook, IPdfDocument } from '@ketrics/sdk-backend';
-
-interface SalesRecord {
-  id: number;
-  product: string;
-  quantity: number;
-  total: number;
-}
-
-export async function generateSalesReport(month: string) {
-  // Get secrets for external API
-  const apiKey = await ketrics.Secret.get('analytics-api-key');
-
-  // Query database
-  const db = await ketrics.DatabaseConnection.connect('sales-db');
-  const sales = await db.query<SalesRecord>(
-    'SELECT * FROM sales WHERE month = ? ORDER BY total DESC',
-    [month]
-  );
-  await db.close();
-
-  // Create Excel report
-  const workbook: IExcelWorkbook = ketrics.Excel.create();
-  const sheet = workbook.addWorksheet('Sales Report');
-
-  sheet.addRow(['ID', 'Product', 'Quantity', 'Total']);
-  for (const sale of sales.rows) {
-    sheet.addRow([sale.id, sale.product, sale.quantity, sale.total]);
+// Type guards for error handling
+try {
+  const db = await ketrics.DatabaseConnection.connect('main-db');
+} catch (error) {
+  if (ketrics.isDatabaseError(error)) {
+    // Specific database error
+    console.log(`Database error: ${error.message}`);
   }
 
-  const excelBuffer = await workbook.toBuffer();
-
-  // Create PDF summary
-  const pdf: IPdfDocument = await ketrics.Pdf.create();
-  pdf.setTitle(`Sales Report - ${month}`);
-  pdf.setAuthor(ketrics.requestor.name);
-
-  const page = pdf.addPage('A4');
-  const font = await pdf.embedStandardFont('HelveticaBold');
-
-  await page.drawText(`Sales Report: ${month}`, {
-    x: 50, y: 750, size: 24, font
-  });
-
-  await page.drawText(`Total Records: ${sales.rowCount}`, {
-    x: 50, y: 700, size: 14
-  });
-
-  const pdfBuffer = await pdf.toBuffer();
-
-  // Save to volume
-  const volume = await ketrics.Volume.connect('reports');
-  await volume.put(`${month}/sales.xlsx`, excelBuffer);
-  await volume.put(`${month}/summary.pdf`, pdfBuffer);
-
-  // Generate download URLs
-  const excelUrl = await volume.generateDownloadUrl(`${month}/sales.xlsx`, {
-    expiresIn: 86400
-  });
-
-  ketrics.console.log('Report generated', {
-    month,
-    recordCount: sales.rowCount
-  });
+  if (ketrics.isDatabaseErrorType(error, 'DatabaseNotFoundError')) {
+    // Exact error type check
+    console.log(`Database not found: ${error.databaseCode}`);
+  }
 
-  return {
-    success: true,
-    downloadUrl: excelUrl.url,
-    expiresAt: excelUrl.expiresAt
-  };
+  if (error instanceof ketrics.DatabaseAccessDeniedError) {
+    // Direct instanceof check
+    console.log('Application lacks database access grant');
+  }
 }
 ```
 
-### Testing
-
-Since this package contains only type definitions, testing focuses on ensuring:
-1. TypeScript compiles without errors
-2. All types are correctly exported
-3. Error class hierarchies work with `instanceof`
-
-The actual runtime behavior is tested in the Data Plane API where the SDK is implemented.
-
-```bash
-# Verify types compile correctly
-npm run build
-
-# Type checking is performed as part of build
-# No separate test command needed for type-only package
-```
-
-### Publishing
+### Testing Approach
 
+**Unit Testing Tenant Code**:
 ```bash
-# Bump version in package.json
-npm version patch|minor|major
+# Tenant applications test their handlers without running in Ketrics platform
+npm install --save-dev jest @types/jest ts-jest
 
-# Build and publish
-npm publish --access public
+# Mock the global ketrics object for tests
+jest.mock('@ketrics/sdk-backend', () => ({
+  // Provide mock implementations
+}));
 ```
 
-## License
-
-MIT
+**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