@openfin/cloud-interop-core-api 0.0.1-alpha.e6793f0 → 0.0.1-alpha.e6a1a71

package/index.mjs

@@ -0,0 +1,754 @@
+import { Buffer } from 'buffer';
+import mqtt from 'mqtt';
+
+var l=t=>{let e=t.replaceAll("-","+").replaceAll("_","/");return e.padEnd(e.length+(4-e.length%4)%4,"=")};
+
+class CloudInteropAPIError extends Error {
+    code;
+    constructor(message = 'An unexpected error has occurred', code = 'UNEXPECTED_ERROR', cause) {
+        super(message, { cause: cause });
+        this.name = this.constructor.name;
+        this.code = code;
+    }
+}
+class AuthorizationError extends CloudInteropAPIError {
+    constructor(message = 'Not authorized', code = 'ERR_UNAUTHORIZED') {
+        super(message, code, undefined);
+    }
+}
+
+class EventController {
+    #eventListeners = new Map();
+    addEventListener(type, callback) {
+        const listeners = this.#eventListeners.get(type) || [];
+        listeners.push(callback);
+        this.#eventListeners.set(type, listeners);
+    }
+    removeEventListener(type, callback) {
+        const listeners = this.#eventListeners.get(type) || [];
+        const index = listeners.indexOf(callback);
+        if (index !== -1) {
+            listeners.splice(index, 1);
+        }
+        this.#eventListeners.set(type, listeners);
+    }
+    once(type, callback) {
+        const listener = (...args) => {
+            this.removeEventListener(type, listener);
+            // @ts-expect-error - TS doesn't like the spread operator here
+            callback(...args);
+        };
+        this.addEventListener(type, listener);
+    }
+    emitEvent(type, ...args) {
+        const listeners = this.#eventListeners.get(type) || [];
+        listeners.forEach((listener) => listener(...args));
+    }
+}
+
+const isErrorIntentResult = (result) => 'error' in result;
+
+const APP_ID_DELIM = '::';
+const getRequestHeaders = (connectionParameters) => {
+    const headers = {};
+    headers['Content-Type'] = 'application/json';
+    if (connectionParameters.authenticationType === 'jwt' && connectionParameters.jwtAuthenticationParameters) {
+        const tokenResult = connectionParameters.jwtAuthenticationParameters.jwtRequestCallback();
+        if (!tokenResult) {
+            throw new Error('jwtRequestCallback must return a token');
+        }
+        headers['x-of-auth-id'] = connectionParameters.jwtAuthenticationParameters.authenticationId;
+        headers['Authorization'] =
+            typeof tokenResult === 'string' ? `Bearer ${tokenResult}` : `Bearer ${Buffer.from(JSON.stringify(tokenResult)).toString('base64')}`;
+    }
+    if (connectionParameters.authenticationType === 'basic' && connectionParameters.basicAuthenticationParameters) {
+        const { username, password } = connectionParameters.basicAuthenticationParameters;
+        headers['Authorization'] = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+    }
+    return headers;
+};
+/**
+ * Encodes all app intents in the format: `appId::sourceId::sessionId`,
+ * where sourceId and sessionId are URI encoded
+ * @param appIntents
+ * @param source
+ * @returns
+ */
+const encodeAppIntents = (appIntents, source) => appIntents.map((intent) => ({
+    ...intent,
+    apps: intent.apps.map((app) => ({ ...app, appId: encodeAppId(app.appId, source) })),
+}));
+/**
+ * Decodes all app intents by URI decoding the parts previously encoded by `encodeAppIntents`
+ * @param appIntents
+ * @returns
+ */
+const decodeAppIntents = (appIntents) => appIntents.map((intent) => ({
+    ...intent,
+    apps: intent.apps.map((app) => ({ ...app, appId: decodeAppId(app.appId) })),
+}));
+const encodeAppId = (appIdString, { sessionId, sourceId }) => {
+    const id = encodeURIComponent(appIdString);
+    const sId = encodeURIComponent(sourceId);
+    return `${id}${APP_ID_DELIM}${sId}${APP_ID_DELIM}${sessionId}`;
+};
+const decodeAppId = (appId) => {
+    const [encodedAppId, encodedSourceId, sessionId] = appId.split(APP_ID_DELIM);
+    const id = decodeURIComponent(encodedAppId);
+    const sourceId = decodeURIComponent(encodedSourceId);
+    return `${id}${APP_ID_DELIM}${sourceId}${APP_ID_DELIM}${sessionId}`;
+};
+/**
+ * Decodes the AppIdentifier to extract the appId, sourceId, and sessionId.
+ * @returns an object with:
+ * - appId: The appId, or the original appId if unable to parse.
+ * - sourceId: The sourceId, or an '' if unable to parse.
+ * - sessionId: The sessionId, or an '' if unable to parse.
+ */
+const parseCloudAppId = (appId = '') => {
+    const originalAppString = typeof appId === 'string' ? appId : (appId.appId ?? '');
+    const parts = originalAppString.split(APP_ID_DELIM);
+    return {
+        appId: parts[0]?.trim() ?? originalAppString,
+        sourceId: parts[1]?.trim() ?? '',
+        sessionId: parts[2]?.trim() ?? '',
+    };
+};
+const getSourceFromSession = (sessionDetails) => ({
+    sessionId: sessionDetails.sessionId,
+    sourceId: sessionDetails.sourceId,
+    userId: sessionDetails.sub,
+    orgId: sessionDetails.orgId,
+    platformId: sessionDetails.platformId,
+});
+
+const MIN_TIMEOUT = 500;
+const DEFAULT_TIMEOUT = 3000;
+const newDiscovery = () => ({
+    id: undefined,
+    pendingIntentDetailsEvents: [],
+    sessionCount: 0,
+    responseCount: 0,
+    state: 'not-started',
+});
+class IntentController {
+    #url;
+    #mqttClient;
+    #sessionDetails;
+    #connectionParams;
+    #events;
+    #logger;
+    #discovery = newDiscovery();
+    #discoveryTimeout;
+    constructor(url, mqttClient, sessionDetails, connectionParameters, events, logger) {
+        this.#url = url;
+        this.#mqttClient = mqttClient;
+        this.#sessionDetails = sessionDetails;
+        this.#connectionParams = connectionParameters;
+        this.#events = events;
+        this.#logger = logger;
+    }
+    async startIntentDiscovery(options) {
+        if (this.#discovery.state === 'in-progress') {
+            throw new Error('Intent discovery already in progress');
+        }
+        const { timeout = DEFAULT_TIMEOUT, findOptions } = options;
+        // clamp min value to 500ms
+        const clampedTimeout = Math.max(timeout, MIN_TIMEOUT);
+        try {
+            const startResponse = await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}`, {
+                method: 'POST',
+                headers: getRequestHeaders(this.#connectionParams),
+                body: JSON.stringify({ findOptions }),
+            });
+            if (!startResponse.ok) {
+                throw new Error(`Error creating intent discovery record: ${startResponse.statusText}`);
+            }
+            // TODO: type this response?
+            const json = await startResponse.json();
+            this.#discovery.id = json.discoveryId;
+            this.#discovery.sessionCount = json.sessionCount;
+            this.#discovery.state = 'in-progress';
+            if (this.#discovery.sessionCount === 1) {
+                // since we have no other connected sessions, we can end discovery immediately
+                await this.#endIntentDiscovery(false);
+                return;
+            }
+            // Listen out for discovery results directly sent to us
+            await this.#mqttClient.subscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`);
+            this.#discoveryTimeout = setTimeout(() => this.#endIntentDiscovery(), clampedTimeout);
+        }
+        catch (error) {
+            // Clean up any ongoing discoveries
+            this.#endIntentDiscovery();
+            throw new CloudInteropAPIError('Error starting intent discovery', 'ERR_STARTING_INTENT_DISCOVERY', error);
+        }
+    }
+    async #endIntentDiscovery(mqttUnsubscribe = true) {
+        if (this.#discovery.state !== 'in-progress') {
+            return;
+        }
+        if (this.#discoveryTimeout) {
+            clearTimeout(this.#discoveryTimeout);
+            this.#discoveryTimeout = undefined;
+        }
+        this.#discovery.state = 'ended';
+        // emit our aggregated events
+        this.#events.emitEvent('aggregate-intent-details', { responses: this.#discovery.pendingIntentDetailsEvents });
+        if (mqttUnsubscribe) {
+            // gracefully end discovery
+            await this.#mqttClient.unsubscribeAsync(`${this.#sessionDetails.sessionRootTopic}/commands/${this.#discovery.id}`).catch(() => {
+                this.#logger('warn', `Error ending intent discovery: could not unsubscribe from discovery id ${this.#discovery.id}`);
+            });
+        }
+        await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}/${this.#discovery.id}`, {
+            method: 'DELETE',
+            headers: getRequestHeaders(this.#connectionParams),
+        })
+            .then((deleteResponse) => {
+            if (!deleteResponse.ok) {
+                throw new Error(`Error ending intent discovery: ${deleteResponse.statusText}`);
+            }
+        })
+            .catch((error) => {
+            this.#logger('warn', `Error ending intent discovery: ${error}`);
+        });
+        // clean up
+        this.#discovery = newDiscovery();
+    }
+    async raiseIntent({ raiseOptions, appId }) {
+        const targetSessionId = parseCloudAppId(appId).sessionId;
+        if (!targetSessionId) {
+            // TODO: should we add more info here about the format?
+            throw new CloudInteropAPIError(`Invalid AppId specified, must be encoded as a cloud-session app id`, 'ERR_INVALID_TARGET_SESSION_ID');
+        }
+        const postResponse = await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}/sessions/${targetSessionId}`, {
+            method: 'POST',
+            headers: getRequestHeaders(this.#connectionParams),
+            body: JSON.stringify({ raiseOptions }),
+        });
+        if (!postResponse.ok) {
+            // TODO: maybe add a debug flag to print these when dev'ing?
+            // console.log(`Error raising intent: ${await postResponse.text()}`);
+            throw new CloudInteropAPIError(`Error raising intent`, 'ERR_RAISING_INTENT', new Error(postResponse.statusText));
+        }
+    }
+    async reportAppIntents(discoveryId, intents) {
+        intents = encodeAppIntents(intents, getSourceFromSession(this.#sessionDetails));
+        try {
+            const reportResponse = await fetch(`${this.#url}/api/intents/${this.#sessionDetails.sessionId}/${discoveryId}`, {
+                method: 'POST',
+                headers: getRequestHeaders(this.#connectionParams),
+                body: JSON.stringify({ intents }),
+            });
+            if (reportResponse.ok) {
+                return true;
+            }
+            throw new CloudInteropAPIError('Error reporting intents', 'ERR_REPORTING_INTENTS', new Error(reportResponse.statusText));
+        }
+        catch (error) {
+            this.#logger('warn', `Error reporting intents for discovery ID ${discoveryId}: ${error}`);
+        }
+        return false;
+    }
+    async sendIntentResult(initiatingSessionId, result) {
+        if (!isErrorIntentResult(result)) {
+            // cloud-encode the source app id to support chained intent actions over cloud
+            // https://fdc3.finos.org/docs/2.0/api/spec#resolution-object -> "Use metadata about the resolving app instance to target a further intent"
+            const source = getSourceFromSession(this.#sessionDetails);
+            const encoded = encodeAppId(typeof result.source === 'string' ? result.source : result.source.appId, source);
+            result.source = typeof result.source === 'string' ? encoded : { ...result.source, appId: encoded };
+        }
+        const { sessionId } = getSourceFromSession(this.#sessionDetails);
+        const resultResponse = await fetch(`${this.#url}/api/intents/${initiatingSessionId}/result/${sessionId}`, {
+            method: 'POST',
+            headers: getRequestHeaders(this.#connectionParams),
+            body: JSON.stringify({ result }),
+        });
+        if (!resultResponse.ok) {
+            throw new CloudInteropAPIError('Error sending intent result', 'ERR_SENDING_INTENT_RESULT', new Error(resultResponse.statusText));
+        }
+    }
+    handleCommandMessage(message) {
+        switch (message.command) {
+            case 'report-intents': {
+                if (message.initiatingSessionId === this.#sessionDetails?.sessionId) {
+                    // Ignore if this originated from us
+                    return;
+                }
+                const { command: _, ...event } = message;
+                this.#events.emitEvent('report-intents', event);
+                break;
+            }
+            case 'intent-details': {
+                /**
+                 * We aggregate intent details commands from all connected sessions on the server side
+                 * to ensure upstream clients don't have to do this. Also given @openfin/cloud-interop
+                 * exposes FDC3 compliant APIs, there is no concept of streaming available, hence we
+                 * aggregate the responses here and send them in a synchronous manner.
+                 */
+                const { command: _, ...event } = message;
+                // Decode intents before emitting to client
+                event.intents = decodeAppIntents(event.intents);
+                // always emit individual intent-details events in addition to aggregate-intent-details
+                // for flexibility after intent discovery has ended, this can be useful for late-joining
+                // clients nearing the timeout
+                this.#events.emitEvent('intent-details', event);
+                if (message.discoveryId !== this.#discovery.id || this.#discovery.state !== 'in-progress') {
+                    // Ignore if its any other discovery id for some reason, or
+                    // if we're not in the middle of a discovery
+                    return;
+                }
+                this.#discovery.responseCount += 1;
+                this.#logger('debug', `Received intent details from ${message.source.sessionId}, received: ${this.#discovery.responseCount}, out of connected sessions: ${this.#discovery.sessionCount - 1}`);
+                this.#discovery.pendingIntentDetailsEvents.push(event);
+                const allResponded = this.#discovery.responseCount === this.#discovery.sessionCount - 1;
+                if (allResponded) {
+                    this.#endIntentDiscovery();
+                }
+                break;
+            }
+            case 'raise-intent': {
+                if (message.targetSessionId === this.#sessionDetails?.sessionId) {
+                    const { command: _, ...event } = message;
+                    this.#events.emitEvent('raise-intent', event);
+                }
+                break;
+            }
+            case 'intent-result': {
+                if (message.initiatingSessionId === this.#sessionDetails?.sessionId) {
+                    // Return result to originator and end discovery
+                    const { command: _, ...resultEvent } = message;
+                    this.#events.emitEvent('intent-result', resultEvent);
+                }
+                break;
+            }
+            default: {
+                this.#logger('warn', `Unknown command message received:\n${JSON.stringify(message, null, 2)}`);
+                break;
+            }
+        }
+    }
+}
+
+// Error codes as defined in https://docs.emqx.com/en/cloud/latest/connect_to_deployments/mqtt_client_error_codes.html
+const BadUserNamePasswordError = 134;
+/**
+ * Represents a single connection to a Cloud Interop service
+ *
+ * @public
+ * @class
+ */
+class CloudInteropAPI {
+    #cloudInteropSettings;
+    #sessionDetails;
+    #mqttClient;
+    #reconnectRetryLimit = 30;
+    #keepAliveIntervalSeconds = 30;
+    #logger = (level, message) => {
+        console[level](message);
+    };
+    #reconnectRetries = 0;
+    #connectionParams;
+    #attemptingToReconnect = false;
+    #events = new EventController();
+    #intents;
+    #sessionTimer;
+    constructor(cloudInteropSettings) {
+        this.#cloudInteropSettings = cloudInteropSettings;
+    }
+    get sessionDetails() {
+        return this.#sessionDetails;
+    }
+    get mqttClient() {
+        return this.#mqttClient;
+    }
+    /**
+     * Connects and creates a session on the Cloud Interop service
+     *
+     * @param parameters - The parameters to use to connect
+     * @returns Promise that resolves when connection is established
+     * @memberof CloudInteropAPI
+     * @throws CloudInteropAPIError - If an error occurs during connection
+     * @throws AuthorizationError - If the connection is unauthorized
+     */
+    async connect(parameters) {
+        this.#validateConnectParams(parameters);
+        this.#connectionParams = parameters;
+        this.#reconnectRetryLimit = parameters.reconnectRetryLimit || this.#reconnectRetryLimit;
+        this.#keepAliveIntervalSeconds = parameters.keepAliveIntervalSeconds || this.#keepAliveIntervalSeconds;
+        this.#logger = parameters.logger || this.#logger;
+        const { sourceId, platformId } = this.#connectionParams;
+        const createSessionResponse = await fetch(`${this.#cloudInteropSettings.url}/api/sessions`, {
+            method: 'POST',
+            headers: getRequestHeaders(this.#connectionParams),
+            body: JSON.stringify({ sourceId: sourceId.trim(), platformId }),
+        });
+        if (!createSessionResponse.ok) {
+            if (createSessionResponse.status === 401 || createSessionResponse.status === 403) {
+                throw new AuthorizationError();
+            }
+            throw new CloudInteropAPIError();
+        }
+        if (createSessionResponse.status !== 201) {
+            throw new CloudInteropAPIError(`Failed to connect to the Cloud Interop service: ${this.#cloudInteropSettings.url}`, 'ERR_CONNECT', new Error(createSessionResponse.statusText));
+        }
+        this.#sessionDetails = (await createSessionResponse.json());
+        // If local session expiry handling is enabled, start the session timer
+        if (this.#sessionDetails.localSessionExpiryHandling) {
+            this.#logger('debug', `Local session expiry handling is enabled`);
+            this.#startSessionTimer();
+        }
+        const sessionRootTopic = this.#sessionDetails.sessionRootTopic;
+        const clientOptions = {
+            keepalive: this.#keepAliveIntervalSeconds,
+            clientId: this.#sessionDetails.sessionId,
+            clean: true,
+            protocolVersion: 5,
+            // The "will" message will be published on an unexpected disconnection
+            // The server can then tidy up.  So it needs every for this client to do that, the session details is perfect
+            will: {
+                topic: 'interop/lastwill',
+                payload: Buffer.from(JSON.stringify(this.#sessionDetails)),
+                qos: 0,
+                retain: false,
+            },
+            username: this.#sessionDetails.token,
+        };
+        this.#mqttClient = await mqtt.connectAsync(this.#sessionDetails.url, clientOptions);
+        // TODO: Dynamic intent discovery
+        // search for any ongoing discoveries in DB and fire report-intents on self
+        this.#logger('log', `Cloud Interop successfully connected to ${this.#cloudInteropSettings.url}`);
+        this.#mqttClient.on('error', async (error) => {
+            // We will receive errors for each failed reconnection attempt
+            // We don't want to disconnect on these else we will never reconnect
+            if (!this.#attemptingToReconnect) {
+                await this.#disconnect(false);
+            }
+            if (error instanceof mqtt.ErrorWithReasonCode) {
+                switch (error.code) {
+                    case BadUserNamePasswordError: {
+                        this.#handleSessionExpiry();
+                        return;
+                    }
+                    default: {
+                        this.#logger('error', `Unknown Infrastructure Error Code ${error.code} : ${error.message}${this.#attemptingToReconnect ? ' during reconnection attempt' : ''}`);
+                        // As we are in the middle of a reconnect, lets not emit an error to cut down on the event noise
+                        if (!this.#attemptingToReconnect) {
+                            this.#events.emitEvent('error', new CloudInteropAPIError(`Unknown Infrastructure Error Code ${error.code} : ${error.message}`, 'ERR_INFRASTRUCTURE', error));
+                            break;
+                        }
+                    }
+                }
+            }
+            else {
+                this.#logger('error', `Unknown Error${this.#attemptingToReconnect ? ' during reconnection attempt' : ''}: ${error}`);
+                // As we are in the middle of a reconnect, lets not emit an error to cut down on the event noise
+                if (!this.#attemptingToReconnect) {
+                    this.#events.emitEvent('error', new CloudInteropAPIError(`Unknown Error`, 'ERR_UNKNOWN', error));
+                }
+            }
+        });
+        this.#mqttClient.on('reconnect', () => {
+            this.#attemptingToReconnect = true;
+            this.#reconnectRetries += 1;
+            this.#logger('debug', `Cloud Interop attempting reconnection - ${this.#reconnectRetries}...`);
+            if (this.#reconnectRetries === this.#reconnectRetryLimit) {
+                this.#logger('warn', `Cloud Interop reached max reconnection attempts - ${this.#reconnectRetryLimit}...`);
+                this.#disconnect(true);
+            }
+            this.#events.emitEvent('reconnecting', this.#reconnectRetries);
+        });
+        // Does not fire on initial connection, only successful reconnection attempts
+        this.#mqttClient.on('connect', () => {
+            this.#logger('debug', `Cloud Interop successfully reconnected after ${this.#reconnectRetries} attempts`);
+            this.#reconnectRetries = 0;
+            this.#attemptingToReconnect = false;
+            this.#events.emitEvent('reconnected');
+        });
+        this.#mqttClient.on('message', (topic, message) => {
+            if (!this.#sessionDetails) {
+                this.#logger('warn', 'Received message when session not connected');
+                return;
+            }
+            this.#handleMessage(topic, message, this.#sessionDetails);
+        });
+        // Subscribe to all context groups
+        this.#mqttClient.subscribe(`${sessionRootTopic}/context-groups/#`);
+        // Listen out for global commands
+        this.#mqttClient.subscribe(`${sessionRootTopic}/commands`);
+        this.#initControllers(this.#mqttClient, this.#sessionDetails, this.#connectionParams);
+    }
+    /**
+     * Disconnects from the Cloud Interop service
+     *
+     * @returns Promise that resolves when disconnected
+     * @memberof CloudInteropAPI
+     * @throws CloudInteropAPIError - If an error occurs during disconnection
+     */
+    async disconnect() {
+        await this.#disconnect(true);
+    }
+    /**
+     * Publishes a new context for the given context group to the other connected sessions
+     *
+     * @param contextGroup - The context group to publish to
+     * @param context - The context to publish
+     * @returns Promise that resolves when context is published
+     * @memberof CloudInteropAPI
+     */
+    async setContext(contextGroup, context) {
+        // TODO: make context of type OpenFin.Context
+        if (!this.#sessionDetails || !this.#connectionParams) {
+            throw new Error('Session not connected');
+        }
+        if (!this.#mqttClient) {
+            throw new Error('MQTT client not connected');
+        }
+        const payload = {
+            context,
+            timestamp: Date.now(),
+        };
+        const postResponse = await fetch(`${this.#cloudInteropSettings.url}/api/context-groups/${this.#sessionDetails.sessionId}/${contextGroup}`, {
+            method: 'POST',
+            headers: getRequestHeaders(this.#connectionParams),
+            body: JSON.stringify(payload),
+        });
+        if (!postResponse.ok) {
+            throw new CloudInteropAPIError(`Error setting context for ${contextGroup}`, 'ERR_SETTING_CONTEXT', new Error(postResponse.statusText));
+        }
+    }
+    /**
+     * Starts an intent discovery operation
+     *
+     * @returns Promise that resolves when intent discovery is started
+     * @memberof CloudInteropAPI
+     * @throws CloudInteropAPIError - If an error occurs during intent discovery
+     */
+    async startIntentDiscovery(options) {
+        this.#throwIfNotConnected();
+        return this.#intents?.startIntentDiscovery(options);
+    }
+    async raiseIntent(options) {
+        this.#throwIfNotConnected();
+        return this.#intents?.raiseIntent(options);
+    }
+    async reportAppIntents(discoveryId, intents) {
+        this.#throwIfNotConnected();
+        return this.#intents?.reportAppIntents(discoveryId, intents) ?? false;
+    }
+    async sendIntentResult(initiatingSessionId, result) {
+        this.#throwIfNotConnected();
+        return this.#intents?.sendIntentResult(initiatingSessionId, result);
+    }
+    parseSessionId(appId) {
+        return parseCloudAppId(appId).sessionId;
+    }
+    parseAppId(appId) {
+        return parseCloudAppId(appId).appId;
+    }
+    addEventListener(type, callback) {
+        this.#events.addEventListener(type, callback);
+    }
+    removeEventListener(type, callback) {
+        this.#events.removeEventListener(type, callback);
+    }
+    once(type, callback) {
+        this.#events.once(type, callback);
+    }
+    async #disconnect(fireDisconnectedEvent) {
+        if (!this.#sessionDetails) {
+            return;
+        }
+        try {
+            if (!this.#connectionParams) {
+                throw new Error('Connect parameters must be provided');
+            }
+            // Cancel session timer if it's running
+            if (this.#sessionTimer) {
+                clearTimeout(this.#sessionTimer);
+                this.#sessionTimer = undefined;
+            }
+            const disconnectResponse = await fetch(`${this.#cloudInteropSettings.url}/api/sessions/${this.#sessionDetails.sessionId}`, {
+                method: 'DELETE',
+                headers: getRequestHeaders(this.#connectionParams),
+            });
+            if (disconnectResponse.status !== 200) {
+                throw new CloudInteropAPIError('Error during session tear down - unexpected status', 'ERR_DISCONNECT', new Error(disconnectResponse.statusText));
+            }
+        }
+        catch (error) {
+            throw new CloudInteropAPIError('Error during disconnection', 'ERR_DISCONNECT', error);
+        }
+        finally {
+            this.#destroyControllers();
+            this.#mqttClient?.removeAllListeners();
+            await this.#mqttClient?.endAsync(true);
+            this.#sessionDetails = undefined;
+            this.#mqttClient = undefined;
+            this.#reconnectRetries = 0;
+            this.#attemptingToReconnect = false;
+            if (fireDisconnectedEvent) {
+                this.#events.emitEvent('disconnected');
+            }
+        }
+    }
+    #handleMessage(topic, message, sessionDetails) {
+        if (message.length === 0 || !sessionDetails) {
+            // Ignore clean up messages
+            return;
+        }
+        const messageEnvelope = JSON.parse(message.toString());
+        if (topic.startsWith(`${sessionDetails.sessionRootTopic}/context-groups/`)) {
+            const contextEvent = messageEnvelope;
+            if (contextEvent.source.sessionId === sessionDetails.sessionId) {
+                return;
+            }
+            const { context, payload, contextGroup, channelName, source, history } = contextEvent;
+            this.#events.emitEvent('context', {
+                contextGroup: channelName || contextGroup,
+                context: payload || context,
+                source,
+                history: { ...history, clientReceived: Date.now() },
+            });
+        }
+        else if (topic.startsWith(`${sessionDetails.sessionRootTopic}/commands`)) {
+            this.#handleCommandMessage(messageEnvelope);
+        }
+    }
+    #handleCommandMessage(message) {
+        switch (message.command) {
+            case 'report-intents':
+            case 'intent-details':
+            case 'raise-intent':
+            case 'intent-result': {
+                this.#intents?.handleCommandMessage(message);
+                break;
+            }
+            default: {
+                this.#logger('warn', `Unknown command message received:\n${JSON.stringify(message, null, 2)}`);
+                break;
+            }
+        }
+    }
+    #validateConnectParams = (parameters) => {
+        if (!parameters) {
+            throw new Error('Connect parameters must be provided');
+        }
+        if (!parameters.sourceId) {
+            throw new Error('sourceId must be provided');
+        }
+        if (parameters.sourceId.includes(APP_ID_DELIM)) {
+            throw new Error(`sourceId cannot contain "${APP_ID_DELIM}"`);
+        }
+        if (!parameters.platformId) {
+            throw new Error('platformId must be provided');
+        }
+        if (parameters.authenticationType === 'jwt' &&
+            (!parameters.jwtAuthenticationParameters?.jwtRequestCallback || !parameters.jwtAuthenticationParameters?.authenticationId)) {
+            throw new Error('jwtAuthenticationParameters must be provided when using jwt authentication');
+        }
+        if (parameters.authenticationType === 'basic' &&
+            (!parameters.basicAuthenticationParameters?.username || !parameters.basicAuthenticationParameters?.password)) {
+            throw new Error('basicAuthenticationParameters must be provided when using basic authentication');
+        }
+    };
+    #initControllers(mqttClient, sessionDetails, connectionParameters) {
+        this.#intents = new IntentController(this.#cloudInteropSettings.url, mqttClient, sessionDetails, connectionParameters, this.#events, this.#logger);
+    }
+    #destroyControllers() {
+        this.#intents = undefined;
+    }
+    #throwIfNotConnected() {
+        if (!this.#sessionDetails || !this.#connectionParams) {
+            throw new Error('Session not connected');
+        }
+        if (!this.#mqttClient) {
+            throw new Error('MQTT client not connected');
+        }
+    }
+    /**
+     * Extracts the expiration timestamp from a JWT token.
+     *
+     * @param token - The JWT token string
+     * @returns The expiration timestamp in seconds, or null if extraction fails
+     */
+    #extractExpirationFromJwt(token) {
+        try {
+            // JWT tokens have three parts separated by dots: header.payload.signature
+            // The exp claim is in the payload
+            const parts = token.split('.');
+            if (parts.length < 2) {
+                this.#logger('warn', 'Invalid JWT token format: expected at least 2 parts');
+                return null;
+            }
+            const payload = parts[1];
+            // Decode base64url encoded payload
+            const decodedBytes = Buffer.from(l(payload), 'base64');
+            const payloadJson = decodedBytes.toString('utf8');
+            // Parse JSON to get the exp claim
+            const claims = JSON.parse(payloadJson);
+            const exp = claims.exp;
+            if (exp === undefined || exp === null) {
+                this.#logger('warn', "JWT token does not contain 'exp' claim");
+                return null;
+            }
+            if (typeof exp !== 'number') {
+                this.#logger('warn', `JWT token 'exp' claim is not a number: ${exp}`);
+                return null;
+            }
+            return exp;
+        }
+        catch (error) {
+            this.#logger('error', `Failed to extract expiration from JWT token: ${error instanceof Error ? error.message : error}`);
+            return null;
+        }
+    }
+    /**
+     * Start a session timer that will expire at the time specified in the JWT token's exp claim.
+     * When the timer fires, it executes the same actions as the BadUserNamePasswordError case.
+     */
+    #startSessionTimer() {
+        if (!this.#sessionDetails?.localSessionExpiryHandling) {
+            return;
+        }
+        const token = this.#sessionDetails.token;
+        if (!token) {
+            this.#logger('warn', 'Cannot start session timer: token not available');
+            return;
+        }
+        // Extract expiration time from JWT token
+        const expTimestamp = this.#extractExpirationFromJwt(token);
+        if (expTimestamp === null) {
+            this.#logger('warn', 'Cannot start session timer: could not extract expiration from JWT token');
+            return;
+        }
+        const currentTimeSeconds = Math.floor(Date.now() / 1000);
+        const delaySeconds = expTimestamp - currentTimeSeconds;
+        if (delaySeconds <= 0) {
+            this.#logger('warn', 'JWT token has already expired or expires immediately');
+            // Execute the same actions as BadUserNamePasswordError case
+            this.#handleSessionExpiry();
+            return;
+        }
+        // Clear any existing timer
+        if (this.#sessionTimer) {
+            clearTimeout(this.#sessionTimer);
+        }
+        const expirationTimeString = new Date(expTimestamp * 1000).toISOString();
+        this.#logger('debug', `Starting session timer to expire in ${delaySeconds} seconds (at ${expirationTimeString})`);
+        this.#sessionTimer = setTimeout(async () => {
+            this.#handleSessionExpiry();
+        }, delaySeconds * 1000);
+    }
+    /**
+     * Handles session expiry by executing the same actions as the BadUserNamePasswordError case.
+     */
+    async #handleSessionExpiry() {
+        await this.#disconnect(false);
+        this.#logger('warn', 'Session expired');
+        this.#events.emitEvent('session-expired');
+    }
+}
+
+export { AuthorizationError, CloudInteropAPI, CloudInteropAPIError };