npm package: @inbox-api/client
Description: HTTP client for the Inbox API — shared by MCP server and CLI
Author: CloudWorks
Latest version: 0.1.4

# @inbox-api/client

Shared HTTP client and TypeScript types for the [Inbox API](https://inbox-api.com). Used internally by `@inbox-api/mcp` and `@inbox-api/cli`.

## Installation

```bash
npm install @inbox-api/client
```

## Usage

```typescript
import { ApiClient, ApiError } from '@inbox-api/client';
import type { AccountInfo, MessageListResponse, PagedResult } from '@inbox-api/client';

const client = new ApiClient('https://api.inbox-api.com', 'cw_your_token');

// List email accounts (paginated)
const accounts = await client.get<PagedResult<AccountInfo>>('/api/email/accounts', {
  pageSize: '100',
});

// List messages with filters and sorting
const messages = await client.get<MessageListResponse>('/api/email/messages', {
  accountId: 'some-uuid',
  isRead: 'false',
  sort: 'date',
  page: '1',
  pageSize: '10',
});

// Search messages with BM25 ranking
const results = await client.get<MessageListResponse>('/api/email/messages', {
  q: 'invoice from:billing@vendor.com',
  sort: 'relevance',
  pageSize: '10',
});

// Send an email
await client.post('/api/email/send', {
  accountId: 'some-uuid',
  to: [{ email: 'recipient@example.com', name: 'Recipient' }],
  subject: 'Hello',
  textBody: 'Message body here.',
});

// Error handling
try {
  await client.get('/api/email/messages/invalid-id');
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.status);  // HTTP status code (e.g. 404)
    console.error(err.message); // "API error 404: Not found"
  }
}
```

## API

### `ApiClient`

```typescript
new ApiClient(baseUrl: string, token: string)
```

| Method | Signature | Description |
|--------|-----------|-------------|
| `get` | `get<T>(path, params?)` | GET request with optional query parameters |
| `post` | `post<T>(path, body?)` | POST request with optional JSON body |
| `put` | `put<T>(path, body?)` | PUT request with optional JSON body |
| `patch` | `patch<T>(path, body?)` | PATCH request with optional JSON body |
| `delete` | `delete<T>(path)` | DELETE request |

All methods return `Promise<T>` and throw `ApiError` on non-2xx responses.

### `ApiError`

```typescript
class ApiError extends Error {
  readonly status: number;
}
```

### Types

**Entity types:**

- `AccountInfo` — email account summary (id, displayName, emailAddress, provider, messageCount, unreadCount)
- `MessageDto` — email message metadata (id, subject, from/to/cc, dates, flags)
- `MessageBody` — email content (textBody, htmlBody)
- `ThreadDetailDto` — conversation thread with nested messages
- `DraftDto` — draft email (id, accountId, subject, body, createdAt)
- `FolderDto` — mailbox folder (id, name, fullPath, counts)
- `AddressDto` — email address with optional display name
- `AttachmentDto` — attachment metadata (fileName, mimeType, size, isInline)
- `ContactDto` — email contact with frequency and last seen date
- `WebhookDto` — webhook subscription (url, events, payloadLevel, isActive)
- `WebhookDeliveryDto` — webhook delivery status

**Request types:**

- `SendEmailRequest`, `ReplyRequest`, `ForwardEmailRequest`
- `CreateDraftRequest`, `UpdateDraftRequest`
- `MoveMessageRequest`, `UpdateMessageFlagsRequest`
- `CreateWebhookRequest`, `UpdateWebhookRequest`

**Response types:**

- `PagedResult<T>` — generic paged response (items, totalCount, page, pageSize)
- `MessageListResponse` — alias for `PagedResult<MessageDto>`
- `DigestResponse` — email digest with per-account summaries
- `AccountHealthDto` — IMAP connection health status
- `BatchOperationResponse` — batch operation results

## Prerequisites

- Node.js >= 18 (uses built-in `fetch`)

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev
```

This package has no runtime dependencies. It uses the built-in `fetch` API available in Node.js 18+.

## License

MIT