@opengeni/sdk 3.1.0 → 3.1.2

package/dist/workspace-integrations.js

@@ -0,0 +1,65 @@
+import {
+  OPENGENI_DELIVERY_ID_HEADER,
+  OPENGENI_EVENT_ID_HEADER,
+  OPENGENI_SIGNATURE_HEADER,
+  OPENGENI_TEST_REQUEST_NIL_ID,
+  OPENGENI_WEBHOOK_HEADERS,
+  OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+  OpenGeniSignatureError,
+  WORKSPACE_WEBHOOK_EVENT_TYPES,
+  createOrganizationWebhook,
+  deleteOrganizationCredentialProvider,
+  deleteOrganizationWebhook,
+  getOrganizationCredentialProvider,
+  getOrganizationWebhook,
+  getWorkspaceInheritedIntegrations,
+  getWorkspaceWebhook,
+  listOrganizationWebhookDeliveries,
+  listOrganizationWebhooks,
+  putOrganizationCredentialProvider,
+  redeliverOrganizationWebhookDelivery,
+  rotateOrganizationCredentialProviderSecret,
+  rotateOrganizationWebhookSecret,
+  rotateWorkspaceCredentialProviderSecret,
+  rotateWorkspaceWebhookSecret,
+  signOpenGeniPayload,
+  testWorkspaceCredentialProvider,
+  testWorkspaceWebhook,
+  updateOrganizationWebhook,
+  verifyCredentialProviderRequest,
+  verifyOpenGeniSignature,
+  verifyWebhookEvent
+} from "./chunk-RJHCBZF7.js";
+export {
+  OPENGENI_DELIVERY_ID_HEADER,
+  OPENGENI_EVENT_ID_HEADER,
+  OPENGENI_SIGNATURE_HEADER,
+  OPENGENI_TEST_REQUEST_NIL_ID,
+  OPENGENI_WEBHOOK_HEADERS,
+  OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+  OpenGeniSignatureError,
+  WORKSPACE_WEBHOOK_EVENT_TYPES,
+  createOrganizationWebhook,
+  deleteOrganizationCredentialProvider,
+  deleteOrganizationWebhook,
+  getOrganizationCredentialProvider,
+  getOrganizationWebhook,
+  getWorkspaceInheritedIntegrations,
+  getWorkspaceWebhook,
+  listOrganizationWebhookDeliveries,
+  listOrganizationWebhooks,
+  putOrganizationCredentialProvider,
+  redeliverOrganizationWebhookDelivery,
+  rotateOrganizationCredentialProviderSecret,
+  rotateOrganizationWebhookSecret,
+  rotateWorkspaceCredentialProviderSecret,
+  rotateWorkspaceWebhookSecret,
+  signOpenGeniPayload,
+  testWorkspaceCredentialProvider,
+  testWorkspaceWebhook,
+  updateOrganizationWebhook,
+  verifyCredentialProviderRequest,
+  verifyOpenGeniSignature,
+  verifyWebhookEvent
+};
+//# sourceMappingURL=workspace-integrations.js.map

package/dist/workspace-integrations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/workspace-state.d.ts

@@ -1,41 +1,4 @@
 import type { WorkspaceInstructionPolicyKind, WorkspaceInstructionPolicyProvenanceSource, WorkspaceInstructionPolicyScope } from "./workspace-instruction-policies.js";
-export type WorkspaceStateDocumentStatusCounts = {
-    queued: number;
-    indexing: number;
-    ready: number;
-    failed: number;
-};
-export type WorkspaceStateSourceKindCounts = {
-    manual_upload: number;
-    meeting_transcript: number;
-    repository: number;
-    email: number;
-    chat: number;
-    document: number;
-    web: number;
-    other: number;
-};
-export type WorkspaceStateDocumentAuthorityKindCounts = {
-    organization: number;
-    workspace: number;
-    personal: number;
-};
-export type WorkspaceStateMemoryStatusCounts = {
-    proposed: number;
-    approved: number;
-    rejected: number;
-    active: number;
-    superseded: number;
-    archived: number;
-};
-export type WorkspaceStateMemoryKindCounts = {
-    semantic: number;
-    episodic: number;
-    procedural: number;
-    decision: number;
-    preference: number;
-};
-export type WorkspaceStateGapCode = "no_document_bases" | "no_visible_documents" | "failed_documents" | "processing_documents" | "missing_topic_coverage" | "no_memory_records" | "pending_memory_review" | "partial_inventory";
 export type WorkspaceStateGovernanceDriftStatus = "identical" | "changed" | "superseded" | "missing" | "unavailable" | "truncated";
 export type WorkspaceStateGetOptions = {
     attemptId?: string;
@@ -164,42 +127,16 @@ export type WorkspaceStateResponse = {
         requiredPermission: "documents:search";
     } | {
         availability: "available";
+        authority: "knowledge_entries";
         coverage: "complete" | "partial";
-        baseCount: number;
-        bases: Array<{
+        sampleLimit: 50;
+        entries: Array<{
             id: string;
-            name: string;
-            visibleDocumentCount: number;
-            statusCounts: WorkspaceStateDocumentStatusCounts;
-            latestUpdatedAt: string | null;
-        }>;
-        basesTruncated: boolean;
-        inspectedVisibleDocumentCount: number;
-        documentStatusCounts: WorkspaceStateDocumentStatusCounts;
-        sourceKindCounts: WorkspaceStateSourceKindCounts;
-        authorityKindCounts: WorkspaceStateDocumentAuthorityKindCounts;
-        topics: Array<{
-            name: string;
-            documentCount: number;
-        }>;
-        topicsTruncated: boolean;
-        latestDocumentUpdatedAt: string | null;
-        memorySample: {
-            recordCount: number;
-            sampleLimit: 100;
-            limitReached: boolean;
-            statusCounts: WorkspaceStateMemoryStatusCounts;
-            kindCounts: WorkspaceStateMemoryKindCounts;
-            preferenceAuthority: {
-                kindCountSource: "knowledge_memories_legacy_observations";
-                activeAuthority: "structured_preference_registry";
-            };
-            latestUpdatedAt: string | null;
-        };
-        gaps: Array<{
-            code: WorkspaceStateGapCode;
-            severity: "info" | "warning";
-            relatedCount: number | null;
+            revisionId: string;
+            title: string;
+            kind: "source" | "fact" | "decision" | "requirement" | "incident" | "note" | "group";
+            scope: "organization" | "workspace" | "personal";
+            updatedAt: string;
         }>;
     };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@opengeni/sdk",
-  "version": "3.1.0",
-  "description": "Framework-agnostic TypeScript SDK for the OpenGeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
+  "version": "3.1.2",
+  "description": "Framework-agnostic TypeScript SDK for the Opengeni API: typed client, session lifecycle, SSE event streaming with reconnect + replay-by-sequence, and proxy re-streaming helpers.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -22,6 +22,14 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./allowance-refusal": {
+      "types": "./dist/allowance-refusal.d.ts",
+      "import": "./dist/allowance-refusal.js"
+    },
+    "./app-links": {
+      "types": "./dist/app-links.d.ts",
+      "import": "./dist/app-links.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -34,6 +42,46 @@
       "types": "./dist/browser.d.ts",
       "import": "./dist/browser.js"
     },
+    "./site-document": {
+      "types": "./dist/site-document.d.ts",
+      "import": "./dist/site-document.js"
+    },
+    "./site": {
+      "types": "./dist/site.d.ts",
+      "import": "./dist/site.js"
+    },
+    "./site-bridge-host": {
+      "types": "./dist/site-bridge-host.d.ts",
+      "import": "./dist/site-bridge-host.js"
+    },
+    "./github-repositories": {
+      "types": "./dist/github-repositories.d.ts",
+      "import": "./dist/github-repositories.js"
+    },
+    "./knowledge": {
+      "types": "./dist/knowledge.d.ts",
+      "import": "./dist/knowledge.js"
+    },
+    "./usage-allowances": {
+      "types": "./dist/usage-allowances.d.ts",
+      "import": "./dist/usage-allowances.js"
+    },
+    "./session-usage-limits": {
+      "types": "./dist/session-usage-limits.d.ts",
+      "import": "./dist/session-usage-limits.js"
+    },
+    "./insights-usage": {
+      "types": "./dist/insights-usage.d.ts",
+      "import": "./dist/insights-usage.js"
+    },
+    "./workspace-integrations": {
+      "types": "./dist/workspace-integrations.d.ts",
+      "import": "./dist/workspace-integrations.js"
+    },
+    "./session-history-import": {
+      "types": "./dist/session-history-import.d.ts",
+      "import": "./dist/session-history-import.js"
+    },
     "./document-authority": {
       "types": "./dist/document-authority.d.ts",
       "import": "./dist/document-authority.js"
@@ -58,6 +106,10 @@
       "types": "./dist/pr-review.d.ts",
       "import": "./dist/pr-review.js"
     },
+    "./organization-integration-policy": {
+      "types": "./dist/organization-integration-policy.d.ts",
+      "import": "./dist/organization-integration-policy.js"
+    },
     "./organization-private-session-settings": {
       "types": "./dist/organization-private-session-settings.d.ts",
       "import": "./dist/organization-private-session-settings.js"
@@ -89,7 +141,48 @@
     "./gateway-realtime-transport": {
       "types": "./dist/gateway-realtime-transport.d.ts",
       "import": "./dist/gateway-realtime-transport.js"
-    }
+    },
+    "./model-picker-order": {
+      "types": "./dist/model-picker-order.d.ts",
+      "import": "./dist/model-picker-order.js"
+    },
+    "./model-display": {
+      "types": "./dist/model-display.d.ts",
+      "import": "./dist/model-display.js"
+    },
+    "./chat": {
+      "types": "./dist/chat/index.d.ts",
+      "import": "./dist/chat/index.js"
+    },
+    "./tenant-workspaces": {
+      "types": "./dist/tenant-workspaces.d.ts",
+      "import": "./dist/tenant-workspaces.js"
+    },
+    "./session-proxy": {
+      "types": "./dist/session-proxy.d.ts",
+      "import": "./dist/session-proxy.js"
+    },
+    "./tool-auth": {
+      "types": "./dist/tool-auth.d.ts",
+      "import": "./dist/tool-auth.js"
+    },
+    "./next": {
+      "types": "./dist/adapters/next.d.ts",
+      "import": "./dist/adapters/next.js"
+    },
+    "./express": {
+      "types": "./dist/adapters/express.d.ts",
+      "import": "./dist/adapters/express.js"
+    },
+    "./hono": {
+      "types": "./dist/adapters/hono.d.ts",
+      "import": "./dist/adapters/hono.js"
+    },
+    "./session-list-entries": {
+      "types": "./dist/session-list-entries.d.ts",
+      "import": "./dist/session-list-entries.js"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public",
@@ -97,11 +190,12 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "bun ../../scripts/build-typescript-package.ts",
+    "build": "bun ../../scripts/generate-site-browser-runtime.ts && bun ../../scripts/build-typescript-package.ts",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/contracts": "^2.7.0"
+    "@opengeni/connect": "3.1.2",
+    "@opengeni/contracts": "3.1.2"
   },
   "engines": {
     "node": ">=18"

package/src/accounts.ts

@@ -15,6 +15,8 @@ import {
   ManagedAuthSessionSetErrorCode,
   ResolveManagedAuthDeepLinkRequest,
   SelectManagedAuthLoginSlotRequest,
+  StartManagedAuthSocialTransactionRequest,
+  StartManagedAuthSocialTransactionResponse,
   type BeginManagedAuthLoginTransactionRequest as BeginManagedAuthLoginTransactionRequestType,
   type BootstrapManagedAuthSessionSetRequest as BootstrapManagedAuthSessionSetRequestType,
   type CancelManagedAuthLoginTransactionRequest as CancelManagedAuthLoginTransactionRequestType,
@@ -28,6 +30,8 @@ import {
   type ManagedAuthSessionSetProjection as ManagedAuthSessionSetProjectionType,
   type ResolveManagedAuthDeepLinkRequest as ResolveManagedAuthDeepLinkRequestType,
   type SelectManagedAuthLoginSlotRequest as SelectManagedAuthLoginSlotRequestType,
+  type StartManagedAuthSocialTransactionRequest as StartManagedAuthSocialTransactionRequestType,
+  type StartManagedAuthSocialTransactionResponse as StartManagedAuthSocialTransactionResponseType,
 } from "@opengeni/contracts/managed-auth-session-sets";
 import type { z } from "zod";
 
@@ -53,6 +57,9 @@ export interface BrowserAccountsClientLike {
   completeEmailPasswordTransaction(
     request: CompleteManagedAuthEmailPasswordTransactionRequestType,
   ): Promise<CompleteManagedAuthLoginTransactionResponseType>;
+  startSocialTransaction?(
+    request: StartManagedAuthSocialTransactionRequestType,
+  ): Promise<StartManagedAuthSocialTransactionResponseType>;
   cancelLoginTransaction(
     request: CancelManagedAuthLoginTransactionRequestType,
   ): Promise<ManagedAuthSessionSetProjectionType>;
@@ -178,6 +185,17 @@ export class BrowserAccountsClient implements BrowserAccountsClientLike {
     return response;
   }
 
+  async startSocialTransaction(request: StartManagedAuthSocialTransactionRequestType) {
+    return StartManagedAuthSocialTransactionResponse.parse(
+      await this.#mutation(
+        "POST",
+        "/v1/auth/session-set/transactions/social",
+        StartManagedAuthSocialTransactionRequest,
+        request,
+      ),
+    );
+  }
+
   async cancelLoginTransaction(request: CancelManagedAuthLoginTransactionRequestType) {
     return this.#projectionResponse(
       "DELETE",

package/src/adapters/express.ts

@@ -0,0 +1,136 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** Express/Connect request: Node's `IncomingMessage` plus what those frameworks add. */
+export type NodeRequestLike = IncomingMessage & {
+  originalUrl?: string | undefined;
+  /** Set when a body parser (for example `express.json()`) already consumed the body. */
+  body?: unknown;
+  protocol?: string | undefined;
+};
+
+export type NodeMiddleware = (
+  request: NodeRequestLike,
+  response: ServerResponse,
+  next?: (error?: unknown) => void,
+) => void;
+
+export type NodeMiddlewareOptions = {
+  /** Origin used to build the request URL. Defaults to the Host header over http(s). */
+  origin?: string | undefined;
+};
+
+/**
+ * Expose a web-standard handler as Express/Connect (or plain `node:http`)
+ * middleware. Mount it with the same path the browser client uses:
+ *
+ * ```ts
+ * app.use("/api/opengeni", toNodeMiddleware(handler));
+ * ```
+ *
+ * The full original URL is forwarded (Express strips the mount path from
+ * `req.url`), bodies stream through unless a body parser already consumed
+ * them, responses (including SSE) are written as they arrive, and a client
+ * disconnect aborts the request signal.
+ */
+export function toNodeMiddleware(
+  handler: WebHandler,
+  options: NodeMiddlewareOptions = {},
+): NodeMiddleware {
+  return (request, response, next) => {
+    void (async () => {
+      const abort = new AbortController();
+      response.once("close", () => {
+        if (!response.writableFinished) abort.abort();
+      });
+      const web = await handler(toWebRequest(request, abort.signal, options));
+      await writeWebResponse(web, response);
+    })().catch((error: unknown) => {
+      if (next) next(error);
+      else if (!response.headersSent) {
+        response.statusCode = 500;
+        response.end();
+      } else response.destroy(error instanceof Error ? error : undefined);
+    });
+  };
+}
+
+/** Express/Connect naming alias. */
+export const toExpressMiddleware = toNodeMiddleware;
+
+function toWebRequest(
+  request: NodeRequestLike,
+  signal: AbortSignal,
+  options: NodeMiddlewareOptions,
+): Request {
+  const encrypted = (request.socket as { encrypted?: boolean } | undefined)?.encrypted === true;
+  const origin =
+    options.origin?.replace(/\/+$/, "") ??
+    `${request.protocol ?? (encrypted ? "https" : "http")}://${request.headers.host ?? "localhost"}`;
+  const url = new URL(request.originalUrl ?? request.url ?? "/", origin);
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+    else headers.set(name, value);
+  }
+  const method = request.method ?? "GET";
+  let body: BodyInit | undefined;
+  if (method !== "GET" && method !== "HEAD") {
+    if (request.body !== undefined && (request.readableEnded || request.complete)) {
+      // A body parser consumed the stream: forward what it parsed.
+      body =
+        typeof request.body === "string" || request.body instanceof Uint8Array
+          ? (request.body as string | Uint8Array<ArrayBuffer>)
+          : JSON.stringify(request.body);
+      headers.delete("content-length");
+    } else {
+      body = Readable.toWeb(request) as unknown as ReadableStream<Uint8Array>;
+    }
+  }
+  return new Request(url, {
+    method,
+    headers,
+    signal,
+    ...(body !== undefined ? { body, duplex: "half" } : {}),
+  } as RequestInit);
+}
+
+async function writeWebResponse(web: Response, response: ServerResponse): Promise<void> {
+  response.statusCode = web.status;
+  const cookies = web.headers.getSetCookie?.() ?? [];
+  web.headers.forEach((value, name) => {
+    if (name.toLowerCase() !== "set-cookie") response.setHeader(name, value);
+  });
+  if (cookies.length > 0) response.setHeader("set-cookie", cookies);
+  if (!web.body) {
+    response.end();
+    return;
+  }
+  // Send headers now so SSE clients see the stream open before the first event.
+  response.flushHeaders();
+  const reader = web.body.getReader();
+  response.once("close", () => {
+    void reader.cancel().catch(() => undefined);
+  });
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!response.write(value)) {
+      await new Promise<void>((resolve) => {
+        const settle = () => {
+          response.off("drain", settle);
+          response.off("close", settle);
+          resolve();
+        };
+        response.once("drain", settle);
+        response.once("close", settle);
+      });
+    }
+    if (response.destroyed) break;
+  }
+  response.end();
+}

package/src/adapters/hono.ts

@@ -0,0 +1,18 @@
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** The part of Hono's context this adapter uses (no Hono dependency). */
+export type HonoContextLike = { req: { raw: Request } };
+
+/**
+ * Expose a web-standard handler as a Hono handler:
+ *
+ * ```ts
+ * app.all("/api/opengeni/*", toHonoHandler(handler));
+ * ```
+ */
+export function toHonoHandler(
+  handler: WebHandler,
+): (context: HonoContextLike) => Promise<Response> {
+  return async (context) => await handler(context.req.raw);
+}

package/src/adapters/next.ts

@@ -0,0 +1,42 @@
+import { createSessionProxyHandler, type SessionProxyHandlerOptions } from "../session-proxy";
+
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** Route handlers for a Next.js App Router catch-all route. */
+export type NextRouteHandlers = {
+  GET: WebHandler;
+  POST: WebHandler;
+  PUT: WebHandler;
+  PATCH: WebHandler;
+  DELETE: WebHandler;
+};
+
+/**
+ * Expose a web-standard handler as Next.js App Router route handlers.
+ *
+ * ```ts
+ * // app/api/opengeni/[...path]/route.ts
+ * export const dynamic = "force-dynamic";
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ *
+ * Next passes the full request URL (including any `basePath`), so the proxy's
+ * own `/v1/` detection routes it; responses, including SSE, stream as-is.
+ */
+export function toNextRouteHandlers(handler: WebHandler): NextRouteHandlers {
+  // Next calls route handlers with (request, context); only the request matters.
+  const route: WebHandler = async (request) => await handler(request);
+  return { GET: route, POST: route, PUT: route, PATCH: route, DELETE: route };
+}
+
+/**
+ * `createSessionProxyHandler` as Next.js App Router route handlers, for
+ * `app/<mount>/[...path]/route.ts`.
+ */
+export function createSessionProxyRoute(
+  target: Parameters<typeof createSessionProxyHandler>[0],
+  options: SessionProxyHandlerOptions,
+): NextRouteHandlers {
+  return toNextRouteHandlers(createSessionProxyHandler(target, options));
+}

package/src/allowance-refusal.ts

@@ -0,0 +1,5 @@
+/** Browser-safe allowance presentation without exposing the server core. */
+export {
+  allowanceExhaustedMessage,
+  parseAllowanceExhaustedRefusal,
+} from "@opengeni/contracts/allowance-refusal";

package/src/app-links.ts

@@ -0,0 +1,117 @@
+// Opengeni web links that a native app (phone or desktop) can show itself, and
+// the account each belongs to. Pure: no platform modules, so every app shares it.
+
+/** A deployment address as typed: trimmed, https by default, no trailing slash. */
+export function normalizeServerUrl(input: string): string | null {
+  const raw = input.trim();
+  if (!raw) return null;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//iu.test(raw) ? raw : `https://${raw}`;
+  const match = /^(https?):\/\/([a-z0-9.-]+(?::\d{1,5})?)(?:[/?#].*)?$/iu.exec(withScheme);
+  return match ? `${match[1]!.toLowerCase()}://${match[2]!.toLowerCase()}` : null;
+}
+
+/** The host a person recognizes, e.g. app.opengeni.ai. */
+export function serverLabel(baseUrl: string): string {
+  return baseUrl.replace(/^https?:\/\//iu, "");
+}
+
+/** The part of a signed-in app account that link routing reads. */
+export interface AppLinkAccount {
+  id: string;
+  /** The deployment's web origin, e.g. https://app.opengeni.ai. */
+  baseUrl: string;
+  /** The workspace last used with this account. */
+  workspaceId: string | null;
+  /** Set when the deployment rejected the credential. */
+  signedOut?: boolean;
+}
+
+/**
+ * A web link the app can show itself: a conversation or a workspace on some
+ * deployment. Everything else on the web (settings, organization, artifacts)
+ * stays in the browser.
+ */
+export interface AppLink {
+  /** The deployment's origin, normalized like a stored account's baseUrl. */
+  origin: string;
+  /** Absent for the web's workspace-less `/sessions/:id` links. */
+  workspaceId: string | null;
+  /** Absent for a link to the workspace itself. */
+  sessionId: string | null;
+  /** The session moment the link points at (`?at=`). */
+  at: number | null;
+  /** The web address the link came from, for the browser fallback. */
+  webUrl: string;
+}
+
+/** The app's own scheme for links handed over from the web: opengeni://open?url=… */
+const HANDOFF = /^opengeni:\/\/open\/?\?(.*)$/iu;
+const WEB_URL = /^(https?:\/\/[^/?#]+)(\/[^?#]*)?(\?[^#]*)?(#.*)?$/iu;
+const ID = "([A-Za-z0-9][A-Za-z0-9_-]{0,127})";
+const SESSION_PATH = new RegExp(`^/workspaces/${ID}/sessions/${ID}/?$`, "u");
+const WORKSPACE_PATH = new RegExp(`^/workspaces/${ID}(?:/sessions)?/?$`, "u");
+const BARE_SESSION_PATH = new RegExp(`^/sessions/${ID}/?$`, "u");
+
+function queryParam(query: string | undefined, name: string): string | null {
+  for (const part of (query ?? "").replace(/^\?/u, "").split("&")) {
+    const [key, value = ""] = part.split("=");
+    if (key !== name) continue;
+    try {
+      return decodeURIComponent(value.replace(/\+/gu, " "));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** The web link a raw URL points at, unwrapping the web's "Open in app" handoff. */
+export function parseAppLink(raw: string): AppLink | null {
+  const trimmed = raw.trim();
+  const handoff = HANDOFF.exec(trimmed);
+  const webUrl = handoff ? queryParam(handoff[1], "url") : trimmed;
+  if (!webUrl) return null;
+  const match = WEB_URL.exec(webUrl);
+  if (!match) return null;
+  const origin = normalizeServerUrl(match[1]!);
+  if (!origin) return null;
+  const path = match[2] ?? "/";
+  const atRaw = queryParam(match[3], "at");
+  const at = atRaw && /^[1-9][0-9]{0,15}$/u.test(atRaw) ? Number(atRaw) : null;
+  const session = SESSION_PATH.exec(path);
+  if (session) return { origin, workspaceId: session[1]!, sessionId: session[2]!, at, webUrl };
+  const bare = BARE_SESSION_PATH.exec(path);
+  if (bare) return { origin, workspaceId: null, sessionId: bare[1]!, at, webUrl };
+  const workspace = WORKSPACE_PATH.exec(path);
+  if (workspace) return { origin, workspaceId: workspace[1]!, sessionId: null, at: null, webUrl };
+  return null;
+}
+
+/**
+ * The signed-in account a link belongs to, or null when the app has none on
+ * that deployment (the browser opens it instead). With several accounts on the
+ * same deployment: the one last used in the link's workspace, else the active
+ * one, else the first.
+ */
+export function accountForAppLink<Account extends AppLinkAccount>(
+  link: AppLink,
+  accounts: readonly Account[],
+  activeId: string | null,
+): Account | null {
+  const candidates = accounts.filter(
+    (account) => !account.signedOut && normalizeServerUrl(account.baseUrl) === link.origin,
+  );
+  return (
+    (link.workspaceId
+      ? candidates.find((account) => account.workspaceId === link.workspaceId)
+      : undefined) ??
+    candidates.find((account) => account.id === activeId) ??
+    candidates[0] ??
+    null
+  );
+}
+
+/** The web's handoff link that opens a web page in the app. */
+export function appHandoffUrl(webUrl: string): string {
+  return `opengeni://open?url=${encodeURIComponent(webUrl)}`;
+}