@opengeni/sdk 3.3.2 → 3.4.0

package/src/codex-realtime-controller.ts

@@ -47,7 +47,7 @@ export type { SessionRealtimeLifecycleProjection } from "./codex-realtime-lifecy
 const HEARTBEAT_INTERVAL_MS = 10_000;
 const OUTBOUND_SYNC_INTERVAL_MS = 1_000;
 export const CODEX_REALTIME_NEGOTIATION_TIMEOUT_MS = 20_000;
-// OpenGeni policy: rotate conservatively without asserting an upstream lifetime.
+// Opengeni policy: rotate conservatively without asserting an upstream lifetime.
 const DEFAULT_CONNECTION_ROTATION_INTERVAL_MS = 15 * 60_000;
 const DEFAULT_RECONNECT_BACKOFF_MS = [250, 1_000, 2_000, 5_000] as const;
 const MAX_BROWSER_TIMEOUT_MS = 2_147_483_647;
@@ -120,8 +120,39 @@ export type CodexRealtimeControllerSnapshot = {
   reconnectAttempt: number;
   diagnostic: CodexRealtimeDiagnostic | null;
   error: string | null;
+  /**
+   * Set when Opengeni refused or ended deployment-funded voice for credits or
+   * availability. Codes match voice input: `insufficient_credits`,
+   * `allowance_exhausted`, `monthly_model_cost_limit`, plus
+   * `realtime_voice_unavailable`. Cleared on the next start.
+   */
+  refusal?: CodexRealtimeRefusal | null;
 };
 
+export type CodexRealtimeRefusal = { code: string; message: string };
+
+const REALTIME_REFUSAL_CODES = new Set([
+  "insufficient_credits",
+  "allowance_exhausted",
+  "monthly_model_cost_limit",
+  "realtime_voice_unavailable",
+]);
+
+/** A definitive credit/availability refusal from Opengeni, with its plain message. */
+export function codexRealtimeRefusal(error: unknown): CodexRealtimeRefusal | null {
+  if (!(error instanceof OpenGeniApiError) || !error.code) return null;
+  if (!REALTIME_REFUSAL_CODES.has(error.code)) return null;
+  const message = apiErrorMessage(error);
+  return {
+    code: error.code,
+    message:
+      message ??
+      (error.code === "insufficient_credits"
+        ? "Live voice needs Opengeni credits. Add credits to continue."
+        : "Live voice is unavailable right now."),
+  };
+}
+
 export type CodexRealtimeControllerClient = {
   beginSessionRealtime(
     workspaceId: string,
@@ -178,6 +209,7 @@ export type CodexRealtimeOwnerStorage = Pick<Storage, "getItem" | "setItem" | "r
 
 /** Canonical browser-owner storage namespace for a public realtime model. */
 export function sessionRealtimeOwnerStorageNamespace(model: SessionRealtimeModel): string {
+  if (model === "opengeni-azure/gpt-live-1") return "azure-live-owner";
   if (model === "gpt-live-1-boulder-alpha") return "codex-realtime-owner";
   if (model === "supergrok/grok-voice-think-fast-2.0") return "xai-realtime-owner";
   return "gateway-realtime-owner";
@@ -355,6 +387,7 @@ export function createCodexRealtimeController(
     reconnectAttempt: 0,
     diagnostic: null,
     error: null,
+    refusal: null,
   };
   let active: ConnectionRuntime | null = null;
   let pendingAbort: AbortController | null = null;
@@ -371,6 +404,9 @@ export function createCodexRealtimeController(
   let generation = 0;
   let reconnectAttempt = 0;
   let recoveryTerminal = false;
+  // Whether this mode ever reached a live provider connection. A definitive
+  // failure before that ends the mode instead of leaving an empty call open.
+  let connectedInMode = false;
   let mutationTail = Promise.resolve();
   let connectionTask: Promise<void> | null = null;
   const acceptedDelegationItemIds = new Set(
@@ -699,6 +735,12 @@ export function createCodexRealtimeController(
     if (closed || stopping || isAbortError(error)) return;
     const message = safeError(error);
     if (error instanceof CodexRealtimeMicrophoneError) {
+      if (error.code !== "track_ended" && !connectedInMode) {
+        // No conversation exists yet: end the call and say how to fix the
+        // microphone instead of holding an empty "reconnecting" call open.
+        await endAfterFailure(microphoneFailureMessage(error), null);
+        return;
+      }
       if (error.code === "track_ended" && state.mode?.state === "active") {
         reconnectAttempt += 1;
         publish({
@@ -720,6 +762,11 @@ export function createCodexRealtimeController(
       transitionEnded("Realtime owner no longer exists");
       return;
     }
+    const refusal = codexRealtimeRefusal(error);
+    if (refusal) {
+      await endForRefusal(refusal);
+      return;
+    }
     if (error instanceof OpenGeniApiError && error.status === 409 && error.retryable && owner) {
       try {
         const reconciled = await begin(owner, true, false);
@@ -737,6 +784,9 @@ export function createCodexRealtimeController(
           return;
         }
       }
+    } else if (error instanceof OpenGeniApiError && !error.retryable && !connectedInMode) {
+      await endAfterFailure(message, null);
+      return;
     } else if (error instanceof OpenGeniApiError && !error.retryable) {
       stopTimers();
       if (!active) releaseMicrophone();
@@ -883,6 +933,15 @@ export function createCodexRealtimeController(
     });
     let connected: CodexRealtimeWebrtcSession;
     try {
+      // Persist a fragment provider's tail before the replacement broker reads
+      // its startup history, while the old connection still owns the ledger.
+      if (active?.transport.drain) {
+        await active.transport.drain();
+        await active.bridge.flush();
+      }
+      if (closed || stopping || abort.signal.aborted || pendingGeneration !== targetGeneration) {
+        throw abort.signal.reason ?? new DOMException("Aborted", "AbortError");
+      }
       const media = await ensureMicrophone(replaceMicrophone, abort.signal);
       const operationId = randomUUID();
       const commonTransportInput = {
@@ -1016,6 +1075,7 @@ export function createCodexRealtimeController(
         onFatal: (fatal) => onBridgeFatal(targetGeneration, bridge, fatal),
       });
       active = { generation: targetGeneration, transport: connected, bridge };
+      connectedInMode = true;
       connected.setOutputMuted(state.outputMuted);
       recoveryTerminal = false;
       pendingAbort = null;
@@ -1098,6 +1158,7 @@ export function createCodexRealtimeController(
   };
 
   const heartbeat = async (): Promise<void> => {
+    let stopInstruction: CodexRealtimeRefusal | null = null;
     await exclusive(async () => {
       const current = state.mode;
       if (!owner || !current || current.state !== "active") {
@@ -1121,6 +1182,43 @@ export function createCodexRealtimeController(
         return;
       }
       publish({ mode: result.mode, realtimeId: result.mode.id, error: null });
+      stopInstruction = result.stop ?? null;
+    });
+    // The server stopped extending the lease (for example, out of credits):
+    // drain and end gracefully inside the remaining lease.
+    const instruction = stopInstruction as CodexRealtimeRefusal | null;
+    stopInstruction = null;
+    if (instruction && !stopping && !closed) await endForRefusal(instruction);
+  };
+
+  /**
+   * End the call because Opengeni refused it, keep final speech, and leave a
+   * terminal, non-retrying state that explains why.
+   */
+  const endForRefusal = async (refusal: CodexRealtimeRefusal): Promise<void> =>
+    await endAfterFailure(refusal.message, refusal);
+
+  const endAfterFailure = async (
+    message: string,
+    refusal: CodexRealtimeRefusal | null,
+  ): Promise<void> => {
+    try {
+      await controller.stop();
+    } catch {
+      // The lease is no longer extended; a failed graceful end lapses on its own.
+      stopping = false;
+      closeBrowserResources();
+      clearOwner();
+    }
+    recoveryTerminal = false;
+    publish({
+      status: "error",
+      realtimeId: null,
+      mode: null,
+      bridge: null,
+      diagnostic: diagnostic("terminal_stop", message, false),
+      error: message,
+      refusal,
     });
   };
 
@@ -1176,6 +1274,7 @@ export function createCodexRealtimeController(
       closed = false;
       stopping = false;
       recoveryTerminal = false;
+      connectedInMode = false;
       const record: OwnerRecord = {
         version: OWNER_RECORD_VERSION,
         workspaceId: options.workspaceId,
@@ -1186,11 +1285,12 @@ export function createCodexRealtimeController(
       };
       owner = record;
       storage?.setItem(storageKey, JSON.stringify(record));
-      publish({ status: "starting", error: null, diagnostic: null });
+      publish({ status: "starting", error: null, diagnostic: null, refusal: null });
       try {
         await begin(record, false);
       } catch (error) {
         closeBrowserResources(false);
+        const refusal = codexRealtimeRefusal(error);
         const failedMode = state.mode as SessionRealtimeMode | null;
         if (failedMode?.state === "active") {
           await handleConnectionFailure(error, "reconnect", false);
@@ -1200,9 +1300,13 @@ export function createCodexRealtimeController(
             status: "error",
             realtimeId: null,
             mode: null,
-            error: safeError(error),
+            error: refusal?.message ?? safeError(error),
+            ...(refusal
+              ? { refusal, diagnostic: diagnostic("terminal_stop", refusal.message, false) }
+              : {}),
           });
         }
+        if (refusal) return;
         throw error;
       }
     },
@@ -1211,6 +1315,8 @@ export function createCodexRealtimeController(
         if (recoveryTerminal && state.mode?.state === "active") return;
         const record = readOwnerRecord(storage, storageKey, options);
         if (!record) {
+          // Keep a terminal failure readable after the server records the end.
+          if (state.status === "error" && !state.mode) return;
           transitionEnded();
           return;
         }
@@ -1234,7 +1340,10 @@ export function createCodexRealtimeController(
       if (lifecycle.state === "ended") {
         const record = readOwnerRecord(storage, storageKey, options);
         if (record && record.operationId !== lifecycle.operationId) {
-          if (connectionTask || state.status === "active") return;
+          // An earlier call's end is not news while this browser is starting
+          // its own call (for example, waiting on the microphone prompt):
+          // re-beginning would advance the lease and fail the pending start.
+          if (connectionTask || state.status === "active" || state.status === "starting") return;
           closed = false;
           stopping = false;
           owner = record;
@@ -1250,6 +1359,9 @@ export function createCodexRealtimeController(
           await connectionTask;
           return;
         }
+        // The server's end of a call that failed to start must not wipe the
+        // failure the user still needs to read.
+        if (state.status === "error" && !state.mode) return;
         if (state.realtimeId === null || lifecycle.realtimeId === state.realtimeId) {
           transitionEnded(`Realtime ended: ${lifecycle.reason}`);
         }
@@ -1259,11 +1371,22 @@ export function createCodexRealtimeController(
       if (state.status === "active" && state.realtimeId === lifecycle.realtimeId) return;
       const record = readOwnerRecord(storage, storageKey, options);
       if (!record || record.operationId !== lifecycle.operationId) {
-        closeBrowserResources();
-        owner = null;
         const leaseExpiresAt = Date.parse(lifecycle.leaseExpiresAt);
         const remainingLeaseMs = leaseExpiresAt - now().getTime();
-        if (Number.isFinite(remainingLeaseMs) && remainingLeaseMs <= 0) {
+        const leaseExpired = Number.isFinite(remainingLeaseMs) && remainingLeaseMs <= 0;
+        // An earlier call whose lease already ran out (its end not yet in the
+        // events) is not another owner: it must not fail the call this
+        // browser is starting.
+        if (
+          leaseExpired &&
+          lifecycle.realtimeId !== state.realtimeId &&
+          (connectionTask || state.status === "starting")
+        ) {
+          return;
+        }
+        closeBrowserResources();
+        owner = null;
+        if (leaseExpired) {
           transitionEnded("Realtime lease expired");
           return;
         }
@@ -1337,6 +1460,7 @@ export function createCodexRealtimeController(
       connectionTask = null;
       void retiredTask?.catch(() => undefined);
       try {
+        await active?.transport.drain?.();
         await active?.bridge.sealAndFlush();
         closeBrowserResources();
         let current = state.mode;
@@ -1708,6 +1832,37 @@ function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError";
 }
 
+function microphoneFailureMessage(error: CodexRealtimeMicrophoneError): string {
+  switch (error.code) {
+    case "permission_denied":
+      return "Microphone access is blocked. Allow it in site settings, then try again.";
+    case "device_not_found":
+      return "No microphone was found. Connect one, then try again.";
+    case "device_unavailable":
+      return "Your microphone is busy or unavailable. Close other apps using it, then try again.";
+    default:
+      return /timed out/i.test(error.message)
+        ? "Microphone access wasn't granted in time. Allow it when your browser asks, then try again."
+        : "The microphone could not start. Try again.";
+  }
+}
+
+/** The server's own message, without the transport prefix or reference id. */
+function apiErrorMessage(error: OpenGeniApiError): string | null {
+  try {
+    const body = JSON.parse(error.body) as Record<string, unknown>;
+    const nested =
+      body.error && typeof body.error === "object" ? (body.error as Record<string, unknown>) : body;
+    return typeof nested.message === "string" && nested.message ? nested.message : null;
+  } catch {
+    return null;
+  }
+}
+
 function safeError(error: unknown): string {
-  return error instanceof Error ? error.message : "Codex realtime browser controller failed";
+  if (error instanceof OpenGeniApiError) {
+    const message = apiErrorMessage(error);
+    if (message) return /[.!?]$/.test(message) ? message : `${message}.`;
+  }
+  return error instanceof Error ? error.message : "Live voice failed in this browser.";
 }

package/src/codex-realtime-v3-wire.ts

@@ -3,7 +3,8 @@
  *
  * These shapes are pinned to openai/codex@fa1d4c40. V3 delegates work with
  * `delegation.created`; it does not expose the ordinary Realtime V2
- * `function_call` protocol.
+ * `function_call` protocol. `transcript.segment` is an application adapter
+ * extension for providers that emit fragments without semantic turn boundaries.
  */
 
 export const CODEX_REALTIME_INITIAL_ITEMS_MAX_COUNT = 128;
@@ -40,7 +41,7 @@ export type CodexRealtimeV3Event =
       endMs: number | null;
     })
   | (ProviderEventIdentity & {
-      type: "turn.done";
+      type: "turn.done" | "transcript.segment";
       turnId: string;
       role: "user" | "assistant";
       transcript: string;
@@ -173,7 +174,7 @@ export function parseCodexRealtimeV3Event(payload: string): CodexRealtimeV3Parse
     };
   }
 
-  if (type === "turn.done") {
+  if (type === "turn.done" || type === "transcript.segment") {
     const turn = record(event.turn);
     const turnIdField = boundedStringField(turn, "id", CODEX_REALTIME_V3_MAX_IDENTIFIER_BYTES);
     const transcriptField = boundedStringField(

package/src/codex-realtime-v3.ts

@@ -316,7 +316,7 @@ export function createCodexRealtimeV3Bridge(
       if (closed || fatal) break;
 
       for (const entry of result.outbound) {
-        // This is OpenGeni's durable browser-delivery acknowledgment. The
+        // This is Opengeni's durable browser-delivery acknowledgment. The
         // provider send below remains at-least-once because pinned V3 exposes
         // no provider receipt and providerAckSequences is never populated.
         if (entry.clientAckedAt === null && !clientReceivedSequences.has(entry.sequence)) {
@@ -324,6 +324,12 @@ export function createCodexRealtimeV3Bridge(
           clientAckThroughSequence = Math.max(clientAckThroughSequence ?? 0, entry.sequence);
         }
       }
+      // Persist final inbound fragments even after the provider starts closing.
+      // Pending outbound context remains replayable on the next connection.
+      if (options.events.readyState !== "open") {
+        publish();
+        continue;
+      }
       for (let index = 0; index < result.outbound.length;) {
         const entry = result.outbound[index]!;
         if (sentSequences.has(entry.sequence)) {
@@ -497,7 +503,7 @@ export function createCodexRealtimeV3Bridge(
       }
     } else if (event.type === "output_audio.delta") {
       speaking = true;
-    } else if (event.type === "turn.done") {
+    } else if (event.type === "turn.done" || event.type === "transcript.segment") {
       speaking = false;
       if (event.transcript.length > 0 && !finalizedTurnIds.has(event.turnId)) {
         const coveredByDelegationItemId =
@@ -570,7 +576,7 @@ export function createCodexRealtimeV3Bridge(
 
 function finalTranscript(
   randomUUID: () => string,
-  event: Extract<CodexRealtimeV3Event, { type: "turn.done" }>,
+  event: Extract<CodexRealtimeV3Event, { type: "turn.done" | "transcript.segment" }>,
   coveredByDelegationItemId: string | null,
   modelContext: string | undefined,
 ): SessionRealtimeInboundEntry {
@@ -581,6 +587,9 @@ function finalTranscript(
     text: event.transcript,
     payload: {
       turnId: event.turnId,
+      ...(event.type === "transcript.segment"
+        ? { transcriptSource: "provider_fragments", grouping: "application_segment" }
+        : {}),
       ...(coveredByDelegationItemId ? { coveredByDelegationItemId } : {}),
     },
     ...(modelContext ? { modelContext } : {}),

package/src/codex-realtime.ts

@@ -37,6 +37,8 @@ export type AcquireCodexRealtimeMicrophoneOptions = {
 
 export type StartCodexRealtimeWebrtcOptions = {
   negotiate: CodexRealtimeNegotiator;
+  /** Exact configured provider model expected from the server broker. */
+  expectedModel?: CodexRealtimeWebrtcResponse["model"];
   realtimeId: string;
   operationId: string;
   browserInstanceId: string;
@@ -77,6 +79,8 @@ export type CodexRealtimeWebrtcSession = {
   setOutputMuted(muted: boolean): void;
   activateRemoteAudio(): void;
   retryAudibleOutput(): Promise<boolean>;
+  /** Gracefully finish provider output before sealing the durable ledger. */
+  drain?(): Promise<void>;
   /** Idempotently close media, data channel, and peer transport. */
   stop(): void;
 };
@@ -85,7 +89,7 @@ export type CodexRealtimeWebrtcSession = {
  * Complete the browser half of native connected-Codex GPT-Live V3 negotiation.
  * Provider credentials never enter this boundary: `negotiate` sends SDP,
  * public session configuration, and the active browser-owner proof only to the
- * OpenGeni API.
+ * Opengeni API.
  */
 export async function startCodexRealtimeWebrtc(
   options: StartCodexRealtimeWebrtcOptions,
@@ -260,8 +264,12 @@ export async function startCodexRealtimeWebrtc(
       { signal: options.signal },
     );
     throwIfAborted(options.signal);
-    if (answer.version !== "v3" || answer.model !== "gpt-live-1-boulder-alpha" || !answer.sdp) {
-      throw new Error("OpenGeni returned an incompatible Codex realtime answer");
+    if (
+      answer.version !== "v3" ||
+      answer.model !== (options.expectedModel ?? "gpt-live-1-boulder-alpha") ||
+      !answer.sdp
+    ) {
+      throw new Error("Opengeni returned an incompatible Codex realtime answer");
     }
     await peerConnection.setRemoteDescription({
       type: "answer",

package/src/company-brain.ts

@@ -2,23 +2,11 @@ import type {
   CompanyBrainContextReceiptPage as ContractCompanyBrainContextReceiptPage,
   CompanyBrainKnowledgeProposalPage as ContractCompanyBrainKnowledgeProposalPage,
   CompanyBrainOkfPackage as ContractCompanyBrainOkfPackage,
-  KnowledgeBrowseRequest as ContractKnowledgeBrowseRequest,
-  KnowledgeBrowseResponse as ContractKnowledgeBrowseResponse,
-  KnowledgeGetResponse as ContractKnowledgeGetResponse,
-  KnowledgeRecord as ContractKnowledgeRecord,
-  KnowledgeSearchRequest as ContractKnowledgeSearchRequest,
-  KnowledgeSearchResponse as ContractKnowledgeSearchResponse,
 } from "@opengeni/contracts";
 
 export type CompanyBrainOkfPackage = ContractCompanyBrainOkfPackage;
 export type CompanyBrainContextReceiptPage = ContractCompanyBrainContextReceiptPage;
 export type CompanyBrainKnowledgeProposalPage = ContractCompanyBrainKnowledgeProposalPage;
-export type CompanyBrainKnowledgeSearchRequest = ContractKnowledgeSearchRequest;
-export type CompanyBrainKnowledgeSearchResponse = ContractKnowledgeSearchResponse;
-export type CompanyBrainKnowledgeBrowseRequest = ContractKnowledgeBrowseRequest;
-export type CompanyBrainKnowledgeBrowseResponse = ContractKnowledgeBrowseResponse;
-export type CompanyBrainKnowledgeGetResponse = ContractKnowledgeGetResponse;
-export type CompanyBrainKnowledgeRecord = ContractKnowledgeRecord;
 
 export type CompanyBrainContextReceiptListOptions = {
   attemptId?: string;
@@ -38,34 +26,6 @@ function inspectorPath(workspaceId: string, suffix: string): string {
   return `/v1/workspaces/${workspaceId}/company-brain/${suffix}`;
 }
 
-/** Human-authorized, permission-first Knowledge search for Company Brain inspectors. */
-export function searchCompanyBrainKnowledge(
-  client: CompanyBrainInspectorTransport,
-  workspaceId: string,
-  request: CompanyBrainKnowledgeSearchRequest,
-): Promise<CompanyBrainKnowledgeSearchResponse> {
-  return client.requestJson("POST", inspectorPath(workspaceId, "knowledge/search"), request);
-}
-
-export function getCompanyBrainKnowledge(
-  client: CompanyBrainInspectorTransport,
-  workspaceId: string,
-  recordId: string,
-): Promise<CompanyBrainKnowledgeGetResponse> {
-  return client.requestJson(
-    "GET",
-    `${inspectorPath(workspaceId, "knowledge/record")}?id=${encodeURIComponent(recordId)}`,
-  );
-}
-
-export function browseCompanyBrainKnowledge(
-  client: CompanyBrainInspectorTransport,
-  workspaceId: string,
-  request: CompanyBrainKnowledgeBrowseRequest = {},
-): Promise<CompanyBrainKnowledgeBrowseResponse> {
-  return client.requestJson("POST", inspectorPath(workspaceId, "knowledge/browse"), request);
-}
-
 export function listCompanyBrainContextReceipts(
   client: CompanyBrainInspectorTransport,
   workspaceId: string,

package/src/core.ts

@@ -1,7 +1,21 @@
 /** Backward-compatible non-artifact client surface. */
 export { OpenGeniDocumentAuthorityClient as OpenGeniCoreClient } from "./document-authority-client";
+export {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+} from "./tools";
+export type {
+  OpenGeniGeneratedTools,
+  OpenGeniDynamicToolNode,
+  OpenGeniToolCallOptions,
+  OpenGeniToolFunction,
+  OpenGeniToolsFacade,
+  OpenGeniWorkspaceTools,
+} from "./tools";
 export type {
   FetchLike,
+  FetchResponse,
   GetSessionOptions,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,
@@ -13,9 +27,15 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSetupError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
+  formatErrorMessage,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { parseDeprecationNotice } from "./deprecation";
+export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";

package/src/deprecation.ts

@@ -0,0 +1,149 @@
+/**
+ * Deprecation notices advertised by the Opengeni API.
+ *
+ * Per the public API compatibility policy, a route whose behaviour is scheduled
+ * for removal answers with the standard `Deprecation` (RFC 9745) and `Sunset`
+ * (RFC 8594) headers plus `Link: <notes>; rel="deprecation"`. The client
+ * surfaces them through `OpenGeniClientOptions.onDeprecation`, or by default
+ * as a one-time `console.warn` per route, so an integrator pinned to an older
+ * SDK learns about a removal well before it happens.
+ */
+
+export type OpenGeniDeprecationNotice = {
+  /** Request method, upper case. */
+  method: string;
+  /** Request path with ids collapsed (`/v1/workspaces/:id/...`), stable per route. */
+  route: string;
+  /** Exact request path. */
+  path: string;
+  /** When the deprecation was announced, if the header carried a date. */
+  deprecatedAt: Date | null;
+  /** Earliest removal on the server, if advertised. */
+  sunset: Date | null;
+  /** Migration notes (`rel="deprecation"`), if advertised. */
+  link: string | null;
+  /** Replacement (`rel="successor-version"`), if advertised. */
+  successor: string | null;
+};
+
+/** `false` silences notices; a function receives each route's notice once per client. */
+export type OpenGeniDeprecationHandler = (notice: OpenGeniDeprecationNotice) => void;
+
+type HeaderBag = { get(name: string): string | null };
+
+const ID_SEGMENT =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\d+|[A-Za-z0-9_-]{20,})$/i;
+
+function routeKey(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => (ID_SEGMENT.test(segment) ? ":id" : segment))
+    .join("/");
+}
+
+function parseDeprecationDate(value: string): Date | null {
+  const trimmed = value.trim();
+  // RFC 9745 structured date `@<unix seconds>`; older drafts used `true` or an HTTP-date.
+  const structured = /^@(-?\d+)$/.exec(trimmed);
+  if (structured) return new Date(Number(structured[1]) * 1000);
+  const parsed = Date.parse(trimmed);
+  return Number.isNaN(parsed) ? null : new Date(parsed);
+}
+
+function parseLinks(value: string | null): Map<string, string> {
+  const links = new Map<string, string>();
+  if (!value) return links;
+  for (const match of value.matchAll(/<([^>]*)>\s*((?:;\s*[^;,]+)*)/g)) {
+    const rel = /;\s*rel="?([^";,]+)"?/i.exec(match[2] ?? "")?.[1];
+    if (!rel) continue;
+    for (const name of rel.toLowerCase().split(/\s+/)) {
+      if (!links.has(name)) links.set(name, match[1]!);
+    }
+  }
+  return links;
+}
+
+/** Read a deprecation notice from response headers; `null` when none is advertised. */
+export function parseDeprecationNotice(
+  method: string,
+  url: string,
+  headers: HeaderBag,
+): OpenGeniDeprecationNotice | null {
+  const deprecation = headers.get("deprecation");
+  const sunsetHeader = headers.get("sunset");
+  if (!deprecation && !sunsetHeader) return null;
+  let path = url;
+  try {
+    path = new URL(url, "http://opengeni.invalid").pathname;
+  } catch {
+    // Keep the raw value; the notice is advisory.
+  }
+  const sunset = sunsetHeader ? Date.parse(sunsetHeader) : Number.NaN;
+  const links = parseLinks(headers.get("link"));
+  return {
+    method: method.toUpperCase(),
+    route: routeKey(path),
+    path,
+    deprecatedAt: deprecation ? parseDeprecationDate(deprecation) : null,
+    sunset: Number.isNaN(sunset) ? null : new Date(sunset),
+    link: links.get("deprecation") ?? links.get("sunset") ?? null,
+    successor: links.get("successor-version") ?? null,
+  };
+}
+
+const warnedRoutes = new Set<string>();
+
+/** The default handler: one `console.warn` per route per process. */
+export function warnDeprecationOnce(notice: OpenGeniDeprecationNotice): void {
+  const key = `${notice.method} ${notice.route}`;
+  if (warnedRoutes.has(key)) return;
+  warnedRoutes.add(key);
+  const sunset = notice.sunset ? ` and will be removed after ${notice.sunset.toISOString()}` : "";
+  const notes = notice.link ? ` Migration notes: ${notice.link}.` : "";
+  console.warn(
+    `[@opengeni/sdk] ${key} is deprecated${sunset}.${notes} Upgrade @opengeni/sdk, or pass onDeprecation to handle this notice.`,
+  );
+}
+
+type FetchFunction<R extends { headers: HeaderBag }> = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<R>;
+
+/**
+ * Wrap a fetch implementation so every response is inspected for a deprecation
+ * notice. The handler runs at most once per route for this wrapper and never
+ * affects the request: a throwing handler is swallowed.
+ */
+export function withDeprecationNotices<R extends { headers: HeaderBag }>(
+  fetchImpl: FetchFunction<R>,
+  handler: OpenGeniDeprecationHandler | false | undefined,
+): FetchFunction<R> {
+  if (handler === false) return fetchImpl;
+  const notify = handler ?? warnDeprecationOnce;
+  const seen = new Set<string>();
+  return async (input, init) => {
+    const response = await fetchImpl(input, init);
+    try {
+      const headers = response.headers;
+      if (headers && (headers.get("deprecation") || headers.get("sunset"))) {
+        const method =
+          init?.method ??
+          (typeof Request !== "undefined" && input instanceof Request ? input.method : "GET");
+        const url =
+          typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const notice = parseDeprecationNotice(method, url, headers);
+        if (notice) {
+          const key = `${notice.method} ${notice.route}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            notify(notice);
+          }
+        }
+      }
+    } catch {
+      // Deprecation notices are advisory and must never fail a request.
+    }
+    return response;
+  };
+}