@mfe-orchestrator-hub/client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo De Francesco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @mfe-orchestrator-hub/client
+
+Framework agnostic client for [MFE Orchestrator](https://github.com/mfe-orchestrator). It asks the
+console which microfrontends the current environment serves and hands back their ready to use,
+version pinned URLs.
+
+Zero runtime dependencies, ESM + CJS, ships its own types.
+
+## The one rule
+
+**The host page never decides which version it gets.** It sends the identities it holds and uses the
+URL it receives verbatim. It does not parse the version out of the URL, does not draw any random
+number, does not know that a canary exists. All of that lives in the backend.
+
+## Install
+
+```sh
+pnpm add @mfe-orchestrator-hub/client
+```
+
+## Configure
+
+Call `configure()` at the very top of the host entry point, before anything imports a remote.
+
+```ts
+import { configure } from "@mfe-orchestrator-hub/client"
+
+configure({
+    backendUrl: import.meta.env.VITE_MFE_BACKEND_URL,
+    projectId: import.meta.env.VITE_MFE_PROJECT_ID,
+    environment: import.meta.env.VITE_MFE_ENVIRONMENT
+})
+```
+
+`configure()` is idempotent: calling it again with the same options is a no op, so a framework
+provider may call it on every render. A second call with different options is ignored, with a
+warning, because the manifest of this page load may already be in flight.
+
+## Bundler configuration
+
+The string below is injected into the host bundle, so the bare specifier is resolved by the host's
+own bundler. This is exactly the form the console generates.
+
+### Vite — `@originjs/vite-plugin-federation`
+
+```js
+federation({
+    name: "shell",
+    remotes: {
+        checkoutnew: {
+            external: `import('@mfe-orchestrator-hub/client').then(m => m.remoteUrl('checkout-new'))`,
+            externalType: "promise"
+        }
+    },
+    shared: ["react", "react-dom"]
+})
+```
+
+### Webpack — `ModuleFederationPlugin`
+
+```js
+new ModuleFederationPlugin({
+    name: "shell",
+    remotes: {
+        checkoutnew: `promise import('@mfe-orchestrator-hub/client').then(m => m.remoteUrl('checkout-new'))`
+    },
+    shared: { react: { singleton: true }, "react-dom": { singleton: true } }
+})
+```
+
+## API
+
+```ts
+export interface OrchestratorConfig {
+    backendUrl: string // ex. "https://console.mfe-orchestrator.dev/api"
+    projectId: string
+    environment: string // environment slug, ex. "DEV"
+    userId?: string | (() => string | undefined | Promise<string | undefined>)
+}
+
+/** Call once, synchronously, before any remote is imported. Idempotent. */
+export function configure(config: OrchestratorConfig): void
+
+/** Resolves the ready to use, version pinned URL of a remote. Awaits the manifest internally. */
+export function remoteUrl(slug: string): Promise<string>
+
+/** Whole manifest, fetched once and memoized. */
+export function manifest(): Promise<Manifest>
+
+/** Global variables of the environment, as a plain object. */
+export function globalVariables(): Promise<Record<string, string>>
+
+/** The two ids, exposed for telemetry/debugging. */
+export function identities(): { sessionId: string; deviceId: string }
+```
+
+The types `Manifest`, `Microfrontend`, `GlobalVariable`, `Identities` and `OrchestratorConfig` are
+exported as well.
+
+### `remoteUrl(slug)`
+
+```ts
+import { remoteUrl } from "@mfe-orchestrator-hub/client"
+
+const url = await remoteUrl("checkout-new")
+// https://console…/serve/mfe/files/auto/<projectId>/checkout-new/_v/1.5.0-rc1/assets/remoteEntry.js
+```
+
+Use that URL as it is. Never rebuild it by hand and never strip the `_v/<version>/` segment: a
+classic script (webpack `publicPath: "auto"`) derives the base of its chunks from
+`document.currentScript.src`, which is the URL *before* any redirect, so without the segment already
+in place it would request its chunks off a different version and mix two builds in one page.
+
+An unknown slug rejects with a message listing the slugs the environment does serve.
+
+### `globalVariables()`
+
+```ts
+const variables = await globalVariables()
+// { API_URL: "https://…", FEATURE_FLAG: "on" }
+```
+
+### `identities()`
+
+```ts
+const { sessionId, deviceId } = identities()
+```
+
+## How it talks to the backend
+
+One single successful request per page load, memoized as a promise so that concurrent callers share
+it:
+
+```
+GET {backendUrl}/serve/all/{projectId}/{environment}
+    ?mfeSessionId=<uuid>&mfeDeviceId=<uuid>&mfeUserId=<optional>
+```
+
+### Why identities travel in the query string
+
+Microfrontends are loaded with a cross-site `import()`. Module scripts are fetched with a fixed
+`same-origin` credentials mode, so no cookie of the console domain is ever sent with them and no
+`Set-Cookie` of ours is stored. The host page is the only place holding this state and the URL is the
+only way to hand it over.
+
+| query param | where it is kept | storage key | lifetime |
+| --- | --- | --- | --- |
+| `mfeSessionId` | `sessionStorage` | `mfe-orchestrator.sessionId` | dies with the browser session |
+| `mfeDeviceId` | `localStorage` | `mfe-orchestrator.deviceId` | survives browser restarts |
+| `mfeUserId` | supplied by the host app | — | not stored by the SDK |
+
+All three are sent whenever available: the client does not know, and must not guess, which one the
+backend uses.
+
+`userId` may be a value, a getter, or an async getter. It is resolved as late as possible, right
+before the request is issued, so a host that only knows its user after an auth round trip can pass a
+function.
+
+Both ids are generated with `crypto.randomUUID()` on first use and persisted. Storage can throw —
+Safari in private mode, disabled storage, hardened browsers that throw on the property access
+itself — and in that case the client falls back to ids held in memory for the lifetime of the page.
+This never throws out of the SDK.
+
+### Successes are cached, failures are not
+
+A resolved manifest is memoized for the lifetime of the page. A failed attempt is not: when the
+shared attempt settles as rejected, the memo is dropped, so the next call to `manifest()`,
+`remoteUrl()` or `globalVariables()` starts a fresh request.
+
+Every caller already waiting on the failed attempt still gets that rejection — the memo is cleared
+once, when the attempt settles, not in each caller's own `catch` — so a failure rejects all of them
+and costs exactly one request.
+
+This is not a retry: nothing here loops, schedules or backs off. It only means that one flaky lookup
+or one 502 during a console redeploy does not condemn the page to reject every `remoteUrl()` until a
+full reload. Recovering is the host app's call, by asking again.
+
+## Not in v1
+
+No automatic retries, no offline caching, no service worker, and nothing that reads or writes
+cookies. A network error is surfaced exactly as `fetch` produced it.
+
+## Framework adapters
+
+- React — [`@mfe-orchestrator-hub/client-react`](https://github.com/mfe-orchestrator/client-react)
+- Vue — [`@mfe-orchestrator-hub/client-vue`](https://github.com/mfe-orchestrator/client-vue)
+- Angular — [`@mfe-orchestrator-hub/client-angular`](https://github.com/mfe-orchestrator/client-angular)
+
+They are ergonomics only: every decision lives here, in the core.
+
+## Development
+
+```sh
+pnpm install
+pnpm test        # vitest
+pnpm build       # tsup, ESM + CJS + types
+pnpm typecheck
+```
+
+## License
+
+MIT © Lorenzo De Francesco

package/dist/index.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+// src/state.ts
+var STATE_KEY = "__mfe_orchestrator_client__";
+var globalSlot = globalThis;
+var getState = () => {
+  let state = globalSlot[STATE_KEY];
+  if (!state) {
+    state = { config: null, manifestPromise: null, identities: null };
+    globalSlot[STATE_KEY] = state;
+  }
+  return state;
+};
+
+// src/storage.ts
+var SESSION_ID_KEY = "mfe-orchestrator.sessionId";
+var DEVICE_ID_KEY = "mfe-orchestrator.deviceId";
+var PROBE_KEY = "mfe-orchestrator.probe";
+var inMemoryIds = /* @__PURE__ */ new Map();
+var uuidFromRandomBytes = (bytes) => {
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (const byte of bytes) {
+    hex.push(byte.toString(16).padStart(2, "0"));
+  }
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+};
+var newId = () => {
+  const cryptoApi = globalThis.crypto;
+  try {
+    if (typeof cryptoApi?.randomUUID === "function") {
+      return cryptoApi.randomUUID();
+    }
+    if (typeof cryptoApi?.getRandomValues === "function") {
+      return uuidFromRandomBytes(cryptoApi.getRandomValues(new Uint8Array(16)));
+    }
+  } catch {
+  }
+  const bytes = new Uint8Array(16);
+  for (let index = 0; index < bytes.length; index++) {
+    bytes[index] = Math.floor(Math.random() * 256);
+  }
+  return uuidFromRandomBytes(bytes);
+};
+var openStorage = (kind) => {
+  try {
+    const storage = kind === "local" ? globalThis.localStorage : globalThis.sessionStorage;
+    if (!storage) {
+      return null;
+    }
+    storage.setItem(PROBE_KEY, "1");
+    storage.removeItem(PROBE_KEY);
+    return storage;
+  } catch {
+    return null;
+  }
+};
+var persistentId = (kind, key) => {
+  const storage = openStorage(kind);
+  if (storage) {
+    try {
+      const stored = storage.getItem(key);
+      if (stored) {
+        return stored;
+      }
+      const created2 = newId();
+      storage.setItem(key, created2);
+      return created2;
+    } catch {
+    }
+  }
+  const remembered = inMemoryIds.get(key);
+  if (remembered) {
+    return remembered;
+  }
+  const created = newId();
+  inMemoryIds.set(key, created);
+  return created;
+};
+var readIdentities = () => ({
+  sessionId: persistentId("session", SESSION_ID_KEY),
+  deviceId: persistentId("local", DEVICE_ID_KEY)
+});
+
+// src/index.ts
+var PREFIX = "[@mfe-orchestrator-hub/client]";
+var NOT_CONFIGURED = `${PREFIX} call configure() first. Configure the client at the very top of the host entry point, before anything imports a remote:
+
+    import { configure } from "@mfe-orchestrator-hub/client"
+
+    configure({ backendUrl: "\u2026", projectId: "\u2026", environment: "\u2026" })`;
+var withoutTrailingSlash = (value) => value.replace(/\/+$/, "");
+var resolveUserId = async (userId) => {
+  const value = typeof userId === "function" ? await userId() : userId;
+  return value === void 0 || value === null || value === "" ? void 0 : String(value);
+};
+var sameConfig = (left, right) => left.backendUrl === right.backendUrl && left.projectId === right.projectId && left.environment === right.environment && left.userId === right.userId;
+var requireConfig = (config) => {
+  const missing = ["backendUrl", "projectId", "environment"].filter((key) => !config?.[key]);
+  if (missing.length > 0) {
+    throw new Error(`${PREFIX} configure() is missing required option${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}.`);
+  }
+};
+var manifestUrl = async (config) => {
+  const { sessionId, deviceId } = identities();
+  const query = new URLSearchParams({ mfeSessionId: sessionId, mfeDeviceId: deviceId });
+  const userId = await resolveUserId(config.userId);
+  if (userId) {
+    query.set("mfeUserId", userId);
+  }
+  return `${withoutTrailingSlash(config.backendUrl)}/serve/all/${encodeURIComponent(config.projectId)}/${encodeURIComponent(config.environment)}?${query.toString()}`;
+};
+var fetchManifest = async (config) => {
+  const url = await manifestUrl(config);
+  const response = await fetch(url, { headers: { accept: "application/json" } });
+  if (!response.ok) {
+    throw new Error(`${PREFIX} the manifest request failed with ${response.status} ${response.statusText}. GET ${url}`);
+  }
+  const payload = await response.json();
+  return {
+    globalVariables: payload?.globalVariables ?? [],
+    microfrontends: payload?.microfrontends ?? []
+  };
+};
+var configure = (config) => {
+  requireConfig(config);
+  const state = getState();
+  const current = state.config;
+  if (current) {
+    if (!sameConfig(current, config)) {
+      console.warn(
+        `${PREFIX} configure() was called again with a different configuration. The first one is kept: ${JSON.stringify({ backendUrl: current.backendUrl, projectId: current.projectId, environment: current.environment })}.`
+      );
+    }
+    return;
+  }
+  state.config = { ...config };
+};
+var manifest = () => {
+  const state = getState();
+  const config = state.config;
+  if (!config) {
+    return Promise.reject(new Error(NOT_CONFIGURED));
+  }
+  if (!state.manifestPromise) {
+    const attempt = fetchManifest(config);
+    state.manifestPromise = attempt;
+    attempt.catch(() => {
+      if (state.manifestPromise === attempt) {
+        state.manifestPromise = null;
+      }
+    });
+  }
+  return state.manifestPromise;
+};
+var remoteUrl = async (slug) => {
+  const { microfrontends } = await manifest();
+  const found = microfrontends.find((microfrontend) => microfrontend.slug === slug);
+  if (!found) {
+    const available = microfrontends.map((microfrontend) => `"${microfrontend.slug}"`).join(", ");
+    const { environment } = getState().config ?? { environment: "?" };
+    throw new Error(`${PREFIX} unknown microfrontend slug "${slug}". Available in environment "${environment}": ${available || "none, this environment serves no microfrontend"}.`);
+  }
+  if (!found.url) {
+    throw new Error(`${PREFIX} the microfrontend "${slug}" is in the manifest but carries no url. Check its deployment in the console.`);
+  }
+  return found.url;
+};
+var globalVariables = async () => {
+  const { globalVariables: variables } = await manifest();
+  const result = {};
+  for (const variable of variables) {
+    if (variable && typeof variable.key === "string") {
+      result[variable.key] = variable.value;
+    }
+  }
+  return result;
+};
+var identities = () => {
+  const state = getState();
+  if (!state.identities) {
+    state.identities = readIdentities();
+  }
+  return state.identities;
+};
+
+exports.configure = configure;
+exports.globalVariables = globalVariables;
+exports.identities = identities;
+exports.manifest = manifest;
+exports.remoteUrl = remoteUrl;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state.ts","../src/storage.ts","../src/index.ts"],"names":["created"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Identities, Manifest, OrchestratorConfig } from \"./types\"\n\nexport interface OrchestratorState {\n    config: OrchestratorConfig | null\n    manifestPromise: Promise<Manifest> | null\n    identities: Identities | null\n}\n\n/**\n * The state lives on `globalThis` under this key, not in a module scope variable.\n *\n * A host can end up with two copies of this package loaded at once: the app imports the ESM build\n * while something else pulls the CJS one, or the bundler config and the app resolve to different\n * chunks. Two module scopes would mean two configurations and two manifest requests, which is\n * exactly what the contract forbids. One well known global slot makes the singleton real.\n */\nexport const STATE_KEY = \"__mfe_orchestrator_client__\"\n\nconst globalSlot = globalThis as typeof globalThis & Record<typeof STATE_KEY, OrchestratorState | undefined>\n\nexport const getState = (): OrchestratorState => {\n    let state = globalSlot[STATE_KEY]\n    if (!state) {\n        state = { config: null, manifestPromise: null, identities: null }\n        globalSlot[STATE_KEY] = state\n    }\n    return state\n}\n","import type { Identities } from \"./types\"\n\nexport const SESSION_ID_KEY = \"mfe-orchestrator.sessionId\"\nexport const DEVICE_ID_KEY = \"mfe-orchestrator.deviceId\"\n\nconst PROBE_KEY = \"mfe-orchestrator.probe\"\n\ntype StorageKind = \"local\" | \"session\"\n\n/**\n * Ids minted while storage was unusable. They live for the lifetime of the page so that, even\n * without storage, every request of this page load carries one stable pair of ids.\n */\nconst inMemoryIds = new Map<string, string>()\n\nconst uuidFromRandomBytes = (bytes: Uint8Array): string => {\n    bytes[6] = (bytes[6] & 0x0f) | 0x40\n    bytes[8] = (bytes[8] & 0x3f) | 0x80\n    const hex: string[] = []\n    for (const byte of bytes) {\n        hex.push(byte.toString(16).padStart(2, \"0\"))\n    }\n    return `${hex.slice(0, 4).join(\"\")}-${hex.slice(4, 6).join(\"\")}-${hex.slice(6, 8).join(\"\")}-${hex.slice(8, 10).join(\"\")}-${hex.slice(10, 16).join(\"\")}`\n}\n\n/**\n * A v4 UUID. `crypto.randomUUID` is the intended path; the two fallbacks only exist so that a page\n * served over plain http, or an exotic runtime, still gets an id instead of an exception.\n */\nexport const newId = (): string => {\n    const cryptoApi = globalThis.crypto\n    try {\n        if (typeof cryptoApi?.randomUUID === \"function\") {\n            return cryptoApi.randomUUID()\n        }\n        if (typeof cryptoApi?.getRandomValues === \"function\") {\n            return uuidFromRandomBytes(cryptoApi.getRandomValues(new Uint8Array(16)))\n        }\n    } catch {\n        // fall through to the non cryptographic fallback\n    }\n    const bytes = new Uint8Array(16)\n    for (let index = 0; index < bytes.length; index++) {\n        bytes[index] = Math.floor(Math.random() * 256)\n    }\n    return uuidFromRandomBytes(bytes)\n}\n\n/**\n * The requested storage, or `null` when it is missing or unusable.\n *\n * Both the property access and the write can throw: Safari in private mode exposes the object and\n * then refuses `setItem`, some hardened browsers throw a SecurityError on the access itself. The\n * write probe is the only reliable way to tell a usable storage from a decorative one.\n */\nconst openStorage = (kind: StorageKind): Storage | null => {\n    try {\n        const storage = kind === \"local\" ? globalThis.localStorage : globalThis.sessionStorage\n        if (!storage) {\n            return null\n        }\n        storage.setItem(PROBE_KEY, \"1\")\n        storage.removeItem(PROBE_KEY)\n        return storage\n    } catch {\n        return null\n    }\n}\n\n/**\n * The id under `key`, read from storage and created on first use. Falls back to an id kept in\n * memory when storage cannot be used, so this never throws out of the SDK.\n */\nconst persistentId = (kind: StorageKind, key: string): string => {\n    const storage = openStorage(kind)\n    if (storage) {\n        try {\n            const stored = storage.getItem(key)\n            if (stored) {\n                return stored\n            }\n            const created = newId()\n            storage.setItem(key, created)\n            return created\n        } catch {\n            // storage passed the probe and failed anyway: keep going with an in memory id\n        }\n    }\n    const remembered = inMemoryIds.get(key)\n    if (remembered) {\n        return remembered\n    }\n    const created = newId()\n    inMemoryIds.set(key, created)\n    return created\n}\n\n/** Reads, and creates when needed, the session and device ids. */\nexport const readIdentities = (): Identities => ({\n    sessionId: persistentId(\"session\", SESSION_ID_KEY),\n    deviceId: persistentId(\"local\", DEVICE_ID_KEY)\n})\n","import { getState } from \"./state\"\nimport { readIdentities } from \"./storage\"\nimport type { Identities, Manifest, OrchestratorConfig } from \"./types\"\n\nexport type { GlobalVariable, Identities, Manifest, Microfrontend, OrchestratorConfig } from \"./types\"\n\nconst PREFIX = \"[@mfe-orchestrator-hub/client]\"\n\nconst NOT_CONFIGURED = `${PREFIX} call configure() first. Configure the client at the very top of the host entry point, before anything imports a remote:\n\n    import { configure } from \"@mfe-orchestrator-hub/client\"\n\n    configure({ backendUrl: \"…\", projectId: \"…\", environment: \"…\" })`\n\nconst withoutTrailingSlash = (value: string): string => value.replace(/\\/+$/, \"\")\n\nconst resolveUserId = async (userId: OrchestratorConfig[\"userId\"]): Promise<string | undefined> => {\n    const value = typeof userId === \"function\" ? await userId() : userId\n    return value === undefined || value === null || value === \"\" ? undefined : String(value)\n}\n\nconst sameConfig = (left: OrchestratorConfig, right: OrchestratorConfig): boolean =>\n    left.backendUrl === right.backendUrl && left.projectId === right.projectId && left.environment === right.environment && left.userId === right.userId\n\nconst requireConfig = (config: OrchestratorConfig): void => {\n    const missing = ([\"backendUrl\", \"projectId\", \"environment\"] as const).filter(key => !config?.[key])\n    if (missing.length > 0) {\n        throw new Error(`${PREFIX} configure() is missing required option${missing.length > 1 ? \"s\" : \"\"}: ${missing.join(\", \")}.`)\n    }\n}\n\nconst manifestUrl = async (config: OrchestratorConfig): Promise<string> => {\n    const { sessionId, deviceId } = identities()\n    const query = new URLSearchParams({ mfeSessionId: sessionId, mfeDeviceId: deviceId })\n    // Resolved as late as possible: the host may only know the user after its own auth round trip.\n    const userId = await resolveUserId(config.userId)\n    if (userId) {\n        query.set(\"mfeUserId\", userId)\n    }\n    return `${withoutTrailingSlash(config.backendUrl)}/serve/all/${encodeURIComponent(config.projectId)}/${encodeURIComponent(config.environment)}?${query.toString()}`\n}\n\nconst fetchManifest = async (config: OrchestratorConfig): Promise<Manifest> => {\n    const url = await manifestUrl(config)\n    // No retry in v1: whatever fetch throws travels straight to the caller.\n    const response = await fetch(url, { headers: { accept: \"application/json\" } })\n    if (!response.ok) {\n        throw new Error(`${PREFIX} the manifest request failed with ${response.status} ${response.statusText}. GET ${url}`)\n    }\n    const payload = (await response.json()) as Partial<Manifest> | null\n    return {\n        globalVariables: payload?.globalVariables ?? [],\n        microfrontends: payload?.microfrontends ?? []\n    }\n}\n\n/**\n * Hands the client its configuration. Call it once, synchronously, before any remote is imported.\n *\n * Idempotent: calling it again with the same options is a no op, so a framework provider may safely\n * call it on every render. A second call with different options is ignored, with a warning, because\n * the manifest of this page load may already be in flight or resolved.\n */\nexport const configure = (config: OrchestratorConfig): void => {\n    requireConfig(config)\n    const state = getState()\n    const current = state.config\n    if (current) {\n        if (!sameConfig(current, config)) {\n            console.warn(\n                `${PREFIX} configure() was called again with a different configuration. The first one is kept: ${JSON.stringify({ backendUrl: current.backendUrl, projectId: current.projectId, environment: current.environment })}.`\n            )\n        }\n        return\n    }\n    state.config = { ...config }\n}\n\n/**\n * The whole manifest of the environment, fetched once per page load and memoized as a promise, so\n * that concurrent callers share the single request in flight.\n *\n * A successful result is memoized for good. A failed attempt is not: the memo is dropped when the\n * shared attempt settles as rejected, so the next caller starts a fresh request. That is not a retry\n * — nothing here loops or backs off — it only means one flaky lookup at boot does not condemn the\n * page to reject every `remoteUrl()` until a full reload.\n */\nexport const manifest = (): Promise<Manifest> => {\n    const state = getState()\n    const config = state.config\n    if (!config) {\n        // Not memoized: the host may still configure the client and try again.\n        return Promise.reject(new Error(NOT_CONFIGURED))\n    }\n    if (!state.manifestPromise) {\n        // Assigned before the first await inside fetchManifest, which is what makes N concurrent\n        // callers collapse onto one request.\n        const attempt = fetchManifest(config)\n        state.manifestPromise = attempt\n        // Cleared once, when the shared attempt settles, not in each caller's own catch: every\n        // caller already waiting on this attempt still gets its rejection. The identity check keeps\n        // a late failure from evicting a newer attempt.\n        attempt.catch(() => {\n            if (state.manifestPromise === attempt) {\n                state.manifestPromise = null\n            }\n        })\n    }\n    return state.manifestPromise\n}\n\n/**\n * The ready to use, version pinned URL of a remote. Awaits the manifest internally.\n *\n * The returned URL is used verbatim: the host never parses the version out of it and never strips\n * the `_v/<version>/` segment, or a classic script would load its chunks off another version.\n */\nexport const remoteUrl = async (slug: string): Promise<string> => {\n    const { microfrontends } = await manifest()\n    const found = microfrontends.find(microfrontend => microfrontend.slug === slug)\n    if (!found) {\n        const available = microfrontends.map(microfrontend => `\"${microfrontend.slug}\"`).join(\", \")\n        const { environment } = getState().config ?? { environment: \"?\" }\n        throw new Error(`${PREFIX} unknown microfrontend slug \"${slug}\". Available in environment \"${environment}\": ${available || \"none, this environment serves no microfrontend\"}.`)\n    }\n    if (!found.url) {\n        throw new Error(`${PREFIX} the microfrontend \"${slug}\" is in the manifest but carries no url. Check its deployment in the console.`)\n    }\n    return found.url\n}\n\n/** The global variables of the environment, as a plain object. */\nexport const globalVariables = async (): Promise<Record<string, string>> => {\n    const { globalVariables: variables } = await manifest()\n    const result: Record<string, string> = {}\n    for (const variable of variables) {\n        if (variable && typeof variable.key === \"string\") {\n            result[variable.key] = variable.value\n        }\n    }\n    return result\n}\n\n/**\n * The session and device ids of this page, exposed for telemetry and debugging. Created on first\n * use and stable for the lifetime of the page, whether or not storage is available.\n */\nexport const identities = (): Identities => {\n    const state = getState()\n    if (!state.identities) {\n        state.identities = readIdentities()\n    }\n    return state.identities\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+/**
+ * Configuration of the orchestrator client. Handed over once, at the very top of the host entry point.
+ */
+interface OrchestratorConfig {
+    /** Base URL of the console API, ex. "https://console.mfe-orchestrator.dev/api". */
+    backendUrl: string;
+    /** Id of the project the host belongs to. */
+    projectId: string;
+    /** Environment slug, ex. "DEV". */
+    environment: string;
+    /**
+     * Identity of the logged in user, if the host has one. May be a plain value, a getter, or an
+     * async getter resolved right before the manifest request is issued.
+     */
+    userId?: string | (() => string | undefined | Promise<string | undefined>);
+}
+/** A single environment variable of the deployment. */
+interface GlobalVariable {
+    key: string;
+    value: string;
+}
+/** A microfrontend as served by the console for the current environment. */
+interface Microfrontend {
+    /** Stable, human readable id of the microfrontend. */
+    slug: string;
+    /** Display name. */
+    name: string;
+    /** Federation safe name, the one used as the remote key in the bundler config. */
+    nameToIntegrate: string;
+    /** Version actually served. Informative only: never rebuild the URL out of it. */
+    version: string;
+    continuousDeployment: boolean;
+    /** Ready to use, already version pinned URL of the remote entry. Use it verbatim. */
+    url: string;
+}
+/** The whole payload of `GET {backendUrl}/serve/all/{projectId}/{environmentSlug}`. */
+interface Manifest {
+    globalVariables: GlobalVariable[];
+    microfrontends: Microfrontend[];
+}
+/** The two ids the host holds on behalf of the backend. */
+interface Identities {
+    sessionId: string;
+    deviceId: string;
+}
+
+/**
+ * Hands the client its configuration. Call it once, synchronously, before any remote is imported.
+ *
+ * Idempotent: calling it again with the same options is a no op, so a framework provider may safely
+ * call it on every render. A second call with different options is ignored, with a warning, because
+ * the manifest of this page load may already be in flight or resolved.
+ */
+declare const configure: (config: OrchestratorConfig) => void;
+/**
+ * The whole manifest of the environment, fetched once per page load and memoized as a promise, so
+ * that concurrent callers share the single request in flight.
+ *
+ * A successful result is memoized for good. A failed attempt is not: the memo is dropped when the
+ * shared attempt settles as rejected, so the next caller starts a fresh request. That is not a retry
+ * — nothing here loops or backs off — it only means one flaky lookup at boot does not condemn the
+ * page to reject every `remoteUrl()` until a full reload.
+ */
+declare const manifest: () => Promise<Manifest>;
+/**
+ * The ready to use, version pinned URL of a remote. Awaits the manifest internally.
+ *
+ * The returned URL is used verbatim: the host never parses the version out of it and never strips
+ * the `_v/<version>/` segment, or a classic script would load its chunks off another version.
+ */
+declare const remoteUrl: (slug: string) => Promise<string>;
+/** The global variables of the environment, as a plain object. */
+declare const globalVariables: () => Promise<Record<string, string>>;
+/**
+ * The session and device ids of this page, exposed for telemetry and debugging. Created on first
+ * use and stable for the lifetime of the page, whether or not storage is available.
+ */
+declare const identities: () => Identities;
+
+export { type GlobalVariable, type Identities, type Manifest, type Microfrontend, type OrchestratorConfig, configure, globalVariables, identities, manifest, remoteUrl };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Configuration of the orchestrator client. Handed over once, at the very top of the host entry point.
+ */
+interface OrchestratorConfig {
+    /** Base URL of the console API, ex. "https://console.mfe-orchestrator.dev/api". */
+    backendUrl: string;
+    /** Id of the project the host belongs to. */
+    projectId: string;
+    /** Environment slug, ex. "DEV". */
+    environment: string;
+    /**
+     * Identity of the logged in user, if the host has one. May be a plain value, a getter, or an
+     * async getter resolved right before the manifest request is issued.
+     */
+    userId?: string | (() => string | undefined | Promise<string | undefined>);
+}
+/** A single environment variable of the deployment. */
+interface GlobalVariable {
+    key: string;
+    value: string;
+}
+/** A microfrontend as served by the console for the current environment. */
+interface Microfrontend {
+    /** Stable, human readable id of the microfrontend. */
+    slug: string;
+    /** Display name. */
+    name: string;
+    /** Federation safe name, the one used as the remote key in the bundler config. */
+    nameToIntegrate: string;
+    /** Version actually served. Informative only: never rebuild the URL out of it. */
+    version: string;
+    continuousDeployment: boolean;
+    /** Ready to use, already version pinned URL of the remote entry. Use it verbatim. */
+    url: string;
+}
+/** The whole payload of `GET {backendUrl}/serve/all/{projectId}/{environmentSlug}`. */
+interface Manifest {
+    globalVariables: GlobalVariable[];
+    microfrontends: Microfrontend[];
+}
+/** The two ids the host holds on behalf of the backend. */
+interface Identities {
+    sessionId: string;
+    deviceId: string;
+}
+
+/**
+ * Hands the client its configuration. Call it once, synchronously, before any remote is imported.
+ *
+ * Idempotent: calling it again with the same options is a no op, so a framework provider may safely
+ * call it on every render. A second call with different options is ignored, with a warning, because
+ * the manifest of this page load may already be in flight or resolved.
+ */
+declare const configure: (config: OrchestratorConfig) => void;
+/**
+ * The whole manifest of the environment, fetched once per page load and memoized as a promise, so
+ * that concurrent callers share the single request in flight.
+ *
+ * A successful result is memoized for good. A failed attempt is not: the memo is dropped when the
+ * shared attempt settles as rejected, so the next caller starts a fresh request. That is not a retry
+ * — nothing here loops or backs off — it only means one flaky lookup at boot does not condemn the
+ * page to reject every `remoteUrl()` until a full reload.
+ */
+declare const manifest: () => Promise<Manifest>;
+/**
+ * The ready to use, version pinned URL of a remote. Awaits the manifest internally.
+ *
+ * The returned URL is used verbatim: the host never parses the version out of it and never strips
+ * the `_v/<version>/` segment, or a classic script would load its chunks off another version.
+ */
+declare const remoteUrl: (slug: string) => Promise<string>;
+/** The global variables of the environment, as a plain object. */
+declare const globalVariables: () => Promise<Record<string, string>>;
+/**
+ * The session and device ids of this page, exposed for telemetry and debugging. Created on first
+ * use and stable for the lifetime of the page, whether or not storage is available.
+ */
+declare const identities: () => Identities;
+
+export { type GlobalVariable, type Identities, type Manifest, type Microfrontend, type OrchestratorConfig, configure, globalVariables, identities, manifest, remoteUrl };

package/dist/index.js

@@ -0,0 +1,188 @@
+// src/state.ts
+var STATE_KEY = "__mfe_orchestrator_client__";
+var globalSlot = globalThis;
+var getState = () => {
+  let state = globalSlot[STATE_KEY];
+  if (!state) {
+    state = { config: null, manifestPromise: null, identities: null };
+    globalSlot[STATE_KEY] = state;
+  }
+  return state;
+};
+
+// src/storage.ts
+var SESSION_ID_KEY = "mfe-orchestrator.sessionId";
+var DEVICE_ID_KEY = "mfe-orchestrator.deviceId";
+var PROBE_KEY = "mfe-orchestrator.probe";
+var inMemoryIds = /* @__PURE__ */ new Map();
+var uuidFromRandomBytes = (bytes) => {
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (const byte of bytes) {
+    hex.push(byte.toString(16).padStart(2, "0"));
+  }
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+};
+var newId = () => {
+  const cryptoApi = globalThis.crypto;
+  try {
+    if (typeof cryptoApi?.randomUUID === "function") {
+      return cryptoApi.randomUUID();
+    }
+    if (typeof cryptoApi?.getRandomValues === "function") {
+      return uuidFromRandomBytes(cryptoApi.getRandomValues(new Uint8Array(16)));
+    }
+  } catch {
+  }
+  const bytes = new Uint8Array(16);
+  for (let index = 0; index < bytes.length; index++) {
+    bytes[index] = Math.floor(Math.random() * 256);
+  }
+  return uuidFromRandomBytes(bytes);
+};
+var openStorage = (kind) => {
+  try {
+    const storage = kind === "local" ? globalThis.localStorage : globalThis.sessionStorage;
+    if (!storage) {
+      return null;
+    }
+    storage.setItem(PROBE_KEY, "1");
+    storage.removeItem(PROBE_KEY);
+    return storage;
+  } catch {
+    return null;
+  }
+};
+var persistentId = (kind, key) => {
+  const storage = openStorage(kind);
+  if (storage) {
+    try {
+      const stored = storage.getItem(key);
+      if (stored) {
+        return stored;
+      }
+      const created2 = newId();
+      storage.setItem(key, created2);
+      return created2;
+    } catch {
+    }
+  }
+  const remembered = inMemoryIds.get(key);
+  if (remembered) {
+    return remembered;
+  }
+  const created = newId();
+  inMemoryIds.set(key, created);
+  return created;
+};
+var readIdentities = () => ({
+  sessionId: persistentId("session", SESSION_ID_KEY),
+  deviceId: persistentId("local", DEVICE_ID_KEY)
+});
+
+// src/index.ts
+var PREFIX = "[@mfe-orchestrator-hub/client]";
+var NOT_CONFIGURED = `${PREFIX} call configure() first. Configure the client at the very top of the host entry point, before anything imports a remote:
+
+    import { configure } from "@mfe-orchestrator-hub/client"
+
+    configure({ backendUrl: "\u2026", projectId: "\u2026", environment: "\u2026" })`;
+var withoutTrailingSlash = (value) => value.replace(/\/+$/, "");
+var resolveUserId = async (userId) => {
+  const value = typeof userId === "function" ? await userId() : userId;
+  return value === void 0 || value === null || value === "" ? void 0 : String(value);
+};
+var sameConfig = (left, right) => left.backendUrl === right.backendUrl && left.projectId === right.projectId && left.environment === right.environment && left.userId === right.userId;
+var requireConfig = (config) => {
+  const missing = ["backendUrl", "projectId", "environment"].filter((key) => !config?.[key]);
+  if (missing.length > 0) {
+    throw new Error(`${PREFIX} configure() is missing required option${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}.`);
+  }
+};
+var manifestUrl = async (config) => {
+  const { sessionId, deviceId } = identities();
+  const query = new URLSearchParams({ mfeSessionId: sessionId, mfeDeviceId: deviceId });
+  const userId = await resolveUserId(config.userId);
+  if (userId) {
+    query.set("mfeUserId", userId);
+  }
+  return `${withoutTrailingSlash(config.backendUrl)}/serve/all/${encodeURIComponent(config.projectId)}/${encodeURIComponent(config.environment)}?${query.toString()}`;
+};
+var fetchManifest = async (config) => {
+  const url = await manifestUrl(config);
+  const response = await fetch(url, { headers: { accept: "application/json" } });
+  if (!response.ok) {
+    throw new Error(`${PREFIX} the manifest request failed with ${response.status} ${response.statusText}. GET ${url}`);
+  }
+  const payload = await response.json();
+  return {
+    globalVariables: payload?.globalVariables ?? [],
+    microfrontends: payload?.microfrontends ?? []
+  };
+};
+var configure = (config) => {
+  requireConfig(config);
+  const state = getState();
+  const current = state.config;
+  if (current) {
+    if (!sameConfig(current, config)) {
+      console.warn(
+        `${PREFIX} configure() was called again with a different configuration. The first one is kept: ${JSON.stringify({ backendUrl: current.backendUrl, projectId: current.projectId, environment: current.environment })}.`
+      );
+    }
+    return;
+  }
+  state.config = { ...config };
+};
+var manifest = () => {
+  const state = getState();
+  const config = state.config;
+  if (!config) {
+    return Promise.reject(new Error(NOT_CONFIGURED));
+  }
+  if (!state.manifestPromise) {
+    const attempt = fetchManifest(config);
+    state.manifestPromise = attempt;
+    attempt.catch(() => {
+      if (state.manifestPromise === attempt) {
+        state.manifestPromise = null;
+      }
+    });
+  }
+  return state.manifestPromise;
+};
+var remoteUrl = async (slug) => {
+  const { microfrontends } = await manifest();
+  const found = microfrontends.find((microfrontend) => microfrontend.slug === slug);
+  if (!found) {
+    const available = microfrontends.map((microfrontend) => `"${microfrontend.slug}"`).join(", ");
+    const { environment } = getState().config ?? { environment: "?" };
+    throw new Error(`${PREFIX} unknown microfrontend slug "${slug}". Available in environment "${environment}": ${available || "none, this environment serves no microfrontend"}.`);
+  }
+  if (!found.url) {
+    throw new Error(`${PREFIX} the microfrontend "${slug}" is in the manifest but carries no url. Check its deployment in the console.`);
+  }
+  return found.url;
+};
+var globalVariables = async () => {
+  const { globalVariables: variables } = await manifest();
+  const result = {};
+  for (const variable of variables) {
+    if (variable && typeof variable.key === "string") {
+      result[variable.key] = variable.value;
+    }
+  }
+  return result;
+};
+var identities = () => {
+  const state = getState();
+  if (!state.identities) {
+    state.identities = readIdentities();
+  }
+  return state.identities;
+};
+
+export { configure, globalVariables, identities, manifest, remoteUrl };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state.ts","../src/storage.ts","../src/index.ts"],"names":["created"],"mappings":"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","file":"index.js","sourcesContent":["import type { Identities, Manifest, OrchestratorConfig } from \"./types\"\n\nexport interface OrchestratorState {\n    config: OrchestratorConfig | null\n    manifestPromise: Promise<Manifest> | null\n    identities: Identities | null\n}\n\n/**\n * The state lives on `globalThis` under this key, not in a module scope variable.\n *\n * A host can end up with two copies of this package loaded at once: the app imports the ESM build\n * while something else pulls the CJS one, or the bundler config and the app resolve to different\n * chunks. Two module scopes would mean two configurations and two manifest requests, which is\n * exactly what the contract forbids. One well known global slot makes the singleton real.\n */\nexport const STATE_KEY = \"__mfe_orchestrator_client__\"\n\nconst globalSlot = globalThis as typeof globalThis & Record<typeof STATE_KEY, OrchestratorState | undefined>\n\nexport const getState = (): OrchestratorState => {\n    let state = globalSlot[STATE_KEY]\n    if (!state) {\n        state = { config: null, manifestPromise: null, identities: null }\n        globalSlot[STATE_KEY] = state\n    }\n    return state\n}\n","import type { Identities } from \"./types\"\n\nexport const SESSION_ID_KEY = \"mfe-orchestrator.sessionId\"\nexport const DEVICE_ID_KEY = \"mfe-orchestrator.deviceId\"\n\nconst PROBE_KEY = \"mfe-orchestrator.probe\"\n\ntype StorageKind = \"local\" | \"session\"\n\n/**\n * Ids minted while storage was unusable. They live for the lifetime of the page so that, even\n * without storage, every request of this page load carries one stable pair of ids.\n */\nconst inMemoryIds = new Map<string, string>()\n\nconst uuidFromRandomBytes = (bytes: Uint8Array): string => {\n    bytes[6] = (bytes[6] & 0x0f) | 0x40\n    bytes[8] = (bytes[8] & 0x3f) | 0x80\n    const hex: string[] = []\n    for (const byte of bytes) {\n        hex.push(byte.toString(16).padStart(2, \"0\"))\n    }\n    return `${hex.slice(0, 4).join(\"\")}-${hex.slice(4, 6).join(\"\")}-${hex.slice(6, 8).join(\"\")}-${hex.slice(8, 10).join(\"\")}-${hex.slice(10, 16).join(\"\")}`\n}\n\n/**\n * A v4 UUID. `crypto.randomUUID` is the intended path; the two fallbacks only exist so that a page\n * served over plain http, or an exotic runtime, still gets an id instead of an exception.\n */\nexport const newId = (): string => {\n    const cryptoApi = globalThis.crypto\n    try {\n        if (typeof cryptoApi?.randomUUID === \"function\") {\n            return cryptoApi.randomUUID()\n        }\n        if (typeof cryptoApi?.getRandomValues === \"function\") {\n            return uuidFromRandomBytes(cryptoApi.getRandomValues(new Uint8Array(16)))\n        }\n    } catch {\n        // fall through to the non cryptographic fallback\n    }\n    const bytes = new Uint8Array(16)\n    for (let index = 0; index < bytes.length; index++) {\n        bytes[index] = Math.floor(Math.random() * 256)\n    }\n    return uuidFromRandomBytes(bytes)\n}\n\n/**\n * The requested storage, or `null` when it is missing or unusable.\n *\n * Both the property access and the write can throw: Safari in private mode exposes the object and\n * then refuses `setItem`, some hardened browsers throw a SecurityError on the access itself. The\n * write probe is the only reliable way to tell a usable storage from a decorative one.\n */\nconst openStorage = (kind: StorageKind): Storage | null => {\n    try {\n        const storage = kind === \"local\" ? globalThis.localStorage : globalThis.sessionStorage\n        if (!storage) {\n            return null\n        }\n        storage.setItem(PROBE_KEY, \"1\")\n        storage.removeItem(PROBE_KEY)\n        return storage\n    } catch {\n        return null\n    }\n}\n\n/**\n * The id under `key`, read from storage and created on first use. Falls back to an id kept in\n * memory when storage cannot be used, so this never throws out of the SDK.\n */\nconst persistentId = (kind: StorageKind, key: string): string => {\n    const storage = openStorage(kind)\n    if (storage) {\n        try {\n            const stored = storage.getItem(key)\n            if (stored) {\n                return stored\n            }\n            const created = newId()\n            storage.setItem(key, created)\n            return created\n        } catch {\n            // storage passed the probe and failed anyway: keep going with an in memory id\n        }\n    }\n    const remembered = inMemoryIds.get(key)\n    if (remembered) {\n        return remembered\n    }\n    const created = newId()\n    inMemoryIds.set(key, created)\n    return created\n}\n\n/** Reads, and creates when needed, the session and device ids. */\nexport const readIdentities = (): Identities => ({\n    sessionId: persistentId(\"session\", SESSION_ID_KEY),\n    deviceId: persistentId(\"local\", DEVICE_ID_KEY)\n})\n","import { getState } from \"./state\"\nimport { readIdentities } from \"./storage\"\nimport type { Identities, Manifest, OrchestratorConfig } from \"./types\"\n\nexport type { GlobalVariable, Identities, Manifest, Microfrontend, OrchestratorConfig } from \"./types\"\n\nconst PREFIX = \"[@mfe-orchestrator-hub/client]\"\n\nconst NOT_CONFIGURED = `${PREFIX} call configure() first. Configure the client at the very top of the host entry point, before anything imports a remote:\n\n    import { configure } from \"@mfe-orchestrator-hub/client\"\n\n    configure({ backendUrl: \"…\", projectId: \"…\", environment: \"…\" })`\n\nconst withoutTrailingSlash = (value: string): string => value.replace(/\\/+$/, \"\")\n\nconst resolveUserId = async (userId: OrchestratorConfig[\"userId\"]): Promise<string | undefined> => {\n    const value = typeof userId === \"function\" ? await userId() : userId\n    return value === undefined || value === null || value === \"\" ? undefined : String(value)\n}\n\nconst sameConfig = (left: OrchestratorConfig, right: OrchestratorConfig): boolean =>\n    left.backendUrl === right.backendUrl && left.projectId === right.projectId && left.environment === right.environment && left.userId === right.userId\n\nconst requireConfig = (config: OrchestratorConfig): void => {\n    const missing = ([\"backendUrl\", \"projectId\", \"environment\"] as const).filter(key => !config?.[key])\n    if (missing.length > 0) {\n        throw new Error(`${PREFIX} configure() is missing required option${missing.length > 1 ? \"s\" : \"\"}: ${missing.join(\", \")}.`)\n    }\n}\n\nconst manifestUrl = async (config: OrchestratorConfig): Promise<string> => {\n    const { sessionId, deviceId } = identities()\n    const query = new URLSearchParams({ mfeSessionId: sessionId, mfeDeviceId: deviceId })\n    // Resolved as late as possible: the host may only know the user after its own auth round trip.\n    const userId = await resolveUserId(config.userId)\n    if (userId) {\n        query.set(\"mfeUserId\", userId)\n    }\n    return `${withoutTrailingSlash(config.backendUrl)}/serve/all/${encodeURIComponent(config.projectId)}/${encodeURIComponent(config.environment)}?${query.toString()}`\n}\n\nconst fetchManifest = async (config: OrchestratorConfig): Promise<Manifest> => {\n    const url = await manifestUrl(config)\n    // No retry in v1: whatever fetch throws travels straight to the caller.\n    const response = await fetch(url, { headers: { accept: \"application/json\" } })\n    if (!response.ok) {\n        throw new Error(`${PREFIX} the manifest request failed with ${response.status} ${response.statusText}. GET ${url}`)\n    }\n    const payload = (await response.json()) as Partial<Manifest> | null\n    return {\n        globalVariables: payload?.globalVariables ?? [],\n        microfrontends: payload?.microfrontends ?? []\n    }\n}\n\n/**\n * Hands the client its configuration. Call it once, synchronously, before any remote is imported.\n *\n * Idempotent: calling it again with the same options is a no op, so a framework provider may safely\n * call it on every render. A second call with different options is ignored, with a warning, because\n * the manifest of this page load may already be in flight or resolved.\n */\nexport const configure = (config: OrchestratorConfig): void => {\n    requireConfig(config)\n    const state = getState()\n    const current = state.config\n    if (current) {\n        if (!sameConfig(current, config)) {\n            console.warn(\n                `${PREFIX} configure() was called again with a different configuration. The first one is kept: ${JSON.stringify({ backendUrl: current.backendUrl, projectId: current.projectId, environment: current.environment })}.`\n            )\n        }\n        return\n    }\n    state.config = { ...config }\n}\n\n/**\n * The whole manifest of the environment, fetched once per page load and memoized as a promise, so\n * that concurrent callers share the single request in flight.\n *\n * A successful result is memoized for good. A failed attempt is not: the memo is dropped when the\n * shared attempt settles as rejected, so the next caller starts a fresh request. That is not a retry\n * — nothing here loops or backs off — it only means one flaky lookup at boot does not condemn the\n * page to reject every `remoteUrl()` until a full reload.\n */\nexport const manifest = (): Promise<Manifest> => {\n    const state = getState()\n    const config = state.config\n    if (!config) {\n        // Not memoized: the host may still configure the client and try again.\n        return Promise.reject(new Error(NOT_CONFIGURED))\n    }\n    if (!state.manifestPromise) {\n        // Assigned before the first await inside fetchManifest, which is what makes N concurrent\n        // callers collapse onto one request.\n        const attempt = fetchManifest(config)\n        state.manifestPromise = attempt\n        // Cleared once, when the shared attempt settles, not in each caller's own catch: every\n        // caller already waiting on this attempt still gets its rejection. The identity check keeps\n        // a late failure from evicting a newer attempt.\n        attempt.catch(() => {\n            if (state.manifestPromise === attempt) {\n                state.manifestPromise = null\n            }\n        })\n    }\n    return state.manifestPromise\n}\n\n/**\n * The ready to use, version pinned URL of a remote. Awaits the manifest internally.\n *\n * The returned URL is used verbatim: the host never parses the version out of it and never strips\n * the `_v/<version>/` segment, or a classic script would load its chunks off another version.\n */\nexport const remoteUrl = async (slug: string): Promise<string> => {\n    const { microfrontends } = await manifest()\n    const found = microfrontends.find(microfrontend => microfrontend.slug === slug)\n    if (!found) {\n        const available = microfrontends.map(microfrontend => `\"${microfrontend.slug}\"`).join(\", \")\n        const { environment } = getState().config ?? { environment: \"?\" }\n        throw new Error(`${PREFIX} unknown microfrontend slug \"${slug}\". Available in environment \"${environment}\": ${available || \"none, this environment serves no microfrontend\"}.`)\n    }\n    if (!found.url) {\n        throw new Error(`${PREFIX} the microfrontend \"${slug}\" is in the manifest but carries no url. Check its deployment in the console.`)\n    }\n    return found.url\n}\n\n/** The global variables of the environment, as a plain object. */\nexport const globalVariables = async (): Promise<Record<string, string>> => {\n    const { globalVariables: variables } = await manifest()\n    const result: Record<string, string> = {}\n    for (const variable of variables) {\n        if (variable && typeof variable.key === \"string\") {\n            result[variable.key] = variable.value\n        }\n    }\n    return result\n}\n\n/**\n * The session and device ids of this page, exposed for telemetry and debugging. Created on first\n * use and stable for the lifetime of the page, whether or not storage is available.\n */\nexport const identities = (): Identities => {\n    const state = getState()\n    if (!state.identities) {\n        state.identities = readIdentities()\n    }\n    return state.identities\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "@mfe-orchestrator-hub/client",
+    "version": "0.1.0",
+    "description": "Framework agnostic client for MFE Orchestrator: resolves version pinned microfrontend URLs from the console manifest",
+    "license": "MIT",
+    "author": "Lorenzo De Francesco",
+    "type": "module",
+    "packageManager": "pnpm@10.19.0",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "keywords": [
+        "mfe",
+        "microfrontend",
+        "module-federation",
+        "orchestrator",
+        "vite",
+        "webpack"
+    ],
+    "homepage": "https://github.com/mfe-orchestrator/client-core#readme",
+    "bugs": {
+        "url": "https://github.com/mfe-orchestrator/client-core/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mfe-orchestrator/client-core.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        },
+        "./package.json": "./package.json"
+    },
+    "sideEffects": false,
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome lint --write ./src ./test",
+        "format": "biome format --write ./src ./test",
+        "prepublishOnly": "pnpm build"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.5.7",
+        "tsup": "^8.5.0",
+        "typescript": "^5.9.3",
+        "vitest": "^3.2.4"
+    }
+}