@ketrics/sdk-backend 0.3.0 → 0.4.0

package/README.md

@@ -1,238 +1,1160 @@
-# @ketrics/sdk
+# @ketrics/sdk-backend
 
 TypeScript type definitions for building tenant applications on the Ketrics platform.
 
 ## Installation
 
 ```bash
-npm install @ketrics/sdk
+npm install @ketrics/sdk-backend
 ```
 
-## Usage
+## Overview
 
 The SDK provides TypeScript types for the global `ketrics` object that is automatically injected into your tenant application code at runtime. Everything is accessible via the `ketrics` object:
 
-- **Context**: `ketrics.tenant`, `ketrics.application`, `ketrics.user`, `ketrics.env`
-- **Utilities**: `ketrics.console`, `ketrics.http`, `ketrics.databases`
+- **Context**: `ketrics.tenant`, `ketrics.application`, `ketrics.user`, `ketrics.env`, `ketrics.environment`
+- **Utilities**: `ketrics.console`, `ketrics.http`
 - **Volume**: `ketrics.Volume.connect()` for S3-backed storage
-- **Error classes**: `ketrics.VolumeNotFoundError`, etc. for `instanceof` checks
+- **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
 
-### Basic Example
+---
+
+## Quick Start
 
 ```typescript
 // Import types only if needed for type annotations
-import type { FileContent, IVolume } from '@ketrics/sdk';
+import type { FileContent, IVolume, IDatabaseConnection } from '@ketrics/sdk-backend';
 
 export async function handler() {
-  // The global `ketrics` object is automatically typed
+  // Context is always available
   console.log('Tenant:', ketrics.tenant.name);
   console.log('User:', ketrics.user.email);
   console.log('App:', ketrics.application.code);
 
-  // Use ketrics.Volume.connect() for S3 storage
-  try {
-    const volume = await ketrics.Volume.connect('uploads');
-
-    // Get a file
-    const file = await volume.get('documents/report.pdf');
-    console.log('Content-Type:', file.contentType);
-    console.log('Size:', file.contentLength);
-
-    return { success: true, size: file.contentLength };
-  } catch (error) {
-    // Error classes are on the ketrics object
-    if (error instanceof ketrics.VolumeNotFoundError) {
-      return { error: `Volume '${error.volumeCode}' not found` };
-    }
-    if (error instanceof ketrics.FileNotFoundError) {
-      return { error: `File '${error.key}' not found` };
-    }
-    throw error;
-  }
+  // Access S3 volumes
+  const volume = await ketrics.Volume.connect('uploads');
+  const file = await volume.get('report.pdf');
+
+  // Access external databases
+  const db = await ketrics.DatabaseConnection.connect('main-db');
+  const result = await db.query('SELECT * FROM users');
+  await db.close();
+
+  // Access encrypted secrets
+  const apiKey = await ketrics.Secret.get('stripe-api-key');
+
+  // Read/write Excel files
+  const workbook = await ketrics.Excel.read(file.content);
+  const sheet = workbook.getWorksheet('Sheet1');
+
+  return { success: true };
 }
 ```
 
-## Available APIs
+---
+
+## Context Properties (Read-only)
 
-### Context (Read-only)
+### Tenant Context
 
-Access information about the current tenant, application, user, and environment:
+Access information about the current tenant:
 
 ```typescript
-// Tenant context
-ketrics.tenant.id       // Tenant UUID
-ketrics.tenant.code     // e.g., "acme-corp"
-ketrics.tenant.name     // e.g., "ACME Corporation"
+ketrics.tenant.id       // Tenant UUID (e.g., "550e8400-e29b-41d4-a716-446655440000")
+ketrics.tenant.code     // Tenant code/slug (e.g., "acme-corp")
+ketrics.tenant.name     // Tenant display name (e.g., "ACME Corporation")
+```
+
+### Application Context
+
+Access information about the current application:
 
-// Application context
+```typescript
 ketrics.application.id           // Application UUID
-ketrics.application.code         // e.g., "inventory"
-ketrics.application.name         // e.g., "Inventory Manager"
+ketrics.application.code         // Application code (e.g., "inventory")
+ketrics.application.name         // Application display name (e.g., "Inventory Manager")
+ketrics.application.version      // Application version (optional)
 ketrics.application.deploymentId // Current deployment ID
+```
+
+### User Context
 
-// User context
+Access information about the user making the request:
+
+```typescript
 ketrics.user.id       // User UUID
-ketrics.user.email    // e.g., "user@example.com"
-ketrics.user.name     // e.g., "John Doe"
-ketrics.user.isAdmin  // boolean
+ketrics.user.email    // User email (e.g., "john@example.com")
+ketrics.user.name     // User full name (e.g., "John Doe")
+ketrics.user.isAdmin  // Whether user is tenant admin (boolean)
+```
+
+### Environment Context
+
+Access runtime environment information:
+
+```typescript
+ketrics.env.nodeVersion  // Node.js version (e.g., "v18.17.0")
+ketrics.env.runtime      // Runtime platform ("ecs-fargate")
+ketrics.env.region       // AWS region (e.g., "us-east-1")
+```
+
+### Environment Variables
+
+Access application-level environment variables configured in the Ketrics portal:
 
-// Environment context
-ketrics.env.nodeVersion  // e.g., "18.x"
-ketrics.env.runtime      // "ecs-fargate"
-ketrics.env.region       // e.g., "us-east-1"
+```typescript
+// Access custom environment variables set for your application
+const apiEndpoint = ketrics.environment['API_ENDPOINT'];
+const debugMode = ketrics.environment['DEBUG_MODE'];
+const maxRetries = ketrics.environment['MAX_RETRIES'];
+
+// Example: Configure behavior based on env vars
+if (ketrics.environment['FEATURE_FLAG_NEW_UI'] === 'true') {
+  // Use new UI logic
+}
 ```
 
-### Console Logging
+---
+
+## Console Logging
 
-Logs are forwarded to CloudWatch with proper context:
+Logs are automatically forwarded to CloudWatch with proper context (tenant, application, user, request ID):
 
 ```typescript
-ketrics.console.log('Info message');
-ketrics.console.error('Error message');
-ketrics.console.warn('Warning message');
-ketrics.console.info('Info message');
-ketrics.console.debug('Debug message');
+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 });
 ```
 
-### HTTP Client
+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)
 
-Make external API requests:
+---
+
+## HTTP Client
+
+Make external API requests with built-in timeout and user agent:
 
 ```typescript
 // GET request
 const response = await ketrics.http.get<MyData>('https://api.example.com/data');
 console.log(response.data, response.status);
 
-// POST request
-const result = await ketrics.http.post('https://api.example.com/submit', {
-  name: 'Test',
+// 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',
 });
 
-// With options
+// 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 token' },
-  timeout: 5000,
+  headers: {
+    'Authorization': 'Bearer token123',
+    'X-Custom-Header': 'value',
+  },
+  timeout: 5000,  // 5 seconds
   params: { page: 1, limit: 10 },
+  maxRedirects: 3,
 });
 ```
 
-### Volume Storage
+### Response Structure
 
-S3-backed file storage with granular permissions. Access via `ketrics.Volume`:
+```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 types only if needed for type annotations
-import type { FileContent, PutResult, ListResult, IVolume } from '@ketrics/sdk';
+import type { IVolume, FileContent, PutResult, ListResult } from '@ketrics/sdk-backend';
 
-// Connect to a volume via ketrics.Volume
+// Connect to a volume by code
 const volume = await ketrics.Volume.connect('uploads');
 
-// Check permissions
+// Check volume info
 console.log(volume.code);        // 'uploads'
 console.log(volume.permissions); // Set { 'ReadObject', 'CreateObject', ... }
+```
+
+### Reading Files
 
-// Read a file
+```typescript
+// Get file content
 const file: FileContent = await volume.get('documents/report.pdf');
-console.log(file.content);        // Buffer
+console.log(file.content);        // Buffer containing file data
 console.log(file.contentType);    // 'application/pdf'
-console.log(file.contentLength);  // 12345
-console.log(file.lastModified);   // Date
-console.log(file.etag);           // 'abc123'
+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');
 
-// Write a file
-const result: PutResult = await volume.put('output/data.json', JSON.stringify(data), {
+// 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',
-  metadata: { author: ketrics.user.email },
 });
 console.log(result.key, result.etag, result.size);
 
-// Check if file exists
-const exists = await volume.exists('config.json');
+// Write binary content
+const buffer = Buffer.from('Hello World');
+await volume.put('files/hello.txt', buffer);
 
-// Get file metadata (without downloading content)
-const meta = await volume.getMetadata('large-file.zip');
-console.log(meta.size, meta.contentType);
+// Write with metadata
+await volume.put('documents/report.pdf', pdfBuffer, {
+  contentType: 'application/pdf',
+  metadata: {
+    author: ketrics.user.email,
+    version: '1.0',
+  },
+});
 
-// List files
-const list: ListResult = await volume.list({ prefix: 'documents/', maxResults: 100 });
+// Create only if file doesn't exist
+try {
+  await volume.put('config.json', defaultConfig, { ifNotExists: true });
+} catch (error) {
+  if (error instanceof ketrics.FileAlreadyExistsError) {
+    console.log('Config already exists, skipping');
+  }
+}
+```
+
+### 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);
 }
-if (list.isTruncated) {
-  // Fetch next page
-  const nextPage = await volume.list({
-    prefix: 'documents/',
-    continuationToken: list.continuationToken,
+
+// 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,
   });
 }
 
-// Delete a file
+// 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 deleteResult = await volume.deleteByPrefix('temp/');
-console.log(`Deleted ${deleteResult.deletedCount} files`);
+const result = await volume.deleteByPrefix('temp/');
+console.log(`Deleted ${result.deletedCount} files`);
+console.log('Deleted keys:', result.deletedKeys);
+```
+
+### Copying and Moving Files
 
+```typescript
 // Copy a file
 await volume.copy('source.pdf', 'backup/source.pdf');
 
-// Move a file
+// Copy with metadata replacement
+await volume.copy('source.pdf', 'archive/source.pdf', {
+  metadataDirective: 'REPLACE',
+  metadata: { archived: 'true', archivedBy: ketrics.user.email },
+});
+
+// Move a file (copy + delete)
 await volume.move('temp/upload.pdf', 'documents/final.pdf');
+```
+
+### Generating Presigned URLs
 
-// Generate presigned URLs
+```typescript
+// Generate download URL (for sharing)
 const downloadUrl = await volume.generateDownloadUrl('report.pdf', {
   expiresIn: 3600, // 1 hour
   responseContentDisposition: 'attachment; filename="report.pdf"',
 });
-console.log(downloadUrl.url, downloadUrl.expiresAt);
+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
 ```
 
-### Database Connections
+---
+
+## Database Connections
+
+Access external databases (PostgreSQL, MySQL, MSSQL) with connection pooling:
+
+### Connecting to a Database
+
+```typescript
+import type { IDatabaseConnection, DatabaseQueryResult } from '@ketrics/sdk-backend';
+
+// Connect to a database by code
+const db = await ketrics.DatabaseConnection.connect('main-db');
+
+// Check connection info
+console.log(db.code);        // 'main-db'
+console.log(db.permissions); // Set { 'query', 'execute', ... }
+```
+
+### Querying Data
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  created_at: Date;
+}
+
+// Simple query
+const result = await db.query<User>('SELECT * FROM users');
+console.log(result.rows);     // [{ id: 1, name: 'John', ... }, ...]
+console.log(result.rowCount); // 10
+
+// Query with parameters (prevents SQL injection)
+const users = await db.query<User>(
+  'SELECT * FROM users WHERE age > ? AND status = ?',
+  [18, 'active']
+);
+
+// Query single record
+const user = await db.query<User>(
+  'SELECT * FROM users WHERE id = ?',
+  [userId]
+);
+if (user.rows.length > 0) {
+  console.log('Found user:', user.rows[0].name);
+}
+```
 
-Access external databases:
+### Executing Statements
 
 ```typescript
-const db = await ketrics.databases.connect('main-db');
-if (db) {
-  // SELECT query
-  const result = await db.query<User>('SELECT * FROM users WHERE id = ?', [userId]);
-  console.log(result.rows, result.rowCount);
+// INSERT
+const insertResult = await db.execute(
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['John Doe', 'john@example.com']
+);
+console.log(insertResult.affectedRows); // 1
+console.log(insertResult.insertId);     // 123 (auto-increment ID)
+
+// UPDATE
+const updateResult = await db.execute(
+  'UPDATE users SET status = ? WHERE id = ?',
+  ['inactive', userId]
+);
+console.log(updateResult.affectedRows); // Number of rows updated
+
+// DELETE
+const deleteResult = await db.execute(
+  'DELETE FROM users WHERE status = ?',
+  ['deleted']
+);
+console.log(deleteResult.affectedRows); // Number of rows deleted
+```
+
+### Transactions
 
-  // INSERT/UPDATE/DELETE
-  const execResult = await db.execute(
-    'INSERT INTO logs (message) VALUES (?)',
-    ['User logged in']
+```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]
   );
-  console.log(execResult.affectedRows, execResult.insertId);
 
-  // Transaction
-  const transactionResult = await db.transaction(async (tx) => {
-    await tx.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [100, fromId]);
-    await tx.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [100, toId]);
-    return { success: true };
+  // Credit to account
+  await tx.execute(
+    'UPDATE accounts SET balance = balance + ? WHERE id = ?',
+    [100, toAccountId]
+  );
+
+  // Record transfer
+  const transfer = await tx.execute(
+    'INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)',
+    [fromAccountId, toAccountId, 100]
+  );
+
+  return { transferId: transfer.insertId };
+});
+
+console.log('Transfer completed:', result.transferId);
+```
+
+### Closing Connections
+
+```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();
+}
+```
+
+---
+
+## Secrets
+
+Access encrypted secrets stored with tenant-specific KMS encryption:
+
+### Getting Secrets
+
+```typescript
+// Get a secret value
+const apiKey = await ketrics.Secret.get('stripe-api-key');
+
+// Use the secret (value is decrypted automatically)
+const response = await ketrics.http.post('https://api.stripe.com/v1/charges', data, {
+  headers: { 'Authorization': `Bearer ${apiKey}` },
+});
+```
+
+### Checking Secret Existence
+
+```typescript
+// Check if a secret exists before using it
+if (await ketrics.Secret.exists('optional-webhook-secret')) {
+  const secret = await ketrics.Secret.get('optional-webhook-secret');
+  // Use the optional secret
+} else {
+  // Use default behavior
+}
+```
+
+### Common Patterns
+
+```typescript
+// Database password from secret
+const dbPassword = await ketrics.Secret.get('db-password');
+
+// API keys
+const stripeKey = await ketrics.Secret.get('stripe-api-key');
+const sendgridKey = await ketrics.Secret.get('sendgrid-api-key');
+
+// OAuth credentials
+const clientId = await ketrics.Secret.get('oauth-client-id');
+const clientSecret = await ketrics.Secret.get('oauth-client-secret');
+```
+
+---
+
+## Excel Files
+
+Read and write Excel files (.xlsx) using a simple API:
+
+### Reading Excel Files
+
+```typescript
+import type { IExcelWorkbook, IExcelWorksheet, IExcelRow } from '@ketrics/sdk-backend';
+
+// Read from volume
+const volume = await ketrics.Volume.connect('uploads');
+const file = await volume.get('data/report.xlsx');
+
+// Parse Excel file
+const workbook = await ketrics.Excel.read(file.content);
+
+// Get worksheet by name
+const sheet = workbook.getWorksheet('Sheet1');
+if (!sheet) {
+  throw new Error('Sheet not found');
+}
+
+// Get worksheet by index (1-indexed)
+const firstSheet = workbook.getWorksheet(1);
+
+// List all worksheets
+console.log(`Workbook has ${workbook.worksheetCount} sheets`);
+for (const ws of workbook.worksheets) {
+  console.log(`- ${ws.name}: ${ws.actualRowCount} rows`);
+}
+```
+
+### Reading Rows and Cells
+
+```typescript
+// Get all rows with values
+const rows = sheet.getRows();
+for (const row of rows) {
+  console.log('Row', row.number, ':', row.values);
+}
+
+// Get a specific row (1-indexed)
+const headerRow = sheet.getRow(1);
+console.log('Headers:', headerRow.values);
+
+// Get a specific cell
+const cell = sheet.getCell('A1');
+console.log(cell.value, cell.text, cell.address);
+
+// Get cell by coordinates
+const cellB2 = sheet.getCell(2, 2);
+
+// Iterate over rows
+sheet.eachRow((row, rowNumber) => {
+  console.log(`Row ${rowNumber}:`, row.values);
+});
+
+// Include empty rows
+sheet.eachRow((row, rowNumber) => {
+  console.log(`Row ${rowNumber}:`, row.values);
+}, { includeEmpty: true });
+
+// Get all values as 2D array
+const allValues = sheet.getSheetValues();
+// allValues[1] = first row, allValues[1][1] = cell A1
+```
+
+### Working with Cells
+
+```typescript
+// Get cell properties
+const cell = sheet.getCell('B5');
+console.log(cell.value);    // Cell value (number, string, Date, etc.)
+console.log(cell.text);     // Text representation
+console.log(cell.address);  // 'B5'
+console.log(cell.row);      // 5
+console.log(cell.col);      // 2
+console.log(cell.formula);  // Formula if present (e.g., '=SUM(A1:A10)')
+console.log(cell.type);     // Cell type
+
+// Iterate over cells in a row
+const row = sheet.getRow(1);
+row.eachCell((cell, colNumber) => {
+  console.log(`Column ${colNumber}:`, cell.value);
+});
+```
+
+### Creating Excel Files
+
+```typescript
+// Create new workbook
+const workbook = ketrics.Excel.create();
+
+// Add worksheet
+const sheet = workbook.addWorksheet('Sales Report', {
+  tabColor: 'FF0000', // Red tab
+  defaultRowHeight: 20,
+  defaultColWidth: 15,
+});
+
+// Define columns (optional)
+sheet.columns = [
+  { header: 'ID', key: 'id', width: 10 },
+  { header: 'Product', key: 'product', width: 30 },
+  { header: 'Price', key: 'price', width: 15 },
+  { header: 'Quantity', key: 'qty', width: 10 },
+];
+
+// Add rows
+sheet.addRow(['1', 'Widget A', 9.99, 100]);
+sheet.addRow(['2', 'Widget B', 19.99, 50]);
+sheet.addRow(['3', 'Widget C', 29.99, 25]);
+
+// Add multiple rows at once
+sheet.addRows([
+  ['4', 'Widget D', 39.99, 10],
+  ['5', 'Widget E', 49.99, 5],
+]);
+
+// Insert row at position
+sheet.insertRow(2, ['INSERTED', 'Row', 0, 0]);
+
+// Merge cells
+sheet.mergeCells('A1', 'D1'); // Merge A1:D1
+sheet.mergeCells(5, 1, 5, 4); // Merge row 5, columns 1-4
+
+// Write to buffer
+const buffer = await workbook.toBuffer();
+
+// Save to volume
+await volume.put('output/report.xlsx', buffer, {
+  contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+});
+```
+
+### Converting to CSV
+
+```typescript
+// Convert worksheet to CSV
+const csvContent = await workbook.toCsv('Sheet1');
+
+// Save as CSV
+await volume.put('output/data.csv', csvContent, {
+  contentType: 'text/csv',
+});
+```
+
+### Managing Worksheets
+
+```typescript
+// Remove worksheet
+workbook.removeWorksheet('TempSheet');
+workbook.removeWorksheet(2); // By index
+
+// Rename worksheet
+const sheet = workbook.getWorksheet('OldName');
+if (sheet) {
+  sheet.name = 'NewName';
+}
+```
+
+---
+
+## PDF Files
+
+Read, create, and modify PDF files using the pdf-lib wrapper:
+
+### Reading PDF Files
+
+```typescript
+import type { IPdfDocument, IPdfPage } from '@ketrics/sdk-backend';
+
+// Read from volume
+const volume = await ketrics.Volume.connect('uploads');
+const file = await volume.get('documents/report.pdf');
+
+// Parse PDF file
+const doc = await ketrics.Pdf.read(file.content);
+
+// Get document info
+console.log('Page count:', doc.getPageCount());
+console.log('Title:', doc.getTitle());
+console.log('Author:', doc.getAuthor());
+
+// Get all pages
+const pages = doc.getPages();
+for (const page of pages) {
+  console.log(`Page size: ${page.width}x${page.height}`);
+}
+
+// Get specific page (0-indexed)
+const firstPage = doc.getPage(0);
+console.log('First page size:', firstPage.getSize());
+```
+
+### Creating PDF Files
+
+```typescript
+// Create new empty document
+const doc = await ketrics.Pdf.create();
+
+// Set document metadata
+doc.setTitle('Sales Report Q4 2024');
+doc.setAuthor(ketrics.user.name);
+doc.setSubject('Quarterly sales data');
+doc.setKeywords(['sales', 'report', 'Q4', '2024']);
+doc.setCreator('Ketrics Application');
+
+// Add pages with different sizes
+const pageA4 = doc.addPage('A4');        // Standard A4
+const pageLetter = doc.addPage('Letter'); // US Letter
+const pageCustom = doc.addPage([600, 400]); // Custom size in points
+
+// Insert page at specific position (0-indexed)
+const insertedPage = doc.insertPage(1, 'A4');
+
+// Remove a page
+doc.removePage(2);
+
+// Write to buffer
+const buffer = await doc.toBuffer();
+
+// Save to volume
+await volume.put('output/report.pdf', buffer, {
+  contentType: 'application/pdf',
+});
+```
+
+### Drawing Text
+
+```typescript
+const doc = await ketrics.Pdf.create();
+const page = doc.addPage('A4');
+
+// Simple text (default: Helvetica, 12pt, black)
+await page.drawText('Hello, World!', { x: 50, y: 700 });
+
+// Styled text
+await page.drawText('Large Red Title', {
+  x: 50,
+  y: 750,
+  size: 32,
+  color: ketrics.Pdf.rgb(1, 0, 0), // Red (RGB values 0-1)
+});
+
+// Text with custom font
+const boldFont = await doc.embedStandardFont('HelveticaBold');
+await page.drawText('Bold Text', {
+  x: 50,
+  y: 650,
+  size: 16,
+  font: boldFont,
+});
+
+// Rotated text
+await page.drawText('Rotated', {
+  x: 200,
+  y: 500,
+  size: 14,
+  rotate: 45, // degrees
+});
+
+// Text with opacity
+await page.drawText('Semi-transparent', {
+  x: 50,
+  y: 600,
+  size: 14,
+  opacity: 0.5,
+});
+
+// Multiline text with wrapping
+await page.drawText('This is a long paragraph that will wrap to multiple lines when it exceeds the maximum width.', {
+  x: 50,
+  y: 550,
+  size: 12,
+  maxWidth: 200,
+  lineHeight: 16,
+});
+```
+
+### Drawing Shapes
+
+```typescript
+const doc = await ketrics.Pdf.create();
+const page = doc.addPage('A4');
+
+// Rectangle (filled)
+page.drawRectangle({
+  x: 50,
+  y: 600,
+  width: 200,
+  height: 100,
+  color: ketrics.Pdf.rgb(0.2, 0.4, 0.8), // Blue fill
+});
+
+// Rectangle (outlined)
+page.drawRectangle({
+  x: 50,
+  y: 480,
+  width: 200,
+  height: 100,
+  borderColor: ketrics.Pdf.rgb(0, 0, 0),
+  borderWidth: 2,
+});
+
+// Rectangle (filled with border)
+page.drawRectangle({
+  x: 50,
+  y: 360,
+  width: 200,
+  height: 100,
+  color: ketrics.Pdf.rgb(0.9, 0.9, 0.9), // Light gray fill
+  borderColor: ketrics.Pdf.rgb(0, 0, 0),
+  borderWidth: 1,
+  opacity: 0.8,
+});
+
+// Line
+page.drawLine({
+  start: { x: 50, y: 340 },
+  end: { x: 250, y: 340 },
+  thickness: 2,
+  color: ketrics.Pdf.rgb(0, 0, 0),
+});
+
+// Circle
+page.drawCircle({
+  x: 150,
+  y: 250,
+  radius: 50,
+  color: ketrics.Pdf.rgb(0.8, 0.2, 0.2), // Red fill
+  borderColor: ketrics.Pdf.rgb(0, 0, 0),
+  borderWidth: 2,
+});
+```
+
+### Embedding Images
+
+```typescript
+const doc = await ketrics.Pdf.create();
+const page = doc.addPage('A4');
+
+// Read image from volume
+const volume = await ketrics.Volume.connect('uploads');
+const logoFile = await volume.get('images/logo.png');
+const photoFile = await volume.get('images/photo.jpg');
+
+// Embed PNG image
+const pngImage = await doc.embedPng(logoFile.content);
+console.log('PNG dimensions:', pngImage.width, 'x', pngImage.height);
+
+// Embed JPG image
+const jpgImage = await doc.embedJpg(photoFile.content);
+
+// Draw image at original size
+page.drawImage(pngImage, { x: 50, y: 700 });
+
+// Draw image at specific size
+page.drawImage(jpgImage, {
+  x: 50,
+  y: 500,
+  width: 200,
+  height: 150,
+});
+
+// Draw image with opacity
+page.drawImage(pngImage, {
+  x: 300,
+  y: 700,
+  opacity: 0.5,
+});
+
+// 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 });
+```
+
+### 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),
   });
+}
 
-  // Always close when done
+// Save modified document
+const buffer = await doc.toBuffer();
+await volume.put('modified.pdf', buffer, {
+  contentType: 'application/pdf',
+});
+```
+
+### Complete PDF Generation Example
+
+```typescript
+export async function generateInvoice(orderId: string) {
+  // Get order data from database
+  const db = await ketrics.DatabaseConnection.connect('orders-db');
+  const orderResult = await db.query(
+    'SELECT * FROM orders WHERE id = ?',
+    [orderId]
+  );
+  const order = orderResult.rows[0];
   await db.close();
+
+  // Create PDF
+  const doc = await ketrics.Pdf.create();
+  doc.setTitle(`Invoice #${order.invoice_number}`);
+  doc.setAuthor(ketrics.tenant.name);
+
+  const page = doc.addPage('A4');
+  const { width, height } = page.getSize();
+
+  // Embed fonts
+  const boldFont = await doc.embedStandardFont('HelveticaBold');
+  const regularFont = await doc.embedStandardFont('Helvetica');
+
+  // Header
+  await page.drawText(ketrics.tenant.name, {
+    x: 50,
+    y: height - 50,
+    size: 24,
+    font: boldFont,
+  });
+
+  await page.drawText(`Invoice #${order.invoice_number}`, {
+    x: 50,
+    y: height - 90,
+    size: 18,
+    font: regularFont,
+    color: ketrics.Pdf.rgb(0.4, 0.4, 0.4),
+  });
+
+  // Customer info
+  await page.drawText('Bill To:', {
+    x: 50,
+    y: height - 150,
+    size: 12,
+    font: boldFont,
+  });
+
+  await page.drawText(order.customer_name, {
+    x: 50,
+    y: height - 170,
+    size: 12,
+    font: regularFont,
+  });
+
+  // Line items header
+  const tableTop = height - 250;
+  page.drawRectangle({
+    x: 50,
+    y: tableTop - 5,
+    width: width - 100,
+    height: 25,
+    color: ketrics.Pdf.rgb(0.9, 0.9, 0.9),
+  });
+
+  await page.drawText('Item', { x: 55, y: tableTop, size: 10, font: boldFont });
+  await page.drawText('Qty', { x: 300, y: tableTop, size: 10, font: boldFont });
+  await page.drawText('Price', { x: 380, y: tableTop, size: 10, font: boldFont });
+  await page.drawText('Total', { x: 460, y: tableTop, size: 10, font: boldFont });
+
+  // Line items (simplified example)
+  let yPos = tableTop - 30;
+  for (const item of order.items) {
+    await page.drawText(item.name, { x: 55, y: yPos, size: 10, font: regularFont });
+    await page.drawText(String(item.quantity), { x: 300, y: yPos, size: 10, font: regularFont });
+    await page.drawText(`$${item.price.toFixed(2)}`, { x: 380, y: yPos, size: 10, font: regularFont });
+    await page.drawText(`$${(item.quantity * item.price).toFixed(2)}`, { x: 460, y: yPos, size: 10, font: regularFont });
+    yPos -= 20;
+  }
+
+  // Total line
+  page.drawLine({
+    start: { x: 380, y: yPos + 5 },
+    end: { x: width - 50, y: yPos + 5 },
+    thickness: 1,
+    color: ketrics.Pdf.rgb(0, 0, 0),
+  });
+
+  await page.drawText('Total:', { x: 380, y: yPos - 15, size: 12, font: boldFont });
+  await page.drawText(`$${order.total.toFixed(2)}`, { x: 460, y: yPos - 15, size: 12, font: boldFont });
+
+  // Footer
+  await page.drawText(`Generated on ${new Date().toLocaleDateString()}`, {
+    x: 50,
+    y: 30,
+    size: 8,
+    color: ketrics.Pdf.rgb(0.6, 0.6, 0.6),
+  });
+
+  // Save to volume
+  const volume = await ketrics.Volume.connect('invoices');
+  const buffer = await doc.toBuffer();
+  await volume.put(`${order.invoice_number}.pdf`, buffer, {
+    contentType: 'application/pdf',
+    metadata: {
+      orderId: order.id,
+      generatedBy: ketrics.user.email,
+    },
+  });
+
+  return {
+    success: true,
+    invoiceNumber: order.invoice_number,
+  };
 }
 ```
 
+---
+
 ## Error Handling
 
-Error classes are available on the `ketrics` object for `instanceof` checks:
+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) {
-  // Error classes are on the ketrics object
   if (error instanceof ketrics.VolumeNotFoundError) {
     console.log(`Volume '${error.volumeCode}' not found`);
   } else if (error instanceof ketrics.VolumeAccessDeniedError) {
@@ -259,19 +1181,152 @@ try {
 }
 ```
 
-### Available Error Classes (on `ketrics` object)
+### 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;
+  }
+}
+```
+
+### Secret Errors
+
+```typescript
+try {
+  const secret = await ketrics.Secret.get('api-key');
+} catch (error) {
+  if (error instanceof ketrics.SecretNotFoundError) {
+    console.log(`Secret '${error.secretCode}' not found`);
+  } else if (error instanceof ketrics.SecretAccessDeniedError) {
+    console.log(`No access to secret '${error.secretCode}'`);
+  } else if (error instanceof ketrics.SecretDecryptionError) {
+    console.log(`Decryption failed: ${error.reason}`);
+  } else if (error instanceof ketrics.SecretError) {
+    // Base class catches all secret errors
+    console.log(`Secret error: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+### Excel Errors
+
+```typescript
+try {
+  const workbook = await ketrics.Excel.read(buffer);
+  const outputBuffer = await workbook.toBuffer();
+} catch (error) {
+  if (error instanceof ketrics.ExcelParseError) {
+    console.log(`Failed to parse Excel: ${error.reason}`);
+  } else if (error instanceof ketrics.ExcelWriteError) {
+    console.log(`Failed to write Excel: ${error.reason}`);
+  } else if (error instanceof ketrics.ExcelError) {
+    // Base class catches all Excel errors
+    console.log(`Excel error: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+### PDF Errors
+
+```typescript
+try {
+  const doc = await ketrics.Pdf.read(buffer);
+  const page = doc.addPage('A4');
+  await page.drawText('Hello');
+  const outputBuffer = await doc.toBuffer();
+} catch (error) {
+  if (error instanceof ketrics.PdfParseError) {
+    console.log(`Failed to parse PDF: ${error.reason}`);
+  } else if (error instanceof ketrics.PdfWriteError) {
+    console.log(`Failed to write PDF: ${error.reason}`);
+  } else if (error instanceof ketrics.PdfError) {
+    // Base class catches all PDF errors
+    console.log(`PDF error: ${error.message}`);
+  } else {
+    throw error;
+  }
+}
+```
+
+---
+
+## Error Class Reference
+
+### Volume Errors
 
 | Error Class | When Thrown |
 |-------------|-------------|
-| `ketrics.VolumeError` | Base class for all volume errors |
-| `ketrics.VolumeNotFoundError` | Volume doesn't exist |
-| `ketrics.VolumeAccessDeniedError` | Application has no access grant |
-| `ketrics.VolumePermissionDeniedError` | Missing required permission |
-| `ketrics.FileNotFoundError` | File doesn't exist |
-| `ketrics.FileAlreadyExistsError` | File exists (with `ifNotExists` option) |
-| `ketrics.InvalidPathError` | Invalid file path |
-| `ketrics.FileSizeLimitError` | File exceeds size limit |
-| `ketrics.ContentTypeNotAllowedError` | Content type not allowed |
+| `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
 
@@ -314,16 +1369,145 @@ import type {
   PresignedUrl,
 
   // Databases
-  DatabaseManager,
-  DatabaseConnection,
+  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';
+} from '@ketrics/sdk-backend';
+```
+
+---
+
+## Complete Example
+
+Here's a complete example showing multiple SDK features working together:
+
+```typescript
+import type { IVolume, IDatabaseConnection, FileContent } from '@ketrics/sdk-backend';
+
+interface Order {
+  id: number;
+  customer_name: string;
+  total: number;
+  status: string;
+}
+
+export async function generateReport() {
+  ketrics.console.log('Starting report generation', {
+    tenant: ketrics.tenant.code,
+    user: ketrics.user.email,
+  });
+
+  // Get API key from secrets
+  const emailApiKey = await ketrics.Secret.get('sendgrid-api-key');
+
+  // Connect to database
+  const db = await ketrics.DatabaseConnection.connect('orders-db');
+
+  try {
+    // Query orders from database
+    const orders = await db.query<Order>(
+      'SELECT * FROM orders WHERE status = ? AND created_at > ?',
+      ['completed', '2024-01-01']
+    );
+
+    ketrics.console.info(`Found ${orders.rowCount} orders`);
+
+    // Create Excel report
+    const workbook = ketrics.Excel.create();
+    const sheet = workbook.addWorksheet('Orders Report');
+
+    // Add header row
+    sheet.addRow(['Order ID', 'Customer', 'Total', 'Status']);
+
+    // Add data rows
+    for (const order of orders.rows) {
+      sheet.addRow([order.id, order.customer_name, order.total, order.status]);
+    }
+
+    // Calculate total
+    const total = orders.rows.reduce((sum, o) => sum + o.total, 0);
+    sheet.addRow(['', 'TOTAL', total, '']);
+
+    // Generate buffer
+    const buffer = await workbook.toBuffer();
+
+    // Save to volume
+    const volume = await ketrics.Volume.connect('reports');
+    const fileName = `orders-${new Date().toISOString().split('T')[0]}.xlsx`;
+
+    await volume.put(`monthly/${fileName}`, buffer, {
+      contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      metadata: {
+        generatedBy: ketrics.user.email,
+        orderCount: String(orders.rowCount),
+      },
+    });
+
+    // Generate download URL
+    const downloadUrl = await volume.generateDownloadUrl(`monthly/${fileName}`, {
+      expiresIn: 86400, // 24 hours
+    });
+
+    // Send email notification via external API
+    await ketrics.http.post('https://api.sendgrid.com/v3/mail/send', {
+      to: ketrics.user.email,
+      subject: 'Your report is ready',
+      body: `Download your report: ${downloadUrl.url}`,
+    }, {
+      headers: { 'Authorization': `Bearer ${emailApiKey}` },
+    });
+
+    ketrics.console.log('Report generated successfully', { fileName });
+
+    return {
+      success: true,
+      fileName,
+      downloadUrl: downloadUrl.url,
+      orderCount: orders.rowCount,
+      total,
+    };
+
+  } finally {
+    await db.close();
+  }
+}
 ```
 
+---
+
 ## License
 
 MIT