@exoquic/sub/src/dist/index.d.ts

Exoquic subscriber API

/**
 * @interface SubscriptionManagerOptions The options for the SubscriptionManager.
 */
export interface SubscriptionManagerOptions {
	/**
	 * @type {'dev' | 'prod'} The environment to use. "dev" for development or "prod" for production. Defaults to "dev".
	 */
	env?: 'dev' | 'prod';

	/**
	 * @type {string} The URL to use for subscribing to events. Defaults to `https://${env}.exoquic.com/subscribe`.
	 */
	subscribeUrl?: string;

	/**
	 * @type {string} The name of the subscription manager. Defaults to "default".
	 */
	name?: string;

	/**
	 * @type {boolean} Whether to enable caching. Defaults to true.
	 */
	cacheEnabled?: boolean;
}

/**
 * @interface SubscriptionSettings The settings for a subscriber.
 */
export interface SubscriptionSettings {
	/**
	 * @type {string} The URL to exoquic's subscribe endpoint.
	 */
	serverUrl?: string;

	/**
	 * @type {boolean} Whether to reconnect if it wasn't a clean close(e.g. if the connection was closed by the server due to an error).
	 */
	shouldReconnect?: boolean;

	/**
	 * @type {number} The maximum reconnect timeout.
	 */
	maxReconnectTimeout?: number;

	/**
	 * @type {number} The current reconnect timeout (changes due to exponential backoff).
	 */
	reconnectTimeout?: number;
}

/**
 * @constant {SubscriptionSettings} DEFAULT_AUTHORIZED_SUBSCRIPTION_SETTINGS The default settings for a subscriber.
 */
export const DEFAULT_AUTHORIZED_SUBSCRIPTION_SETTINGS: SubscriptionSettings = {
	shouldReconnect: true,
	reconnectTimeout: 1000,
	maxReconnectTimeout: 10000,
	serverUrl: 'https://dev.exoquic.com/subscribe',
};

/**
 * @class SubscriptionManager Manages subscriptions, subscription tokens and connections to exoquic.
 */
export class SubscriptionManager {
	/**
	 * @constructor Constructs a new SubscriptionManager.
	 * @param {function} fetcher - The function to use for fetching the authorized subscription token.
	 * @param {SubscriptionManagerOptions} options - The options for the SubscriptionManager.
	 */
	constructor(
		fetcher?: (subscriptionData?: any) => Promise<string>,
		options?: SubscriptionManagerOptions
	);

	/**
	 * @type {function} The function to use for fetching the authorized subscription token.
	 */
	fetcher: (subscriptionData?: any) => Promise<string>;

	/**
	 * @type {string} The URL to exoquic's subscribe endpoint.
	 */
	subscribeUrl: string;

	/**
	 * @type {boolean} Whether to enable caching(using IndexedDB on the browser).
	 */
	cacheEnabled: boolean;

	/**
	 * @type {string} A unique identifier for the subscription manager.
	 */
	name: string;

	/**
	 * @type {IDBDatabase | null} IndexedDB for the SubscriptionManager, storing subscription tokens and subscriber metadata.
	 */
	db: IDBDatabase | null;

	/**
	 * @type {string} The tab ID, used to identify the tab that the user is currently on to avoid storing duplicates in the IndexedDB store when the user has multiple tabs open.
	 */
	tabId: string;

	/**
	 * @method authorizeSubscriber Authorizes a subscriber by calling the provided fetcher function.
	 * @param {any} subscriptionData - The subscription data to use for authorization.
	 * @param {boolean} cacheEnabled - Whether to enable caching. Defaults to the SubscriptionManager's cacheEnabled property.
	 * @returns {Promise<AuthorizedSubscriber>} An Authorized subscriber if the provided fetcher function returns a valid subscription token. Throws error otherwise.
	 */
	authorizeSubscriber(
		subscriptionData?: any,
		cacheEnabled?: boolean
	): Promise<AuthorizedSubscriber>;
}

/**
 * @class AuthorizedSubscriber Represents a subscriber that has a subscription token.
 */
export class AuthorizedSubscriber {
	/**
	 * @constructor Constructs a new AuthorizedSubscriber.
	 * @param {string} authorizationToken - The subscription token.
	 * @param {SubscriptionSettings} settings - The settings for the subscription.
	 * @param {IDBDatabase | null} db - IndexedDB for the underlying SubscriptionManager.
	 * @param {function} fetcherFunc - The function to use for fetching the authorized subscription token.
	 * @param {boolean} cacheEnabled - Whether to enable caching for this specific subscriber.
	 * @param {any} decodedToken - The decoded subscription token.
	 * @param {string} subscriptionManagerName - The name of the subscription manager.
	 * @param {object | null} subscriberMetadata - The metadata for the subscriber.
	 * @param {string} tabId - The tab ID.
	 */
	constructor(
		authorizationToken: string,
		settings: SubscriptionSettings,
		db: IDBDatabase | null,
		fetcherFunc: (subscriptionData?: any) => Promise<string>,
		cacheEnabled: boolean,
		decodedToken: any,
		subscriptionManagerName: string,
		subscriberMetadata: { name: string } | null,
		tabId: string
	);

	/**
	 * @type {string} The subscription token.
	 */
	authorizationToken: string;

	/**
	 * @type {string} The URL to exoquic's subscribe endpoint.
	 */
	serverUrl: string;
	
	/**
	 * @type {boolean} Whether to reconnect if it wasn't a clean close(e.g. if the connection was closed by the server due to an error).
	 */
	shouldReconnect: boolean;

	/**
	 * @type {number} The current reconnect timeout (changes due to exponential backoff).
	 */
	reconnectTimeout: number;

	/**
	 * @type {number} The maximum reconnect timeout.
	 */
	maxReconnectTimeout: number;

	/**
	 * @type {boolean} Whether the subscriber is subscribed to events.
	 */
	isSubscribed: boolean;

	/**
	 * @type {boolean} Whether the subscriber is connected to the WebSocket.
	 */
	isConnected: boolean;

	/**
	 * @type {IDBDatabase | null} IndexedDB for the underlying SubscriptionManager.
	 */
	db: IDBDatabase | null;

	/**
	 * @type {function} The function to use for fetching the authorized subscription token.
	 */
	fetcherFunc: (subscriptionData?: any) => Promise<string>;

	/**
	 * @type {boolean} Whether to enable caching for this specific subscriber.
	 */
	cacheEnabled: boolean;

	/**
	 * @type {any} The decoded subscription token.
	 */
	decodedToken: any;

	/**
	 * @type {string} The name of the subscription manager.
	 */
	name: string;

	/**
	 * @type {object | null} The metadata for the subscriber.
	 */
	subscriberMetadata: { name: string } | null;

	/**
	 * @type {string} The tab ID.
	 */
	tabId: string;

	/**
	 * @type {WebSocket} The WebSocket connection.
	 */
	ws: WebSocket;

	/**
	 * @method subscribe Subscribes to events with the subscription token.
	 * @param {function} onEventBatchReceivedCallback - The callback to use for handling event batches.
	 * @returns {void} 
	 */
	subscribe(onEventBatchReceivedCallback: (eventBatch: any[]) => void): void;
	
	/**
	 * @method unsubscribe Unsubscribes from events.
	 * @returns {void}
	 */
	unsubscribe(): void;
}