@apinator/server 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Configuration options for the Realtime client.
+ */
+interface RealtimeOptions {
+    /** Application ID */
+    appId: string;
+    /** API key */
+    key: string;
+    /** API secret */
+    secret: string;
+    /** Cluster region identifier (e.g. "eu", "us") */
+    cluster: string;
+}
+/**
+ * Parameters for triggering an event.
+ */
+interface TriggerParams {
+    /** Event name */
+    name: string;
+    /** Single channel name (mutually exclusive with channels) */
+    channel?: string;
+    /** Multiple channel names (mutually exclusive with channel) */
+    channels?: string[];
+    /** Event data as JSON string */
+    data: string;
+    /** Optional socket ID to exclude from receiving the event */
+    socketId?: string;
+}
+/**
+ * Response from channel authentication.
+ */
+interface ChannelAuthResponse {
+    /** Authentication signature in format "key:signature" */
+    auth: string;
+    /** Optional channel data for presence channels */
+    channel_data?: string;
+}
+/**
+ * Information about a channel.
+ */
+interface ChannelInfo {
+    /** Channel name */
+    name: string;
+    /** Number of active subscriptions */
+    subscription_count: number;
+}
+/**
+ * Webhook event data.
+ */
+interface WebhookEvent {
+    /** HTTP headers from the webhook request */
+    headers: Record<string, string | string[] | undefined>;
+    /** Raw request body */
+    body: string;
+}
+
+/**
+ * Server-side client for triggering events and managing channels.
+ *
+ * @example
+ * ```ts
+ * import { Apinator } from '@apinator/server';
+ *
+ * const client = new Apinator({
+ *   appId: 'my-app-id',
+ *   key: 'my-key',
+ *   secret: 'my-secret',
+ *   cluster: 'eu', // or 'us'
+ * });
+ *
+ * // Trigger an event
+ * await client.trigger({
+ *   name: 'order-placed',
+ *   channel: 'orders',
+ *   data: JSON.stringify({ orderId: '123' }),
+ * });
+ *
+ * // Authenticate a channel subscription
+ * const auth = client.authenticateChannel(socketId, 'private-chat');
+ *
+ * // Get channel info
+ * const channel = await client.getChannel('orders');
+ * console.log(channel.subscription_count);
+ * ```
+ */
+declare class Apinator {
+    private readonly appId;
+    private readonly key;
+    private readonly secret;
+    private readonly host;
+    constructor(options: RealtimeOptions);
+    /**
+     * Trigger an event on one or more channels.
+     *
+     * @param params - Event parameters
+     * @throws {ValidationError} If the request is invalid (400)
+     * @throws {AuthenticationError} If authentication fails (401)
+     * @throws {ApiError} For other API errors
+     *
+     * @example Single channel
+     * ```ts
+     * await client.trigger({
+     *   name: 'message',
+     *   channel: 'chat',
+     *   data: JSON.stringify({ text: 'Hello!' }),
+     * });
+     * ```
+     *
+     * @example Multiple channels
+     * ```ts
+     * await client.trigger({
+     *   name: 'notification',
+     *   channels: ['user-1', 'user-2'],
+     *   data: JSON.stringify({ message: 'New update' }),
+     * });
+     * ```
+     *
+     * @example Exclude socket
+     * ```ts
+     * await client.trigger({
+     *   name: 'message',
+     *   channel: 'chat',
+     *   data: JSON.stringify({ text: 'Hello!' }),
+     *   socketId: '12345.67890', // Don't send to this connection
+     * });
+     * ```
+     */
+    trigger(params: TriggerParams): Promise<void>;
+    /**
+     * Authenticate a channel subscription request.
+     *
+     * This generates the authentication signature required for private and presence channels.
+     * The returned auth object should be sent back to the client for channel subscription.
+     *
+     * @param socketId - WebSocket connection socket ID from the client
+     * @param channelName - Channel name to authenticate
+     * @param channelData - Optional channel data for presence channels (JSON string with user info)
+     * @returns Channel authentication response with auth signature
+     *
+     * @example Private channel
+     * ```ts
+     * const auth = client.authenticateChannel('12345.67890', 'private-chat');
+     * // Send auth back to client
+     * res.json(auth);
+     * ```
+     *
+     * @example Presence channel
+     * ```ts
+     * const channelData = JSON.stringify({
+     *   user_id: 'user1',
+     *   user_info: { name: 'Alice' }
+     * });
+     * const auth = client.authenticateChannel('12345.67890', 'presence-room', channelData);
+     * res.json(auth);
+     * ```
+     */
+    authenticateChannel(socketId: string, channelName: string, channelData?: string): ChannelAuthResponse;
+    /**
+     * Get a list of channels, optionally filtered by prefix.
+     *
+     * @param prefix - Optional prefix to filter channels (e.g., "private-", "presence-")
+     * @returns Array of channel information
+     * @throws {AuthenticationError} If authentication fails (401)
+     * @throws {ApiError} For other API errors
+     *
+     * @example Get all channels
+     * ```ts
+     * const channels = await client.getChannels();
+     * channels.forEach(ch => console.log(ch.name, ch.subscription_count));
+     * ```
+     *
+     * @example Get presence channels only
+     * ```ts
+     * const presenceChannels = await client.getChannels('presence-');
+     * ```
+     */
+    getChannels(prefix?: string): Promise<ChannelInfo[]>;
+    /**
+     * Get information about a specific channel.
+     *
+     * @param channelName - Channel name
+     * @returns Channel information
+     * @throws {AuthenticationError} If authentication fails (401)
+     * @throws {ApiError} For other API errors (including 404 if channel not found)
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const channel = await client.getChannel('chat');
+     *   console.log(`Channel has ${channel.subscription_count} subscribers`);
+     * } catch (err) {
+     *   if (err instanceof ApiError && err.status === 404) {
+     *     console.log('Channel not found');
+     *   }
+     * }
+     * ```
+     */
+    getChannel(channelName: string): Promise<ChannelInfo>;
+    /**
+     * Verify the authenticity of a webhook request.
+     *
+     * This function verifies that the webhook was sent by the Realtime service
+     * by validating the HMAC signature in the request headers.
+     *
+     * @param headers - HTTP headers from the webhook request
+     * @param body - Raw request body as string
+     * @param maxAge - Optional maximum age in seconds for the webhook timestamp
+     * @returns true if the webhook is valid, false otherwise
+     *
+     * @example Express.js webhook handler
+     * ```ts
+     * app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const body = req.body.toString('utf8');
+     *
+     *   if (!client.verifyWebhook(req.headers, body, 300)) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   const event = JSON.parse(body);
+     *   // Process webhook...
+     * });
+     * ```
+     */
+    verifyWebhook(headers: Record<string, string | string[] | undefined>, body: string, maxAge?: number): boolean;
+    /**
+     * Make an authenticated API request.
+     */
+    private request;
+}
+
+/**
+ * Authenticate a channel subscription request.
+ *
+ * This generates the authentication signature required for private and presence channels.
+ * The returned auth string should be sent back to the client for channel subscription.
+ *
+ * @param secret - API secret
+ * @param key - API key
+ * @param socketId - WebSocket connection socket ID from the client
+ * @param channelName - Channel name to authenticate
+ * @param channelData - Optional channel data for presence channels (JSON string with user info)
+ * @returns Channel authentication response with auth signature
+ *
+ * @example
+ * ```ts
+ * const authResponse = authenticateChannel(
+ *   "my-secret",
+ *   "my-key",
+ *   "12345.67890",
+ *   "private-chat"
+ * );
+ * // Returns: { auth: "my-key:abc123..." }
+ * ```
+ *
+ * @example Presence channel with user data
+ * ```ts
+ * const authResponse = authenticateChannel(
+ *   "my-secret",
+ *   "my-key",
+ *   "12345.67890",
+ *   "presence-room",
+ *   JSON.stringify({ user_id: "user1", user_info: { name: "Alice" } })
+ * );
+ * // Returns: { auth: "my-key:abc123...", channel_data: "..." }
+ * ```
+ */
+declare function authenticateChannel(secret: string, key: string, socketId: string, channelName: string, channelData?: string): ChannelAuthResponse;
+
+/**
+ * Verify the authenticity of a webhook request.
+ *
+ * This function verifies that the webhook was sent by the Realtime service
+ * by validating the HMAC signature in the request headers.
+ *
+ * @param secret - Webhook secret
+ * @param headers - HTTP headers from the webhook request (case-insensitive keys)
+ * @param body - Raw request body as string
+ * @param maxAge - Optional maximum age in seconds for the webhook timestamp
+ * @returns true if the webhook is valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * // Express.js webhook handler
+ * app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const headers = req.headers;
+ *   const body = req.body.toString('utf8');
+ *
+ *   if (!verifyWebhook('my-webhook-secret', headers, body, 300)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   // Process webhook
+ *   const event = JSON.parse(body);
+ *   // ...
+ * });
+ * ```
+ */
+declare function verifyWebhook(secret: string, headers: Record<string, string | string[] | undefined>, body: string, maxAge?: number): boolean;
+
+/**
+ * Compute MD5 hash of data and return as hex string.
+ */
+declare function md5Hex(data: string): string;
+/**
+ * Sign an API request using HMAC-SHA256.
+ *
+ * @param secret - API secret
+ * @param method - HTTP method (e.g., "POST", "GET")
+ * @param path - Request path (e.g., "/apps/123/events")
+ * @param body - Request body as string
+ * @param timestamp - Unix timestamp in seconds
+ * @returns HMAC signature as hex string
+ */
+declare function signRequest(secret: string, method: string, path: string, body: string, timestamp: number): string;
+/**
+ * Sign a channel authentication request using HMAC-SHA256.
+ *
+ * @param secret - API secret
+ * @param socketId - WebSocket connection socket ID
+ * @param channelName - Channel name to authenticate
+ * @param channelData - Optional channel data for presence channels (JSON string)
+ * @returns HMAC signature as hex string
+ */
+declare function signChannel(secret: string, socketId: string, channelName: string, channelData?: string): string;
+/**
+ * Sign a webhook payload using HMAC-SHA256.
+ *
+ * @param secret - Webhook secret
+ * @param timestamp - Timestamp from X-Realtime-Timestamp header
+ * @param payload - Raw webhook body
+ * @returns HMAC signature as hex string
+ */
+declare function signWebhookPayload(secret: string, timestamp: string, payload: string): string;
+
+/**
+ * Base error class for all Realtime SDK errors.
+ */
+declare class RealtimeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when authentication fails (401 responses).
+ */
+declare class AuthenticationError extends RealtimeError {
+    constructor(message: string);
+}
+/**
+ * Error thrown when request validation fails (400 responses).
+ */
+declare class ValidationError extends RealtimeError {
+    constructor(message: string);
+}
+/**
+ * Generic API error with status code and response body.
+ */
+declare class ApiError extends RealtimeError {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+
+export { ApiError, Apinator, AuthenticationError, type ChannelAuthResponse, type ChannelInfo, RealtimeError, type RealtimeOptions, type TriggerParams, ValidationError, type WebhookEvent, authenticateChannel, md5Hex, signChannel, signRequest, signWebhookPayload, verifyWebhook };