@telemetryos/root-sdk 1.0.0

package/dist/bridge.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { clientMessageValidator } from './client-message-validator.js';
+import { bridgeMessageValidator } from './bridge-message-validator.js';
+/**
+ * Defines the structure of a client message as defined in the
+ * clientMessageValidator.
+ */
+export type ClientMessage = z.infer<typeof clientMessageValidator>;
+/**
+ * Defines the structure of a bridge message as defined in the
+ * bridgeMessageValidator.
+ */
+export type BridgeMessage = z.infer<typeof bridgeMessageValidator>;
+/**
+ * The Bridge class is provides a way for host applications to communicate with
+ * TelemetryOS applications. It listens for window message events and sends
+ * messages to all frames.
+ *
+ * SDK Clients will be listening for these messages, discriminating for messages
+ * specifically for them.
+ */
+export declare class Bridge {
+    /**
+     * Must be provided you the host application when using the Bridge. This
+     * function will be called when a message is received. The message will be
+     * passed to the function.
+     */
+    onMessage?: (message: ClientMessage) => void;
+    _windowMessageHandler?: (event: MessageEvent) => void;
+    /**
+     * Binds the Bridge to the window message event. This will allow the Bridge
+     * to listen for messages from the host application.
+     */
+    bind(): void;
+    /**
+     * Unbinds the Bridge from the window message event. Useful if the host
+     * application no longer needs to communicate with SDK clients.
+     */
+    unbind(): void;
+    /**
+     * Sends a message to SDK clients.
+     * @param message The message to send.
+     */
+    send(message: BridgeMessage): void;
+}

package/dist/bridge.js

@@ -0,0 +1,46 @@
+import { z as e } from "./index-B98VDFRY.js";
+const t = e.object({
+  telemetrySdkVersion: e.string(),
+  applicationName: e.string(),
+  name: e.string(),
+  data: e.any(),
+  responseName: e.string().optional(),
+  subscriptionName: e.string().optional(),
+  unsubscribeName: e.string().optional()
+});
+class d {
+  /**
+   * Binds the Bridge to the window message event. This will allow the Bridge
+   * to listen for messages from the host application.
+   */
+  bind() {
+    this._windowMessageHandler = (n) => {
+      var s;
+      if (n.source === window)
+        return;
+      const i = t.safeParse(n.data);
+      if (!i.success)
+        return;
+      const a = i.data;
+      (s = this.onMessage) === null || s === void 0 || s.call(this, a);
+    }, window.addEventListener("message", this._windowMessageHandler);
+  }
+  /**
+   * Unbinds the Bridge from the window message event. Useful if the host
+   * application no longer needs to communicate with SDK clients.
+   */
+  unbind() {
+    this._windowMessageHandler && window.removeEventListener("message", this._windowMessageHandler);
+  }
+  /**
+   * Sends a message to SDK clients.
+   * @param message The message to send.
+   */
+  send(n) {
+    for (let s = 0; s < window.frames.length; s += 1)
+      window.frames[s].postMessage(n, "*");
+  }
+}
+export {
+  d as Bridge
+};

package/dist/client-message-formatter.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { clientMessageValidator } from './client-message-validator.js';
+export type Message = z.infer<typeof clientMessageValidator>;
+export declare function formatClientMessage(data: Message): {
+    telemetrySdkVersion: string;
+    applicationName: string;
+    name: string;
+    data?: any;
+    responseName?: string | undefined;
+    subscriptionName?: string | undefined;
+    unsubscribeName?: string | undefined;
+};

package/dist/client-message-validator.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export declare const clientMessageValidator: z.ZodObject<{
+    telemetrySdkVersion: z.ZodString;
+    applicationName: z.ZodString;
+    name: z.ZodString;
+    data: z.ZodAny;
+    responseName: z.ZodOptional<z.ZodString>;
+    subscriptionName: z.ZodOptional<z.ZodString>;
+    unsubscribeName: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    telemetrySdkVersion: string;
+    applicationName: string;
+    name: string;
+    data?: any;
+    responseName?: string | undefined;
+    subscriptionName?: string | undefined;
+    unsubscribeName?: string | undefined;
+}, {
+    telemetrySdkVersion: string;
+    applicationName: string;
+    name: string;
+    data?: any;
+    responseName?: string | undefined;
+    subscriptionName?: string | undefined;
+    unsubscribeName?: string | undefined;
+}>;

package/dist/client.d.ts

@@ -0,0 +1,293 @@
+import { Applications } from './applications.js';
+import { Media } from './media.js';
+import { Store } from './store.js';
+import { RootSettingsNavigation } from './root-settings-navigation.js';
+import { Accounts } from './accounts.js';
+import { Users } from './users.js';
+/**
+ * The maximum time in milliseconds to wait for a response to a request call.
+ *
+ * When using the request() or subscribe() methods, if no response is received within
+ * this time period, the promise will reject with a timeout error. The default timeout
+ * is 30 seconds (30,000 milliseconds).
+ *
+ * This timeout helps prevent promises from hanging indefinitely if the TelemetryOS
+ * platform doesn't respond or if network connectivity is lost.
+ */
+export declare const requestResponseTimeout: number;
+/**
+ * A callback function type for handling messages received from the TelemetryOS platform.
+ *
+ * Message handlers are registered using the on(), once(), or subscribe() methods and are
+ * invoked when messages of the corresponding type are received. The handler receives
+ * the data payload from the message.
+ *
+ * @template D The type of data expected in the message
+ * @param data The data payload from the received message
+ */
+export type MessageHandler<D> = (data: D) => void;
+export type SubscriptionResult<D = void> = {
+    success: boolean;
+    data: D;
+};
+/**
+ * Client is the core class that powers communication with the TelemetryOS platform.
+ *
+ * This class establishes the communication channel with the TelemetryOS platform
+ * and provides messaging functionality. It manages message sending, request/response
+ * patterns, subscriptions, and event handling.
+ *
+ * For most use cases, you should use the convenience functions exported by the main module
+ * rather than creating your own Client instances.
+ *
+ * Advanced use cases might require direct usage of the Client class, such as
+ * when an application needs to manage multiple independent communication channels.
+ */
+export declare class Client {
+    _applicationName: string;
+    _applicationId: string;
+    _onHandlers: Map<string, MessageHandler<any>[]>;
+    _onceHandlers: Map<string, MessageHandler<any>[]>;
+    _subscriptionNamesByHandler: Map<MessageHandler<any>, string>;
+    _subscriptionNamesBySubjectName: Map<string, string[]>;
+    _windowMessageHandler?: (event: MessageEvent) => void;
+    /**
+     * Creates a new Client instance for communicating with the TelemetryOS platform.
+     *
+     * Note that creating a Client instance alone is not sufficient to begin communication.
+     * You must also call the bind() method to initialize event listeners and extract
+     * the application ID from the URL.
+     *
+     * @param applicationName The name of your application - must match the 'name' property
+     *                        in your application's telemetry.config.json file
+     */
+    constructor(applicationName: string);
+    /**
+     * Provides access to the accounts API for retrieving TelemetryOS account information.
+     *
+     * This property returns a new Accounts instance that allows querying information
+     * about the current TelemetryOS account.
+     *
+     * NOTE: Most application developers should use the global accounts() function
+     * instead of accessing this property directly.
+     *
+     * @returns An Accounts instance bound to this client
+     */
+    get accounts(): Accounts;
+    /**
+     * Provides access to the users API for retrieving TelemetryOS user information.
+     *
+     * This property returns a new Users instance that allows querying information
+     * about the current TelemetryOS user.
+     *
+     * NOTE: Most application developers should use the global users() function
+     * instead of accessing this property directly.
+     *
+     * @returns A Users instance bound to this client
+     */
+    get users(): Users;
+    /**
+     * Provides access to the store API for data persistence with multiple storage scopes.
+     *
+     * This property returns a new Store instance that allows saving, retrieving, and
+     * subscribing to data changes across different scopes (global, local, deviceLocal, shared).
+     *
+     * NOTE: Most application developers should use the global store() function
+     * instead of accessing this property directly.
+     *
+     * @returns A Store instance bound to this client
+     */
+    get store(): Store;
+    /**
+     * Provides access to the applications API for discovering and embedding other TelemetryOS applications.
+     *
+     * This property returns a new Applications instance that allows querying for applications
+     * by name or mount point, and generating URLs for embedding applications in iframes.
+     *
+     * NOTE: Most application developers should use the global applications() function
+     * instead of accessing this property directly.
+     *
+     * @returns An Applications instance bound to this client
+     */
+    get applications(): Applications;
+    /**
+     * Provides access to the media API for working with content hosted on the TelemetryOS platform.
+     *
+     * This property returns a new Media instance that allows applications to browse and access
+     * media content uploaded to TelemetryOS. Applications can query folders, retrieve content,
+     * and access media files.
+     *
+     * NOTE: Most application developers should use the global media() function
+     * instead of accessing this property directly.
+     *
+     * @returns A Media instance bound to this client
+     */
+    get media(): Media;
+    /**
+     * Provides access to the root settings navigation API for TelemetryOS administration UI integration.
+     *
+     * NOTE: This API is not intended for most application developers. It is specifically designed
+     * for root applications that need to integrate with the TelemetryOS administration UI.
+     *
+     * This property returns a new RootSettingsNavigation instance that allows root applications
+     * to register sidebar navigation entries in the TelemetryOS administration UI.
+     *
+     * Most root application developers should use the global rootSettingsNavigation() function
+     * instead of accessing this property directly.
+     *
+     * @returns A RootSettingsNavigation instance bound to this client
+     * @throws {Error} If used by an application not mounted at the 'rootSettingsNavigation' mount point
+     */
+    get rootSettingsNavigation(): RootSettingsNavigation;
+    /**
+     * Initializes the client by setting up message listeners and extracting the application ID.
+     *
+     * This method must be called after creating a Client instance and before using any
+     * of its communication methods. It performs two important tasks:
+     *
+     * 1. Sets up an event listener for window 'message' events to receive messages
+     *    from the TelemetryOS platform
+     * 2. Extracts the application ID from the URL's query parameters
+     *
+     * The application ID is used by several APIs, including the store's local and deviceLocal scopes.
+     *
+     * NOTE: Most application developers should use the global configure() function instead
+     * of creating and binding their own Client instances.
+     */
+    bind(): void;
+    /**
+     * Removes the message event listener and cleans up resources.
+     *
+     * Call this method when you're done with the client to prevent memory leaks
+     * and ensure proper cleanup. After calling unbind(), the client will no longer
+     * receive messages from the TelemetryOS platform.
+     *
+     * Note that this does not cancel any active subscriptions or server-side resources.
+     * You should explicitly unsubscribe from any subscriptions before unbinding.
+     *
+     * NOTE: Most application developers should use the global destroy() function instead
+     * of managing their own Client instances.
+     */
+    unbind(): void;
+    /**
+     * Sends a one-way message to the TelemetryOS platform.
+     *
+     * Use this method for fire-and-forget messages where no response is expected.
+     * The message is sent to the parent window using the postMessage API and includes
+     * metadata such as the SDK version and application name.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * send() function instead of using this method directly.
+     *
+     * @param name The name of the message type to send
+     * @param data The data payload to include with the message
+     */
+    send(name: string, data: any): void;
+    /**
+     * Sends a message to the TelemetryOS platform and waits for a response.
+     *
+     * This method implements a request-response pattern over the postMessage API.
+     * It generates a unique correlation ID and sets up a listener for the response.
+     * If no response is received within the timeout period (30 seconds by default),
+     * the promise will reject.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * request() function instead of using this method directly.
+     *
+     * @template D The expected type of the response data
+     * @param name The name of the message type (endpoint) to request
+     * @param data The data payload to include with the request
+     * @returns A promise that resolves with the response data when received
+     * @throws {Error} If the request times out
+     */
+    request<D>(name: string, data: any): Promise<Awaited<D>>;
+    /**
+     * Sets up a persistent subscription to messages from the TelemetryOS platform.
+     *
+     * This method sends an initial subscription message and registers a handler for
+     * a specific message type. The handler will be called each time a message with the
+     * matching subscription name is received. Unlike the on() method, this establishes
+     * a formal subscription that can be managed with unsubscribe().
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * subscribe() function instead of using this method directly.
+     *
+     * @template D The type of response data in the subscription response
+     * @template S The expected type of the message data
+     * @param name The name of the subscription endpoint
+     * @param data data used in the subscription process
+     * @param handler The callback function that will be invoked when messages are received
+     * @returns A promise that resolves with the subscription result ({success: boolean})
+     * @throws {Error} If the subscription request times out
+     */
+    subscribe<S, D = void>(name: string, handler: MessageHandler<S>): Promise<SubscriptionResult<D>>;
+    subscribe<S, D = void>(name: string, data: any, handler: MessageHandler<S>): Promise<SubscriptionResult<D>>;
+    /**
+     * Cancels a subscription previously created with subscribe().
+     *
+     * This method removes a subscription and stops the handler from receiving messages.
+     * It sends an unsubscribe message to the platform to clean up server-side resources
+     * and removes the local message handler.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * unsubscribe() function instead of using this method directly.
+     *
+     * @template D The expected type of the unsubscribe response data.
+     * @param name The name of the subscription endpoint (same as used in subscribe)
+     * @param key The identifier or parameters for the subscription to cancel
+     * @param handler Optional. The specific handler to unsubscribe. If omitted, all handlers for this key will be unsubscribed.
+     * @returns A promise that resolves with the unsubscribe result ({success: boolean})
+     * @throws {Error} If the unsubscribe request times out
+     */
+    unsubscribe<D = void>(name: string, handler?: MessageHandler<any>): Promise<SubscriptionResult<D>>;
+    unsubscribe<D = void>(name: string, data: any, handler?: MessageHandler<any>): Promise<SubscriptionResult<D>>;
+    /**
+     * Registers a handler function for a specific message type.
+     *
+     * The handler will be called each time a message with the specified name is received.
+     * You can register multiple handlers for the same message type, and all will be executed
+     * when that message is received.
+     *
+     * Unlike subscribe(), this method only sets up a local event listener and doesn't
+     * notify the platform of your interest in a particular message type.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * on() function instead of using this method directly.
+     *
+     * @template T The expected type of the message data
+     * @param name The name of the message type to listen for
+     * @param handler The callback function to execute when messages are received
+     */
+    on<T>(name: string, handler: MessageHandler<T>): void;
+    /**
+     * Registers a one-time handler for a specific message type.
+     *
+     * Similar to the on() method, but the handler will be automatically removed
+     * after it is called once. This is useful for initialization events or operations
+     * that should only happen once in response to a particular message.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * once() function instead of using this method directly.
+     *
+     * @template T The expected type of the message data
+     * @param name The name of the message type to listen for
+     * @param handler The callback function to execute when the message is received
+     */
+    once<T>(name: string, handler: MessageHandler<T>): void;
+    /**
+     * Removes previously registered message handlers.
+     *
+     * Use this method to stop receiving messages of a specific type or to remove
+     * specific handler functions when they're no longer needed. This applies to
+     * handlers registered with both on() and once() methods.
+     *
+     * NOTE: Most application developers should use the resource-specific APIs or the global
+     * off() function instead of using this method directly.
+     *
+     * @template T The expected type of the message data
+     * @param name The name of the message type to stop listening for
+     * @param handler Optional. The specific handler function to remove. If omitted,
+     *                all handlers for this message type will be removed.
+     */
+    off<T>(name: string, handler?: MessageHandler<T>): void;
+}

package/dist/client.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/do-async.d.ts

@@ -0,0 +1 @@
+export declare function doAsync(fn: () => Promise<void>, onRejected?: (err: any) => void): void;

package/dist/environment.d.ts

@@ -0,0 +1,10 @@
+import { Client } from './index.js';
+type ColorScheme = 'light' | 'dark' | 'system';
+export declare class Environment {
+    _client: Client;
+    constructor(client: Client);
+    getColorScheme(): Promise<ColorScheme>;
+    subscribeColorScheme(handler: (colorScheme: ColorScheme) => void): void;
+    unsubscribeColorScheme(handler: (colorScheme: ColorScheme) => void): void;
+}
+export {};