@octostar/platform-api 0.5.30 → 0.5.32

package/dist/apis.d.ts

@@ -1,4 +1,5 @@
 import type { Desktop, Ontology, ExtrasApi, RemoteAppApi, SavedSearchAPIInterface } from '@octostar/platform-types';
+import { getOctostarConnectionManager, type OctostarConnectionManager } from './factory';
 import type { ContextApi, EnsureMethodsReturnPromise } from './types';
 /**
  * @beta
@@ -36,4 +37,15 @@ export declare const getOntologyApi: () => Promise<EnsureMethodsReturnPromise<On
  * Get the context API asynchronously.
  */
 export declare const getContextApi: () => Promise<EnsureMethodsReturnPromise<ContextApi<unknown>>>;
+/**
+ * @beta
+ * Gets the singleton instance of OctostarConnectionManager.
+ * This is the primary way to access connection management functionality.
+ */
+export { getOctostarConnectionManager };
+/**
+ * @beta
+ * Type for OctostarConnectionManager class.
+ */
+export type { OctostarConnectionManager };
 //# sourceMappingURL=apis.d.ts.map

package/dist/apis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAGpH,OAAO,KAAK,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAsCtE;;;;GAIG;AACH,eAAO,MAAM,UAAU,2CAAsE,CAAC;AAE9F,eAAO,MAAM,SAAS,6CAAqE,CAAC;AAE5F,eAAO,MAAM,YAAY,gDAAwE,CAAC;AAElG,eAAO,MAAM,cAAc,2DAA0E,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,WAAW,4CAAuE,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,UAAU,uDAAsE,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,aAAa,oDAA2D,CAAC;AAEtF;;;GAGG;AACH,eAAO,MAAM,cAAc,qDAA6D,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,aAAa,gEAA2D,CAAC"}
+{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEpH,OAAO,EAGL,4BAA4B,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,UAAU,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAsCtE;;;;GAIG;AACH,eAAO,MAAM,UAAU,2CAAsE,CAAC;AAE9F,eAAO,MAAM,SAAS,6CAAqE,CAAC;AAE5F,eAAO,MAAM,YAAY,gDAAwE,CAAC;AAElG,eAAO,MAAM,cAAc,2DAA0E,CAAC;AAEtG;;;;GAIG;AACH,eAAO,MAAM,WAAW,4CAAuE,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,UAAU,uDAAsE,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,aAAa,oDAA2D,CAAC;AAEtF;;;GAGG;AACH,eAAO,MAAM,cAAc,qDAA6D,CAAC;AAEzF;;;GAGG;AACH,eAAO,MAAM,aAAa,gEAA2D,CAAC;AAEtF;;;;GAIG;AACH,OAAO,EAAE,4BAA4B,EAAE,CAAC;AAExC;;;GAGG;AACH,YAAY,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/apis.js

@@ -1,5 +1,5 @@
 import { AsyncServiceLocator } from './lib/AsyncServiceLocator';
-import { forwardCallsToFutureObject, createRemoteApiHandle } from './factory';
+import { forwardCallsToFutureObject, createRemoteApiHandle, getOctostarConnectionManager, } from './factory';
 import { apiNames } from './constants';
 const apisLocator = AsyncServiceLocator.getInstance('platform-api', {
     cache: false,
@@ -60,4 +60,10 @@ export const getOntologyApi = async () => apisLocator.getService('ontology');
  * Get the context API asynchronously.
  */
 export const getContextApi = async () => apisLocator.getService('context');
+/**
+ * @beta
+ * Gets the singleton instance of OctostarConnectionManager.
+ * This is the primary way to access connection management functionality.
+ */
+export { getOctostarConnectionManager };
 //# sourceMappingURL=apis.js.map

package/dist/apis.js.map

@@ -1 +1 @@
-{"version":3,"file":"apis.js","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE9E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,WAAW,GAAG,mBAAmB,CAAC,WAAW,CAAC,cAAc,EAAE;IAClE,KAAK,EAAE,KAAK;CACb,CAAC;KACC,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,CAC/B,qBAAqB,CAAsC;IACzD,IAAI,EAAE,QAAQ,CAAC,OAAO;CACvB,CAAC,CACH;KACA,eAAe,CAAC,UAAU,EAAE,GAAG,EAAE,CAChC,qBAAqB,CAAuC;IAC1D,IAAI,EAAE,QAAQ,CAAC,QAAQ;CACxB,CAAC,CACH;KACA,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE;AAC/B,uCAAuC;AACvC,qBAAqB,CAAkD;IACrE,IAAI,EAAE,QAAQ,CAAC,OAAO;CACvB,CAAC,CACH;KACA,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,CAC9B,qBAAqB,CAAwC;IAC3D,IAAI,EAAE,QAAQ,CAAC,MAAM;CACtB,CAAC,CACH;KACA,eAAe,CAAC,WAAW,EAAE,GAAG,EAAE,CACjC,qBAAqB,CAA2C;IAC9D,IAAI,EAAE,QAAQ,CAAC,SAAS;CACzB,CAAC,CACH;KACA,eAAe,CAAC,aAAa,EAAE,GAAG,EAAE,CACnC,qBAAqB,CAAsD;IACzE,IAAI,EAAE,QAAQ,CAAC,WAAW;CAC3B,CAAC,CACH,CAAC;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;AAE5F,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC;AAEtG;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAY,SAAS,CAAC,CAAC;AAEtF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAa,UAAU,CAAC,CAAC;AAEzF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAY,SAAS,CAAC,CAAC"}
+{"version":3,"file":"apis.js","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,4BAA4B,GAE7B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,MAAM,WAAW,GAAG,mBAAmB,CAAC,WAAW,CAAC,cAAc,EAAE;IAClE,KAAK,EAAE,KAAK;CACb,CAAC;KACC,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,CAC/B,qBAAqB,CAAsC;IACzD,IAAI,EAAE,QAAQ,CAAC,OAAO;CACvB,CAAC,CACH;KACA,eAAe,CAAC,UAAU,EAAE,GAAG,EAAE,CAChC,qBAAqB,CAAuC;IAC1D,IAAI,EAAE,QAAQ,CAAC,QAAQ;CACxB,CAAC,CACH;KACA,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE;AAC/B,uCAAuC;AACvC,qBAAqB,CAAkD;IACrE,IAAI,EAAE,QAAQ,CAAC,OAAO;CACvB,CAAC,CACH;KACA,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,CAC9B,qBAAqB,CAAwC;IAC3D,IAAI,EAAE,QAAQ,CAAC,MAAM;CACtB,CAAC,CACH;KACA,eAAe,CAAC,WAAW,EAAE,GAAG,EAAE,CACjC,qBAAqB,CAA2C;IAC9D,IAAI,EAAE,QAAQ,CAAC,SAAS;CACzB,CAAC,CACH;KACA,eAAe,CAAC,aAAa,EAAE,GAAG,EAAE,CACnC,qBAAqB,CAAsD;IACzE,IAAI,EAAE,QAAQ,CAAC,WAAW;CAC3B,CAAC,CACH,CAAC;AAEJ;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAE9F,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;AAE5F,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC;AAEtG;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,0BAA0B,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAE9F;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAY,SAAS,CAAC,CAAC;AAEtF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAa,UAAU,CAAC,CAAC;AAEzF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,UAAU,CAAY,SAAS,CAAC,CAAC;AAEtF;;;;GAIG;AACH,OAAO,EAAE,4BAA4B,EAAE,CAAC"}

package/dist/factory.d.ts

@@ -1,4 +1,131 @@
 import type { GetRemoteApiParams } from './types';
+type ChannelIdChangeCallback = (channelId: string) => void;
+/**
+ * Manages Octostar connection state, including remote dev mode, channel IDs, window references,
+ * and connection lifecycle. This is a singleton class accessed via getOctostarConnectionManager().
+ */
+export declare class OctostarConnectionManager {
+    private resolvedMode;
+    private remoteDevWindow;
+    private channelIdSubscribers;
+    private hasParent;
+    private getParentOctostarWindow;
+    private tryFetchingFromAttributes;
+    private traverseForChannelId;
+    private clearConnectionHistory;
+    private notifyChannelIdChanged;
+    private handlePostResponse;
+    private createObjectProxy;
+    /**
+     * Sets the remote dev window reference.
+     * This should be called when opening a remote dev window from a React component.
+     */
+    setWindow(window: Window | null): void;
+    /**
+     * Gets the remote dev window reference.
+     */
+    getWindow(): Window | null;
+    /**
+     * Gets or creates a remote dev channel ID.
+     * If a channel ID already exists in sessionStorage, returns it.
+     * Otherwise, generates a new one and stores it.
+     */
+    getOrCreateChannelId(): string;
+    /**
+     * Checks if a remote dev channel ID exists without creating one.
+     * Used to determine if a connection attempt has been made.
+     */
+    hasChannelId(): boolean;
+    /**
+     * Subscribe to remote dev channel ID changes.
+     * Returns an unsubscribe function.
+     */
+    onChannelIdChanged(callback: ChannelIdChangeCallback): () => void;
+    /**
+     * Marks that a successful remote dev connection was established.
+     * This is called when a connection is successfully made (e.g., ping succeeds).
+     */
+    markConnectionSuccess(): void;
+    /**
+     * Marks whether the remote dev connection was intentionally disconnected.
+     * @param intentionallyDisconnected - true if user clicked Disconnect/Reset, false if user is trying to connect
+     */
+    markIntentionallyDisconnected(intentionallyDisconnected: boolean): void;
+    /**
+     * Returns whether a successful remote dev connection was ever established in this session.
+     * This persists across component remounts and page refreshes (within the same session).
+     * Only returns true if a channel ID exists (fixes initial load bug).
+     */
+    wasEverConnected(): boolean;
+    /**
+     * Returns whether the remote dev connection was intentionally disconnected.
+     * This is used to determine whether to show "Connect" vs "Reconnect" button.
+     */
+    wasIntentionallyDisconnected(): boolean;
+    /**
+     * Gets the remote dev URL from sessionStorage.
+     * Returns empty string if not set.
+     */
+    getUrl(): string;
+    /**
+     * Sets the remote dev URL in sessionStorage.
+     */
+    setUrl(url: string): void;
+    /**
+     * Returns true when the app is not in connected iframe mode (no octostarChannelId found in URL or
+     * iframe chain), i.e. running in remote dev mode. Returns false when running inside an Octostar
+     * iframe (embedded).
+     */
+    isRemoteDevMode(): boolean;
+    /**
+     * Clears resolvedMode if the channel ID has changed.
+     * This is called when SET_CHANNEL_ID message is received to ensure
+     * createRemoteApiHandle re-resolves with the new channel ID.
+     * @param newChannelId - The new channel ID that was set
+     */
+    clearResolvedModeIfChannelChanged(newChannelId: string): void;
+    /**
+     * Resets the remote dev connection state.
+     * This clears the resolved mode and window reference, allowing the connection to be re-established.
+     * Should be called when connection is lost and user wants to reconnect.
+     */
+    resetConnection(): void;
+    /**
+     * Resets remote dev mode by closing the window and clearing all connection state.
+     * This puts the app back into a disconnected startup state.
+     * A new channel ID will be generated automatically when the user clicks Connect.
+     */
+    resetMode(): void;
+    /**
+     * Opens a remote dev window with the given URL.
+     * This function:
+     * - Validates the URL
+     * - Saves it to sessionStorage
+     * - Gets or creates a channel ID
+     * - Adds remoteDevChannelId as a URL parameter
+     * - Opens the window and stores the reference
+     * - Returns the window or null if popup was blocked
+     */
+    openWindow(url: string): Window | null;
+    /**
+     * Creates a remote API handle for communicating with Octostar.
+     * This resolves the connection mode (iframe vs remote dev) and sets up post-robot communication.
+     */
+    createRemoteApiHandle<T extends object>(params: GetRemoteApiParams): Promise<T>;
+}
+/**
+ * Gets the singleton instance of OctostarConnectionManager.
+ * Creates a new instance if one doesn't exist.
+ */
+export declare function getOctostarConnectionManager(): OctostarConnectionManager;
+/**
+ * Creates a remote API handle. This is a convenience function that delegates to the manager.
+ * @deprecated Use getOctostarConnectionManager().createRemoteApiHandle() instead
+ */
 export declare const createRemoteApiHandle: <T extends object>(params: GetRemoteApiParams) => Promise<T>;
+/**
+ * Forwards calls to a future object. Used for creating proxies that forward to promises.
+ */
 export declare const forwardCallsToFutureObject: <T>(chain: Promise<T>) => T;
+export {};
 //# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAA2C,MAAM,SAAS,CAAC;AAmK3F,eAAO,MAAM,qBAAqB,GAAU,CAAC,SAAS,MAAM,EAAE,QAAQ,kBAAkB,eA0BvF,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,CAAC,EAAE,OAAO,OAAO,CAAC,CAAC,CAAC,KAAG,CAS1D,CAAC"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAA2C,MAAM,SAAS,CAAC;AAI3F,KAAK,uBAAuB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;AAM3D;;;GAGG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,oBAAoB,CAAsC;IAMlE,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,uBAAuB;IA6B/B,OAAO,CAAC,yBAAyB;IAcjC,OAAO,CAAC,oBAAoB;IA+C5B,OAAO,CAAC,sBAAsB;IAK9B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IA4BzB;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAItC;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAQ1B;;;;OAIG;IACH,oBAAoB,IAAI,MAAM;IAc9B;;;OAGG;IACH,YAAY,IAAI,OAAO;IAKvB;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,MAAM,IAAI;IASjE;;;OAGG;IACH,qBAAqB,IAAI,IAAI;IAM7B;;;OAGG;IACH,6BAA6B,CAAC,yBAAyB,EAAE,OAAO,GAAG,IAAI;IAQvE;;;;OAIG;IACH,gBAAgB,IAAI,OAAO;IAM3B;;;OAGG;IACH,4BAA4B,IAAI,OAAO;IAQvC;;;OAGG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQzB;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAW1B;;;;;OAKG;IACH,iCAAiC,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAY7D;;;;OAIG;IACH,eAAe,IAAI,IAAI;IAUvB;;;;OAIG;IACH,SAAS,IAAI,IAAI;IAiCjB;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkDtC;;;OAGG;IACG,qBAAqB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;CAuEtF;AAQD;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,yBAAyB,CAKxE;AAoBD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAU,CAAC,SAAS,MAAM,EAAE,QAAQ,kBAAkB,KAAG,OAAO,CAAC,CAAC,CAEnG,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,EAAE,OAAO,OAAO,CAAC,CAAC,CAAC,KAAG,CAS1D,CAAC"}