@clearly-hub/node 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,668 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  clearlyHub: () => clearlyHub
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../shared/src/screens.ts
+var SCREEN_ACTIONS = [
+  "SELECT_SUBSCRIPTION",
+  "DATA_PICKER",
+  "REGISTER_RESOURCE",
+  "SELECT_HUB"
+];
+function isScreenAction(value) {
+  return SCREEN_ACTIONS.includes(value);
+}
+
+// ../shared/src/protocol.ts
+var DEFAULT_BASE_PATH = "/clearly-hub";
+var DEFAULT_HUB_URL = "https://hub.clearly.app";
+var DEFAULT_AUTH_URL = "https://auth.clearly.app";
+var DEFAULT_ISSUER = "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_1fM1Zd9mJ";
+var ROUTES = {
+  signIn: "/sign-in",
+  callback: "/callback",
+  signOut: "/sign-out",
+  session: "/session",
+  open: "/open",
+  answer: "/answer",
+  result: "/result"
+};
+var ANSWER_CHANNEL = "clearly-hub-answers";
+
+// src/config.ts
+var trimSlash = (url) => url.replace(/\/+$/, "");
+function resolveConfig(options) {
+  if (!options.clientId) throw new Error("Clearly.HUB: clientId is required");
+  if (!options.appUrl) throw new Error("Clearly.HUB: appUrl is required");
+  if (!options.secret || options.secret.length < 32) {
+    throw new Error("Clearly.HUB: secret must be at least 32 characters");
+  }
+  const appUrl = trimSlash(options.appUrl);
+  const hubUrl = trimSlash(options.hubUrl ?? DEFAULT_HUB_URL);
+  const api = trimSlash(options.urls?.api ?? hubUrl);
+  return {
+    clientId: options.clientId,
+    m2mClientId: options.m2mClientId,
+    m2mClientSecret: options.m2mClientSecret,
+    appUrl,
+    secret: options.secret,
+    basePath: trimSlash(options.basePath ?? DEFAULT_BASE_PATH),
+    hubUrl,
+    urls: {
+      screens: trimSlash(options.urls?.screens ?? `${hubUrl}/components`),
+      api,
+      usage: options.urls?.usage ?? `${hubUrl}/register-usage`,
+      publicKey: options.urls?.publicKey ?? `${api}/.well-known/public-key.pem`,
+      auth: trimSlash(options.urls?.auth ?? DEFAULT_AUTH_URL),
+      issuer: options.urls?.issuer ?? DEFAULT_ISSUER
+    },
+    signedOutUrl: options.signedOutUrl ?? appUrl,
+    onSignIn: options.onSignIn,
+    onAnswer: options.onAnswer,
+    fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+    isSecure: appUrl.startsWith("https://")
+  };
+}
+
+// src/express.ts
+function toNodeMiddleware(handle, appUrl) {
+  return async (req, res, next) => {
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value)) value.forEach((item) => headers.append(name, item));
+        else if (value !== void 0) headers.set(name, value);
+      }
+      const url = new URL(req.originalUrl ?? req.url ?? "/", appUrl);
+      const response = await handle(new Request(url, { method: req.method, headers }));
+      if (response.headers.get("X-Clearly-Hub") === "unhandled" && next) {
+        next();
+        return;
+      }
+      res.statusCode = response.status;
+      response.headers.forEach((value, name) => {
+        if (name !== "set-cookie") res.setHeader(name, value);
+      });
+      const cookies = response.headers.getSetCookie();
+      if (cookies.length) res.setHeader("Set-Cookie", cookies);
+      res.end(Buffer.from(await response.arrayBuffer()));
+    } catch (error) {
+      if (next) next(error);
+      else {
+        res.statusCode = 500;
+        res.end("Internal error");
+      }
+    }
+  };
+}
+
+// src/screens.ts
+var Screens = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  publicKey;
+  get answerUrl() {
+    return `${this.config.appUrl}${this.config.basePath}/answer`;
+  }
+  screenUrl(action, state, email, data) {
+    const request = {
+      actions: [action],
+      client_id: this.config.clientId,
+      // Must be one of your sign-in client's callback URLs, exactly
+      redirect_url: this.answerUrl,
+      state,
+      // Clearly.HUB warns when someone else is signed in there
+      email,
+      data
+    };
+    return `${this.config.urls.screens}/${base64Encode(JSON.stringify(request))}`;
+  }
+  // Checks the signature and returns the answer. Ed25519, over the base64 text
+  // of `data` as it arrived.
+  async readAnswer(data, signature) {
+    const isSigned = await crypto.subtle.verify(
+      "Ed25519",
+      await this.getPublicKey(),
+      base64Decode(signature),
+      new TextEncoder().encode(data)
+    );
+    if (!isSigned) throw new AnswerError("This answer was not signed by Clearly.HUB");
+    const { request, response } = JSON.parse(new TextDecoder().decode(base64Decode(data)));
+    return { state: request.state, response };
+  }
+  // Fetched once; a key change needs a restart
+  getPublicKey() {
+    this.publicKey ??= this.config.fetch(this.config.urls.publicKey).then((response) => {
+      if (!response.ok) throw new Error(`No public key at ${this.config.urls.publicKey}`);
+      return response.text();
+    }).then((pem) => crypto.subtle.importKey("spki", pemToDer(pem), "Ed25519", false, ["verify"])).catch((error) => {
+      this.publicKey = void 0;
+      throw error;
+    });
+    return this.publicKey;
+  }
+};
+var AnswerError = class extends Error {
+};
+function toScreenResult(action, response) {
+  const { result, ...answer } = response;
+  if (result === "SUCCESS") return { action, result: "SUCCESS", answer };
+  return { action, result: result === "FAILURE" ? "FAILURE" : "CANCELLED" };
+}
+function base64Encode(text) {
+  return btoa(String.fromCharCode(...new TextEncoder().encode(text)));
+}
+function base64Decode(base64) {
+  return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+}
+function pemToDer(pem) {
+  return base64Decode(pem.replace(/-----[A-Z ]+-----/g, "").replace(/\s/g, ""));
+}
+function readRawQuery(url) {
+  const params = /* @__PURE__ */ new Map();
+  for (const pair of url.search.slice(1).split("&")) {
+    const index = pair.indexOf("=");
+    if (index > 0) params.set(pair.slice(0, index), decodeURIComponent(pair.slice(index + 1)));
+  }
+  return params;
+}
+
+// src/handler.ts
+var SCREEN_TTL_MS = 30 * 60 * 1e3;
+var MAX_PENDING_SCREENS = 10;
+function createHandler(parts) {
+  const { config, sessions } = parts;
+  return async function handle(request) {
+    const url = new URL(request.url);
+    if (!url.pathname.startsWith(config.basePath)) return notFound();
+    const route = url.pathname.slice(config.basePath.length) || "/";
+    if (request.method !== "GET") return new Response("Method not allowed", { status: 405 });
+    const { data, chunkCount } = await sessions.read(request);
+    const before = JSON.stringify(data);
+    let response;
+    try {
+      response = await routeRequest(route, url, data, parts);
+    } catch (error) {
+      response = errorPage(error instanceof AnswerError ? 400 : 500, error.message);
+    }
+    if (JSON.stringify(data) !== before) {
+      for (const cookie of await sessions.write(data, chunkCount)) {
+        response.headers.append("Set-Cookie", cookie);
+      }
+    }
+    return response;
+  };
+}
+async function routeRequest(route, url, session, parts) {
+  switch (route) {
+    case ROUTES.signIn:
+      return startSignIn(url, session, parts);
+    case ROUTES.callback:
+      return finishSignIn(url, session, parts);
+    case ROUTES.signOut:
+      for (const key of Object.keys(session)) delete session[key];
+      return redirect(parts.signIn.signOutUrl());
+    case ROUTES.session:
+      return json(await readSession(session, parts));
+    case ROUTES.open:
+      return openScreen(url, session, parts);
+    case ROUTES.answer:
+      return receiveAnswer(url, session, parts);
+    case ROUTES.result: {
+      const result = session.result ?? null;
+      delete session.result;
+      return json(result);
+    }
+    default:
+      return notFound();
+  }
+}
+async function startSignIn(url, session, { config, signIn }) {
+  const { url: authorizationUrl, pending } = await signIn.start(safeReturnTo(url, config));
+  session.signIn = pending;
+  return redirect(authorizationUrl);
+}
+async function finishSignIn(url, session, { config, signIn }) {
+  const pending = session.signIn;
+  if (!pending) return redirect(config.appUrl);
+  delete session.signIn;
+  const currentUrl = new URL(`${signIn.callbackUrl}${url.search}`);
+  const { person, tokens } = await signIn.finish(currentUrl, pending);
+  const appUserId = await config.onSignIn?.(person) ?? void 0;
+  session.user = { ...person, appUserId };
+  session.tokens = tokens;
+  return redirect(`${config.appUrl}${pending.returnTo}`);
+}
+async function readSession(session, parts) {
+  const accessToken = await getFreshAccessToken(session, parts);
+  if (!session.user || !accessToken) return { signedIn: false };
+  return { signedIn: true, user: session.user };
+}
+async function getFreshAccessToken(session, { signIn }) {
+  const tokens = session.tokens;
+  if (!tokens) return void 0;
+  if (tokens.expiresAt > Date.now() / 1e3 + 60) return tokens.accessToken;
+  if (!tokens.refreshToken) return void 0;
+  try {
+    session.tokens = await signIn.refresh(tokens.refreshToken);
+    return session.tokens.accessToken;
+  } catch {
+    delete session.tokens;
+    delete session.user;
+    return void 0;
+  }
+}
+function openScreen(url, session, { config, screens }) {
+  const action = url.searchParams.get("action");
+  if (!isScreenAction(action)) return errorPage(400, `Unknown screen: ${action}`);
+  const display = url.searchParams.get("display") === "redirect" ? "redirect" : "popup";
+  const dataParam = url.searchParams.get("data");
+  const state = crypto.randomUUID();
+  session.screens = pruneScreens(session.screens);
+  session.screens[state] = {
+    action,
+    display,
+    ref: url.searchParams.get("ref") ?? state,
+    returnTo: safeReturnTo(url, config),
+    createdAt: Date.now()
+  };
+  return redirect(
+    screens.screenUrl(
+      action,
+      state,
+      session.user?.email,
+      dataParam ? JSON.parse(dataParam) : void 0
+    )
+  );
+}
+async function receiveAnswer(url, session, { config, screens }) {
+  const query = readRawQuery(url);
+  const { state, response } = await screens.readAnswer(
+    query.get("data") ?? "",
+    query.get("signature") ?? ""
+  );
+  const pending = state ? session.screens?.[state] : void 0;
+  if (!pending || Date.now() - pending.createdAt > SCREEN_TTL_MS) {
+    throw new AnswerError("This answer does not belong to a screen opened in this browser");
+  }
+  delete session.screens[state];
+  let result = toScreenResult(pending.action, response);
+  try {
+    await config.onAnswer?.(result, { user: session.user });
+  } catch (error) {
+    result = { action: pending.action, result: "FAILURE", error: error.message };
+  }
+  if (pending.display === "redirect") {
+    session.result = { ref: pending.ref, result };
+    return redirect(`${config.appUrl}${pending.returnTo}`);
+  }
+  return popupHandOver({ ref: pending.ref, result });
+}
+function popupHandOver(message) {
+  const payload = JSON.stringify(message).replace(/</g, "\\u003c");
+  return html(`<!doctype html>
+<meta charset="utf-8">
+<title>Clearly.HUB</title>
+<p>Done. You can close this window.</p>
+<script>
+  new BroadcastChannel(${JSON.stringify(ANSWER_CHANNEL)}).postMessage(${payload});
+  window.close();
+</script>`);
+}
+function pruneScreens(screens = {}) {
+  const fresh = Object.entries(screens).filter(([, screen]) => Date.now() - screen.createdAt < SCREEN_TTL_MS).slice(-(MAX_PENDING_SCREENS - 1));
+  return Object.fromEntries(fresh);
+}
+function safeReturnTo(url, config) {
+  const returnTo = url.searchParams.get("returnTo") ?? "/";
+  if (!returnTo.startsWith("/") || returnTo.startsWith("//")) return "/";
+  try {
+    return new URL(returnTo, config.appUrl).origin === new URL(config.appUrl).origin ? returnTo : "/";
+  } catch {
+    return "/";
+  }
+}
+var redirect = (location) => new Response(null, { status: 302, headers: { Location: location } });
+var json = (body) => new Response(JSON.stringify(body), {
+  headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
+});
+var html = (body, status = 200) => new Response(body, { status, headers: { "Content-Type": "text/html; charset=utf-8" } });
+var notFound = () => new Response("Not found", { status: 404, headers: { "X-Clearly-Hub": "unhandled" } });
+function errorPage(status, message) {
+  const escaped = message.replace(/[&<>"]/g, (char) => `&#${char.charCodeAt(0)};`);
+  return html(
+    `<!doctype html><meta charset="utf-8"><title>Clearly.HUB</title><p>${escaped}</p>`,
+    status
+  );
+}
+
+// src/hubApi.ts
+var SUBSCRIPTIONS_CACHE_MS = 3e4;
+var HubApi = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  appToken;
+  subscriptions;
+  get hasAppKey() {
+    return Boolean(this.config.m2mClientId && this.config.m2mClientSecret);
+  }
+  // Your app's own key: OAuth client credentials for its M2M client, cached
+  // until shortly before it expires
+  async getAppToken() {
+    const now = Date.now() / 1e3;
+    if (this.appToken && this.appToken.expiresAt > now + 60) return this.appToken.value;
+    if (!this.hasAppKey) {
+      throw new Error("Clearly.HUB: m2mClientId and m2mClientSecret are needed for this");
+    }
+    const credentials = btoa(`${this.config.m2mClientId}:${this.config.m2mClientSecret}`);
+    const response = await this.config.fetch(`${this.config.urls.auth}/oauth2/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Authorization: `Basic ${credentials}`
+      },
+      body: new URLSearchParams({
+        grant_type: "client_credentials",
+        scope: "CallbackScopes/data.usage"
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Clearly.HUB refused the app's key (${response.status})`);
+    }
+    const body = await response.json();
+    this.appToken = { value: body.access_token, expiresAt: now + body.expires_in };
+    return body.access_token;
+  }
+  // Every hub that bought your app, with status and your plan id
+  async getSubscriptions() {
+    if (this.subscriptions && Date.now() - this.subscriptions.fetchedAt < SUBSCRIPTIONS_CACHE_MS) {
+      return this.subscriptions.value;
+    }
+    const response = await this.config.fetch(`${this.config.urls.api}/api/app-api/subscriptions`, {
+      headers: { Authorization: `Bearer ${await this.getAppToken()}` }
+    });
+    if (!response.ok) {
+      throw new Error(`Could not read the subscriptions from Clearly.HUB (${response.status})`);
+    }
+    const items = await response.json();
+    const value = items.map((item) => ({
+      subscriptionId: item.subscriptionId,
+      status: item.status,
+      hubId: item.hubId,
+      hubName: item.hubName,
+      planName: item.planName,
+      planId: item.externalReference || void 0
+    }));
+    this.subscriptions = { value, fetchedAt: Date.now() };
+    return value;
+  }
+  // Report one billable use; Clearly.HUB bills the hub
+  async reportUsage(usage) {
+    const response = await this.config.fetch(this.config.urls.usage, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        // This endpoint wants the token without "Bearer", for now
+        Authorization: await this.getAppToken()
+      },
+      body: JSON.stringify({
+        clientId: this.config.m2mClientId,
+        userId: usage.sub,
+        activeHubId: usage.hubId,
+        subscriptionId: usage.subscriptionId,
+        quantity: usage.quantity
+      })
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw new Error(`Clearly.HUB did not accept the usage: ${body.message ?? response.status}`);
+    }
+  }
+};
+function pickSubscription(subscriptions, hubId) {
+  const ofHub = subscriptions.filter((subscription) => subscription.hubId === hubId);
+  return ofHub.find((s) => s.status === "ACTIVE") ?? ofHub.find((s) => s.status === "PENDING");
+}
+
+// src/oidc.ts
+var oidc = __toESM(require("openid-client"), 1);
+var SignIn = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  configuration;
+  get callbackUrl() {
+    return `${this.config.appUrl}${this.config.basePath}/callback`;
+  }
+  // Discovery happens once, on the first sign-in
+  getConfiguration() {
+    this.configuration ??= oidc.discovery(new URL(this.config.urls.issuer), this.config.clientId, void 0, oidc.None()).catch((error) => {
+      this.configuration = void 0;
+      throw error;
+    });
+    return this.configuration;
+  }
+  async start(returnTo) {
+    const configuration = await this.getConfiguration();
+    const codeVerifier = oidc.randomPKCECodeVerifier();
+    const state = oidc.randomState();
+    const nonce = oidc.randomNonce();
+    const url = oidc.buildAuthorizationUrl(configuration, {
+      redirect_uri: this.callbackUrl,
+      scope: "openid email profile",
+      code_challenge: await oidc.calculatePKCECodeChallenge(codeVerifier),
+      code_challenge_method: "S256",
+      state,
+      nonce
+    });
+    return { url: url.href, pending: { codeVerifier, state, nonce, returnTo } };
+  }
+  async finish(currentUrl, pending) {
+    const tokens = await oidc.authorizationCodeGrant(await this.getConfiguration(), currentUrl, {
+      pkceCodeVerifier: pending.codeVerifier,
+      expectedState: pending.state,
+      expectedNonce: pending.nonce
+    });
+    const claims = tokens.claims();
+    if (!claims) throw new Error("Clearly.HUB sent no ID token");
+    return {
+      person: {
+        sub: claims.sub,
+        email: String(claims.email ?? ""),
+        name: typeof claims.name === "string" ? claims.name : void 0
+      },
+      tokens: toSessionTokens(tokens)
+    };
+  }
+  async refresh(refreshToken) {
+    const tokens = await oidc.refreshTokenGrant(await this.getConfiguration(), refreshToken);
+    return toSessionTokens(tokens, refreshToken);
+  }
+  // Signing out of Clearly.HUB too, or the next sign-in goes straight through
+  signOutUrl() {
+    const url = new URL(`${this.config.urls.auth}/logout`);
+    url.searchParams.set("client_id", this.config.clientId);
+    url.searchParams.set("logout_uri", this.config.signedOutUrl);
+    return url.href;
+  }
+};
+function toSessionTokens(tokens, previousRefreshToken) {
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? previousRefreshToken,
+    expiresAt: Math.floor(Date.now() / 1e3) + (tokens.expiresIn() ?? 3600)
+  };
+}
+
+// src/session.ts
+var import_jose = require("jose");
+var COOKIE_NAME = "clearly_hub";
+var CHUNK_SIZE = 3800;
+var MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+function readCookieHeader(source) {
+  if (source instanceof Request) return source.headers.get("cookie") ?? "";
+  const header = source.headers.cookie;
+  return Array.isArray(header) ? header.join("; ") : header ?? "";
+}
+function parseCookies(header) {
+  const cookies = /* @__PURE__ */ new Map();
+  for (const part of header.split(";")) {
+    const index = part.indexOf("=");
+    if (index > 0) cookies.set(part.slice(0, index).trim(), part.slice(index + 1).trim());
+  }
+  return cookies;
+}
+async function deriveKey(secret) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+  return new Uint8Array(digest);
+}
+var SessionStore = class {
+  constructor(config) {
+    this.config = config;
+    this.keyPromise = deriveKey(config.secret);
+  }
+  config;
+  keyPromise;
+  async read(source) {
+    const cookies = parseCookies(readCookieHeader(source));
+    const chunks = [];
+    for (let i = 0; cookies.has(`${COOKIE_NAME}.${i}`); i++) {
+      chunks.push(cookies.get(`${COOKIE_NAME}.${i}`));
+    }
+    if (!chunks.length) return { data: {}, chunkCount: 0 };
+    try {
+      const { plaintext } = await (0, import_jose.compactDecrypt)(chunks.join(""), await this.keyPromise);
+      return { data: JSON.parse(new TextDecoder().decode(plaintext)), chunkCount: chunks.length };
+    } catch {
+      return { data: {}, chunkCount: chunks.length };
+    }
+  }
+  // Set-Cookie headers for the new session, clearing chunks it no longer needs
+  async write(data, previousChunkCount) {
+    const isEmpty = Object.keys(data).length === 0;
+    const chunks = isEmpty ? [] : (await this.encrypt(data)).match(new RegExp(`.{1,${CHUNK_SIZE}}`, "g"));
+    const attributes = `Path=/; HttpOnly; SameSite=Lax${this.config.isSecure ? "; Secure" : ""}`;
+    const headers = chunks.map(
+      (chunk, i) => `${COOKIE_NAME}.${i}=${chunk}; Max-Age=${MAX_AGE_SECONDS}; ${attributes}`
+    );
+    for (let i = chunks.length; i < previousChunkCount; i++) {
+      headers.push(`${COOKIE_NAME}.${i}=; Max-Age=0; ${attributes}`);
+    }
+    return headers;
+  }
+  async encrypt(data) {
+    return new import_jose.CompactEncrypt(new TextEncoder().encode(JSON.stringify(data))).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).encrypt(await this.keyPromise);
+  }
+};
+
+// src/index.ts
+function clearlyHub(options) {
+  const config = resolveConfig(options);
+  const parts = {
+    config,
+    sessions: new SessionStore(config),
+    signIn: new SignIn(config),
+    screens: new Screens(config),
+    api: new HubApi(config)
+  };
+  const handler = createHandler(parts);
+  if (!parts.api.hasAppKey) {
+    console.warn(
+      'Clearly.HUB: no m2mClientId/m2mClientSecret. Every hub shows "no subscription", and getSubscription() and reportUsage() fail.'
+    );
+  }
+  async function getUserToken(request) {
+    const { data } = await parts.sessions.read(request);
+    return getFreshAccessToken(data, parts);
+  }
+  return {
+    // Mount for any fetch-style server: Next.js route handlers, Hono, Bun, Deno
+    handler,
+    // Mount in Express: app.use('/clearly-hub', hub.express())
+    express: () => toNodeMiddleware(handler, config.appUrl),
+    // Who's signed in, for your own routes
+    async getUser(request) {
+      const { data } = await parts.sessions.read(request);
+      return data.user ?? null;
+    },
+    getUserToken,
+    // Fetch protected or paid data (for example from DATA_PICKER) with the
+    // person's key. Open data works without it.
+    async fetchAsUser(request, url, init = {}) {
+      const token = await getUserToken(request);
+      if (!token) throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
+      const headers = new Headers(init.headers);
+      headers.set("Authorization", token);
+      return config.fetch(url, { ...init, headers });
+    },
+    // Your app's own key, for calls of your own to Clearly.HUB
+    getAppToken: () => parts.api.getAppToken(),
+    // Every hub that bought your app
+    getSubscriptions: () => parts.api.getSubscriptions(),
+    // A hub's subscription to your app: the active one, else one waiting for
+    // your approval, else null
+    async getSubscription(hubId) {
+      return pickSubscription(await parts.api.getSubscriptions(), hubId) ?? null;
+    },
+    // Report billable use by the signed-in person in a hub
+    async reportUsage({
+      request,
+      hubId,
+      quantity = 1
+    }) {
+      const { data } = await parts.sessions.read(request);
+      if (!data.user) throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
+      const subscription = pickSubscription(await parts.api.getSubscriptions(), hubId);
+      if (subscription?.status !== "ACTIVE") {
+        throw new Error(`Clearly.HUB: hub ${hubId} has no active subscription to your app`);
+      }
+      await parts.api.reportUsage({
+        sub: data.user.sub,
+        hubId,
+        subscriptionId: subscription.subscriptionId,
+        quantity
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearlyHub
+});