@ketrics/sdk-backend 0.7.0 → 0.7.1

package/README.md

@@ -1,1513 +1,760 @@
 # @ketrics/sdk-backend
 
-TypeScript type definitions for building tenant applications on the Ketrics platform.
+TypeScript type definitions and runtime interfaces for building tenant applications on the Ketrics platform.
 
-## Installation
+## 1. Overview
 
-```bash
-npm install @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:
+### Purpose
 
-- **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();
+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.
 
-  // Access encrypted secrets
-  const apiKey = await ketrics.Secret.get('stripe-api-key');
+### Role in the Architecture
 
-  // 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")
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           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       │                      │
+│  │  }                                                │                      │
+│  └───────────────────────────────────────────────────┘                      │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-### Application Context
+The SDK sits between the Data Plane runtime (which injects the actual `ketrics` global object) and tenant application code. It provides:
 
-Access information about the current application:
+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
 
-```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
-```
+### Key Responsibilities
 
-### User Context
+- 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
 
-Access information about the user making the request:
+### Boundaries
 
-```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)
-```
+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
 
-### Environment Context
+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
 
-Access runtime environment information:
+## 2. Business Logic
 
-```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
-}
-```
+### 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
 
-## Console Logging
+### Core Workflows
 
-Logs are automatically forwarded to CloudWatch with proper context (tenant, application, user, request ID):
+#### 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
-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 });
+// 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
 ```
 
-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)
-
----
+#### 2. Resource Access Pattern
+All resources (volumes, databases, secrets) follow a consistent pattern:
 
-## HTTP Client
-
-Make external API requests with built-in timeout and user agent:
+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`
 
 ```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',
-  },
-});
-
-// Create only if file doesn't exist
 try {
-  await volume.put('config.json', defaultConfig, { ifNotExists: true });
+  const volume = await ketrics.Volume.connect('uploads');  // Step 1
+  const file = await volume.get('report.pdf');             // Step 2
 } catch (error) {
-  if (error instanceof ketrics.FileAlreadyExistsError) {
-    console.log('Config already exists, skipping');
+  if (error instanceof ketrics.FileNotFoundError) {        // Step 3
+    // Handle specific error
   }
 }
 ```
 
-### 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,
-  });
+#### 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, ...
 }
-
-// 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
+#### IVolume (S3-Backed Storage)
 
 ```typescript
-// Copy a file
-await volume.copy('source.pdf', 'backup/source.pdf');
+interface IVolume {
+  readonly code: string;
+  readonly permissions: ReadonlySet<string>;
 
-// Copy with metadata replacement
-await volume.copy('source.pdf', 'archive/source.pdf', {
-  metadataDirective: 'REPLACE',
-  metadata: { archived: 'true', archivedBy: ketrics.user.email },
-});
+  // Read
+  get(key: string): Promise<FileContent>;
+  exists(key: string): Promise<boolean>;
+  getMetadata(key: string): Promise<FileMetadata>;
 
-// Move a file (copy + delete)
-await volume.move('temp/upload.pdf', 'documents/final.pdf');
-```
+  // Write
+  put(key: string, content: PutContent, options?: PutOptions): Promise<PutResult>;
 
-### Generating Presigned URLs
+  // Delete
+  delete(key: string): Promise<DeleteResult>;
+  deleteByPrefix(prefix: string): Promise<DeleteByPrefixResult>;
 
-```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
-});
-// Client can PUT directly to uploadUrl.url
-```
+  // 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>;
 
-## 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', ... }
+  // URL Generation
+  generateDownloadUrl(key: string, options?: DownloadUrlOptions): Promise<PresignedUrl>;
+  generateUploadUrl(key: string, options?: UploadUrlOptions): Promise<PresignedUrl>;
+}
 ```
 
-### Querying Data
+#### IDatabaseConnection (External Database Access)
 
 ```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  created_at: Date;
-}
+interface IDatabaseConnection {
+  readonly code: string;
+  readonly permissions: ReadonlySet<string>;
 
-// 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);
+  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>;
 }
 ```
 
-### 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
+### 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
+```
+
+## 5. Error Handling
+
+### Error Hierarchy Design
+
+Each SDK module follows a consistent error hierarchy pattern:
+
+```
+Error (built-in)
+└── ModuleError (abstract base)
+    ├── ModuleNotFoundError
+    ├── ModuleAccessDeniedError
+    └── ModuleSpecificError1
+    └── ModuleSpecificError2
+    └── ...
 ```
 
-### 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]
-  );
+### Volume Errors
 
-  return { transferId: transfer.insertId };
-});
+| 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 |
 
-console.log('Transfer completed:', result.transferId);
-```
+### Database Errors
 
-### Closing Connections
+| 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) |
 
-```typescript
-// Always close when done to return connection to pool
-const db = await ketrics.DatabaseConnection.connect('main-db');
-try {
-  const result = await db.query('SELECT * FROM users');
-  return result.rows;
-} finally {
-  await db.close();
-}
-```
+### 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) |
 
-## Secrets
+### File Processing Errors
 
-Access encrypted secrets stored with tenant-specific KMS encryption:
+| 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 |
 
-### Getting Secrets
+### Job Errors
 
-```typescript
-// Get a secret value
-const apiKey = await ketrics.Secret.get('stripe-api-key');
+| 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 |
 
-// Use the secret (value is decrypted automatically)
-const response = await ketrics.http.post('https://api.stripe.com/v1/charges', data, {
-  headers: { 'Authorization': `Bearer ${apiKey}` },
-});
-```
+### Message Errors
 
-### Checking Secret Existence
+| Error Class | Description |
+|-------------|-------------|
+| `MessageError` | Base class |
+| `MessageValidationError` | Invalid message parameters |
+| `GroupNotFoundError` | Group code doesn't exist |
+| `TenantGrantPermissionDeniedError` | Missing IAM-data permissions for group messaging |
 
-```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
-}
-```
+### Type Guards
 
-### Common Patterns
+Each module provides type guard functions:
 
 ```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');
+// Check if any error from module
+if (isVolumeError(error)) { /* error is VolumeError */ }
+if (isDatabaseError(error)) { /* error is DatabaseError */ }
+if (isSecretError(error)) { /* error is SecretError */ }
 
-// OAuth credentials
-const clientId = await ketrics.Secret.get('oauth-client-id');
-const clientSecret = await ketrics.Secret.get('oauth-client-secret');
+// Check for specific error type
+if (isVolumeErrorType(error, FileNotFoundError)) {
+  console.log(error.key); // TypeScript knows error.key exists
+}
 ```
 
----
-
-## Excel Files
+### Error Properties
 
-Read and write Excel files (.xlsx) using a simple API:
+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)
 
-### Reading Excel Files
+Module-specific properties:
+- Volume errors: `volumeCode`, `operation`
+- Database errors: `databaseCode`, `operation`
+- Secret errors: `secretCode`, `operation`
+- File errors: `key` (the file path)
+- Permission errors: `requiredPermission`
 
-```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');
+### Security Considerations
 
-// Parse Excel file
-const workbook = await ketrics.Excel.read(file.content);
+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`
 
-// Get worksheet by name
-const sheet = workbook.getWorksheet('Sheet1');
-if (!sheet) {
-  throw new Error('Sheet not found');
-}
+## 6. Usage
 
-// Get worksheet by index (1-indexed)
-const firstSheet = workbook.getWorksheet(1);
+### Installation
 
-// List all worksheets
-console.log(`Workbook has ${workbook.worksheetCount} sheets`);
-for (const ws of workbook.worksheets) {
-  console.log(`- ${ws.name}: ${ws.actualRowCount} rows`);
-}
+```bash
+npm install @ketrics/sdk-backend
 ```
 
-### 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);
-}
+### Development Requirements
 
-// Get a specific row (1-indexed)
-const headerRow = sheet.getRow(1);
-console.log('Headers:', headerRow.values);
+- Node.js 24.x or higher
+- TypeScript 5.x
 
-// Get a specific cell
-const cell = sheet.getCell('A1');
-console.log(cell.value, cell.text, cell.address);
+### Build Commands
 
-// Get cell by coordinates
-const cellB2 = sheet.getCell(2, 2);
+```bash
+# Install dependencies
+npm install
 
-// Iterate over rows
-sheet.eachRow((row, rowNumber) => {
-  console.log(`Row ${rowNumber}:`, row.values);
-});
+# Build TypeScript to JavaScript + declarations
+npm run build
 
-// Include empty rows
-sheet.eachRow((row, rowNumber) => {
-  console.log(`Row ${rowNumber}:`, row.values);
-}, { includeEmpty: true });
+# Clean build output
+npm run clean
 
-// Get all values as 2D array
-const allValues = sheet.getSheetValues();
-// allValues[1] = first row, allValues[1][1] = cell A1
+# Build and publish to npm
+npm run prepublishOnly  # Runs build automatically
 ```
 
-### Working with Cells
+### Using in Tenant Applications
 
-```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
+The SDK is designed for **type imports only** in tenant code:
 
 ```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',
-});
-```
+// Import types for type annotations
+import type {
+  IVolume,
+  FileContent,
+  IDatabaseConnection,
+  DatabaseQueryResult
+} from '@ketrics/sdk-backend';
 
-### Converting to CSV
+// 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}`);
 
-```typescript
-// Convert worksheet to CSV
-const csvContent = await workbook.toCsv('Sheet1');
+  // Log to CloudWatch
+  ketrics.console.log('Starting order processing', { orderId });
 
-// Save as CSV
-await volume.put('output/data.csv', csvContent, {
-  contentType: 'text/csv',
-});
-```
+  // Access S3 volume
+  const volume: IVolume = await ketrics.Volume.connect('orders');
+  const orderFile: FileContent = await volume.get(`${orderId}.json`);
 
-### Managing Worksheets
+  // 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();
 
-```typescript
-// Remove worksheet
-workbook.removeWorksheet('TempSheet');
-workbook.removeWorksheet(2); // By index
-
-// Rename worksheet
-const sheet = workbook.getWorksheet('OldName');
-if (sheet) {
-  sheet.name = 'NewName';
+  return { success: true, newStatus: result.rows[0].status };
 }
 ```
 
----
-
-## PDF Files
-
-Read, create, and modify PDF files using the pdf-lib wrapper:
-
-### Reading PDF Files
+### Error Handling Pattern
 
 ```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);
+export async function safeVolumeRead(volumeCode: string, key: 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 };
+    }
 
-// Get document info
-console.log('Page count:', doc.getPageCount());
-console.log('Title:', doc.getTitle());
-console.log('Author:', doc.getAuthor());
+    // Fallback for any other volume error
+    if (ketrics.isVolumeError(error)) {
+      return { error: 'VOLUME_ERROR', message: error.message };
+    }
 
-// Get all pages
-const pages = doc.getPages();
-for (const page of pages) {
-  console.log(`Page size: ${page.width}x${page.height}`);
+    // Re-throw unexpected errors
+    throw error;
+  }
 }
-
-// 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
+### Complete Example: Report Generation
 
 ```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,
-});
-
-// 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,
-});
-
-// Scale image by factor
-const factor = pngImage.scale(0.5);
-page.drawImage(pngImage, {
-  x: 250,
-  y: 350,
-  width: factor.width,
-  height: factor.height,
-});
-```
-
-### 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 });
-```
+import type { IExcelWorkbook, IPdfDocument } from '@ketrics/sdk-backend';
 
-### 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
-
-```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
-
-```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),
-  });
+interface SalesRecord {
+  id: number;
+  product: string;
+  quantity: number;
+  total: number;
 }
 
-// Save modified document
-const buffer = await doc.toBuffer();
-await volume.put('modified.pdf', buffer, {
-  contentType: 'application/pdf',
-});
-```
-
-### Complete PDF Generation Example
+export async function generateSalesReport(month: string) {
+  // Get secrets for external API
+  const apiKey = await ketrics.Secret.get('analytics-api-key');
 
-```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]
+  // 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]
   );
-  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);
+  // Create Excel report
+  const workbook: IExcelWorkbook = ketrics.Excel.create();
+  const sheet = workbook.addWorksheet('Sales Report');
 
-  const page = doc.addPage('A4');
-  const { width, height } = page.getSize();
+  sheet.addRow(['ID', 'Product', 'Quantity', 'Total']);
+  for (const sale of sales.rows) {
+    sheet.addRow([sale.id, sale.product, sale.quantity, sale.total]);
+  }
 
-  // Embed fonts
-  const boldFont = await doc.embedStandardFont('HelveticaBold');
-  const regularFont = await doc.embedStandardFont('Helvetica');
+  const excelBuffer = await workbook.toBuffer();
 
-  // Header
-  await page.drawText(ketrics.tenant.name, {
-    x: 50,
-    y: height - 50,
-    size: 24,
-    font: boldFont,
-  });
+  // Create PDF summary
+  const pdf: IPdfDocument = await ketrics.Pdf.create();
+  pdf.setTitle(`Sales Report - ${month}`);
+  pdf.setAuthor(ketrics.requestor.name);
 
-  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),
-  });
+  const page = pdf.addPage('A4');
+  const font = await pdf.embedStandardFont('HelveticaBold');
 
-  // Customer info
-  await page.drawText('Bill To:', {
-    x: 50,
-    y: height - 150,
-    size: 12,
-    font: boldFont,
+  await page.drawText(`Sales Report: ${month}`, {
+    x: 50, y: 750, size: 24, font
   });
 
-  await page.drawText(order.customer_name, {
-    x: 50,
-    y: height - 170,
-    size: 12,
-    font: regularFont,
+  await page.drawText(`Total Records: ${sales.rowCount}`, {
+    x: 50, y: 700, size: 14
   });
 
-  // 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),
-  });
+  const pdfBuffer = await pdf.toBuffer();
 
-  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;
-  }
-
-  // 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 });
+  // Save to volume
+  const volume = await ketrics.Volume.connect('reports');
+  await volume.put(`${month}/sales.xlsx`, excelBuffer);
+  await volume.put(`${month}/summary.pdf`, pdfBuffer);
 
-  // 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),
+  // Generate download URLs
+  const excelUrl = await volume.generateDownloadUrl(`${month}/sales.xlsx`, {
+    expiresIn: 86400
   });
 
-  // 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,
-    },
+  ketrics.console.log('Report generated', {
+    month,
+    recordCount: sales.rowCount
   });
 
   return {
     success: true,
-    invoiceNumber: order.invoice_number,
+    downloadUrl: excelUrl.url,
+    expiresAt: excelUrl.expiresAt
   };
 }
 ```
 
----
-
-## 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;
-  }
-}
-```
-
-### Database Errors
-
-```typescript
-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
-    console.log(`Database error: ${error.message}`);
-  } else {
-    throw error;
-  }
-}
-```
+### Testing
 
-### 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;
-  }
-}
-```
+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`
 
-### Excel Errors
+The actual runtime behavior is tested in the Data Plane API where the SDK is implemented.
 
-```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;
-  }
-}
-```
-
----
-
-## 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,
+```bash
+# Verify types compile correctly
+npm run build
 
-  // 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';
+# Type checking is performed as part of build
+# No separate test command needed for type-only package
 ```
 
----
-
-## 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');
+### Publishing
 
-    // 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]);
-    }
+```bash
+# Bump version in package.json
+npm version patch|minor|major
 
-    // 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();
-  }
-}
+# Build and publish
+npm publish --access public
 ```
 
----
-
 ## License
 
 MIT