@stackend/api/util/StackendWebSocket.d.ts

JS bindings to api.stackend.com

/// <reference types="node" />
import { Thunk } from '../api';
import { Community } from '../stackend';
export interface Message {
    communityContext: string;
    componentName: string;
    messageType: string;
    payload?: any;
}
export declare type Listener = (type: StackendWebSocketEvent, event?: Event, message?: Message) => void;
export declare type RealTimeListener = (message: Message, payload: RealTimePayload) => void;
/**
 * Events
 */
export declare enum StackendWebSocketEvent {
    SOCKET_OPENING = "socketOpening.ws",
    SOCKET_OPENED = "socketOpened.ws",
    MESSAGE_RECEIVED = "messageReceived.ws",
    SOCKET_CLOSED = "socketClosed.ws",
    SOCKET_ERROR = "socketError.ws"
}
/**
 * Functions that supports real time subscriptions
 */
export declare enum RealTimeFunctionName {
    COMMENT = "comment",
    BLOG = "blog",
    LIKE = "like",
    FORUM = "forum"
}
/**
 * Real time message types
 */
export declare enum RealTimeMessageType {
    PING = "PING",
    SUBSCRIBE = "SUBSCRIBE",
    UNSUBSCRIBE = "UNSUBSCRIBE",
    UNSUBSCRIBE_ALL = "UNSUBSCRIBE_ALL",
    PONG = "PONG",
    OBJECT_CREATED = "OBJECT_CREATED",
    OBJECT_MODIFIED = "OBJECT_MODIFIED",
    OBJECT_REMOVED = "OBJECT_REMOVED",
    ERROR = "ERROR"
}
export declare abstract class Subscription {
    component: RealTimeFunctionName;
    context: string;
    referenceId: number;
    key: string;
    protected constructor(component: RealTimeFunctionName, context: string, referenceId: number);
    getKey(): string;
}
export declare class CommentsSubscription extends Subscription {
    constructor(context: string, referenceId: number);
}
export declare class BlogSubscription extends Subscription {
    constructor(context: string, blogId: number);
}
export declare class ForumSubscription extends Subscription {
    constructor(context: string, referenceId: number);
}
/**
 * The payload you can expect from a real time subscription
 */
export interface RealTimePayload {
    /** Community context */
    communityContext: string;
    /** Function name */
    component: RealTimeFunctionName;
    /** Object type */
    type: string;
    /** Object id */
    id: number;
    /** Obfuscated reference of object or null if not available */
    obfuscatedReference: string | null;
    /** Id of the user that modified the object*/
    userId: number;
    /** Reference id of (implementation dependant) */
    referenceId: number;
    /** Reference group id, if any (implementation dependant) */
    referenceGroupId?: number;
    /** Number of likes, if supported */
    likes: number | null;
}
/**
 * Component used for real time notifications about xcap object creation/editing/deletion
 * (a comment has been made in this collection of comments)
 */
export declare const REALTIME_COMPONENT = "realtime";
/**
 * Context used for real time info
 */
export declare const REALTIME_CONTEXT = "realtime";
/**
 * Component used for FB style notifications (X has liked my post, Y has replied to my post ...)
 */
export declare const USER_NOTIFICATION_COMPONENT = "usernotification";
/**
 * Context used for FB style notifications
 */
export declare const USER_NOTIFICATION_CONTEXT = "notifications_site";
/**
 * A web socket that is used to send and receive events from the stackend server.
 *
 * // Register your notification handler
 * addInitializer((sws: StackendWebSocket) => {
 *  sws.addListener((type, event, message) => {
 *    console.log("Got notification: ", type, event, data);
 *  }, StackendWebSocketEvent.MESSAGE_RECEIVED, communityContext, USER_NOTIFICATION_COMPONENT);
 * });
 *
 * // Get the global instance
 * const community: Community = ...;
 * const sws: StackendWebSocket = dispatch(getInstance(community.xcapCommunityName));
 *
 * // Request data from the server
 * sws.send({
 *  communityContext: "stackend:notifications_site",
 *  componentName: USER_NOTIFICATION_COMPONENT,
 *  messageType: "GET_NUMBER_OF_UNSEEN",
 *  });
 *
 * // Subscribe to real time object notifications
 * sws.subscribe(new CommentsSubscription("comments", 123), (message: Message, payload: RealTimePayload) => {
 *   console.log("Real time notification", message, payload);
 * });
 */
export default class StackendWebSocket {
    static DEFAULT_URL: string;
    xcapCommunityName: string;
    url: string;
    debug: boolean;
    hasConnected: boolean;
    socket: WebSocket | null;
    isOpen: boolean;
    sendQueue: Array<Message>;
    pongTimeoutId: any;
    /** Low level listeners. maps from broadcast id to array of listeners */
    listeners: {
        [broadcastId: string]: Array<Listener>;
    };
    realTimeListeners: {
        [key: string]: Array<RealTimeListener>;
    };
    reconnectTimer: NodeJS.Timeout | null;
    reconnectDelayMs: number;
    /**
     * Construct a new web socket
     */
    constructor(community: Community, url: string | null | undefined);
    getXcapCommunityName(): string;
    /**
     * Enable / disable debugging
     * @param debug
     */
    setDebug(debug: boolean): void;
    /**
     * Connect
     */
    connect(): void;
    _onOpen: () => void;
    _onMessage: (m: MessageEvent) => void;
    _onClose: (e: CloseEvent) => void;
    _onError: (e: Event) => void;
    _scheduleReconnect: () => void;
    _doReconnect: () => void;
    close(): void;
    validateMessage(message: Message): void;
    /**
     * Send a message
     * @param message
     */
    send(message: Message): void;
    /**
     * Send a ping
     */
    ping(): void;
    _addRealTimeListenerForSubscription(subscription: Subscription, listener: RealTimeListener): boolean;
    _addRealTimeListenerForReference(component: RealTimeFunctionName, obfuscatedReference: string, listener: RealTimeListener): boolean;
    _getReferenceKey(component: RealTimeFunctionName, obfuscatedReference: string): string;
    _getReferenceData(key: string): {
        component: string;
        obfuscatedReference: string;
    } | null;
    _addRealTimeListener(key: string, listener: RealTimeListener): boolean;
    _removeRealTimeListener(key: string, listener: RealTimeListener): boolean;
    _removeRealTimeListenerForSubscription(subscription: Subscription, listener: RealTimeListener): boolean;
    _removeRealTimeListenerForReference(component: RealTimeFunctionName, obfuscatedReference: string, listener: RealTimeListener): boolean;
    _removeAllRealTimeListeners(context?: string): number;
    /**
     * Subscribe to object creation/modification/deletion notifications
     * @param subscription
     * @param listener
     */
    subscribe(subscription: Subscription, listener: RealTimeListener): void;
    /**
     * Subscribe to a set of references
     * @param component
     * @param context
     * @param obfuscatedReferences
     * @param listener
     */
    subscribeMultiple(component: RealTimeFunctionName, context: string, obfuscatedReferences: Array<string>, listener: RealTimeListener): void;
    /**
     * Unsubscribe from object creation/modification/deletion notifications
     * @param subscription
     * @param listener
     */
    unsubscribe(subscription: Subscription, listener: RealTimeListener): void;
    /**
     * Unsubscribe from a set of references
     * @param component
     * @param context
     * @param obfuscatedReferences
     * @param listener
     */
    unsubscribeMultiple(component: RealTimeFunctionName, context: string, obfuscatedReferences: Array<string>, listener: RealTimeListener): void;
    /**
     * Unsubscribe from all real time notifications
     * @param context
     */
    unsubscribeAll(context?: string): void;
    /**
     * Get a broadcast identifier.
     * @param type
     * @param context
     * @param componentName
     * @returns {string}
     */
    _getBroadcastIdentifier(type?: StackendWebSocketEvent | null | undefined, context?: string | null | undefined, componentName?: string | null | undefined): string;
    _sendInternal(): void;
    /**
     * Call all listeners that matches
     * @param type
     * @param message
     * @param event
     */
    _broadcast(type: StackendWebSocketEvent, event?: Event, message?: Message): void;
    _getSubscriptionKey(payload: RealTimePayload): string;
    /**
     * Add a listener that receives broadcasts.
     * For a catch all listener: sws.addListener(listener);
     * To a catch a specific event in all contexts: sws.addListener(listener, StackendWebSocketEvent.SOCKET_CLOSED);
     * To catch events for specific components ws.addListener(listener, StackendWebSocketEvent.MESSAGE_RECEIVED, 'stackend:notifications_site', 'usernotification');
     *
     * @param listener: Listener
     * @param type
     * @param communityContext as returned by getBroadcastIdentifier
     * @param componentName
     */
    addListener(listener: Listener, type?: StackendWebSocketEvent, communityContext?: string, componentName?: string): void;
    /**
     * Short hand for adding a listener for StackendWebSocketEvent.MESSAGE_RECEIVED
     * @param listener
     * @param communityContext
     * @param componentName
     */
    addMessageListener(listener: Listener, communityContext?: string, componentName?: string): void;
}
export declare type Initializer = (stackendWebSocket: StackendWebSocket) => void;
/**
 * Add a global initializer used when getInstance() creates a StackendWebSocket
 * @param initializer
 */
export declare function addInitializer(initializer: Initializer): void;
/**
 * Remove an initializer
 * @param initializer
 */
export declare function removeInitializer(initializer: Initializer): boolean;
/**
 * Get the community instance. All registered initializers are run
 */
export declare function getInstance(community: Community): Thunk<StackendWebSocket>;
/**
 * Shut down and remove the community instance
 */
export declare function removeInstance(xcapCommunityName: string): boolean;
/**
 * Remove all instances
 */
export declare function removeAll(): number;
//# sourceMappingURL=StackendWebSocket.d.ts.map