@noobforal/openphone-api-sdk/README.md

Unofficial TypeScript SDK for OpenPhone Public API (AI-generated - use with caution)

# OpenPhone API SDK (Unofficial)

A TypeScript SDK for the OpenPhone Public API, built with Bun and designed for modern JavaScript/TypeScript applications.

## ⚠️ Important Disclaimers

**🚨 This is NOT an official OpenPhone SDK. This is an unofficial, community-created SDK.**

**🤖 This SDK was primarily generated by AI and should be used with caution in production environments.**

**👤 Published by: [@noobforal](https://www.npmjs.com/~noobforal) - This is NOT affiliated with OpenPhone company.**

- **Unofficial**: This is not an official OpenPhone product and is not endorsed by OpenPhone
- **Community Support**: This SDK is maintained by the community, not by OpenPhone
- **Code Quality**: While the code has been tested and follows best practices, it may contain issues that weren't caught during initial development
- **Security**: Please review all code thoroughly before using in production, especially authentication and API key handling
- **Testing**: Additional testing is recommended beyond the basic test suite included
- **Maintenance**: This code may require ongoing maintenance and updates as the OpenPhone API evolves
- **Support**: Limited support is available for AI-generated code

**Recommendations:**
- Review all code before production use
- Add comprehensive test coverage for your specific use cases
- Monitor for security vulnerabilities regularly
- Consider contributing improvements back to the project
- Use at your own risk

## Features

- 🔧 **TypeScript First**: Full type safety with auto-generated types from OpenAPI spec
- 🚀 **Modern**: Built with Bun for fast development and execution
- 📦 **Tree-shakable**: ES modules with tree-shaking support
- 🛡️ **Type-safe**: End-to-end type safety for all API calls
- 🔄 **Auto-generated**: Types and client generated from OpenAPI specification
- 📱 **Complete API Coverage**: Support for calls, messages, phone numbers, and webhooks

## Installation

```bash
# Using Bun (recommended)
bun add @noobforal/openphone-api-sdk

# Using npm
npm install @noobforal/openphone-api-sdk

# Using yarn
yarn add @noobforal/openphone-api-sdk

# Using pnpm
pnpm add @noobforal/openphone-api-sdk
```

## Quick Start

```typescript
import { OpenPhoneClient } from '@noobforal/openphone-api-sdk';

// Initialize the client
const client = new OpenPhoneClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.openphone.com', // optional, defaults to this
});

// List phone numbers
const phoneNumbers = await client.listPhoneNumbers();

// List calls
const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 10,
});

// Send a message
const message = await client.sendMessage({
  content: 'Hello from the SDK!',
  from: 'PN123abc',
  to: ['+1234567890'],
});
```

## API Reference

### Configuration

```typescript
interface OpenPhoneConfig {
  apiKey: string;           // Your OpenPhone API key
  baseUrl?: string;         // API base URL (default: 'https://api.openphone.com')
  timeout?: number;         // Request timeout in ms (default: 30000)
}
```

### Calls API

#### `listCalls(params)`

Retrieve a paginated list of calls.

```typescript
const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',     // Required: OpenPhone number ID
  userId: 'US123abc',            // Optional: User ID
  participants: ['+1234567890'], // Required: Array of participant phone numbers
  since: '2024-01-01T00:00:00Z', // Optional: Start date filter
  createdAfter: '2024-01-01T00:00:00Z', // Optional: Created after filter
  createdBefore: '2024-01-31T23:59:59Z', // Optional: Created before filter
  maxResults: 50,                // Required: Maximum number of results
  pageToken: 'next-page-token',  // Optional: Pagination token
});
```

#### `getCall(callId)`

Get details for a specific call.

```typescript
const call = await client.getCall('call-id-here');
```

### Messages API

#### `listMessages(params)`

Retrieve a chronological list of messages.

```typescript
const messages = await client.listMessages({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 50,
  // ... other optional filters
});
```

#### `getMessage(messageId)`

Get details for a specific message.

```typescript
const message = await client.getMessage('message-id-here');
```

#### `sendMessage(params)`

Send a new message.

```typescript
const message = await client.sendMessage({
  content: 'Hello, world!',
  from: 'PN123abc',              // OpenPhone number ID
  to: ['+1234567890'],           // Array of recipient phone numbers
  phoneNumberId: 'PN123abc',     // Optional: Alternative to 'from'
  userId: 'US123abc',            // Optional: User ID
  setInboxStatus: 'done',        // Optional: Set inbox status
});
```

### Phone Numbers API

#### `listPhoneNumbers(params?)`

Retrieve the list of phone numbers and users.

```typescript
const phoneNumbers = await client.listPhoneNumbers({
  userId: 'US123abc', // Optional: Filter by user ID
});
```

### Webhooks API

#### `listWebhooks(params?)`

List all webhooks for a user.

```typescript
const webhooks = await client.listWebhooks({
  userId: 'US123abc', // Optional: Filter by user ID
});
```

#### `getWebhook(webhookId)`

Get details for a specific webhook.

```typescript
const webhook = await client.getWebhook('webhook-id-here');
```

#### Create Webhooks

Create webhooks for different event types:

```typescript
// Message webhook
const messageWebhook = await client.createMessageWebhook({
  url: 'https://your-app.com/webhooks/messages',
  events: ['message.received', 'message.delivered'],
  label: 'My Message Webhook',
  resourceIds: ['PN123abc'], // or '*' for all resources
  status: 'enabled',
});

// Call webhook
const callWebhook = await client.createCallWebhook({
  url: 'https://your-app.com/webhooks/calls',
  events: ['call.completed', 'call.ringing'],
  label: 'My Call Webhook',
  resourceIds: '*',
  status: 'enabled',
});

// Call summary webhook
const summaryWebhook = await client.createCallSummaryWebhook({
  url: 'https://your-app.com/webhooks/summaries',
  events: ['call.summary.completed'],
  label: 'My Summary Webhook',
  resourceIds: '*',
  status: 'enabled',
});

// Call transcript webhook
const transcriptWebhook = await client.createCallTranscriptWebhook({
  url: 'https://your-app.com/webhooks/transcripts',
  events: ['call.transcript.completed'],
  label: 'My Transcript Webhook',
  resourceIds: '*',
  status: 'enabled',
});
```

### Utility Methods

#### `getConfig()`

Get the current client configuration.

```typescript
const config = client.getConfig();
console.log(config.apiKey); // 'your-api-key-here'
```

#### `updateConfig(newConfig)`

Update the client configuration.

```typescript
client.updateConfig({
  baseUrl: 'https://staging-api.openphone.com',
  timeout: 60000,
});
```

## Error Handling

All API methods return a response object with `data`, `error`, and `response` properties:

```typescript
const { data, error, response } = await client.listCalls(params);

if (error) {
  console.error('API Error:', error);
  console.error('Status:', response.status);
  console.error('Status Text:', response.statusText);
} else {
  console.log('Success:', data);
}
```

## TypeScript Support

This SDK is built with TypeScript and provides full type safety. All API responses, request parameters, and client methods are fully typed.

```typescript
import { OpenPhoneClient, OpenPhoneConfig } from '@openphone/api-sdk';
import type { paths } from '@openphone/api-sdk';

// Full type safety for all operations
const client: OpenPhoneClient = new OpenPhoneClient({
  apiKey: 'your-api-key',
});

// TypeScript will provide autocomplete and type checking
const calls = await client.listCalls({
  phoneNumberId: 'PN123abc',
  participants: ['+1234567890'],
  maxResults: 10,
});
```

## Development

### Prerequisites

- [Bun](https://bun.sh) (recommended) or Node.js 18+
- TypeScript 5+

### Building

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run in development mode
bun run dev

# Run tests
bun test

# Lint code
bun run lint

# Format code
bun run format
```

### Project Structure

```
src/
├── index.ts          # Main entry point
├── client.ts         # OpenPhoneClient class
└── types.ts          # Auto-generated TypeScript types
dist/                 # Built output
├── index.js          # Bundled JavaScript
├── index.d.ts        # TypeScript declarations
└── index.d.ts.map    # Source maps
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run the build and tests
6. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- 📧 Email: support@openphone.com
- 📚 Documentation: [https://support.openphone.com/hc/en-us](https://support.openphone.com/hc/en-us)
- 🐛 Issues: [GitHub Issues](https://github.com/openphone/openphone-api-sdk/issues)

## Changelog

### 1.0.1

- Initial release
- Full TypeScript support
- Complete API coverage for calls, messages, phone numbers, and webhooks
- Auto-generated types from OpenAPI specification
- Modern ES modules with tree-shaking support