@horizonmedia/blu-sdk 0.0.0-stage → 1.8.4

package/types/frame.d.ts

@@ -0,0 +1,139 @@
+import { ComponentType } from 'react';
+
+interface BluUser {
+    id: string;
+    email: string;
+    displayName: string;
+    provider: string;
+}
+interface BluClient {
+    id: string;
+    name: string;
+}
+interface BluEnvironment {
+    /** The deployment stage of whatever is hosting the module (local | dev | staging | prod). */
+    stage: string;
+    /**
+     * This module's OWN backend for that stage — resolved by the host from the
+     * registry (or by the standalone harness from its deployment config). Modules
+     * call this; they never build URLs from `stage` themselves.
+     */
+    apiBaseUrl: string;
+    moduleId: string;
+}
+/** Who is hosting the module right now. Added in 1.1 (optional: additive, no major bump). */
+interface BluShellInfo {
+    kind: "blu-shell" | "standalone";
+    /** e.g. "Blu shell (embedded in IFrame Host)" or "Team A standalone app". */
+    label: string;
+    /** Who chose the active client: the embedder (IFrame Host), the Blu shell, or the standalone app. */
+    clientChosenBy: "iframe-host" | "blu-shell" | "standalone";
+    /**
+     * How this module is mounted (1.2, optional): "inline" in the Blu page (Module
+     * Federation), "isolated" in its own sandboxed frame, or "standalone".
+     */
+    mount?: "inline" | "isolated" | "standalone";
+}
+/**
+ * Where the user is INSIDE this module (1.3, optional). Paths are
+ * module-relative ("/campaigns/acme-2"); the host maps them under the module's
+ * nav path, keeps the address bar and back button in sync, and opens them from
+ * links (e.g. in the Concierge's answers). Declare linkable ones in
+ * blu.module.json `routes`.
+ */
+interface BluRoute {
+    path: string;
+    /** The query string, with its "?" ("" when none). Since 1.5. */
+    search?: string;
+    /**
+     * Go to a module-relative path, optionally with a query ("/campaigns?status=Live"),
+     * or change only the query ("?status=Live"). `replace` rewrites the current
+     * history entry instead of adding one (e.g. a filter kept in the URL). Since 1.5.
+     */
+    navigate(path: string, opts?: {
+        replace?: boolean;
+    }): void;
+}
+interface BluTheme {
+    primary: string;
+    surface: string;
+    surfaceAlt: string;
+    text: string;
+    textMuted: string;
+    border: string;
+    danger: string;
+    success: string;
+    radius: string;
+    font: string;
+}
+interface BluEvent {
+    type: string;
+    source: string;
+    payload: unknown;
+    at: string;
+}
+interface EventBus {
+    emit(type: string, payload?: unknown): void;
+    on(type: string | "*", handler: (event: BluEvent) => void): () => void;
+}
+interface HostContextValue {
+    contractVersion: string;
+    user: BluUser;
+    client: BluClient;
+    roles: string[];
+    environment: BluEnvironment;
+    theme: BluTheme;
+    embedded: {
+        inIframe: boolean;
+        parentOrigin: string | null;
+    };
+    shell?: BluShellInfo;
+    route?: BluRoute;
+    /**
+     * Always returns a non-expired Blu token for THIS module's API only (audience
+     * `blu-module:<moduleId>`): useless at Blu or at any other module's API.
+     * The host refreshes behind this.
+     */
+    getToken(): Promise<string>;
+    navigate(path: string): void;
+    events: EventBus;
+}
+
+declare function mountIsolated({ Page, rootId }: {
+    Page: ComponentType;
+    rootId?: string;
+}): Promise<void>;
+/**
+ * The bridge on its own, for apps that render their own root and router (e.g. a
+ * Next.js app mounted isolated with `frame.routing: "url"`): you get the same
+ * HostContextValue the hooks provide, and `reportRoute()` to keep Blu's
+ * address bar in step with your router. mountIsolated() uses it too.
+ */
+declare function connectToBluShell(hostOrigins: Set<string> | string[]): {
+    /**
+     * The app moved (its own router): Blu updates its URL. Pass `replace: true`
+     * when your router already added a browser-history entry (it did, if it uses
+     * pushState) — then Blu replaces its URL instead of adding a second entry, and
+     * the back button steps once.
+     */
+    reportRoute(path: string, opts?: {
+        replace?: boolean;
+    }): void;
+    onContext(l: (c: HostContextValue) => void): () => any;
+};
+type BluShellConnection = ReturnType<typeof createBridge>;
+declare function createBridge(hostOrigins: Set<string>): {
+    /**
+     * The app moved (its own router): Blu updates its URL. Pass `replace: true`
+     * when your router already added a browser-history entry (it did, if it uses
+     * pushState) — then Blu replaces its URL instead of adding a second entry, and
+     * the back button steps once.
+     */
+    reportRoute(path: string, opts?: {
+        replace?: boolean;
+    }): void;
+    onContext(l: (c: HostContextValue) => void): () => any;
+};
+
+export { connectToBluShell, mountIsolated };
+export type { BluShellConnection };

package/types/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * "Sign in with Blu" for a browser app — OAuth 2.1 authorization code + PKCE.
+ *
+ * Used by the Blu shell (client "blu-host") and by every module's standalone
+ * app (client = the module id). The person signs in on Blu's own page, never
+ * inside the calling app, and Blu only sends them back to a redirect address
+ * that client registered. What comes back is a token for THAT client only.
+ *
+ * The one-time PKCE verifier and state live in sessionStorage between the
+ * redirect out and the redirect back (same tab, same origin); tokens never do.
+ */
+interface BluTokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    refresh_token?: string;
+    /** Clients this token may switch between, with display names (module tokens only). */
+    blu_clients?: {
+        id: string;
+        name: string;
+    }[];
+    authz_version?: number;
+}
+type BluSignInResult = {
+    kind: "none";
+} | {
+    kind: "error";
+    error: string;
+    description: string;
+} | {
+    kind: "signed-in";
+    tokens: BluTokenResponse;
+    hostApi: string;
+};
+/** Leave for Blu's sign-in page. `redirectUri` must exactly match one the client registered. */
+declare function beginBluSignIn({ hostApi, clientId, redirectUri }: {
+    hostApi: string;
+    clientId: string;
+    redirectUri: string;
+}): Promise<void>;
+/**
+ * Finish a sign-in if this page load is Blu's redirect back. Safe to call more
+ * than once per page load (React StrictMode): the work happens once.
+ */
+declare function completeBluSignIn(): Promise<BluSignInResult>;
+
+interface BluUser {
+    id: string;
+    email: string;
+    displayName: string;
+    provider: string;
+}
+interface BluClient {
+    id: string;
+    name: string;
+}
+interface BluEnvironment {
+    /** The deployment stage of whatever is hosting the module (local | dev | staging | prod). */
+    stage: string;
+    /**
+     * This module's OWN backend for that stage — resolved by the host from the
+     * registry (or by the standalone harness from its deployment config). Modules
+     * call this; they never build URLs from `stage` themselves.
+     */
+    apiBaseUrl: string;
+    moduleId: string;
+}
+/** Who is hosting the module right now. Added in 1.1 (optional: additive, no major bump). */
+interface BluShellInfo {
+    kind: "blu-shell" | "standalone";
+    /** e.g. "Blu shell (embedded in IFrame Host)" or "Team A standalone app". */
+    label: string;
+    /** Who chose the active client: the embedder (IFrame Host), the Blu shell, or the standalone app. */
+    clientChosenBy: "iframe-host" | "blu-shell" | "standalone";
+    /**
+     * How this module is mounted (1.2, optional): "inline" in the Blu page (Module
+     * Federation), "isolated" in its own sandboxed frame, or "standalone".
+     */
+    mount?: "inline" | "isolated" | "standalone";
+}
+/**
+ * Where the user is INSIDE this module (1.3, optional). Paths are
+ * module-relative ("/campaigns/acme-2"); the host maps them under the module's
+ * nav path, keeps the address bar and back button in sync, and opens them from
+ * links (e.g. in the Concierge's answers). Declare linkable ones in
+ * blu.module.json `routes`.
+ */
+interface BluRoute {
+    path: string;
+    /** The query string, with its "?" ("" when none). Since 1.5. */
+    search?: string;
+    /**
+     * Go to a module-relative path, optionally with a query ("/campaigns?status=Live"),
+     * or change only the query ("?status=Live"). `replace` rewrites the current
+     * history entry instead of adding one (e.g. a filter kept in the URL). Since 1.5.
+     */
+    navigate(path: string, opts?: {
+        replace?: boolean;
+    }): void;
+}
+interface BluTheme {
+    primary: string;
+    surface: string;
+    surfaceAlt: string;
+    text: string;
+    textMuted: string;
+    border: string;
+    danger: string;
+    success: string;
+    radius: string;
+    font: string;
+}
+interface BluEvent {
+    type: string;
+    source: string;
+    payload: unknown;
+    at: string;
+}
+interface EventBus {
+    emit(type: string, payload?: unknown): void;
+    on(type: string | "*", handler: (event: BluEvent) => void): () => void;
+}
+interface HostContextValue {
+    contractVersion: string;
+    user: BluUser;
+    client: BluClient;
+    roles: string[];
+    environment: BluEnvironment;
+    theme: BluTheme;
+    embedded: {
+        inIframe: boolean;
+        parentOrigin: string | null;
+    };
+    shell?: BluShellInfo;
+    route?: BluRoute;
+    /**
+     * Always returns a non-expired Blu token for THIS module's API only (audience
+     * `blu-module:<moduleId>`): useless at Blu or at any other module's API.
+     * The host refreshes behind this.
+     */
+    getToken(): Promise<string>;
+    navigate(path: string): void;
+    events: EventBus;
+}
+declare function useHost(): HostContextValue;
+/**
+ * The host context if this code is running inside a Blu host, otherwise null —
+ * for components shared with an app that also runs on its own (e.g. a team's
+ * client switcher: render nothing inside Blu, because Blu chose the client).
+ */
+declare function useOptionalHost(): HostContextValue | null;
+declare const useUser: () => BluUser;
+declare const useClient: () => BluClient;
+declare const useRoles: () => string[];
+declare const useEnvironment: () => BluEnvironment;
+declare const useTheme: () => BluTheme;
+declare const useEventBus: () => EventBus;
+declare const useShell: () => BluShellInfo;
+declare const useAuthToken: () => () => Promise<string>;
+/** The module-relative route; a host older than 1.3 gives "/" and ignores navigation. */
+declare const useRoute: () => BluRoute;
+declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    url: string;
+    constructor(status: number, body: unknown, url: string);
+}
+interface ApiClient {
+    baseUrl: string;
+    get<T = unknown>(path: string, init?: RequestInit): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, init?: RequestInit): Promise<T>;
+}
+declare function useApiClient(): ApiClient;
+
+export { ApiError, beginBluSignIn, completeBluSignIn, useApiClient, useAuthToken, useClient, useEnvironment, useEventBus, useHost, useOptionalHost, useRoles, useRoute, useShell, useTheme, useUser };
+export type { ApiClient, BluClient, BluEnvironment, BluEvent, BluRoute, BluShellInfo, BluSignInResult, BluTheme, BluTokenResponse, BluUser, EventBus };