@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

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)

// 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:

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)

// 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)

// 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:

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

# 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:

// 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