@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

$3

#### 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);
});
`

$3

`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

$3

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

$3

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