@reliantlabs/forge-web-runtime 0.12.0 → 0.13.2

package/dist/service-hooks.js

@@ -29,12 +29,14 @@
 // an engine with its own dependency footprint gets its own entry point, and
 // React Query is an OPTIONAL peer.
 //
-// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the
-// app-wide MutationCache in src/lib/query-client.ts is the single error-toast
-// chokepoint, and pages that render errors inline pass
-// `meta: { silenceErrorToast: true }`. It never defaults success-side UX
-// either: "CreateOrder succeeded" leaks RPC names into the UI, so the toast /
-// redirect / inline confirmation stays the call site's via options.onSuccess.
+// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — they
+// belong to one app-wide chokepoint, a MutationCache onError on the app's
+// QueryClient (a forge scaffold installs it in src/lib/query-client.ts, and
+// pages that render errors inline pass `meta: { silenceErrorToast: true }`);
+// an app without one handles errors at the call site. It never defaults
+// success-side UX either: "CreateOrder succeeded" leaks RPC names into the
+// UI, so the toast / redirect / inline confirmation stays the call site's via
+// options.onSuccess.
 import { create, toJson, } from "@bufbuild/protobuf";
 import { infiniteQueryOptions, queryOptions, useInfiniteQuery, useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
 /**

package/dist/service-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  infiniteQueryOptions,\n  queryOptions,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type DataTag,\n  type InfiniteData,\n  type UseInfiniteQueryOptions,\n  type UseInfiniteQueryResult,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/**\n * One read's key entry in a generated factory: `orderServiceKeys.getOrder`.\n *\n * Called, it is that request's key, [service, entity?, method,\n * protojson(req)]. Its `.all` is the rpc's scope, [service, entity?,\n * method]: a prefix of every key the rpc caches under — every request, the\n * plain query and the `<method>Infinite` read alike — and of no other rpc's.\n *\n *   queryClient.invalidateQueries({ queryKey: orderServiceKeys.listOrders.all })\n *   queryClient.setQueriesData({ queryKey: orderServiceKeys.getOrder.all }, patch)\n *\n * It exists so code never names a key's tuple positions. A predicate like\n * `query.queryKey[1] === \"listOrders\"` breaks silently when a\n * `// forge:query-scope` marker inserts the entity at index 1; `.all` is\n * built by the same function that builds the keys, so it moves with them.\n *\n * `.all` is not data-tagged. It names a SET of entries, and for a paged\n * read that set holds two shapes (the response, and the infinite read's\n * `{ pages, pageParams }`), so a `setQueriesData` updater over it must\n * handle both.\n */\nexport type ServiceMethodKey<Schema extends DescMessage> = ((\n  req: MessageInitShape<Schema>,\n) => ServiceQueryKey) & {\n  /** Every cached request of this rpc: [service, entity?, method]. */\n  readonly all: ServiceQueryKey;\n};\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use, with the rpc's scope\n   * [service, entity?, method] on it as `.all` (ServiceMethodKey).\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): ServiceMethodKey<Schema>;\n  /**\n   * One paged read: [service, entity?, method, protojson(req), \"infinite\"],\n   * where req is the request WITHOUT its page token — the hook owns the\n   * token, so every page of one listing shares one cache entry.\n   *\n   * It nests under the same scopes as `query`, so an entity or service-wide\n   * invalidation refetches it. The \"infinite\" suffix keeps it OFF the plain\n   * query's entry for the same request: an infinite query caches\n   * `{ pages, pageParams }`, not one response, and a plain hook reading that\n   * entry would get the wrong shape.\n   */\n  infinite<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: PageRequest<Schema>) => ServiceQueryKey;\n}\n\n/**\n * Omit distributed over a union. MessageInitShape is `Message | init\n * object`, and a plain Omit over a union keeps only the keys both members\n * share — which would silently drop every field from the init side.\n */\ntype DistributiveOmit<T, K extends PropertyKey> = T extends unknown\n  ? Omit<T, K>\n  : never;\n\n/**\n * The request a generated infinite hook takes: the rpc's request without\n * `pageToken`, which the hook supplies page by page.\n */\nexport type PageRequest<Schema extends DescMessage> = DistributiveOmit<\n  MessageInitShape<Schema>,\n  \"pageToken\"\n>;\n\n/**\n * The response shape forge's list-pagination convention (AIP-158) gives a\n * paged read: `string next_page_token`, empty on the last page. Optional so\n * an `optional string next_page_token` response satisfies it too.\n */\nexport interface PagedResponse {\n  nextPageToken?: string;\n}\n\n/**\n * pageRequestKey is requestKey with the page token dropped, so every page of\n * one listing hashes to one key even when a caller (JS, or a cast) passes a\n * token anyway. It is dropped from the protojson rather than from the init\n * object: a spread Message keeps its $typeName, and create() would hand that\n * token-less copy back as if it were a complete message.\n */\nfunction pageRequestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: PageRequest<Schema>,\n): unknown {\n  const json = requestKey(schema, req as unknown as MessageInitShape<Schema>);\n  if (json === null || typeof json !== \"object\" || Array.isArray(json)) {\n    return json;\n  }\n  const { pageToken: _pageToken, ...rest } = json as Record<string, unknown>;\n  return rest;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  // The rpc scope every key below starts with. Both builders derive their\n  // keys from it, so `.all` is a prefix of them by construction, not by a\n  // second copy of the tuple layout.\n  const rpcScope = (method: string, entityScope?: string): ServiceQueryKey =>\n    entityScope === undefined\n      ? ([service, method] as const)\n      : ([service, entityScope, method] as const);\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query: <Schema extends DescMessage>(\n      method: string,\n      schema: Schema,\n      entityScope?: string,\n    ): ServiceMethodKey<Schema> => {\n      const all = rpcScope(method, entityScope);\n      return Object.assign(\n        (req: MessageInitShape<Schema>): ServiceQueryKey => [\n          ...all,\n          requestKey(schema, req),\n        ],\n        { all },\n      );\n    },\n    infinite:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: PageRequest<Schema>): ServiceQueryKey => [\n        ...rpcScope(method, entityScope),\n        pageRequestKey(schema, req),\n        \"infinite\",\n      ],\n  };\n}\n\n/**\n * How a generated file calls one rpc. `signal` is React Query's: a query\n * that is unmounted or superseded (a new key while typing) aborts its\n * request instead of letting it land on a cache entry nobody reads.\n */\nexport type ServiceCall<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  signal?: AbortSignal,\n) => Promise<Response>;\n\n/**\n * The options a generated read takes — its hook (`useGetOrder(req,\n * options?)`) and its query-options builder\n * (`orderServiceQueries.getOrder(req, options?)`) alike: React Query's own,\n * minus the two the read owns, the key and the fetch. Everything else\n * (`select`, `enabled`, `staleTime`, `placeholderData`, …) passes through.\n *\n * TData is what `data` is, exactly as in React Query's own useQuery: the\n * response by default, or whatever `select` returns. A call site mapping the\n * proto response to a view model passes `select: (r) => toView(r)` and gets\n * `data: View` — no useMemo over `data`, and React Query re-runs the mapping\n * only when the response changes (or when `select` itself does, so hoist it\n * or wrap it in useCallback when it is expensive).\n */\nexport type ServiceQueryInput<Response, TData = Response> = Partial<\n  Omit<\n    UseQueryOptions<Response, ConnectClientError, TData, ServiceQueryKey>,\n    \"queryKey\" | \"queryFn\"\n  >\n>;\n\n/**\n * What a query-options builder returns: TanStack's `queryOptions(...)`\n * result, so it goes anywhere React Query takes one —\n * `queryClient.fetchQuery`, `ensureQueryData`, `prefetchQuery`,\n * `useQueries({ queries })`, `useQuery`, `useSuspenseQuery`. Its `queryKey`\n * is data-tagged, so `queryClient.getQueryData(opts.queryKey)` and\n * `setQueryData` are typed as the response with no annotation.\n *\n * fetchQuery / ensureQueryData resolve to the RESPONSE, not to `select`'s\n * TData: they return what the cache holds, and `select` is an observer\n * option that only a hook or useQueries applies.\n */\nexport type ServiceQueryOptions<Response, TData = Response> = UseQueryOptions<\n  Response,\n  ConnectClientError,\n  TData,\n  ServiceQueryKey\n> & {\n  queryKey: DataTag<ServiceQueryKey, Response, ConnectClientError>;\n};\n\n/**\n * A generated query-options builder: `orderServiceQueries.getOrder(req,\n * options?)`. It is the read's single definition — the generated hook\n * `useGetOrder` is `useQuery` over exactly this — so code outside React (an\n * imperative action, a stream handler, a router loader, a prefetch) shares\n * the hook's cache entry and fetch by construction rather than by copying\n * its key and its client call.\n */\nexport type ServiceQueryOptionsBuilder<Schema extends DescMessage, Response> = <\n  TData = Response,\n>(\n  req: MessageInitShape<Schema>,\n  options?: ServiceQueryInput<Response, TData>,\n) => ServiceQueryOptions<Response, TData>;\n\n/**\n * A generated query hook: `useGetOrder(req, options?)` — `useQuery` over the\n * service's query-options builder for the same rpc. TData is inferred from\n * `select` and is a parameter of the HOOK, not of the factory, so every call\n * site picks its own.\n */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = <\n  TData = Response,\n>(\n  req: MessageInitShape<Schema>,\n  options?: ServiceQueryInput<Response, TData>,\n) => UseQueryResult<TData, ConnectClientError>;\n\n/**\n * The options a generated infinite read takes: React Query's own, minus the\n * three the read owns — the key, the fetch, and the first page param.\n * `getNextPageParam` defaults to the response's `nextPageToken` (empty means\n * last page) and may be overridden; everything else (`select`,\n * `placeholderData`, `staleTime`, `enabled`, `maxPages`, …) passes through.\n */\nexport type ServiceInfiniteQueryInput<Response, TData> = Partial<\n  Omit<\n    UseInfiniteQueryOptions<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\"\n  >\n>;\n\n/**\n * What an infinite query-options builder returns: TanStack's\n * `infiniteQueryOptions(...)` result, for `queryClient.fetchInfiniteQuery`,\n * `prefetchInfiniteQuery`, `ensureInfiniteQueryData` and\n * `useInfiniteQuery`. Its key is data-tagged as `InfiniteData<Response,\n * string>`, the `{ pages, pageParams }` the cache holds.\n */\nexport type ServiceInfiniteQueryOptions<\n  Response,\n  TData = InfiniteData<Response, string>,\n> = UseInfiniteQueryOptions<\n  Response,\n  ConnectClientError,\n  TData,\n  ServiceQueryKey,\n  string\n> & {\n  queryKey: DataTag<\n    ServiceQueryKey,\n    InfiniteData<Response, string>,\n    ConnectClientError\n  >;\n};\n\n/**\n * A generated infinite query-options builder:\n * `orderServiceQueries.listOrdersInfinite(req, options?)`, for a read that\n * follows forge's list-pagination shape. `useListOrdersInfinite` is\n * `useInfiniteQuery` over exactly this.\n */\nexport type ServiceInfiniteQueryOptionsBuilder<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n> = <TData = InfiniteData<Response, string>>(\n  req: PageRequest<Schema>,\n  options?: ServiceInfiniteQueryInput<Response, TData>,\n) => ServiceInfiniteQueryOptions<Response, TData>;\n\n/**\n * A generated infinite-query hook: `useListOrdersInfinite(req, options?)`,\n * for a read that follows forge's list-pagination shape (`string page_token`\n * on the request, `string next_page_token` on the response).\n *\n * `req` is the first page's request without its token. `data` is React\n * Query's `{ pages, pageParams }` by default; `select` reshapes it, so\n * flattening the pages into one list is\n * `select: (d) => d.pages.flatMap((p) => p.orders)`.\n */\nexport type ServiceInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n> = <TData = InfiniteData<Response, string>>(\n  req: PageRequest<Schema>,\n  options?: ServiceInfiniteQueryInput<Response, TData>,\n) => UseInfiniteQueryResult<TData, ConnectClientError>;\n\n/**\n * A generated mutation hook: `useCreateOrder(options?)`.\n *\n * TContext is React Query's fourth type parameter — what `onMutate` returns\n * and `onError` / `onSettled` receive back. It is a parameter of the HOOK,\n * not of the factory, so each call site gets its own: TypeScript infers it\n * from the `onMutate` the caller passes, and an optimistic update reads its\n * rollback off `context` with no cast. Fixing it at the factory (or leaving\n * it out, which pinned it to `unknown`) forced every such call site to\n * narrow `unknown` by hand. It defaults to `unknown`, so a call without\n * `onMutate` types exactly as before.\n */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = <\n  TContext = unknown,\n>(\n  options?: Partial<\n    UseMutationOptions<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >\n  >,\n) => UseMutationResult<\n  Response,\n  ConnectClientError,\n  MessageInitShape<Schema>,\n  TContext\n>;\n\n/**\n * createQueryOptions builds one read's query-options builder — the single\n * definition of its cache key and its fetch that the generated hook, and\n * every caller outside React, share.\n *\n * The error is typed as ConnectClientError rather than React Query's default\n * `Error`, on the options themselves, because React Query takes a result's\n * error type from the TError it reads there: `query.error` is a\n * ConnectClientError at every call site with nothing to pass. Typing it as\n * `Error` hid `.reason`, `.codeName`, `.status` and `.retryable`, and left\n * `err.message.includes(...)` as the only expression that compiled — the one\n * thing the error contract forbids.\n *\n * The caller's options are spread BEFORE the key and the fetch: a caller may\n * set anything else, never the two that make this read this read.\n */\nexport function createQueryOptions<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceQueryOptionsBuilder<Schema, Response> {\n  return <TData = Response>(\n    req: MessageInitShape<Schema>,\n    options?: ServiceQueryInput<Response, TData>,\n  ): ServiceQueryOptions<Response, TData> =>\n    queryOptions<Response, ConnectClientError, TData, ServiceQueryKey>({\n      ...options,\n      queryKey: keyFor(req),\n      queryFn: ({ signal }) => call(req, signal),\n    }) as ServiceQueryOptions<Response, TData>;\n}\n\n/**\n * createQueryHook builds one useQuery wrapper over a read's query-options\n * builder. It adds nothing to the options: a hook and a `fetchQuery` of the\n * same request therefore read and write one cache entry with one fetch.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  optionsFor: ServiceQueryOptionsBuilder<Schema, Response>,\n): ServiceQueryHook<Schema, Response> {\n  return <TData = Response>(\n    req: MessageInitShape<Schema>,\n    options?: ServiceQueryInput<Response, TData>,\n  ) => useQuery(optionsFor(req, options));\n}\n\n/**\n * createInfiniteQueryOptions builds one paged read's infinite query-options\n * builder.\n *\n * The page token is the builder's: the first page is fetched with the\n * caller's request as given (no token, so an `optional string page_token`\n * stays unset), each later one with the previous response's\n * `nextPageToken`, and an empty token ends the listing. The key is\n * `keys.infinite(...)`, which strips the token and sits under the service and\n * entity scopes, so the mutations that invalidate a plain list refetch this\n * one too.\n *\n * The caller's options are spread BETWEEN the default getNextPageParam and\n * the three fields the read owns: a caller may replace the default, never the\n * key, the fetch or the first page.\n */\nexport function createInfiniteQueryOptions<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n>(\n  keyFor: (req: PageRequest<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceInfiniteQueryOptionsBuilder<Schema, Response> {\n  return <TData = InfiniteData<Response, string>>(\n    req: PageRequest<Schema>,\n    options?: ServiceInfiniteQueryInput<Response, TData>,\n  ): ServiceInfiniteQueryOptions<Response, TData> =>\n    infiniteQueryOptions<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >({\n      getNextPageParam: (last) => last.nextPageToken || undefined,\n      ...options,\n      queryKey: keyFor(req),\n      queryFn: ({ pageParam, signal }) =>\n        call(\n          (pageParam === \"\"\n            ? req\n            : {\n                ...req,\n                pageToken: pageParam,\n              }) as unknown as MessageInitShape<Schema>,\n          signal,\n        ),\n      initialPageParam: \"\",\n    }) as ServiceInfiniteQueryOptions<Response, TData>;\n}\n\n/**\n * createInfiniteQueryHook builds one useInfiniteQuery wrapper over a paged\n * read's infinite query-options builder, adding nothing to it — so a hook\n * and a `fetchInfiniteQuery` of the same request share one cache entry.\n */\nexport function createInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n>(\n  optionsFor: ServiceInfiniteQueryOptionsBuilder<Schema, Response>,\n): ServiceInfiniteQueryHook<Schema, Response> {\n  return <TData = InfiniteData<Response, string>>(\n    req: PageRequest<Schema>,\n    options?: ServiceInfiniteQueryInput<Response, TData>,\n  ) => useInfiniteQuery(optionsFor(req, options));\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return <TContext = unknown>(\n    options?: Partial<\n      UseMutationOptions<\n        Response,\n        ConnectClientError,\n        MessageInitShape<Schema>,\n        TContext\n      >\n    >,\n  ) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}
+{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — they\n// belong to one app-wide chokepoint, a MutationCache onError on the app's\n// QueryClient (a forge scaffold installs it in src/lib/query-client.ts, and\n// pages that render errors inline pass `meta: { silenceErrorToast: true }`);\n// an app without one handles errors at the call site. It never defaults\n// success-side UX either: \"CreateOrder succeeded\" leaks RPC names into the\n// UI, so the toast / redirect / inline confirmation stays the call site's via\n// options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  infiniteQueryOptions,\n  queryOptions,\n  useInfiniteQuery,\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type DataTag,\n  type InfiniteData,\n  type UseInfiniteQueryOptions,\n  type UseInfiniteQueryResult,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/**\n * One read's key entry in a generated factory: `orderServiceKeys.getOrder`.\n *\n * Called, it is that request's key, [service, entity?, method,\n * protojson(req)]. Its `.all` is the rpc's scope, [service, entity?,\n * method]: a prefix of every key the rpc caches under — every request, the\n * plain query and the `<method>Infinite` read alike — and of no other rpc's.\n *\n *   queryClient.invalidateQueries({ queryKey: orderServiceKeys.listOrders.all })\n *   queryClient.setQueriesData({ queryKey: orderServiceKeys.getOrder.all }, patch)\n *\n * It exists so code never names a key's tuple positions. A predicate like\n * `query.queryKey[1] === \"listOrders\"` breaks silently when a\n * `// forge:query-scope` marker inserts the entity at index 1; `.all` is\n * built by the same function that builds the keys, so it moves with them.\n *\n * `.all` is not data-tagged. It names a SET of entries, and for a paged\n * read that set holds two shapes (the response, and the infinite read's\n * `{ pages, pageParams }`), so a `setQueriesData` updater over it must\n * handle both.\n */\nexport type ServiceMethodKey<Schema extends DescMessage> = ((\n  req: MessageInitShape<Schema>,\n) => ServiceQueryKey) & {\n  /** Every cached request of this rpc: [service, entity?, method]. */\n  readonly all: ServiceQueryKey;\n};\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use, with the rpc's scope\n   * [service, entity?, method] on it as `.all` (ServiceMethodKey).\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): ServiceMethodKey<Schema>;\n  /**\n   * One paged read: [service, entity?, method, protojson(req), \"infinite\"],\n   * where req is the request WITHOUT its page token — the hook owns the\n   * token, so every page of one listing shares one cache entry.\n   *\n   * It nests under the same scopes as `query`, so an entity or service-wide\n   * invalidation refetches it. The \"infinite\" suffix keeps it OFF the plain\n   * query's entry for the same request: an infinite query caches\n   * `{ pages, pageParams }`, not one response, and a plain hook reading that\n   * entry would get the wrong shape.\n   */\n  infinite<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: PageRequest<Schema>) => ServiceQueryKey;\n}\n\n/**\n * Omit distributed over a union. MessageInitShape is `Message | init\n * object`, and a plain Omit over a union keeps only the keys both members\n * share — which would silently drop every field from the init side.\n */\ntype DistributiveOmit<T, K extends PropertyKey> = T extends unknown\n  ? Omit<T, K>\n  : never;\n\n/**\n * The request a generated infinite hook takes: the rpc's request without\n * `pageToken`, which the hook supplies page by page.\n */\nexport type PageRequest<Schema extends DescMessage> = DistributiveOmit<\n  MessageInitShape<Schema>,\n  \"pageToken\"\n>;\n\n/**\n * The response shape forge's list-pagination convention (AIP-158) gives a\n * paged read: `string next_page_token`, empty on the last page. Optional so\n * an `optional string next_page_token` response satisfies it too.\n */\nexport interface PagedResponse {\n  nextPageToken?: string;\n}\n\n/**\n * pageRequestKey is requestKey with the page token dropped, so every page of\n * one listing hashes to one key even when a caller (JS, or a cast) passes a\n * token anyway. It is dropped from the protojson rather than from the init\n * object: a spread Message keeps its $typeName, and create() would hand that\n * token-less copy back as if it were a complete message.\n */\nfunction pageRequestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: PageRequest<Schema>,\n): unknown {\n  const json = requestKey(schema, req as unknown as MessageInitShape<Schema>);\n  if (json === null || typeof json !== \"object\" || Array.isArray(json)) {\n    return json;\n  }\n  const { pageToken: _pageToken, ...rest } = json as Record<string, unknown>;\n  return rest;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  // The rpc scope every key below starts with. Both builders derive their\n  // keys from it, so `.all` is a prefix of them by construction, not by a\n  // second copy of the tuple layout.\n  const rpcScope = (method: string, entityScope?: string): ServiceQueryKey =>\n    entityScope === undefined\n      ? ([service, method] as const)\n      : ([service, entityScope, method] as const);\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query: <Schema extends DescMessage>(\n      method: string,\n      schema: Schema,\n      entityScope?: string,\n    ): ServiceMethodKey<Schema> => {\n      const all = rpcScope(method, entityScope);\n      return Object.assign(\n        (req: MessageInitShape<Schema>): ServiceQueryKey => [\n          ...all,\n          requestKey(schema, req),\n        ],\n        { all },\n      );\n    },\n    infinite:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: PageRequest<Schema>): ServiceQueryKey => [\n        ...rpcScope(method, entityScope),\n        pageRequestKey(schema, req),\n        \"infinite\",\n      ],\n  };\n}\n\n/**\n * How a generated file calls one rpc. `signal` is React Query's: a query\n * that is unmounted or superseded (a new key while typing) aborts its\n * request instead of letting it land on a cache entry nobody reads.\n */\nexport type ServiceCall<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  signal?: AbortSignal,\n) => Promise<Response>;\n\n/**\n * The options a generated read takes — its hook (`useGetOrder(req,\n * options?)`) and its query-options builder\n * (`orderServiceQueries.getOrder(req, options?)`) alike: React Query's own,\n * minus the two the read owns, the key and the fetch. Everything else\n * (`select`, `enabled`, `staleTime`, `placeholderData`, …) passes through.\n *\n * TData is what `data` is, exactly as in React Query's own useQuery: the\n * response by default, or whatever `select` returns. A call site mapping the\n * proto response to a view model passes `select: (r) => toView(r)` and gets\n * `data: View` — no useMemo over `data`, and React Query re-runs the mapping\n * only when the response changes (or when `select` itself does, so hoist it\n * or wrap it in useCallback when it is expensive).\n */\nexport type ServiceQueryInput<Response, TData = Response> = Partial<\n  Omit<\n    UseQueryOptions<Response, ConnectClientError, TData, ServiceQueryKey>,\n    \"queryKey\" | \"queryFn\"\n  >\n>;\n\n/**\n * What a query-options builder returns: TanStack's `queryOptions(...)`\n * result, so it goes anywhere React Query takes one —\n * `queryClient.fetchQuery`, `ensureQueryData`, `prefetchQuery`,\n * `useQueries({ queries })`, `useQuery`, `useSuspenseQuery`. Its `queryKey`\n * is data-tagged, so `queryClient.getQueryData(opts.queryKey)` and\n * `setQueryData` are typed as the response with no annotation.\n *\n * fetchQuery / ensureQueryData resolve to the RESPONSE, not to `select`'s\n * TData: they return what the cache holds, and `select` is an observer\n * option that only a hook or useQueries applies.\n */\nexport type ServiceQueryOptions<Response, TData = Response> = UseQueryOptions<\n  Response,\n  ConnectClientError,\n  TData,\n  ServiceQueryKey\n> & {\n  queryKey: DataTag<ServiceQueryKey, Response, ConnectClientError>;\n};\n\n/**\n * A generated query-options builder: `orderServiceQueries.getOrder(req,\n * options?)`. It is the read's single definition — the generated hook\n * `useGetOrder` is `useQuery` over exactly this — so code outside React (an\n * imperative action, a stream handler, a router loader, a prefetch) shares\n * the hook's cache entry and fetch by construction rather than by copying\n * its key and its client call.\n */\nexport type ServiceQueryOptionsBuilder<Schema extends DescMessage, Response> = <\n  TData = Response,\n>(\n  req: MessageInitShape<Schema>,\n  options?: ServiceQueryInput<Response, TData>,\n) => ServiceQueryOptions<Response, TData>;\n\n/**\n * A generated query hook: `useGetOrder(req, options?)` — `useQuery` over the\n * service's query-options builder for the same rpc. TData is inferred from\n * `select` and is a parameter of the HOOK, not of the factory, so every call\n * site picks its own.\n */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = <\n  TData = Response,\n>(\n  req: MessageInitShape<Schema>,\n  options?: ServiceQueryInput<Response, TData>,\n) => UseQueryResult<TData, ConnectClientError>;\n\n/**\n * The options a generated infinite read takes: React Query's own, minus the\n * three the read owns — the key, the fetch, and the first page param.\n * `getNextPageParam` defaults to the response's `nextPageToken` (empty means\n * last page) and may be overridden; everything else (`select`,\n * `placeholderData`, `staleTime`, `enabled`, `maxPages`, …) passes through.\n */\nexport type ServiceInfiniteQueryInput<Response, TData> = Partial<\n  Omit<\n    UseInfiniteQueryOptions<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >,\n    \"queryKey\" | \"queryFn\" | \"initialPageParam\"\n  >\n>;\n\n/**\n * What an infinite query-options builder returns: TanStack's\n * `infiniteQueryOptions(...)` result, for `queryClient.fetchInfiniteQuery`,\n * `prefetchInfiniteQuery`, `ensureInfiniteQueryData` and\n * `useInfiniteQuery`. Its key is data-tagged as `InfiniteData<Response,\n * string>`, the `{ pages, pageParams }` the cache holds.\n */\nexport type ServiceInfiniteQueryOptions<\n  Response,\n  TData = InfiniteData<Response, string>,\n> = UseInfiniteQueryOptions<\n  Response,\n  ConnectClientError,\n  TData,\n  ServiceQueryKey,\n  string\n> & {\n  queryKey: DataTag<\n    ServiceQueryKey,\n    InfiniteData<Response, string>,\n    ConnectClientError\n  >;\n};\n\n/**\n * A generated infinite query-options builder:\n * `orderServiceQueries.listOrdersInfinite(req, options?)`, for a read that\n * follows forge's list-pagination shape. `useListOrdersInfinite` is\n * `useInfiniteQuery` over exactly this.\n */\nexport type ServiceInfiniteQueryOptionsBuilder<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n> = <TData = InfiniteData<Response, string>>(\n  req: PageRequest<Schema>,\n  options?: ServiceInfiniteQueryInput<Response, TData>,\n) => ServiceInfiniteQueryOptions<Response, TData>;\n\n/**\n * A generated infinite-query hook: `useListOrdersInfinite(req, options?)`,\n * for a read that follows forge's list-pagination shape (`string page_token`\n * on the request, `string next_page_token` on the response).\n *\n * `req` is the first page's request without its token. `data` is React\n * Query's `{ pages, pageParams }` by default; `select` reshapes it, so\n * flattening the pages into one list is\n * `select: (d) => d.pages.flatMap((p) => p.orders)`.\n */\nexport type ServiceInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n> = <TData = InfiniteData<Response, string>>(\n  req: PageRequest<Schema>,\n  options?: ServiceInfiniteQueryInput<Response, TData>,\n) => UseInfiniteQueryResult<TData, ConnectClientError>;\n\n/**\n * A generated mutation hook: `useCreateOrder(options?)`.\n *\n * TContext is React Query's fourth type parameter — what `onMutate` returns\n * and `onError` / `onSettled` receive back. It is a parameter of the HOOK,\n * not of the factory, so each call site gets its own: TypeScript infers it\n * from the `onMutate` the caller passes, and an optimistic update reads its\n * rollback off `context` with no cast. Fixing it at the factory (or leaving\n * it out, which pinned it to `unknown`) forced every such call site to\n * narrow `unknown` by hand. It defaults to `unknown`, so a call without\n * `onMutate` types exactly as before.\n */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = <\n  TContext = unknown,\n>(\n  options?: Partial<\n    UseMutationOptions<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >\n  >,\n) => UseMutationResult<\n  Response,\n  ConnectClientError,\n  MessageInitShape<Schema>,\n  TContext\n>;\n\n/**\n * createQueryOptions builds one read's query-options builder — the single\n * definition of its cache key and its fetch that the generated hook, and\n * every caller outside React, share.\n *\n * The error is typed as ConnectClientError rather than React Query's default\n * `Error`, on the options themselves, because React Query takes a result's\n * error type from the TError it reads there: `query.error` is a\n * ConnectClientError at every call site with nothing to pass. Typing it as\n * `Error` hid `.reason`, `.codeName`, `.status` and `.retryable`, and left\n * `err.message.includes(...)` as the only expression that compiled — the one\n * thing the error contract forbids.\n *\n * The caller's options are spread BEFORE the key and the fetch: a caller may\n * set anything else, never the two that make this read this read.\n */\nexport function createQueryOptions<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceQueryOptionsBuilder<Schema, Response> {\n  return <TData = Response>(\n    req: MessageInitShape<Schema>,\n    options?: ServiceQueryInput<Response, TData>,\n  ): ServiceQueryOptions<Response, TData> =>\n    queryOptions<Response, ConnectClientError, TData, ServiceQueryKey>({\n      ...options,\n      queryKey: keyFor(req),\n      queryFn: ({ signal }) => call(req, signal),\n    }) as ServiceQueryOptions<Response, TData>;\n}\n\n/**\n * createQueryHook builds one useQuery wrapper over a read's query-options\n * builder. It adds nothing to the options: a hook and a `fetchQuery` of the\n * same request therefore read and write one cache entry with one fetch.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  optionsFor: ServiceQueryOptionsBuilder<Schema, Response>,\n): ServiceQueryHook<Schema, Response> {\n  return <TData = Response>(\n    req: MessageInitShape<Schema>,\n    options?: ServiceQueryInput<Response, TData>,\n  ) => useQuery(optionsFor(req, options));\n}\n\n/**\n * createInfiniteQueryOptions builds one paged read's infinite query-options\n * builder.\n *\n * The page token is the builder's: the first page is fetched with the\n * caller's request as given (no token, so an `optional string page_token`\n * stays unset), each later one with the previous response's\n * `nextPageToken`, and an empty token ends the listing. The key is\n * `keys.infinite(...)`, which strips the token and sits under the service and\n * entity scopes, so the mutations that invalidate a plain list refetch this\n * one too.\n *\n * The caller's options are spread BETWEEN the default getNextPageParam and\n * the three fields the read owns: a caller may replace the default, never the\n * key, the fetch or the first page.\n */\nexport function createInfiniteQueryOptions<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n>(\n  keyFor: (req: PageRequest<Schema>) => ServiceQueryKey,\n  call: ServiceCall<Schema, Response>,\n): ServiceInfiniteQueryOptionsBuilder<Schema, Response> {\n  return <TData = InfiniteData<Response, string>>(\n    req: PageRequest<Schema>,\n    options?: ServiceInfiniteQueryInput<Response, TData>,\n  ): ServiceInfiniteQueryOptions<Response, TData> =>\n    infiniteQueryOptions<\n      Response,\n      ConnectClientError,\n      TData,\n      ServiceQueryKey,\n      string\n    >({\n      getNextPageParam: (last) => last.nextPageToken || undefined,\n      ...options,\n      queryKey: keyFor(req),\n      queryFn: ({ pageParam, signal }) =>\n        call(\n          (pageParam === \"\"\n            ? req\n            : {\n                ...req,\n                pageToken: pageParam,\n              }) as unknown as MessageInitShape<Schema>,\n          signal,\n        ),\n      initialPageParam: \"\",\n    }) as ServiceInfiniteQueryOptions<Response, TData>;\n}\n\n/**\n * createInfiniteQueryHook builds one useInfiniteQuery wrapper over a paged\n * read's infinite query-options builder, adding nothing to it — so a hook\n * and a `fetchInfiniteQuery` of the same request share one cache entry.\n */\nexport function createInfiniteQueryHook<\n  Schema extends DescMessage,\n  Response extends PagedResponse,\n>(\n  optionsFor: ServiceInfiniteQueryOptionsBuilder<Schema, Response>,\n): ServiceInfiniteQueryHook<Schema, Response> {\n  return <TData = InfiniteData<Response, string>>(\n    req: PageRequest<Schema>,\n    options?: ServiceInfiniteQueryInput<Response, TData>,\n  ) => useInfiniteQuery(optionsFor(req, options));\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return <TContext = unknown>(\n    options?: Partial<\n      UseMutationOptions<\n        Response,\n        ConnectClientError,\n        MessageInitShape<Schema>,\n        TContext\n      >\n    >,\n  ) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation<\n      Response,\n      ConnectClientError,\n      MessageInitShape<Schema>,\n      TContext\n    >({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}

package/dist/session-cookie-fallback.d.ts

@@ -0,0 +1,23 @@
+/** The SDK's session cookie (otel-web COOKIE_NAME). */
+export declare const RUM_SESSION_COOKIE = "__rum_sid";
+/** Where the session cookie is kept when cookies do not persist. */
+export declare const RUM_SESSION_STORAGE_KEY = "forge.rum.session";
+/** The slice of Storage the fallback needs. */
+export interface SessionStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Whether `document.cookie` keeps what is written to it. Writes a short-lived
+ * probe cookie, reads it back and removes it.
+ */
+export declare function cookiesPersist(doc: Pick<Document, "cookie">): boolean;
+/**
+ * Keep the SDK's session cookie in `storage` when `doc` cannot keep cookies.
+ * Returns whether the fallback is now in place (it was installed by this call,
+ * or already was). Idempotent; never throws.
+ *
+ * Call it before the SDK initialises: the SDK reads the session at init.
+ */
+export declare function installSessionCookieFallback(doc: Document, storage: SessionStore | null, now?: () => number): boolean;

package/dist/session-cookie-fallback.js

@@ -0,0 +1,203 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// A stable RUM session on an origin that cannot keep cookies.
+//
+// ── Why ──────────────────────────────────────────────────────────────────
+//
+// The HyperDX SDK (its otel-web layer) keeps the session ONLY in a cookie,
+// `__rum_sid`: `{ id, startTime }`, written with `max-age=900` and renewed
+// while the user is active. Every 60 s it reads the cookie back, and when it
+// finds none it mints a new session id. There is no other store and no seam
+// to supply one: the session module is bundled inside the HyperDX browser package.
+//
+// Some origins accept a `document.cookie` write and silently keep nothing.
+// The one that matters is an Electron renderer served from a custom scheme
+// (`app://bundle/`): Chromium treats a non-http(s) scheme as non-cookieable
+// even when it is registered `standard` + `secure`, so the write is dropped
+// and `session.cookies.set` refuses with EXCLUDE_NONCOOKIEABLE_SCHEME.
+// Verified against Electron 41. On such an origin every open window starts a
+// new "session" every minute; each one re-uploads a full replay snapshot and
+// none of them is a session anyone can watch.
+//
+// ── What ─────────────────────────────────────────────────────────────────
+//
+// When, and only when, a probe cookie does not round-trip, the session cookie
+// is kept in localStorage instead. An own `cookie` accessor on `document`
+// answers reads and writes of `__rum_sid` from localStorage, honouring the
+// max-age the SDK writes, and passes every other cookie to the browser
+// untouched. The SDK's own rules then hold unchanged: the session expires 15
+// minutes after the last activity (max-age=900, renewed on activity) and never
+// outlives 4 hours (the startTime inside the value). localStorage is shared by
+// every window of the origin, as a cookie jar is, so the windows of one app
+// share one session the way the tabs of one browser do.
+//
+// An origin whose cookies work is left exactly as it was.
+/** The SDK's session cookie (otel-web COOKIE_NAME). */
+export const RUM_SESSION_COOKIE = "__rum_sid";
+/** Where the session cookie is kept when cookies do not persist. */
+export const RUM_SESSION_STORAGE_KEY = "forge.rum.session";
+const PROBE_COOKIE = "forge_cookie_probe";
+/**
+ * Whether `document.cookie` keeps what is written to it. Writes a short-lived
+ * probe cookie, reads it back and removes it.
+ */
+export function cookiesPersist(doc) {
+    try {
+        const token = Math.random().toString(36).slice(2);
+        doc.cookie = `${PROBE_COOKIE}=${token}; path=/; max-age=60; SameSite=Strict`;
+        const kept = doc.cookie
+            .split(";")
+            .some((c) => c.trim() === `${PROBE_COOKIE}=${token}`);
+        doc.cookie = `${PROBE_COOKIE}=; path=/; max-age=0; SameSite=Strict`;
+        return kept;
+    }
+    catch {
+        // A sandboxed document throws on cookie access: nothing persists.
+        return false;
+    }
+}
+/**
+ * Keep the SDK's session cookie in `storage` when `doc` cannot keep cookies.
+ * Returns whether the fallback is now in place (it was installed by this call,
+ * or already was). Idempotent; never throws.
+ *
+ * Call it before the SDK initialises: the SDK reads the session at init.
+ */
+export function installSessionCookieFallback(doc, storage, now = Date.now) {
+    try {
+        if (installed.has(doc)) {
+            return true;
+        }
+        if (!storage || !storageWorks(storage) || cookiesPersist(doc)) {
+            return false;
+        }
+        const native = findCookieDescriptor(doc);
+        if (!native?.get || !native.set) {
+            return false;
+        }
+        const nativeGet = native.get;
+        const nativeSet = native.set;
+        Object.defineProperty(doc, "cookie", {
+            configurable: true,
+            enumerable: true,
+            get() {
+                const jar = String(nativeGet.call(this) ?? "");
+                const session = readStored(storage, now());
+                if (session === null) {
+                    return jar;
+                }
+                const entry = `${RUM_SESSION_COOKIE}=${session}`;
+                return jar ? `${jar}; ${entry}` : entry;
+            },
+            set(value) {
+                const text = String(value);
+                if (!text.startsWith(`${RUM_SESSION_COOKIE}=`)) {
+                    nativeSet.call(this, text);
+                    return;
+                }
+                writeStored(storage, text, now());
+            },
+        });
+        installed.add(doc);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const installed = new WeakSet();
+/** The accessor `doc.cookie` resolves to: its own, or its prototype chain's. */
+function findCookieDescriptor(doc) {
+    for (let o = doc; o; o = Object.getPrototypeOf(o)) {
+        const d = Object.getOwnPropertyDescriptor(o, "cookie");
+        if (d) {
+            return d;
+        }
+    }
+    return undefined;
+}
+function storageWorks(storage) {
+    const key = `${RUM_SESSION_STORAGE_KEY}.probe`;
+    try {
+        storage.setItem(key, "1");
+        const ok = storage.getItem(key) === "1";
+        storage.removeItem(key);
+        return ok;
+    }
+    catch {
+        return false;
+    }
+}
+function readStored(storage, at) {
+    try {
+        const raw = storage.getItem(RUM_SESSION_STORAGE_KEY);
+        if (!raw) {
+            return null;
+        }
+        const stored = JSON.parse(raw);
+        if (typeof stored.v !== "string" || typeof stored.exp !== "number") {
+            storage.removeItem(RUM_SESSION_STORAGE_KEY);
+            return null;
+        }
+        if (stored.exp <= at) {
+            // Expired, as the browser would have expired the cookie.
+            storage.removeItem(RUM_SESSION_STORAGE_KEY);
+            return null;
+        }
+        return stored.v;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Store a `__rum_sid=<value>; …attributes` write. `max-age` (seconds) or
+ * `expires` set the expiry; `max-age=0` or a past expiry deletes. A write with
+ * neither is a session cookie, which here lasts the SDK's inactivity window:
+ * the SDK always sends max-age, so this is only a defined answer for a write
+ * it does not make.
+ */
+function writeStored(storage, text, at) {
+    const [pair = "", ...attributes] = text.split(";");
+    const value = pair.slice(RUM_SESSION_COOKIE.length + 1).trim();
+    let exp = null;
+    for (const attribute of attributes) {
+        const eq = attribute.indexOf("=");
+        const name = (eq < 0 ? attribute : attribute.slice(0, eq))
+            .trim()
+            .toLowerCase();
+        const raw = eq < 0 ? "" : attribute.slice(eq + 1).trim();
+        if (name === "max-age") {
+            const seconds = Number(raw);
+            if (Number.isFinite(seconds)) {
+                // max-age wins over expires, as in a browser.
+                exp = at + seconds * 1000;
+                break;
+            }
+        }
+        else if (name === "expires" && exp === null) {
+            const when = Date.parse(raw);
+            if (!Number.isNaN(when)) {
+                exp = when;
+            }
+        }
+    }
+    try {
+        if (value === "" || (exp !== null && exp <= at)) {
+            storage.removeItem(RUM_SESSION_STORAGE_KEY);
+            return;
+        }
+        const stored = {
+            v: value,
+            exp: exp ?? at + SESSION_COOKIE_FALLBACK_MS,
+        };
+        storage.setItem(RUM_SESSION_STORAGE_KEY, JSON.stringify(stored));
+    }
+    catch {
+        // Storage full or revoked: the SDK sees no cookie and starts a session,
+        // as it would have without the fallback.
+    }
+}
+/** The SDK's inactivity window (otel-web InactivityTimeoutSeconds). */
+const SESSION_COOKIE_FALLBACK_MS = 15 * 60 * 1000;
+//# sourceMappingURL=session-cookie-fallback.js.map

package/dist/session-cookie-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cookie-fallback.js","sourceRoot":"","sources":["../src/session-cookie-fallback.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// A stable RUM session on an origin that cannot keep cookies.\n//\n// ── Why ──────────────────────────────────────────────────────────────────\n//\n// The HyperDX SDK (its otel-web layer) keeps the session ONLY in a cookie,\n// `__rum_sid`: `{ id, startTime }`, written with `max-age=900` and renewed\n// while the user is active. Every 60 s it reads the cookie back, and when it\n// finds none it mints a new session id. There is no other store and no seam\n// to supply one: the session module is bundled inside the HyperDX browser package.\n//\n// Some origins accept a `document.cookie` write and silently keep nothing.\n// The one that matters is an Electron renderer served from a custom scheme\n// (`app://bundle/`): Chromium treats a non-http(s) scheme as non-cookieable\n// even when it is registered `standard` + `secure`, so the write is dropped\n// and `session.cookies.set` refuses with EXCLUDE_NONCOOKIEABLE_SCHEME.\n// Verified against Electron 41. On such an origin every open window starts a\n// new \"session\" every minute; each one re-uploads a full replay snapshot and\n// none of them is a session anyone can watch.\n//\n// ── What ─────────────────────────────────────────────────────────────────\n//\n// When, and only when, a probe cookie does not round-trip, the session cookie\n// is kept in localStorage instead. An own `cookie` accessor on `document`\n// answers reads and writes of `__rum_sid` from localStorage, honouring the\n// max-age the SDK writes, and passes every other cookie to the browser\n// untouched. The SDK's own rules then hold unchanged: the session expires 15\n// minutes after the last activity (max-age=900, renewed on activity) and never\n// outlives 4 hours (the startTime inside the value). localStorage is shared by\n// every window of the origin, as a cookie jar is, so the windows of one app\n// share one session the way the tabs of one browser do.\n//\n// An origin whose cookies work is left exactly as it was.\n\n/** The SDK's session cookie (otel-web COOKIE_NAME). */\nexport const RUM_SESSION_COOKIE = \"__rum_sid\";\n\n/** Where the session cookie is kept when cookies do not persist. */\nexport const RUM_SESSION_STORAGE_KEY = \"forge.rum.session\";\n\nconst PROBE_COOKIE = \"forge_cookie_probe\";\n\n/** The slice of Storage the fallback needs. */\nexport interface SessionStore {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n  removeItem(key: string): void;\n}\n\ninterface StoredCookie {\n  /** The cookie value exactly as the SDK wrote it (URI-encoded JSON). */\n  v: string;\n  /** Epoch ms at which the cookie expires. */\n  exp: number;\n}\n\n/**\n * Whether `document.cookie` keeps what is written to it. Writes a short-lived\n * probe cookie, reads it back and removes it.\n */\nexport function cookiesPersist(doc: Pick<Document, \"cookie\">): boolean {\n  try {\n    const token = Math.random().toString(36).slice(2);\n    doc.cookie = `${PROBE_COOKIE}=${token}; path=/; max-age=60; SameSite=Strict`;\n    const kept = doc.cookie\n      .split(\";\")\n      .some((c) => c.trim() === `${PROBE_COOKIE}=${token}`);\n    doc.cookie = `${PROBE_COOKIE}=; path=/; max-age=0; SameSite=Strict`;\n    return kept;\n  } catch {\n    // A sandboxed document throws on cookie access: nothing persists.\n    return false;\n  }\n}\n\n/**\n * Keep the SDK's session cookie in `storage` when `doc` cannot keep cookies.\n * Returns whether the fallback is now in place (it was installed by this call,\n * or already was). Idempotent; never throws.\n *\n * Call it before the SDK initialises: the SDK reads the session at init.\n */\nexport function installSessionCookieFallback(\n  doc: Document,\n  storage: SessionStore | null,\n  now: () => number = Date.now,\n): boolean {\n  try {\n    if (installed.has(doc)) {\n      return true;\n    }\n    if (!storage || !storageWorks(storage) || cookiesPersist(doc)) {\n      return false;\n    }\n    const native = findCookieDescriptor(doc);\n    if (!native?.get || !native.set) {\n      return false;\n    }\n    const nativeGet = native.get;\n    const nativeSet = native.set;\n    Object.defineProperty(doc, \"cookie\", {\n      configurable: true,\n      enumerable: true,\n      get(this: Document): string {\n        const jar = String(nativeGet.call(this) ?? \"\");\n        const session = readStored(storage, now());\n        if (session === null) {\n          return jar;\n        }\n        const entry = `${RUM_SESSION_COOKIE}=${session}`;\n        return jar ? `${jar}; ${entry}` : entry;\n      },\n      set(this: Document, value: string) {\n        const text = String(value);\n        if (!text.startsWith(`${RUM_SESSION_COOKIE}=`)) {\n          nativeSet.call(this, text);\n          return;\n        }\n        writeStored(storage, text, now());\n      },\n    });\n    installed.add(doc);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nconst installed = new WeakSet<object>();\n\n/** The accessor `doc.cookie` resolves to: its own, or its prototype chain's. */\nfunction findCookieDescriptor(doc: object): PropertyDescriptor | undefined {\n  for (\n    let o: object | null = doc;\n    o;\n    o = Object.getPrototypeOf(o) as object | null\n  ) {\n    const d = Object.getOwnPropertyDescriptor(o, \"cookie\");\n    if (d) {\n      return d;\n    }\n  }\n  return undefined;\n}\n\nfunction storageWorks(storage: SessionStore): boolean {\n  const key = `${RUM_SESSION_STORAGE_KEY}.probe`;\n  try {\n    storage.setItem(key, \"1\");\n    const ok = storage.getItem(key) === \"1\";\n    storage.removeItem(key);\n    return ok;\n  } catch {\n    return false;\n  }\n}\n\nfunction readStored(storage: SessionStore, at: number): string | null {\n  try {\n    const raw = storage.getItem(RUM_SESSION_STORAGE_KEY);\n    if (!raw) {\n      return null;\n    }\n    const stored = JSON.parse(raw) as Partial<StoredCookie>;\n    if (typeof stored.v !== \"string\" || typeof stored.exp !== \"number\") {\n      storage.removeItem(RUM_SESSION_STORAGE_KEY);\n      return null;\n    }\n    if (stored.exp <= at) {\n      // Expired, as the browser would have expired the cookie.\n      storage.removeItem(RUM_SESSION_STORAGE_KEY);\n      return null;\n    }\n    return stored.v;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Store a `__rum_sid=<value>; …attributes` write. `max-age` (seconds) or\n * `expires` set the expiry; `max-age=0` or a past expiry deletes. A write with\n * neither is a session cookie, which here lasts the SDK's inactivity window:\n * the SDK always sends max-age, so this is only a defined answer for a write\n * it does not make.\n */\nfunction writeStored(storage: SessionStore, text: string, at: number): void {\n  const [pair = \"\", ...attributes] = text.split(\";\");\n  const value = pair.slice(RUM_SESSION_COOKIE.length + 1).trim();\n  let exp: number | null = null;\n  for (const attribute of attributes) {\n    const eq = attribute.indexOf(\"=\");\n    const name = (eq < 0 ? attribute : attribute.slice(0, eq))\n      .trim()\n      .toLowerCase();\n    const raw = eq < 0 ? \"\" : attribute.slice(eq + 1).trim();\n    if (name === \"max-age\") {\n      const seconds = Number(raw);\n      if (Number.isFinite(seconds)) {\n        // max-age wins over expires, as in a browser.\n        exp = at + seconds * 1000;\n        break;\n      }\n    } else if (name === \"expires\" && exp === null) {\n      const when = Date.parse(raw);\n      if (!Number.isNaN(when)) {\n        exp = when;\n      }\n    }\n  }\n  try {\n    if (value === \"\" || (exp !== null && exp <= at)) {\n      storage.removeItem(RUM_SESSION_STORAGE_KEY);\n      return;\n    }\n    const stored: StoredCookie = {\n      v: value,\n      exp: exp ?? at + SESSION_COOKIE_FALLBACK_MS,\n    };\n    storage.setItem(RUM_SESSION_STORAGE_KEY, JSON.stringify(stored));\n  } catch {\n    // Storage full or revoked: the SDK sees no cookie and starts a session,\n    // as it would have without the fallback.\n  }\n}\n\n/** The SDK's inactivity window (otel-web InactivityTimeoutSeconds). */\nconst SESSION_COOKIE_FALLBACK_MS = 15 * 60 * 1000;\n"]}

package/dist/telemetry-gate.d.ts

@@ -8,5 +8,9 @@ export declare function registerTelemetryStartup(p: Promise<unknown>): void;
  * has already settled.
  */
 export declare function telemetryReady(maxMs?: number): Promise<void>;
+/** Called by initBrowserTelemetry with the SDK's session getter, or null. */
+export declare function registerRumSession(source: (() => string | undefined) | null): void;
+/** The current RUM session id, or undefined with telemetry off. Never throws. */
+export declare function rumSessionId(): string | undefined;
 /** Test seam. */
 export declare function resetTelemetryGate(): void;

package/dist/telemetry-gate.js

@@ -44,8 +44,33 @@ export function telemetryReady(maxMs = TELEMETRY_WAIT_MS) {
         p.then(done, done);
     });
 }
+// ── The RUM session the requests belong to ─────────────────────────────────
+//
+// initBrowserTelemetry registers the SDK's session id here once it runs, and
+// clears it when telemetry is disabled. injectTraceContext (trace.ts) sends it
+// as the W3C baggage member `session.id`, which forge servers copy onto their
+// server span (forge/pkg/observe, span_identity.go), so a backend trace links
+// back to the browser session that caused it.
+/** The shape of a RUM session id; forge servers drop anything else. */
+const RUM_SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+let sessionSource = null;
+/** Called by initBrowserTelemetry with the SDK's session getter, or null. */
+export function registerRumSession(source) {
+    sessionSource = source;
+}
+/** The current RUM session id, or undefined with telemetry off. Never throws. */
+export function rumSessionId() {
+    try {
+        const id = sessionSource?.();
+        return id && RUM_SESSION_ID_RE.test(id) ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Test seam. */
 export function resetTelemetryGate() {
     startup = null;
+    sessionSource = null;
 }
 //# sourceMappingURL=telemetry-gate.js.map

package/dist/telemetry-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-gate.js","sourceRoot":"","sources":["../src/telemetry-gate.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,qEAAqE;AACrE,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,uEAAuE;AACvE,gFAAgF;AAChF,0EAA0E;AAC1E,SAAS;AACT,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,2EAA2E;AAC3E,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,iCAAiC;AAEjC,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,IAAI,OAAO,GAA4B,IAAI,CAAC;AAE5C,2EAA2E;AAC3E,MAAM,UAAU,wBAAwB,CAAC,CAAmB;IAC1D,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,iBAAiB;IAEjC,MAAM,CAAC,GAAG,OAAO,CAAC;IAClB,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// The hand-off between browser telemetry startup and the first RPCs.\n//\n// The HyperDX SDK is a ~600 KB lazy chunk, so it patches `fetch` some hundreds\n// of milliseconds after the app is interactive — and a page fires its first\n// queries on mount, inside that window. A call made before the patch carries a\n// SYNTHESIZED traceparent (trace.ts) that names a span no browser ever\n// exported: the API's span has a parent id that matches nothing, and \"this page\n// load, end to end\" has no answer exactly for the requests the page makes\n// first.\n//\n// So initBrowserTelemetry registers its startup here, and the trace interceptor\n// waits for it — at most TELEMETRY_WAIT_MS, so a blocked chunk or an ad blocker\n// delays a request by that much and no more, then falls back to the synthesized\n// traceparent. With telemetry off nothing is registered and nothing waits.\n//\n// DOM-free and import-free on purpose: the transport entry point\n// (@reliantlabs/forge-web-runtime/interceptors) imports this and must stay\n// light enough for React Native.\n\n/** The longest an RPC waits for browser telemetry to finish starting. */\nexport const TELEMETRY_WAIT_MS = 2000;\n\nlet startup: Promise<unknown> | null = null;\n\n/** Called once by initBrowserTelemetry with the promise of its startup. */\nexport function registerTelemetryStartup(p: Promise<unknown>): void {\n  startup = p;\n}\n\n/**\n * Resolves when telemetry has finished starting (or failed to), or after\n * `maxMs`, whichever is first. Resolves immediately when none is starting or it\n * has already settled.\n */\nexport function telemetryReady(\n  maxMs: number = TELEMETRY_WAIT_MS,\n): Promise<void> {\n  const p = startup;\n  if (!p) {\n    return Promise.resolve();\n  }\n  return new Promise<void>((resolve) => {\n    const timer = setTimeout(resolve, maxMs);\n    const done = () => {\n      clearTimeout(timer);\n      resolve();\n    };\n    p.then(done, done);\n  });\n}\n\n/** Test seam. */\nexport function resetTelemetryGate(): void {\n  startup = null;\n}\n"]}
+{"version":3,"file":"telemetry-gate.js","sourceRoot":"","sources":["../src/telemetry-gate.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,qEAAqE;AACrE,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,uEAAuE;AACvE,gFAAgF;AAChF,0EAA0E;AAC1E,SAAS;AACT,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,2EAA2E;AAC3E,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,iCAAiC;AAEjC,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,IAAI,OAAO,GAA4B,IAAI,CAAC;AAE5C,2EAA2E;AAC3E,MAAM,UAAU,wBAAwB,CAAC,CAAmB;IAC1D,OAAO,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,iBAAiB;IAEjC,MAAM,CAAC,GAAG,OAAO,CAAC;IAClB,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,8CAA8C;AAE9C,uEAAuE;AACvE,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEnD,IAAI,aAAa,GAAsC,IAAI,CAAC;AAE5D,6EAA6E;AAC7E,MAAM,UAAU,kBAAkB,CAChC,MAAyC;IAEzC,aAAa,GAAG,MAAM,CAAC;AACzB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,aAAa,EAAE,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,kBAAkB;IAChC,OAAO,GAAG,IAAI,CAAC;IACf,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// The hand-off between browser telemetry startup and the first RPCs.\n//\n// The HyperDX SDK is a ~600 KB lazy chunk, so it patches `fetch` some hundreds\n// of milliseconds after the app is interactive — and a page fires its first\n// queries on mount, inside that window. A call made before the patch carries a\n// SYNTHESIZED traceparent (trace.ts) that names a span no browser ever\n// exported: the API's span has a parent id that matches nothing, and \"this page\n// load, end to end\" has no answer exactly for the requests the page makes\n// first.\n//\n// So initBrowserTelemetry registers its startup here, and the trace interceptor\n// waits for it — at most TELEMETRY_WAIT_MS, so a blocked chunk or an ad blocker\n// delays a request by that much and no more, then falls back to the synthesized\n// traceparent. With telemetry off nothing is registered and nothing waits.\n//\n// DOM-free and import-free on purpose: the transport entry point\n// (@reliantlabs/forge-web-runtime/interceptors) imports this and must stay\n// light enough for React Native.\n\n/** The longest an RPC waits for browser telemetry to finish starting. */\nexport const TELEMETRY_WAIT_MS = 2000;\n\nlet startup: Promise<unknown> | null = null;\n\n/** Called once by initBrowserTelemetry with the promise of its startup. */\nexport function registerTelemetryStartup(p: Promise<unknown>): void {\n  startup = p;\n}\n\n/**\n * Resolves when telemetry has finished starting (or failed to), or after\n * `maxMs`, whichever is first. Resolves immediately when none is starting or it\n * has already settled.\n */\nexport function telemetryReady(\n  maxMs: number = TELEMETRY_WAIT_MS,\n): Promise<void> {\n  const p = startup;\n  if (!p) {\n    return Promise.resolve();\n  }\n  return new Promise<void>((resolve) => {\n    const timer = setTimeout(resolve, maxMs);\n    const done = () => {\n      clearTimeout(timer);\n      resolve();\n    };\n    p.then(done, done);\n  });\n}\n\n// ── The RUM session the requests belong to ─────────────────────────────────\n//\n// initBrowserTelemetry registers the SDK's session id here once it runs, and\n// clears it when telemetry is disabled. injectTraceContext (trace.ts) sends it\n// as the W3C baggage member `session.id`, which forge servers copy onto their\n// server span (forge/pkg/observe, span_identity.go), so a backend trace links\n// back to the browser session that caused it.\n\n/** The shape of a RUM session id; forge servers drop anything else. */\nconst RUM_SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;\n\nlet sessionSource: (() => string | undefined) | null = null;\n\n/** Called by initBrowserTelemetry with the SDK's session getter, or null. */\nexport function registerRumSession(\n  source: (() => string | undefined) | null,\n): void {\n  sessionSource = source;\n}\n\n/** The current RUM session id, or undefined with telemetry off. Never throws. */\nexport function rumSessionId(): string | undefined {\n  try {\n    const id = sessionSource?.();\n    return id && RUM_SESSION_ID_RE.test(id) ? id : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Test seam. */\nexport function resetTelemetryGate(): void {\n  startup = null;\n  sessionSource = null;\n}\n"]}

package/dist/telemetry.d.ts

@@ -1,4 +1,8 @@
 import { type AttributionTouch } from "./attribution.js";
+import { type BenignErrorClassifier } from "./benign-errors.js";
+export { clientResourceAttributes, type ForgeDesktopInfo, viewportAttributes, } from "./client-context.js";
+export { cookiesPersist, installSessionCookieFallback, RUM_SESSION_COOKIE, RUM_SESSION_STORAGE_KEY, } from "./session-cookie-fallback.js";
+export { type BenignErrorClassifier, type BenignErrorKind, classifyBenignError, FILTERED_ERRORS_ACTION, } from "./benign-errors.js";
 /** Where the browser ships telemetry: this origin's `/_otel`. */
 export declare const DEFAULT_INGEST_PATH = "/_otel";
 /**
@@ -95,6 +99,18 @@ export interface BrowserTelemetryConfig {
      * site attributing acquisition to the campaign that first brought a visitor.
      */
     attributionTouch?: AttributionTouch;
+    /**
+     * Decides which errors are benign browser noise: kept out of the error
+     * pipeline and counted as `forge.errors_filtered` actions instead
+     * (benign-errors.ts). Default classifyBenignError: an AbortError, and the
+     * browser's generic "Failed to fetch" TypeError; never a ConnectError. It
+     * applies to what the SDK records from unhandled rejections, uncaught
+     * errors, console.error and reportException; the app's own handlers see
+     * every event unchanged. For an unhandled rejection or uncaught error it is
+     * handed `{ name, message }` as the SDK recorded them, not the original
+     * value. Pass `() => null` to record everything.
+     */
+    classifyBenignError?: BenignErrorClassifier;
 }
 /**
  * Turn on visitor attribution for a page that started telemetry with
@@ -115,9 +131,11 @@ export declare function enableAttribution(options?: {
 export declare function initBrowserTelemetry(config: BrowserTelemetryConfig): Promise<boolean>;
 /**
  * The options passed to HyperDX.init. Exported for tests and for apps that
- * want to see exactly what is configured — it is pure.
+ * want to see exactly what is configured — it is pure. `clientAttributes`
+ * are the page's own client resource attributes (client-context.ts:
+ * browser.* client hints, app.desktop.*); the config's keys win over them.
  */
-export declare function buildSdkOptions(config: BrowserTelemetryConfig, ingestUrl: string, pageOrigin: string): Record<string, unknown>;
+export declare function buildSdkOptions(config: BrowserTelemetryConfig, ingestUrl: string, pageOrigin: string, clientAttributes?: Record<string, string>): Record<string, unknown>;
 /** Elements a replay never records: their pixels stay in the browser. */
 export declare const REPLAY_BLOCK_SELECTOR = "img, picture, video, audio, iframe, object, embed";
 /** Where a replay sampling decision is held for the tab's session. */
@@ -137,6 +155,15 @@ interface DecisionStore {
 export declare function decideReplay(config: Pick<BrowserTelemetryConfig, "replay" | "replaySampleRate">, store: DecisionStore | null, random: () => number): boolean;
 /** `url` without its query string and fragment. */
 export declare function stripUrlQuery(url: string): string;
+/**
+ * The name a fetch/XHR span gets: `<METHOD> /<package>.<Service>/<Method>`,
+ * the server span's name with the method in front, when the URL is a
+ * Connect/gRPC procedure. Empty for any other URL, which keeps the SDK's
+ * `HTTP <METHOD>`: an arbitrary path can hold values (ids, tokens, emails) no
+ * pattern recognises reliably, and a span name must be neither sensitive nor
+ * unbounded. Empty too when `url` cannot be parsed. Exported for tests.
+ */
+export declare function spanRouteName(method: string, url: string): string;
 /**
  * resolveIngestUrl turns the configured endpoint into the absolute URL the SDK
  * is given, or null when telemetry is off. A path resolves against the page