@bloomscorp/blooms-ai-embed 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Type declarations for `@bloomscorp/blooms-ai-embed`.
+ *
+ * Hand-written to mirror the runtime exactly (the bundle ships no declarations
+ * of its own). Kept in step with, in the blooms.ai repo:
+ *   client/src/app/core/embed/embed-config.ts        — config, modes, storage
+ *   client/src/app/core/embed/embed-session.store.ts — session, user, events
+ *   client/src/app/core/embed/embed-api.client.ts    — manifest
+ *   client/src/app/core/embed/blooms-embed.api.ts    — the SDK surface
+ */
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+/** The resolved rendering mode. `mode()` never reports `'auto'`. */
+export type EmbedMode = 'element' | 'iframe';
+
+/** What `configure()` accepts for `mode`. `'auto'` is the default. */
+export type EmbedModeSetting = EmbedMode | 'auto';
+
+/** Where the session is kept between page loads. */
+export type EmbedStorage = 'local' | 'session' | 'memory';
+
+export interface BloomsEmbedConfig {
+  /** The publishable project embed token: `blm_embed_…`. Required. */
+  token: string;
+  /** Absolute origin of the blooms.ai API. Derived from the bundle URL when omitted. */
+  apiBase?: string;
+  /**
+   * Absolute URL of the DIRECTORY holding `blooms-embed.css`, used to load the
+   * shared stylesheet that is adopted into each component's shadow root.
+   *
+   * Defaults to the directory the bundle's own JavaScript was served from, which
+   * is correct when you load the bundle from blooms.ai. When you install from npm
+   * your bundler inlines the bundle into your own output, so the default resolves
+   * to YOUR build directory — where the stylesheet is not. Copy
+   * `blooms-embed.css` somewhere your app serves and name that directory here.
+   */
+  assetBase?: string;
+  /** Where the session is kept. Default `'local'`. */
+  storage?: EmbedStorage;
+  /** Rendering mode. Default `'auto'`. */
+  mode?: EmbedModeSetting;
+  /** CSS custom properties applied to each element's shadow root. */
+  theme?: Record<string, string>;
+  /**
+   * Set by the iframe shell only, never by a host: the parent dashboard's origin
+   * as verified server-side, forwarded so the audit trail names the dashboard the
+   * user was working in.
+   */
+  parentOrigin?: string | null;
+}
+
+/**
+ * A config after defaulting and auto-detection. Returned by nothing on the
+ * public surface today; exported because it is the shape the SDK works with
+ * internally and hosts occasionally want to name it.
+ */
+export interface ResolvedEmbedConfig extends Required<Omit<BloomsEmbedConfig, 'theme'>> {
+  theme: Record<string, string>;
+  mode: EmbedMode;
+}
+
+// ── Session ─────────────────────────────────────────────────────────────────
+
+export interface EmbedUser {
+  id: string;
+  name: string;
+  email: string;
+  avatar: string | null;
+}
+
+export interface EmbedProject {
+  id: string;
+  name: string;
+}
+
+/**
+ * One project a session may act on, with what the signed-in user can do in it.
+ *
+ * `grantedKeys` has already been intersected with the integration's ceiling by
+ * the server, so it is exactly what this user may use in this project — grants
+ * differ per project, which is why they are listed per entry rather than once.
+ */
+export interface EmbedProjectAccess extends EmbedProject {
+  grantedKeys: string[];
+  isOwner: boolean;
+}
+
+export interface EmbedSessionState {
+  /** Access token. Sent by the elements automatically; hosts rarely need it. */
+  token: string;
+  refreshToken: string;
+  /** Epoch ms at which the access token expires. */
+  expiresAt: number;
+  user: EmbedUser;
+  project: EmbedProject;
+  /** Feature keys this user may use in the ACTIVE project, already intersected with the token's ceiling. */
+  grantedKeys: string[];
+  isProjectOwner: boolean;
+  /**
+   * Every project this integration authorizes AND the user can reach, each with
+   * its own grants. One entry for a single-project integration.
+   *
+   * Optional because a session persisted by an older bundle will not have it;
+   * readers fall back to a one-entry list built from `project`.
+   */
+  projects?: EmbedProjectAccess[];
+}
+
+// ── Events ──────────────────────────────────────────────────────────────────
+
+/** Sign-in, refresh, sign-out and expiry. `session` is `null` when signed out. */
+export interface EmbedSessionEvent {
+  type: 'session';
+  session: EmbedSessionState | null;
+  mode: EmbedMode;
+}
+
+/** A failure worth surfacing to the host, e.g. `EMBED_TOKEN_REVOKED`. */
+export interface EmbedErrorEvent {
+  type: 'error';
+  code: string;
+  message: string;
+  status?: number;
+}
+
+/** A component asking the host to move somewhere, for hosts that mirror state in their own URL. */
+export interface EmbedNavigateEvent {
+  type: 'navigate';
+  feature: string;
+  view: string;
+  params: Record<string, unknown>;
+}
+
+export type EmbedEvent = EmbedSessionEvent | EmbedErrorEvent | EmbedNavigateEvent;
+
+// ── Manifest ────────────────────────────────────────────────────────────────
+
+/** Pre-login bootstrap: project name, enabled features, theme, branding. */
+export interface EmbedManifest {
+  /** The primary project. Equal to `projects[0]` for a multi-project integration. */
+  project: { id: string; name: string };
+  /**
+   * Every project this integration declares, names only.
+   *
+   * Pre-login, so this is the integration's declared SCOPE, not anything the
+   * caller is entitled to — which of these a given user can actually reach is
+   * decided at login and reported as `session.projects`.
+   */
+  projects: Array<{ id: string; name: string }>;
+  /** The integration's feature ceiling. Empty means "whatever the user already has". */
+  features: string[];
+  theme: Record<string, string>;
+  hideBranding: boolean;
+  sessionTtlMinutes: number;
+  /** Where to send someone who cannot sign in — opens the blooms.ai portal. */
+  portalUrl: string;
+}
+
+// ── SDK ─────────────────────────────────────────────────────────────────────
+
+export interface MountOptions {
+  /** Which component to mount, e.g. `'login'` for `<blooms-login>`. */
+  feature: string;
+  /** Initial height in px before the frame reports its own. Iframe mode only. */
+  minHeight?: number;
+  /** Extra attributes for the created element or iframe (`title`, `class`, ...). */
+  attributes?: Record<string, string>;
+}
+
+/** Handle returned by `mount()` in iframe mode. */
+export interface MountedFrame {
+  readonly iframe: HTMLIFrameElement;
+  /** Push the current session into the frame. Done automatically on handshake. */
+  sync(): void;
+  destroy(): void;
+}
+
+export interface BloomsEmbedSdk {
+  readonly version: string;
+  /** Must be called once, before anything else. Throws on a missing or non-`blm_embed_` token. */
+  configure(config: BloomsEmbedConfig): void;
+  /** The resolved rendering mode, after auto-detection. `null` before `configure()`. */
+  mode(): EmbedMode | null;
+  manifest(): Promise<EmbedManifest>;
+  login(credentials: { email: string; password: string }): Promise<EmbedSessionState>;
+  /** Current session, or `null`. Restored from storage by `configure()`. */
+  session(): EmbedSessionState | null;
+  /** Revalidate a restored session against the server and re-read permissions. */
+  resume(): Promise<EmbedSessionState | null>;
+  /**
+   * Can the signed-in user use a feature? Defaults to the active project; pass
+   * `projectId` to ask about another project the integration authorizes, since
+   * grants differ per project.
+   *
+   * Returns `false` for a project the session cannot act on — it does NOT fall
+   * back to the active project's grants.
+   *
+   * A UI convenience only: the server re-authorizes every request.
+   */
+  can(featureKey: string, projectId?: string): boolean;
+  /** Every project this session can act on, each with its own grants. */
+  projects(): EmbedProjectAccess[];
+  /** The active project, or `null` when not signed in. */
+  project(): EmbedProject | null;
+  /**
+   * Switch the active project. Local and instant — the session already covers
+   * every project `projects()` lists, so there is no round trip and no
+   * re-authentication. Returns `false` if the session cannot act on it.
+   *
+   * Emits a `session` event, so an `on('session', …)` listener re-renders on a
+   * switch without a separate subscription.
+   */
+  setProject(projectId: string): boolean;
+  logout(): Promise<void>;
+  /** Subscribe. Returns an unsubscribe function. */
+  on(event: EmbedEvent['type'] | 'all', handler: (event: EmbedEvent) => void): () => void;
+  /**
+   * Render a component into `target`.
+   *
+   * Element mode creates the custom element and returns it. Iframe mode creates
+   * the frame, drives the postMessage bridge, and returns a `MountedFrame`. The
+   * call is the same either way — the mode is resolved by `configure()`.
+   */
+  mount(target: HTMLElement | string, options: MountOptions): MountedFrame | HTMLElement;
+}
+
+/**
+ * The SDK. Importing this package defines the custom elements and installs the
+ * same object on `window.BloomsEmbed`.
+ */
+export const BloomsEmbed: BloomsEmbedSdk;
+
+// ── Elements ────────────────────────────────────────────────────────────────
+
+/**
+ * `<blooms-login>`.
+ *
+ * The three inputs are also settable as attributes, but attribute values arrive
+ * as strings — `compact="false"` is a non-empty string and therefore truthy, so
+ * set `compact` as a property (`el.compact = true`) or leave the attribute off.
+ */
+export interface BloomsLoginElement extends HTMLElement {
+  /** Overrides the default heading copy. */
+  heading: string;
+  /** Overrides the default subheading copy ("Continue to <project>"). */
+  subheading: string;
+  /** Render without the card chrome, for placing inside an existing panel. */
+  compact: boolean;
+
+  addEventListener(
+    type: 'bloomssession',
+    listener: (event: CustomEvent<EmbedSessionState | null>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: 'bloomserror',
+    listener: (event: CustomEvent<EmbedErrorEvent>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: HTMLElement, event: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
+
+declare global {
+  interface Window {
+    /** Installed by the bundle as it evaluates, i.e. by importing this package. */
+    BloomsEmbed: BloomsEmbedSdk;
+    /** Double-load marker set by the bundle. Internal; read it only to detect a duplicate include. */
+    __BLOOMS_EMBED_VERSION__?: string;
+  }
+
+  interface HTMLElementTagNameMap {
+    'blooms-login': BloomsLoginElement;
+  }
+}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * `@bloomscorp/blooms-ai-embed` — the blooms.ai embeddable web components.
+ *
+ * Importing this module has two effects:
+ *   1. it defines the custom elements (`<blooms-login>`, …) on the page, and
+ *   2. it installs and re-exports the `BloomsEmbed` SDK object.
+ *
+ * Both come from the prebuilt bundle, which self-registers when it evaluates.
+ * This entry deliberately adds no behaviour of its own — the bundle is the
+ * single implementation, shared with the CDN-hosted bundle at
+ * https://embed-ai.bloomscorp.com/v1/blooms-embed.js.
+ */
+
+// Must stay first: it fails loudly outside a browser before the bundle runs.
+import './browser-guard.js';
+// Side-effect import: defines the custom elements and sets window.BloomsEmbed.
+import './blooms-embed.js';
+
+const sdk = /** @type {any} */ (window).BloomsEmbed;
+
+if (!sdk) {
+  throw new Error(
+    '[BloomsEmbed] The bundle loaded but did not install window.BloomsEmbed. ' +
+      'This usually means a second, incompatible copy of the embed bundle was already on the page ' +
+      '(check for a <script src="https://embed-ai.bloomscorp.com/v1/blooms-embed.js"> alongside '
+      + 'this package — include it once, either way, never both).',
+  );
+}
+
+/**
+ * The SDK object. Read from `window` on purpose: if a page somehow ends up with
+ * two copies of the bundle, the first one wins and everybody shares its session
+ * store instead of two stores fighting over the same storage key.
+ *
+ * @type {import('./index.d.ts').BloomsEmbedSdk}
+ */
+export const BloomsEmbed = sdk;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@bloomscorp/blooms-ai-embed",
+  "version": "0.1.0",
+  "description": "blooms.ai embeddable web components \u2014 prebuilt bundle and typed JS SDK for host dashboards, including Electron.",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "sideEffects": true,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./blooms-embed.css": "./dist/blooms-embed.css",
+    "./blooms-embed.js": "./dist/blooms-embed.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/browser-guard.js",
+    "dist/blooms-embed.js",
+    "dist/blooms-embed.css",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs --skip-client-build"
+  },
+  "keywords": [
+    "blooms",
+    "embed",
+    "web-components",
+    "custom-elements",
+    "analytics",
+    "electron"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bloomscorp/blooms-ai.git",
+    "directory": "embed-sdk"
+  },
+  "homepage": "https://github.com/bloomscorp/blooms-ai/tree/master/embed-sdk#readme"
+}