npm - @onaio/akuko-embed-sdk - Versions diffs - 0.1.0 - Mend

@onaio/akuko-embed-sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/LICENSE +201 -0
package/README.md +204 -0
package/dist/AkukoDashboard.d.ts +116 -0
package/dist/PostMessageBridge.d.ts +18 -0
package/dist/akuko-embed-sdk.js +210 -0
package/dist/akuko-embed-sdk.umd.cjs +1 -0
package/dist/index.d.ts +5 -0
package/dist/types.d.ts +205 -0
package/docs/host-recipes.md +134 -0
package/docs/sso-path-d-brokering.md +156 -0
package/examples/keycloak-path-d-setup.sh +173 -0
package/package.json +43 -0

package/dist/akuko-embed-sdk.js ADDED Viewed

@@ -0,0 +1,210 @@
+class d {
+  constructor(t, e) {
+    this.iframe = t, this.expectedOrigin = e, this.handlers = /* @__PURE__ */ new Map(), this.onMessage = (i) => {
+      if (i.origin !== this.expectedOrigin || i.source && i.source !== this.iframe.contentWindow) return;
+      const s = i.data;
+      if (!s || s.version !== 1 || !s.type?.startsWith("akuko:")) return;
+      const a = this.handlers.get(s.type);
+      a && a.forEach((o) => o(s.payload));
+    }, window.addEventListener("message", this.onMessage);
+  }
+  on(t, e) {
+    this.handlers.has(t) || this.handlers.set(t, /* @__PURE__ */ new Set()), this.handlers.get(t).add(e);
+  }
+  off(t, e) {
+    this.handlers.get(t)?.delete(e);
+  }
+  send(t, e) {
+    if (!t.startsWith("akuko:")) throw new Error("Type must start with 'akuko:'");
+    const i = {
+      type: t,
+      payload: e,
+      messageId: crypto.randomUUID(),
+      version: 1
+    };
+    this.iframe.contentWindow?.postMessage(i, this.expectedOrigin);
+  }
+  destroy() {
+    window.removeEventListener("message", this.onMessage), this.handlers.clear();
+  }
+}
+class n {
+  constructor(t) {
+    if (this.opts = t, this.localListeners = /* @__PURE__ */ new Map(), this.loadWatchdog = null, this.container = typeof t.container == "string" ? document.querySelector(t.container) : t.container, !this.container)
+      throw new Error(`Container not found: ${String(t.container)}`);
+    if ([
+      t.onadataOrgId,
+      t.onadataProjectId,
+      t.onadataFormId,
+      t.spaceUuid,
+      t.dashboardId,
+      t.linkProjectsOrgId
+    ].filter(Boolean).length !== 1)
+      throw new Error(
+        "AkukoDashboard: must pass exactly one of onadataOrgId, onadataProjectId, onadataFormId, spaceUuid, dashboardId, linkProjectsOrgId"
+      );
+    this.baseUrl = t.baseUrl ?? "https://akuko.io", this.lastHostUser = this.opts.hostUser, this.iframe = this.createIframe(), this.container.appendChild(this.iframe);
+    const i = this.opts.allowedOrigin ?? new URL(this.baseUrl).origin;
+    this.bridge = new d(this.iframe, i), this.bridge.on("akuko:resize", (s) => {
+      if (this.opts.layout === "fill") return;
+      const a = s;
+      typeof a.height == "number" && (this.iframe.style.height = `${a.height}px`);
+    }), this.bridge.on("akuko:ready", () => this.replayState()), this.startLoadWatchdog();
+  }
+  startLoadWatchdog() {
+    const t = this.opts.iframeLoadTimeoutMs ?? 3e4;
+    t <= 0 || (this.loadWatchdog = setTimeout(() => {
+      this.loadWatchdog = null, this.emitLocal("akuko:error", { code: "IFRAME_LOAD_FAILED" });
+    }, t), this.iframe.addEventListener(
+      "load",
+      () => {
+        this.loadWatchdog && (clearTimeout(this.loadWatchdog), this.loadWatchdog = null);
+      },
+      { once: !0 }
+    ));
+  }
+  createIframe() {
+    const t = document.createElement("iframe");
+    return t.style.width = "100%", t.style.border = "0", this.opts.layout === "fill" ? (t.style.flex = "1 1 0%", t.style.minHeight = "0") : (t.style.height = "600px", this.opts.minHeight != null && (t.style.minHeight = typeof this.opts.minHeight == "number" ? `${this.opts.minHeight}px` : this.opts.minHeight)), t.setAttribute(
+      "sandbox",
+      this.opts.sandbox ?? // allow-downloads: the export feature triggers PNG (blob) and PDF
+      // (render-URL) downloads from inside the iframe; a sandbox without it
+      // silently blocks them.
+      "allow-scripts allow-same-origin allow-popups allow-forms allow-downloads"
+    ), t.setAttribute("allow", "fullscreen; clipboard-write"), t.src = this.computeInitialUrl(), t;
+  }
+  computeInitialUrl() {
+    const t = this.opts;
+    return t.dashboardId ? `${this.baseUrl}/embed/post/${t.dashboardId}${this.queryString()}` : t.spaceUuid ? `${this.baseUrl}/embed/space/${t.spaceUuid}${this.queryString()}` : t.onadataOrgId ? `${this.baseUrl}/embed/resolve/onadata-org/${t.onadataOrgId}${this.queryString()}` : t.onadataProjectId ? `${this.baseUrl}/embed/resolve/onadata-project/${t.onadataProjectId}${this.queryString()}` : t.onadataFormId ? `${this.baseUrl}/embed/resolve/onadata-form/${t.onadataFormId}${this.queryString()}` : t.linkProjectsOrgId ? `${this.baseUrl}/embed/link-projects/onadata-org/${t.linkProjectsOrgId}${this.queryString()}` : `${this.baseUrl}/embed/loading${this.queryString()}`;
+  }
+  queryString() {
+    const t = new URLSearchParams();
+    return this.opts.idpHint && t.set("idp_hint", this.opts.idpHint), this.opts.layout && t.set("layout", this.opts.layout), this.opts.hostIsAdmin && t.set("host_admin", "1"), this.opts.initialPostId && t.set("post", this.opts.initialPostId), this.opts.resolveOnadataOrgId && t.set("onadata_org_id", this.opts.resolveOnadataOrgId), this.opts.resolveOnadataProjectId && t.set("onadata_project_id", this.opts.resolveOnadataProjectId), this.opts.theme?.primary && t.set("theme_primary", this.opts.theme.primary), t.toString() ? `?${t.toString()}` : "";
+  }
+  on(t, e) {
+    this.bridge.on(t, e);
+    let i = this.localListeners.get(t);
+    i || (i = /* @__PURE__ */ new Set(), this.localListeners.set(t, i)), i.add(e);
+  }
+  off(t, e) {
+    this.bridge.off(t, e), this.localListeners.get(t)?.delete(e);
+  }
+  /**
+   * Dispatch an event originated host-side (e.g. the iframe load watchdog) to
+   * any subscribers registered via on(). The bridge is unaffected — its
+   * handlers only fire on iframe → host messages. Note: akuko:resolved now
+   * arrives from the iframe over the bridge (the iframe owns resolve), so
+   * on('akuko:resolved') keeps working without a host-side emit.
+   */
+  emitLocal(t, e) {
+    this.localListeners.get(t)?.forEach((i) => i(e));
+  }
+  replayState() {
+    this.lastTheme && this.bridge.send("akuko:setTheme", this.lastTheme), this.lastVisibility && this.bridge.send("akuko:setVisibility", this.lastVisibility), this.lastFilters && this.bridge.send("akuko:setFilters", this.lastFilters), this.lastHostUser && this.bridge.send("akuko:setHostIdentity", this.lastHostUser), this.lastViewport && this.bridge.send("akuko:viewport", this.lastViewport);
+  }
+  /** Apply a theme to the embedded dashboard. */
+  setTheme(t) {
+    this.lastTheme = t, this.bridge.send("akuko:setTheme", t);
+  }
+  /** Show or hide dashboard UI chrome (header, footer, filter bar, etc.). */
+  setVisibility(t) {
+    this.lastVisibility = t, this.bridge.send("akuko:setVisibility", t);
+  }
+  /**
+   * Report the iframe's currently-visible vertical band (host→iframe), so
+   * in-iframe floating UI can center itself in view even when the host page owns
+   * the scrollbar (`layout: "content"`). The React wrapper computes and pushes
+   * this automatically on scroll/resize; hosts using the vanilla SDK can call it
+   * directly.
+   */
+  setViewport(t) {
+    this.lastViewport = t, this.bridge.send("akuko:viewport", t);
+  }
+  /** Push filter values into the embedded dashboard. */
+  setFilters(t) {
+    this.lastFilters = t, this.bridge.send("akuko:setFilters", t);
+  }
+  /**
+   * Clear specific filter keys, or all filters when called with no arguments.
+   * @param keys - Optional list of filter keys to clear. Omit to clear all.
+   */
+  clearFilters(t) {
+    this.bridge.send("akuko:clearFilters", { keys: t });
+  }
+  /** Ask the embedded dashboard to reload its data. */
+  refresh() {
+    this.bridge.send("akuko:refresh", {});
+  }
+  /**
+   * Navigate the iframe to the org's onboarding / project-picker URL so
+   * an admin can link more projects to an already-linked org. Throws when
+   * the SDK was constructed without `onadataOrgId` — the call has no
+   * unambiguous org context to act on.
+   */
+  linkProjects() {
+    if (!this.opts.onadataOrgId)
+      throw new Error(
+        "linkProjects() requires the SDK to be constructed with onadataOrgId"
+      );
+    this.bridge.send("akuko:linkProjects", {
+      onadataOrgId: this.opts.onadataOrgId
+    });
+  }
+  /**
+   * Request the current state of the embedded dashboard.
+   * The response arrives via the `akuko:stateResponse` event on the bridge.
+   */
+  getState() {
+    this.bridge.send("akuko:getState", {});
+  }
+  /**
+   * Trigger a background re-sync of Onadata members into the linked Akuko
+   * space or folder.
+   *
+   * The backend derives `account_id`/`space_id`/`onadata_org_slug` (and
+   * `folder_id` for project scope) from the authenticated user's session
+   * when those fields aren't passed explicitly. Hosts that need to override
+   * the derivation may supply them on `opts`. Progress events arrive via
+   * `akuko:provisioningStatus` on the bridge.
+   */
+  async resyncMembers(t) {
+    const e = t.scope === "org" ? {
+      scope: "org",
+      onadata_org_id: this.opts.onadataOrgId,
+      ...t.account_id ? { account_id: t.account_id } : {},
+      ...t.space_id ? { space_id: t.space_id } : {},
+      ...t.onadata_org_slug ? { onadata_org_slug: t.onadata_org_slug } : {}
+    } : {
+      scope: "project",
+      onadata_project_id: t.onadata_project_id,
+      ...t.account_id ? { account_id: t.account_id } : {},
+      ...t.space_id ? { space_id: t.space_id } : {},
+      ...t.folder_id ? { folder_id: t.folder_id } : {}
+    };
+    return this.bridge.send("akuko:resyncMembers", e), Promise.resolve({ workflow_id: "" });
+  }
+  /**
+   * Tear down the embedded akuko session: asks the in-iframe akuko app to run
+   * an RP-initiated end-session (clears akuko.io localStorage tokens AND ends
+   * the akuko-keycloak SSO session), then resolves on the iframe's
+   * `akuko:logoutComplete` acknowledgement — or after `logoutTimeoutMs`
+   * (default 2000ms), whichever comes first. Never rejects; never hangs, so a
+   * host can `await dashboard.logout()` in its own logout path safely.
+   */
+  logout() {
+    return new Promise((t) => {
+      let e = !1;
+      const i = () => {
+        e || (e = !0, clearTimeout(a), this.bridge.off("akuko:logoutComplete", s), t());
+      }, s = () => i(), a = setTimeout(i, this.opts.logoutTimeoutMs ?? 2e3);
+      this.bridge.on("akuko:logoutComplete", s), this.bridge.send("akuko:logout", {});
+    });
+  }
+  destroy() {
+    this.loadWatchdog && (clearTimeout(this.loadWatchdog), this.loadWatchdog = null), this.bridge.destroy(), this.iframe.remove();
+  }
+}
+export {
+  n as AkukoDashboard,
+  d as PostMessageBridge
+};

package/dist/akuko-embed-sdk.umd.cjs ADDED Viewed

@@ -0,0 +1 @@

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export { AkukoDashboard } from "./AkukoDashboard";
+export { PostMessageBridge } from "./PostMessageBridge";
+export type { AkukoSDKOptions, AkukoTheme, AkukoViewport, AkukoVisibility, ResolveResponse, } from "./types";
+export type { AkukoEventType, AkukoMessage } from "./PostMessageBridge";
+export type { ResyncMembersOpts } from "./AkukoDashboard";

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,205 @@
+export interface AkukoSDKOptions {
+    container: string | HTMLElement;
+    onadataOrgId?: string;
+    onadataProjectId?: string;
+    /**
+     * OnaData form id for a single-form generated dashboard. The iframe owns
+     * resolve: it loads `/embed/resolve/onadata-form/:id`, which looks up (or
+     * triggers generation of) the form's deterministic dashboard. Mutually
+     * exclusive with the other entry props.
+     */
+    onadataFormId?: string;
+    spaceUuid?: string;
+    dashboardId?: string;
+    /**
+     * Org slug for the standalone "link projects" picker surface, loaded in its
+     * own iframe (host renders it in a modal). Mutually exclusive with the other
+     * entry props. Maps to /embed/link-projects/onadata-org/:id.
+     */
+    linkProjectsOrgId?: string;
+    /**
+     * Grant-INDEPENDENT resolve context — companion fields, NOT entry selectors.
+     * When the host knows the owning org (and, for a form, its project), it passes
+     * them so akuko-api can derive the embed's state (org-provisioned / project-
+     * linked / dashboard) from akuko's own data without the caller's personal
+     * OnaData grant. This lets every authenticated org user — not just the admin
+     * who provisioned analytics — see role-appropriate content.
+     *
+     *  - `resolveOnadataOrgId`: owning org slug. Companion to `onadataProjectId`
+     *    (project embed) and `onadataFormId` (form embed). Forwarded as
+     *    `?onadata_org_id=`.
+     *  - `resolveOnadataProjectId`: the form's project id. Companion to
+     *    `onadataFormId` (form embed). Forwarded as `?onadata_project_id=`.
+     *
+     * Unlike the entry props above, these do NOT count toward the "exactly one
+     * entry prop" rule — they augment whichever entry prop is set.
+     */
+    resolveOnadataOrgId?: string;
+    resolveOnadataProjectId?: string;
+    /**
+     * Origin that serves the embed *frontend* routes (`/embed/*`) loaded into
+     * the iframe. Defaults to `https://akuko.io`.
+     */
+    baseUrl?: string;
+    /**
+     * Origin that serves the akuko *API* (`/v1/*`). Accepted for forward/backward
+     * compatibility but no longer used by the SDK: resolve and resync now run
+     * inside the iframe (same-origin, with the akuko cookie/Bearer), so the host
+     * never makes a cross-origin `/v1/*` call. Safe to keep passing.
+     */
+    apiBaseUrl?: string;
+    idpHint?: string;
+    theme?: AkukoTheme;
+    visibility?: AkukoVisibility;
+    filters?: Record<string, unknown>;
+    /**
+     * Host-settable initial post (dashboard) to open on mount, overriding the
+     * folder/space configured default. Used for deep-linking/sharing: the host
+     * reflects the open post in its own URL (?post=) and passes it back here so a
+     * shared link reproduces the exact view. Forwarded to the iframe as `?post=`.
+     */
+    initialPostId?: string;
+    allowedOrigin?: string;
+    sandbox?: string;
+    /**
+     * Iframe sizing strategy:
+     *  - `content` (default): the iframe auto-resizes to the embed's content
+     *    height (akuko:resize). Right for inline/single-dashboard embeds.
+     *  - `fill`: the host owns the height — the embed fills the iframe (100%) and
+     *    auto-resize is ignored. Right for a full-page analytics surface, so it
+     *    extends down to the host's footer instead of floating in a short box.
+     *    The host must give the iframe's container a real height (e.g. viewport).
+     */
+    layout?: "content" | "fill";
+    /**
+     * Content layout only: a minimum height floor for the iframe. A short
+     * dashboard — or the empty "generate"/"no dashboard yet" state — still fills
+     * down to the host's footer instead of leaving a gap, while the iframe still
+     * grows beyond this floor as the content height grows (the page scrolls).
+     * Accepts a number (px) or any CSS length string (e.g. "calc(100vh - 8.5rem)").
+     * Ignored in `fill` layout (there the host owns the height).
+     */
+    minHeight?: number | string;
+    /**
+     * Host-provided hint that the current user can administer (own/manage) the
+     * embedded org or project. Used ONLY to gate the in-iframe onboarding consent
+     * screen for an unlinked org: admin status can't be computed server-side until
+     * the caller completes the OnaData OAuth grant, so before that the embed trusts
+     * this hint to decide whether to show "Authorize & enable analytics" or "ask
+     * your owner". UX-only — the backend re-verifies ownership at provisioning, so
+     * a spoofed value cannot actually enable an org. Forwarded as `?host_admin=1`.
+     */
+    hostIsAdmin?: boolean;
+    /**
+     * The host's CURRENT signed-in OnaData user identity. Forwarded to the iframe
+     * (postMessage, replayed on akuko:ready) so the embed can detect a host
+     * user-switch and tear down a stale akuko session. UNTRUSTED: used ONLY to force
+     * a re-auth on mismatch, never to grant access or select an identity — the akuko
+     * session identity always derives from the verified OIDC Bearer.
+     */
+    hostUser?: {
+        email: string;
+    };
+    /**
+     * Milliseconds to wait for iframe.onload before emitting
+     * akuko:error{code:'IFRAME_LOAD_FAILED'}. Defaults to 30_000. Set to 0
+     * to disable the watchdog. Values <5_000 are not recommended — the iframe
+     * may still be completing its brokered resolve + redirect.
+     */
+    iframeLoadTimeoutMs?: number;
+    /**
+     * Milliseconds `logout()` waits for the iframe's `akuko:logoutComplete`
+     * acknowledgement before resolving anyway. Defaults to 2000. The host
+     * should use a slightly larger ceiling so the SDK's own timeout wins first.
+     */
+    logoutTimeoutMs?: number;
+}
+export interface AkukoTheme {
+    primary?: string;
+    background?: string;
+    foreground?: string;
+    card?: string;
+    border?: string;
+    radius?: string;
+    fontFamily?: string;
+    darkMode?: boolean;
+    chart1?: string;
+    chart2?: string;
+    chart3?: string;
+    chart4?: string;
+    chart5?: string;
+}
+export interface AkukoVisibility {
+    header?: boolean;
+    breadcrumbs?: boolean;
+    footer?: boolean;
+    undoRedo?: boolean;
+    chartActions?: boolean;
+    filterBar?: boolean;
+}
+/**
+ * The slice of the embed iframe currently visible in the host's browser
+ * viewport, in iframe-local CSS pixels. Sent host→iframe (`akuko:viewport`) so
+ * in-iframe floating UI (e.g. an action panel) can center itself in the visible
+ * band even when the HOST page — not the iframe — owns the scrollbar
+ * (`layout: "content"`, where the iframe auto-grows to full content height).
+ * `top` is the iframe-local Y of the first visible row; `height` is the visible
+ * band's height. In `layout: "fill"` the iframe is itself the scroll viewport,
+ * so `top` is 0 and `height` is the iframe height.
+ */
+export interface AkukoViewport {
+    top: number;
+    height: number;
+}
+/**
+ * Response shape from GET /v1/embed/resolve. Surfaced to the host via the
+ * `akuko:resolved` event so the host can read `links.akuko_*_url` for
+ * "Open in new tab" deep-links without making its own HTTP call.
+ */
+export type ResolveResponse = {
+    status: "linked";
+    space_id: string;
+    folder_id?: string;
+    /**
+     * Project (folder) default dashboard, present on project lookups. The
+     * embed renders it by default; hosts may read it for display/analytics.
+     */
+    default_post_id?: string | null;
+    /**
+     * Org (space) default dashboard, present on org lookups. The embed
+     * renders it by default on the org-level analytics tab.
+     */
+    space_default_post_id?: string | null;
+    links: {
+        akuko_space_url?: string;
+        akuko_space_posts_url?: string;
+        akuko_folder_url?: string;
+    };
+    /** Caller is an OnaData org owner/manager (UX gate; re-verified at provisioning). */
+    is_org_admin?: boolean;
+} | {
+    status: "unlinked";
+    onboarding_url: string;
+    /** Caller is an OnaData org owner/manager (UX gate). */
+    is_org_admin?: boolean;
+    /** OnaData org slug owning the resource; lets the host link to org analytics. */
+    onadata_org_slug?: string;
+    /**
+     * Project scope only: the org IS linked but this project isn't. The embed
+     * renders its own "link this project" / "ask an admin" state, so the host
+     * can keep the iframe rather than showing an org-not-enabled card.
+     */
+    org_linked?: boolean;
+} | {
+    status: "provisioning";
+    /** JIT member-sync workflow id to poll while the caller is provisioned. */
+    workflow_id: string;
+} | {
+    /**
+     * The akuko session belongs to a different person than the current
+     * OnaData user. The embed clears its akuko session and re-brokers; hosts
+     * generally need not react (the iframe self-heals).
+     */
+    status: "reauth_required";
+    reason: "identity_mismatch";
+};

package/docs/host-recipes.md ADDED Viewed

@@ -0,0 +1,134 @@
+# Host recipes
+Concrete integration recipes for embedding Akuko dashboards with
+`@onaio/akuko-embed-sdk`. All examples use the current API
+(`new AkukoDashboard({ … })`).
+For federated/private dashboards, see
+[`./sso-path-d-brokering.md`](./sso-path-d-brokering.md) — wherever a recipe
+passes `idpHint`, that alias must first be wired up as a brokered IdP in Akuko's
+Keycloak.
+---
+## WordPress (public dashboard)
+The simplest case: embedding a **public** Akuko dashboard (a published post that
+needs no login). Drop a container and a module script into a page, a Custom HTML
+block, or a small plugin/shortcode that prints this markup.
+```html
+<div id="akuko-dashboard"></div>
+<script type="module">
+  import { AkukoDashboard } from "https://esm.sh/@onaio/akuko-embed-sdk";
+  new AkukoDashboard({
+    container: "#akuko-dashboard",
+    dashboardId: "your-public-dashboard-id",
+    baseUrl: "https://akuko.io",
+    // No idpHint — public posts skip auth entirely.
+  });
+</script>
+```
+If you bundle your theme's JS, import from the npm package instead of the CDN:
+```js
+import { AkukoDashboard } from "@onaio/akuko-embed-sdk";
+```
+**Private / federated WordPress:** a public post needs no auth, so it "just
+works". To embed a *private* dashboard for logged-in WP users, those users must
+exist in an IdP that Akuko's Keycloak can broker (Path D), and you pass the
+matching `idpHint`. WordPress's own cookie session is not an OIDC IdP — you'd
+front WP with (or federate it to) a brokerable OIDC provider first.
+---
+## Directus
+Two distinct shapes depending on *where* the embed lives.
+### Variant A — Directus Module extension (inside the admin app)
+A custom [Module extension](https://docs.directus.io/extensions/modules.html)
+that renders an Akuko dashboard inside the Directus admin UI. The extension is a
+Vue SFC; mount the SDK in `onMounted` and tear it down in `onBeforeUnmount`:
+```vue
+<template>
+  <private-view title="Analytics">
+    <div ref="mount" style="height: calc(100vh - 60px)"></div>
+  </private-view>
+</template>
+<script setup>
+import { ref, onMounted, onBeforeUnmount } from "vue";
+import { AkukoDashboard } from "@onaio/akuko-embed-sdk";
+const mount = ref(null);
+let dashboard = null;
+let themeObserver = null;
+// Map Directus theme CSS vars → AkukoTheme.
+function readDirectusTheme() {
+  const s = getComputedStyle(document.documentElement);
+  const v = (name) => s.getPropertyValue(name).trim() || undefined;
+  return {
+    primary: v("--theme--primary"),
+    background: v("--theme--background"),
+    foreground: v("--theme--foreground"),
+    border: v("--theme--border-color"),
+    darkMode: document.documentElement.classList.contains("dark"),
+  };
+}
+onMounted(() => {
+  dashboard = new AkukoDashboard({
+    container: mount.value,
+    dashboardId: import.meta.env.AKUKO_DASHBOARD_ID,
+    baseUrl: import.meta.env.AKUKO_BASE_URL,
+    idpHint: import.meta.env.AKUKO_IDP_HINT, // your brokered IdP alias
+    layout: "fill",
+    theme: readDirectusTheme(),
+  });
+  // Re-push the theme when Directus toggles light/dark.
+  themeObserver = new MutationObserver(() => dashboard?.setTheme(readDirectusTheme()));
+  themeObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+});
+onBeforeUnmount(() => {
+  themeObserver?.disconnect();
+  dashboard?.destroy();
+});
+</script>
+```
+Directus extensions are built with Vite. To expose `AKUKO_*` build-time env
+vars to the extension, widen the env prefix in the extension's `vite.config.ts`:
+```ts
+export default defineConfig({
+  envPrefix: ["VITE_", "DIRECTUS_", "AKUKO_"],
+});
+```
+> An `@onaio/akuko-directus-module` drop-in package is a **future** deliverable.
+> Until then, this is the build-your-own recipe.
+### Variant B — A Directus-powered site (separate front-end)
+If your site is a separate app (Next.js, Nuxt, Astro, or plain HTML) that reads
+content from Directus, embed Akuko there like any other host — exactly as in the
+WordPress example above. If that site authenticates users through a brokerable
+OIDC IdP, Path D applies and you pass `idpHint`; if it only renders public
+dashboards, omit it.
+---
+See [`./sso-path-d-brokering.md`](./sso-path-d-brokering.md) for the federation
+setup any `idpHint`-based recipe depends on.