npm package: @midtownhi/ably
Description: A lightweight TypeScript wrapper around the Ably Realtime and REST APIs, supporting both server-side (Node.js) and client-side (browser) usage.
Latest version: 0.3.0

# @midtownhi/ably

A lightweight TypeScript wrapper around the Ably Realtime and REST APIs, supporting both server-side (Node.js) and client-side (browser) usage.

## Installation

```bash
npm install @midtownhi/ably
# or
yarn add @midtownhi/ably
```

## Features

- Simplified API for working with Ably's realtime pub/sub messaging
- TypeScript support with full type definitions
- Channel management for real-time communication
- Support for both Realtime and REST APIs
- Works in both Node.js and browser environments
- Single import with named exports for different implementations

## Usage

### Realtime API

#### Server-Side (Node.js)

```typescript
// Import directly from the package
import ably from '@midtownhi/ably';
// Or use the named export
import { ably_node } from '@midtownhi/ably';

// Subscribe to a channel
const channel = ably.subscribe('my-channel');
// Or with named export
const channel = ably_node.subscribe('my-channel');

// Listen for events on that channel
channel.on('my-event', (message) => {
    console.log('Received message:', message.data);
});
```

You can also create custom instances:

```typescript
import { AblyService, NodeConfig } from '@midtownhi/ably';

// Create custom instance
const service = new AblyService({
    key: 'your-api-key',
    // OR use custom environment object
    environment: { ABLY_API_KEY: 'your-api-key' }
} as NodeConfig);

// Use the custom instance
const channel = service.subscribe('my-channel');
```

#### Client-Side (Browser)

```typescript
// Import browser implementation
import { ably_browser, BrowserConfig } from '@midtownhi/ably';

// Create Ably service for realtime using token auth (recommended for production)
const realtimeService = ably_browser.createService({
    authUrl: '/api/createAblyToken',
    authMethod: 'POST',
    authHeaders: { 'Content-Type': 'application/json' },
    clientId: 'user123'
});

// OR using API key (for development only)
const devService = ably_browser.createService({
    key: 'your-api-key'
});

// Subscribe to a channel
const channel = realtimeService.subscribe('my-channel');

// Listen for events
channel.on('my-event', (message) => {
    console.log('Received message:', message.data);
});
```

### REST API (Works in both Node.js and browser)

```typescript
// Import REST client
import { ably_rest, RestConfig } from '@midtownhi/ably';

// For production with token auth (browser)
const browserClient = ably_rest({
    authUrl: '/api/createAblyToken',
    authMethod: 'POST'
});

// For server-side or development with API key
const serverClient = ably_rest({
    key: 'your-api-key'
});

// Use the client to publish events
await browserClient.emit('my-channel', 'my-event', { hello: 'world' });
```

You can also use the class directly:

```typescript
import { AblyRestService, RestConfig } from '@midtownhi/ably';

const client = new AblyRestService({ 
    key: 'your-api-key' 
} as RestConfig);

await client.emit('my-channel', 'my-event', { data: 'value' });
```

## Configuration

### Server-Side

Set your Ably API key using the `ABLY_API_KEY` environment variable or pass it directly in configuration.

### Client-Side

For browser environments, you have two authentication options:

1. **Token Authentication (Recommended for production)**:

    - `authUrl`: URL to your token server
    - `authMethod`: HTTP method as string (e.g., 'GET', 'POST')
    - `authHeaders`: Optional headers
    - `authParams`: Optional query parameters
    - `clientId`: Optional client identifier

2. **API Key (Development only)**:
    - `key`: Your Ably API key (not recommended for production browser environments)

Note: Both the browser and Node implementations accept either `key` or token auth parameters. The Node implementation additionally supports using environment variables.

## Development

```bash
# Install dependencies
yarn install

# Build the package
yarn build

# Watch for changes and rebuild
yarn build:watch
```

## Type Reference

This library provides specific types to help with TypeScript integration:

```typescript
// Import types
import { 
    BrowserConfig,  // For browser configuration
    NodeConfig,     // For Node.js configuration
    RestConfig,     // For REST client configuration
    Channel         // Channel type
} from '@midtownhi/ably';
```

## Project Structure

The library has a simple structure with a focus on type safety and ease of use:

- `ably_browser.ts` - Browser implementation with token auth
- `ably_node.ts` - Node.js implementation with environment variables
- `ably_rest.ts` - REST client implementation for both environments
- `ably_channel.ts` - Channel management for real-time subscriptions
- `index.ts` - Main entry point that exports all implementations

All are compiled to the `dist` directory with full TypeScript definitions.

## License

MIT