@pompeii-labs/pompeii/README.md

The Pompeii Platform SDK from Pompeii Labs

# Pompeii SDK

A TypeScript SDK for interacting with the Pompeii API - enabling seamless integration with AI agents and platform notifications.

**Note:** Before you write any code, create your project in the Pompeii dashboard and get your project API key.

For questions or support, email [support@pompeiilabs.com](mailto:support@pompeiilabs.com)

## Installation

```bash
npm install @pompeii-labs/pompeii
```

## Usage

### Initialize Client

```typescript
import { Pompeii } from '@pompeii-labs/pompeii';
import dotenv from 'dotenv';

dotenv.config();

// API key will be automatically pulled from POMPEII_API_KEY env var
const pompeii = new Pompeii();

// Or provide API key directly
const pompeii = new Pompeii(process.env.POMPEII_API_KEY);
```

### Send Notifications

Send interactive notifications to users on Pompeii. Notifications appear on users' home pages and can include interactive elements.

```typescript
// Send a simple info notification
await pompeii.notify({
    name: 'task_completed',
    payload: {
        type: 'success',
        description: 'Your task has been completed successfully!'
    }
});

// Send notification with interactive actions
await pompeii.notify({
    name: 'approval_request',
    payload: {
        type: 'info',
        description: 'Please review and approve this request',
        actions: [
            {
                type: 'button',
                label: 'Approve',
                action_id: 'approve_request',
                value: { requestId: '123' }
            },
            {
                type: 'button',
                label: 'Reject',
                action_id: 'reject_request',
                value: { requestId: '123' }
            },
            {
                type: 'input',
                label: 'Add a comment',
                action_id: 'add_comment',
                value: { context: 'approval_flow' }
            }
        ]
    },
    user_id: 'user123',
    session_id: 'session456'
});

// Send notification with a link
await pompeii.notify({
    name: 'report_ready',
    payload: {
        type: 'info',
        description: 'Your monthly report is ready for review',
        actions: [
            {
                type: 'link',
                label: 'View Report',
                url: 'https://your-app.com/reports/monthly'
            }
        ]
    }
});
```

### Log Events

Post events to Pompeii for observability. Events appear in the Agent's Observability tab for monitoring and debugging.

```typescript
// Log a custom event
await pompeii.event({
    name: 'user_action',
    type: 'custom',
    payload: {
        action: 'file_uploaded',
        filename: 'document.pdf',
        size: 1024000
    }
});

// Log an error event
await pompeii.event({
    name: 'processing_error',
    type: 'error',
    payload: {
        error: 'Failed to process document',
        errorCode: 'PROC_001',
        details: { documentId: '123', userId: 'user456' }
    },
    user_id: 'user456',
    session_id: 'session789'
});

// Log system metrics
await pompeii.event({
    name: 'system_metrics',
    type: 'metrics',
    payload: {
        cpu_usage: 75.2,
        memory_usage: 1024,
        active_users: 42
    }
});
```

### Download Files

Download files from Pompeii storage to your local environment.

```typescript
// Download specific files
const downloadedFiles = await pompeii.downloadFiles('./downloads', [
    'document1.pdf',
    'image.jpg',
    'data.csv'
]);

console.log('Downloaded files:', downloadedFiles);

// Download all available files
const allFiles = await pompeii.downloadFiles('./downloads');
```

## Environment Variables

- `POMPEII_API_KEY`: Your Agent's Private API key (required)

## Types

### Notification Types

The SDK provides comprehensive TypeScript types for notifications:

```typescript
import { NotificationInsert, NotificationPayload, NotificationAction } from '@pompeii-labs/pompeii';

// Notification with all possible action types
const notification: NotificationInsert = {
    name: 'complex_notification',
    payload: {
        type: 'info', // 'info' | 'error' | 'warning' | 'success'
        description: 'This is a comprehensive notification',
        actions: [
            // Link action
            {
                type: 'link',
                label: 'External Link',
                url: 'https://example.com'
            },
            // Button action
            {
                type: 'button',
                label: 'Click Me',
                action_id: 'button_clicked',
                value: { metadata: 'example' }
            },
            // Input action
            {
                type: 'input',
                label: 'Enter text',
                action_id: 'text_entered',
                value: { metadata: 'example' }
            }
        ]
    },
    user_id: 'optional_user_id',
    session_id: 'optional_session_id'
};
```

### Event Types

```typescript
import { EventInsert } from '@pompeii-labs/pompeii';

const event: EventInsert = {
    name: 'event_name',
    type: 'custom', // Can be any string
    payload: {
        // Any key-value pairs
        key1: 'value1',
        key2: 123,
        key3: { nested: 'object' }
    },
    user_id: 'optional_user_id',
    session_id: 'optional_session_id'
};
```

## License

MIT - see the LICENSE file for details.