@monterosa/sdk-connect-kit 2.0.0-rc.3 → 2.0.0-rc.5

package/dist/sdk-connect-kit.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Establishes real-time connections to events and projects.
+ *
+ * @packageDocumentation
+ */
+
+import { Emitter } from '@monterosa/sdk-util';
+import Enmasse from '@monterosa/sdk-enmasse-kit';
+import { MonterosaKit } from '@monterosa/sdk-core';
+import { Unsubscribe } from '@monterosa/sdk-util';
+
+/**
+ * Represents a Connect Kit instance. Obtain one via {@link getConnect}.
+ */
+export declare interface Connect extends MonterosaKit, Emitter {
+    /**
+     * Connection state
+     */
+    state: ConnState;
+    /**
+     * Session ID
+     */
+    sessionId: string | null;
+    /**
+     * @internal
+     */
+    initState: InitState;
+    /**
+     * @internal
+     */
+    init(host: string): Promise<void>;
+    /**
+     * @internal
+     */
+    connect(): Promise<void>;
+    /**
+     * @internal
+     */
+    disconnect(): void;
+    /**
+     * @internal
+     */
+    subscribe(channel: string): Promise<void>;
+    /**
+     * @internal
+     */
+    unsubscribe(channel: string): void;
+    /**
+     * @internal
+     */
+    send(channel: string, klass: string, body: (string | number)[]): void;
+    /**
+     * @internal
+     */
+    login(userId: string, timestamp: number, signature: string): Promise<void>;
+    logout(): void;
+}
+
+/**
+ * Starts a connection process.
+ *
+ * @remarks
+ * If connect is successful a promise resolved by
+ * and {@link onConnected} is triggered, otherwise a next attempt will be
+ * automatically invoked and {@link onConnecting} is triggered.
+ *
+ * SDK connects automatically when its created. Connection procedure can be
+ * aborted by calling {@link disconnect} function and the promise is rejected.
+ *
+ * @example
+ * ```javascript
+ * try {
+ *   const conn = await getConnect();
+ *
+ *   await connect(conn);
+ *
+ *   console.log('connected!');
+ * } catch (err) {
+ *   console.log(err)
+ * }
+ * ```
+ *
+ * State of the connection can be handled separately
+ *
+ * @example
+ * ```javascript
+ * onConnected(() => console.log('connected'));
+ *
+ * onConnecting((attempt, delay) => console.log('connecting'));
+ *
+ * onDisconnected(() => console.log('disconnected'));
+ * ```
+ *
+ * @param conn - The {@link Connect} instance
+ * @param host - Interaction Cloud Studio host.
+ *  Can be found in Project Settings in API tab
+ */
+export declare function connect(conn: Connect): Promise<void>;
+
+/**
+ * @internal
+ */
+export declare class ConnectImpl extends Emitter implements Connect {
+    private static instance;
+    initState: InitState;
+    private initPromise;
+    private connectPromise;
+    private constructor();
+    get state(): ConnState;
+    get sessionId(): string | null;
+    static getInstance(): ConnectImpl;
+    static toConnState(state: Enmasse.States): ConnState;
+    init(host: string): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): void;
+    subscribe(channel: string): Promise<void>;
+    unsubscribe(channel: string): void;
+    send(channel: string, klass: string, body: (string | number)[]): void;
+    login(userId: string, timestamp: number, signature: string): Promise<void>;
+    logout(): Promise<void>;
+    delete(): void;
+}
+
+/**
+ * A list of possible connection states.
+ *
+ * @remarks
+ * Can be used with {@link Connect | Connect.state} to determine the current state.
+ *
+ * By default {@link Connect} is in the disconnected state.
+ * When {@link connect} invoked `Connect` state switches to
+ * `ConnState.Connecting` and connection is maintained permanently until
+ * {@link disconnect} method is invoked. If connection was unsucessful,
+ * a new attempt will start after a short delay and `ConnState.connecting`
+ * is triggered. Delays between attempts increased based on this sequence:
+ * 0, 3, 5, 10, 20, 30, 45, 60 where 60 seconds is the max.
+ *
+ * If `Connect` was previously connected and for any reason connection is lost,
+ * the state changed to `ConnState.Connecting` again and the connection process
+ * starts again automatically.
+ *
+ * @example
+ * ```javascript
+ * if (conn.state === ConnState.Connecting) {
+ *   // display "connecting" message
+ * }
+ * ```
+ */
+export declare enum ConnState {
+    /**
+     * Disconnected state
+     */
+    Disconnected = "disconnected",
+    /**
+     * Connecting state
+     */
+    Connecting = "connecting",
+    /**
+     * Connected state
+     */
+    Connected = "connected"
+}
+
+/**
+ * Disconnect from the server and triggers {@link onDisconnected}
+ *
+ * @param conn - The {@link Connect} instance
+ */
+export declare function disconnect(conn: Connect): void;
+
+/**
+ * Returns the {@link Connect} instance associated with the provided
+ * host. If host is not provided, it returns Connect instance for
+ * the host associated with the default sdk.
+ *
+ * @param host - The host URL. If not provided, uses the host
+ *   from the default SDK instance.
+ */
+export declare function getConnect(host?: string): Promise<Connect>;
+
+/**
+ * @internal
+ */
+export declare const getConnectMemoized: (...args: any[]) => Promise<Connect>;
+
+/**
+ * @internal
+ */
+export declare enum InitState {
+    NotInitialised = "not_initialised",
+    Initialised = "initialised",
+    Initialising = "initialising"
+}
+
+/**
+ * @internal
+ */
+export declare const KIT_NAME = "connect";
+
+/**
+ * Class of the {@link Message}
+ */
+export declare enum Klass {
+    /**
+     * Authentication request. Sent by server on client connection.
+     */
+    Authenticate = "auth",
+    /**
+     * Authentication response. Sent by client as response
+     * to authentication request.
+     */
+    AuthenticateResponse = "authr",
+    /**
+     * Authentication acknowledgement. Sent by the server as confirmation
+     * of successful authentication.
+     */
+    AuthenticateSuccess = "authok",
+    /**
+     * Ping message is sent by server periodically as a keep-alive.
+     * Ping message is only sent if no messages are sent for specific time
+     * period, meaning if there are other messages sent frequently enough
+     * then ping messages are not sent at all.
+     */
+    Ping = "ping",
+    /**
+     * Subscribe to a channel. Sent by the client to subscribe to a channel
+     */
+    Subscribe = "sub",
+    /**
+     * Unsubscribe from a channel. Sent by the client to unsubscribe from a channel
+     */
+    Unsububscribe = "unsub",
+    /**
+     * End of cache. Sent by the server to notify that all messages are sent from
+     * a channel cache
+     */
+    EndOfCache = "eoc",
+    /**
+     * User login. Sent by client to supply verified user identity to the server.
+     */
+    Login = "login",
+    /**
+     * User login success
+     */
+    LoginSuccess = "login_ok",
+    /**
+     * User login failure
+     */
+    LoginFail = "login_fail",
+    /**
+     * Averages counters. Client can submit a counter which is processed together
+     * with other counters to determine the average of all counters within specific
+     * demographics segment.
+     */
+    Counter = "counter",
+    /**
+     * Client votes. Sents by a user to vote for a poll option
+     */
+    Vote = "v"
+}
+
+/**
+ * Authenticates the connection with user credentials.
+ *
+ * @param conn - The Connect instance
+ * @param userId - The user identifier
+ * @param timestamp - The signature timestamp in seconds
+ * @param signature - The session signature string
+ *
+ * @public
+ */
+export declare function login(conn: Connect, userId: string, timestamp: number, signature: string): Promise<void>;
+
+export declare function logout(conn: Connect): Promise<void>;
+
+/**
+ * Represents a message received from or sent to the server.
+ * Subscribe via {@link onMessage} to receive messages.
+ */
+export declare interface Message {
+    /**
+     * The channel on which this message was received. You must
+     * {@link subscribe} to a channel to start receiving messages.
+     */
+    channel: string;
+    /**
+     * The class indicates the desired action to be performed or the result of
+     * the action. E.g. in order to authenticate a developer should {@link send}
+     * {@link Klass | Klass.AuthenticateResponse} klass message as a response on
+     * a received {@link Klass | Klass.Authenticate} message
+     */
+    klass: Klass | string;
+    /**
+     * The timestamp (in seconds) when this message was sent
+     */
+    sent_at: number;
+    /**
+     * The message payload. Each piece of data is a `string`
+     */
+    body: string[];
+}
+
+/**
+ * Adds an observer for when connection state changed to connected.
+ *
+ * @param conn - The {@link Connect} instance
+ * @param callback - The callback triggered when {@link ConnState | state}
+ *   changed to connected
+ */
+export declare function onConnected(conn: Connect, callback: (timestamp: number) => void): Unsubscribe;
+
+/**
+ * Adds an observer for when connection state changed to connecting.
+ *
+ * @param conn - The {@link Connect} instance
+ * @param callback - callback triggered on connecting state. Two parameters
+ *   are provided: `attempt`, the sequential number of connect attempt, and
+ *   `delay` - delay in seconds before the next attempt
+ */
+export declare function onConnecting(conn: Connect, callback: (attempt: number, delay: number) => void): Unsubscribe;
+
+/**
+ * Adds an observer for when connection state changed to disconnected.
+ *
+ * @param conn - The {@link Connect} instance
+ * @param callback - callback triggered on disconnected state
+ */
+export declare function onDisconnected(conn: Connect, callback: () => void): Unsubscribe;
+
+/**
+ * Adds an observer for when a new message received
+ *
+ * @example
+ * ```javascript
+ * const unsubscribe = onMessage(conn, (message) => {
+ *   console.log(message.body);
+ * });
+ * ```
+ *
+ * @param conn - The {@link Connect} instance
+ * @param callback - The callback function triggered on message receive
+ */
+export declare function onMessage(conn: Connect, callback: (message: Message) => void): Unsubscribe;
+
+/**
+ * Send message to the server.
+ *
+ * @remarks
+ * The sdk out of the box provides more high level functions that uses
+ * this function to send data to the server. Though a developer still can
+ * use it if he knows a message protocol (klass and body) and a channel
+ * that expect the message.
+ *
+ * @param conn - The Connect instance
+ * @param channel  - Channel name. Only {@link subscribe | subscribers}
+ *   to that channel can send messages.
+ * @param klass - Message class name.
+ * @param body - Message payload
+ */
+export declare function send(conn: Connect, channel: string, klass: Klass | string, body: (string | number)[]): void;
+
+/**
+ * Subscribe to the server channel.
+ *
+ * @remarks
+ * Any message published to a channel is {@link onMessage | received}
+ * only by subscribers to that channel. The sdk out of the box handles
+ * all required subscriptions internally and {@link onMessage | handles messages}
+ * so there is no need in to subscribe by developers.
+ *
+ * To stop receiving messages on a channel {@link unsubscribe} should be called.
+ *
+ * @param conn - The {@link Connect} instance
+ * @param channel - Channel name
+ */
+export declare function subscribe(conn: Connect, channel: string): Promise<void>;
+
+/**
+ * @internal
+ */
+export declare const subscribeMemoized: (...args: any[]) => Promise<void>;
+
+/**
+ * Unsubscribe from the server channel.
+ *
+ * @remarks
+ * Removes subscription to the channel so that recipient no longer receive
+ * messages from that channel.
+ *
+ * @param conn - The {@link Connect} instance
+ * @param channel - Channel name
+ */
+export declare function unsubscribe(conn: Connect, channel: string): void;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.23.0"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monterosa/sdk-connect-kit",
-  "version": "2.0.0-rc.3",
+  "version": "2.0.0-rc.5",
   "description": "Monterosa JS SDK / Connect",
   "author": "Monterosa Productions Limited <hello@monterosa.co.uk> (https://www.monterosa.co/)",
   "main": "./dist/index.cjs",
@@ -32,9 +32,9 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@monterosa/sdk-core": "2.0.0-rc.3",
-    "@monterosa/sdk-enmasse-kit": "2.0.0-rc.3",
-    "@monterosa/sdk-util": "2.0.0-rc.3"
+    "@monterosa/sdk-core": "2.0.0-rc.5",
+    "@monterosa/sdk-enmasse-kit": "2.0.0-rc.5",
+    "@monterosa/sdk-util": "2.0.0-rc.5"
   },
   "devDependencies": {
     "@rollup/plugin-json": "^4.1.0",
@@ -54,5 +54,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d692ad26af0b5ea7cd7b664168bffa069f9ab911"
+  "gitHead": "4f697a9733d36fb689a35b8e1dd6d589a9ae284c"
 }