@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.1

package/dist/_chunks-es/telemetryManager.js

@@ -0,0 +1,93 @@
+import "@sanity/client";
+import { createBatchedStore } from "@sanity/telemetry";
+import { CORE_SDK_VERSION, createLogger } from "./createGroqSearchFilter.js";
+import { SDKSessionEnded, SDKError, SDKHookMounted, SDKSessionStarted } from "./_internal.js";
+const FLUSH_INTERVAL_MS = 3e4, CONSENT_TAG = "telemetry-consent.sdk", BATCH_TAG = "telemetry.batch", log = createLogger("telemetry");
+function createTelemetryManager(options) {
+  const { sessionId, getClient, projectId, environment } = options, startedAt = Date.now(), emittedHooks = /* @__PURE__ */ new Set();
+  let cachedConsent = null;
+  const resolveConsent = async () => {
+    if (cachedConsent) return cachedConsent;
+    try {
+      cachedConsent = await getClient().request({
+        uri: "/intake/telemetry-status",
+        tag: CONSENT_TAG
+      });
+    } catch {
+      cachedConsent = { status: "undetermined" };
+    }
+    return cachedConsent;
+  }, enrichBatch = (batch) => batch.map((event) => {
+    const existing = "context" in event ? event.context : void 0;
+    return {
+      ...event,
+      context: {
+        ...existing,
+        version: CORE_SDK_VERSION,
+        environment,
+        origin: typeof window < "u" ? window.location.origin : "node"
+      }
+    };
+  }), store = createBatchedStore(
+    sessionId,
+    {
+      flushInterval: FLUSH_INTERVAL_MS,
+      resolveConsent,
+      sendEvents: async (batch) => {
+        const client = getClient();
+        return log.debug("sending event batch", { batchSize: batch.length, environment }), client.request({
+          uri: "/intake/batch",
+          method: "POST",
+          body: { projectId, batch: enrichBatch(batch) },
+          tag: BATCH_TAG
+        });
+      }
+    }
+  ), logger = store.logger;
+  return {
+    async checkConsent() {
+      const { status } = await resolveConsent();
+      return status === "granted";
+    },
+    logSessionStarted(data) {
+      log.debug("event: SDK Session Started", {
+        projectId: data.projectId,
+        perspective: data.perspective,
+        authMethod: data.authMethod,
+        version: CORE_SDK_VERSION,
+        environment
+      }), logger.log(SDKSessionStarted, {
+        version: CORE_SDK_VERSION,
+        ...data
+      });
+    },
+    logHookFirstUsed(hookName) {
+      emittedHooks.has(hookName) || (emittedHooks.add(hookName), log.debug("event: SDK Hook Mounted", { hookName }), logger.log(SDKHookMounted, { hookName }));
+    },
+    logError(errorType, hookName) {
+      log.debug("event: SDK Error", { errorType, hookName }), logger.log(SDKError, { errorType, hookName });
+    },
+    endSession() {
+      const durationSeconds = Math.round((Date.now() - startedAt) / 1e3);
+      log.debug("event: SDK Session Ended", {
+        durationSeconds,
+        hooksUsed: [...emittedHooks],
+        environment
+      }), logger.log(SDKSessionEnded, {
+        durationSeconds,
+        hooksUsed: [...emittedHooks]
+      }), store.flush().catch(() => {
+      }), store.end();
+    },
+    dispose() {
+      store.end();
+    },
+    get hooksUsed() {
+      return emittedHooks;
+    }
+  };
+}
+export {
+  createTelemetryManager
+};
+//# sourceMappingURL=telemetryManager.js.map

package/dist/_chunks-es/telemetryManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetryManager.js","sources":["../../src/telemetry/telemetryManager.ts"],"sourcesContent":["import {type SanityClient} from '@sanity/client'\nimport {\n  type ConsentStatus,\n  createBatchedStore,\n  type SessionId,\n  type TelemetryEvent,\n  type TelemetryLogger,\n  type TelemetryStore,\n} from '@sanity/telemetry'\n\nimport {createLogger} from '../utils/logger'\nimport {CORE_SDK_VERSION} from '../version'\nimport {type TelemetryEnvironment} from './environment'\nimport {SDKError, SDKHookMounted, SDKSessionEnded, SDKSessionStarted} from './events'\n\nconst FLUSH_INTERVAL_MS = 30_000\nconst CONSENT_TAG = 'telemetry-consent.sdk'\nconst BATCH_TAG = 'telemetry.batch'\n\nconst log = createLogger('telemetry')\n\n/**\n * Manages telemetry for a single SDK instance.\n *\n * Wraps `@sanity/telemetry`'s batched store with SDK-specific concerns:\n * consent caching, session lifecycle events, and hook usage tracking.\n * The `environment` is captured at construction time and recorded in\n * the event context so downstream pipelines can distinguish dev and\n * production sessions.\n *\n * @internal\n */\nexport interface TelemetryManager {\n  /**\n   * Eagerly resolve and cache the user's consent status.\n   * Returns true only when the user has explicitly opted in (`granted`).\n   * Call this before logging any events to avoid buffering events that\n   * will be dropped on the first flush.\n   */\n  checkConsent(): Promise<boolean>\n\n  /** Log a \"SDK Session Started\" event */\n  logSessionStarted(data: {projectId: string; perspective: string; authMethod: string}): void\n\n  /** Log a \"SDK Hook Mounted\" event (deduplicated per hook name) */\n  logHookFirstUsed(hookName: string): void\n\n  /** Log a \"SDK Error\" event */\n  logError(errorType: string, hookName: string): void\n\n  /** Log a \"SDK Session Ended\" event and tear down the store */\n  endSession(): void\n\n  /** Tear down the store without logging a session-end event */\n  dispose(): void\n\n  /** The set of hook names used during this session */\n  readonly hooksUsed: ReadonlySet<string>\n}\n\ninterface TelemetryManagerOptions {\n  sessionId: string\n  getClient: () => SanityClient\n  projectId: string\n  environment: TelemetryEnvironment\n}\n\n/**\n * Creates a telemetry manager for a single SDK instance session.\n *\n * The manager initializes a `createBatchedStore` from `@sanity/telemetry`,\n * caches the consent check for the lifetime of the session, and provides\n * typed methods for each SDK telemetry event.\n *\n * @internal\n */\nexport function createTelemetryManager(options: TelemetryManagerOptions): TelemetryManager {\n  const {sessionId, getClient, projectId, environment} = options\n  const startedAt = Date.now()\n  const emittedHooks = new Set<string>()\n\n  let cachedConsent: {status: ConsentStatus} | null = null\n\n  const resolveConsent = async (): Promise<{status: ConsentStatus}> => {\n    if (cachedConsent) return cachedConsent\n    try {\n      const client = getClient()\n      const result = await client.request<{status: ConsentStatus}>({\n        uri: '/intake/telemetry-status',\n        tag: CONSENT_TAG,\n      })\n      cachedConsent = result\n    } catch {\n      cachedConsent = {status: 'undetermined'}\n    }\n    return cachedConsent\n  }\n\n  const enrichBatch = (batch: TelemetryEvent[]) =>\n    batch.map((event) => {\n      // Trace events (`trace.start` / `trace.log` / `trace.error` /\n      // `trace.complete`) arrive with their own caller-provided `context`.\n      // Log / userProperties events don't. Narrow via `in` so `event`\n      // stays typed as `TelemetryEvent`, then merge so we don't drop the\n      // trace context. SDK-owned fields below win on conflict.\n      const existing =\n        'context' in event ? (event.context as Record<string, unknown> | undefined) : undefined\n      return {\n        ...event,\n        context: {\n          ...existing,\n          version: CORE_SDK_VERSION,\n          environment,\n          origin: typeof window !== 'undefined' ? window.location.origin : 'node',\n        },\n      }\n    })\n\n  const sendEvents = async (batch: TelemetryEvent[]): Promise<unknown> => {\n    const client = getClient()\n    log.debug('sending event batch', {batchSize: batch.length, environment})\n    return client.request({\n      uri: '/intake/batch',\n      method: 'POST',\n      body: {projectId, batch: enrichBatch(batch)},\n      tag: BATCH_TAG,\n    })\n  }\n\n  const store: TelemetryStore<Record<string, unknown>> = createBatchedStore(\n    sessionId as SessionId,\n    {\n      flushInterval: FLUSH_INTERVAL_MS,\n      resolveConsent,\n      sendEvents,\n    },\n  )\n\n  const logger: TelemetryLogger<Record<string, unknown>> = store.logger\n\n  return {\n    async checkConsent() {\n      const {status} = await resolveConsent()\n      return status === 'granted'\n    },\n\n    logSessionStarted(data) {\n      log.debug('event: SDK Session Started', {\n        projectId: data.projectId,\n        perspective: data.perspective,\n        authMethod: data.authMethod,\n        version: CORE_SDK_VERSION,\n        environment,\n      })\n      logger.log(SDKSessionStarted, {\n        version: CORE_SDK_VERSION,\n        ...data,\n      })\n    },\n\n    logHookFirstUsed(hookName: string) {\n      if (emittedHooks.has(hookName)) return\n      emittedHooks.add(hookName)\n      log.debug('event: SDK Hook Mounted', {hookName})\n      logger.log(SDKHookMounted, {hookName})\n    },\n\n    logError(errorType: string, hookName: string) {\n      log.debug('event: SDK Error', {errorType, hookName})\n      logger.log(SDKError, {errorType, hookName})\n    },\n\n    endSession() {\n      const durationSeconds = Math.round((Date.now() - startedAt) / 1000)\n      log.debug('event: SDK Session Ended', {\n        durationSeconds,\n        hooksUsed: [...emittedHooks],\n        environment,\n      })\n      logger.log(SDKSessionEnded, {\n        durationSeconds,\n        hooksUsed: [...emittedHooks],\n      })\n\n      store.flush().catch(() => {\n        // Best-effort flush on dispose; swallow errors\n      })\n      store.end()\n    },\n\n    dispose() {\n      store.end()\n    },\n\n    get hooksUsed(): ReadonlySet<string> {\n      return emittedHooks\n    },\n  }\n}\n"],"names":[],"mappings":";;;;AAeA,MAAM,oBAAoB,KACpB,cAAc,yBACd,YAAY,mBAEZ,MAAM,aAAa,WAAW;AAyD7B,SAAS,uBAAuB,SAAoD;AACzF,QAAM,EAAC,WAAW,WAAW,WAAW,YAAA,IAAe,SACjD,YAAY,KAAK,IAAA,GACjB,mCAAmB,IAAA;AAEzB,MAAI,gBAAgD;AAEpD,QAAM,iBAAiB,YAA8C;AACnE,QAAI,cAAe,QAAO;AAC1B,QAAI;AAMF,sBAJe,MADA,UAAA,EACa,QAAiC;AAAA,QAC3D,KAAK;AAAA,QACL,KAAK;AAAA,MAAA,CACN;AAAA,IAEH,QAAQ;AACN,sBAAgB,EAAC,QAAQ,eAAA;AAAA,IAC3B;AACA,WAAO;AAAA,EACT,GAEM,cAAc,CAAC,UACnB,MAAM,IAAI,CAAC,UAAU;AAMnB,UAAM,WACJ,aAAa,QAAS,MAAM,UAAkD;AAChF,WAAO;AAAA,MACL,GAAG;AAAA,MACH,SAAS;AAAA,QACP,GAAG;AAAA,QACH,SAAS;AAAA,QACT;AAAA,QACA,QAAQ,OAAO,SAAW,MAAc,OAAO,SAAS,SAAS;AAAA,MAAA;AAAA,IACnE;AAAA,EAEJ,CAAC,GAaG,QAAiD;AAAA,IACrD;AAAA,IACA;AAAA,MACE,eAAe;AAAA,MACf;AAAA,MACA,YAhBe,OAAO,UAA8C;AACtE,cAAM,SAAS,UAAA;AACf,eAAA,IAAI,MAAM,uBAAuB,EAAC,WAAW,MAAM,QAAQ,YAAA,CAAY,GAChE,OAAO,QAAQ;AAAA,UACpB,KAAK;AAAA,UACL,QAAQ;AAAA,UACR,MAAM,EAAC,WAAW,OAAO,YAAY,KAAK,EAAA;AAAA,UAC1C,KAAK;AAAA,QAAA,CACN;AAAA,MACH;AAAA,IAAA;AAAA,EAQE,GAGI,SAAmD,MAAM;AAE/D,SAAO;AAAA,IACL,MAAM,eAAe;AACnB,YAAM,EAAC,WAAU,MAAM,eAAA;AACvB,aAAO,WAAW;AAAA,IACpB;AAAA,IAEA,kBAAkB,MAAM;AACtB,UAAI,MAAM,8BAA8B;AAAA,QACtC,WAAW,KAAK;AAAA,QAChB,aAAa,KAAK;AAAA,QAClB,YAAY,KAAK;AAAA,QACjB,SAAS;AAAA,QACT;AAAA,MAAA,CACD,GACD,OAAO,IAAI,mBAAmB;AAAA,QAC5B,SAAS;AAAA,QACT,GAAG;AAAA,MAAA,CACJ;AAAA,IACH;AAAA,IAEA,iBAAiB,UAAkB;AAC7B,mBAAa,IAAI,QAAQ,MAC7B,aAAa,IAAI,QAAQ,GACzB,IAAI,MAAM,2BAA2B,EAAC,SAAA,CAAS,GAC/C,OAAO,IAAI,gBAAgB,EAAC,UAAS;AAAA,IACvC;AAAA,IAEA,SAAS,WAAmB,UAAkB;AAC5C,UAAI,MAAM,oBAAoB,EAAC,WAAW,SAAA,CAAS,GACnD,OAAO,IAAI,UAAU,EAAC,WAAW,UAAS;AAAA,IAC5C;AAAA,IAEA,aAAa;AACX,YAAM,kBAAkB,KAAK,OAAO,KAAK,IAAA,IAAQ,aAAa,GAAI;AAClE,UAAI,MAAM,4BAA4B;AAAA,QACpC;AAAA,QACA,WAAW,CAAC,GAAG,YAAY;AAAA,QAC3B;AAAA,MAAA,CACD,GACD,OAAO,IAAI,iBAAiB;AAAA,QAC1B;AAAA,QACA,WAAW,CAAC,GAAG,YAAY;AAAA,MAAA,CAC5B,GAED,MAAM,MAAA,EAAQ,MAAM,MAAM;AAAA,MAE1B,CAAC,GACD,MAAM,IAAA;AAAA,IACR;AAAA,IAEA,UAAU;AACR,YAAM,IAAA;AAAA,IACR;AAAA,IAEA,IAAI,YAAiC;AACnC,aAAO;AAAA,IACT;AAAA,EAAA;AAEJ;"}

package/dist/_exports/_internal.d.ts

@@ -0,0 +1,95 @@
+import { A as transformProjectionToPreview, B as getClientErrorApiBody, E as parseQueryKey, H as getClientErrorApiType, R as PREVIEW_PROJECTION, S as defineMutation, U as isProjectUserNotFoundClientError, V as getClientErrorApiDescription, _ as FetcherDefinition, b as MutationResult, ct as isStudioConfig, g as Fetcher, h as CacheWriter, m as CacheTag, n as getUsersKey, ot as SanityInstance, r as parseUsersKey, t as createGroqSearchFilter, v as FetcherSnapshot, w as getQueryKey, x as defineFetcher, y as MutationDefinition, z as ApiErrorBody } from "../_chunks-dts/createGroqSearchFilter.js";
+import { SanityClient } from "@sanity/client";
+/**
+ * Manages telemetry for a single SDK instance.
+ *
+ * Wraps `@sanity/telemetry`'s batched store with SDK-specific concerns:
+ * consent caching, session lifecycle events, and hook usage tracking.
+ * The `environment` is captured at construction time and recorded in
+ * the event context so downstream pipelines can distinguish dev and
+ * production sessions.
+ *
+ * @internal
+ */
+interface TelemetryManager {
+  /**
+   * Eagerly resolve and cache the user's consent status.
+   * Returns true only when the user has explicitly opted in (`granted`).
+   * Call this before logging any events to avoid buffering events that
+   * will be dropped on the first flush.
+   */
+  checkConsent(): Promise<boolean>;
+  /** Log a "SDK Session Started" event */
+  logSessionStarted(data: {
+    projectId: string;
+    perspective: string;
+    authMethod: string;
+  }): void;
+  /** Log a "SDK Hook Mounted" event (deduplicated per hook name) */
+  logHookFirstUsed(hookName: string): void;
+  /** Log a "SDK Error" event */
+  logError(errorType: string, hookName: string): void;
+  /** Log a "SDK Session Ended" event and tear down the store */
+  endSession(): void;
+  /** Tear down the store without logging a session-end event */
+  dispose(): void;
+  /** The set of hook names used during this session */
+  readonly hooksUsed: ReadonlySet<string>;
+}
+/**
+ * Initializes telemetry for a SDK instance if the runtime environment
+ * qualifies. The environment is resolved by `getTelemetryEnvironment()`:
+ *
+ * - `'development'` — local dev servers (`localhost` / `127.0.0.1`, or
+ *   Node with `NODE_ENV=development`). This is the original opt-in
+ *   surface.
+ * - `'production'` — apps deployed to Sanity-controlled domains
+ *   (e.g. `*.sanity.studio`, the dashboard). End users are
+ *   authenticated Sanity users with Populus consent records, so we
+ *   apply the same consent gate as the Studio's `telemetry-sink`.
+ *
+ * Apps on customer-controlled domains return `null` and skip telemetry
+ * entirely.
+ *
+ * `telemetryManager` and `clientStore` are dynamically imported so the
+ * telemetry code path stays out of production bundles for apps that
+ * don't qualify. Only the lightweight environment check runs at boot.
+ *
+ * The `projectId` must be passed explicitly because the resource
+ * configuration is typically set by the React layer after the
+ * instance has already been created.
+ *
+ * @internal
+ */
+declare function initTelemetry(instance: SanityInstance, projectId: string): void;
+/**
+ * Retrieves the telemetry manager for an instance, if one exists.
+ * Returns undefined when telemetry is disabled or not yet initialized.
+ *
+ * @internal
+ */
+declare function getTelemetryManager(instance: SanityInstance): TelemetryManager | undefined;
+/**
+ * Record a hook name for an instance. If the telemetry manager is
+ * already initialized the event is logged immediately. Otherwise
+ * the name is buffered and flushed when init completes.
+ *
+ * @internal
+ */
+declare function trackHookMounted(instance: SanityInstance, hookName: string): void;
+/**
+ * Creates a shallow copy containing only the provided properties.
+ *
+ * @internal
+ */
+declare function pickProperties<T extends object, K extends keyof T>(value: T, keys: readonly K[]): Pick<T, K>;
+/**
+ * Compares values deeply across the plain object, array, map, and set shapes used by the SDK.
+ * This helper is intended for acyclic SDK data structures and does not guard against circular
+ * references.
+ *
+ * @internal
+ */
+declare function isDeepEqual<T>(left: T, right: T): boolean;
+export { type ApiErrorBody, type CacheTag, type CacheWriter, type Fetcher, type FetcherDefinition, type FetcherSnapshot, type MutationDefinition, type MutationResult, PREVIEW_PROJECTION, createGroqSearchFilter, defineFetcher, defineMutation, getClientErrorApiBody, getClientErrorApiDescription, getClientErrorApiType, getQueryKey, getTelemetryManager, getUsersKey, initTelemetry, isDeepEqual, isProjectUserNotFoundClientError, isStudioConfig, parseQueryKey, parseUsersKey, pickProperties, trackHookMounted, transformProjectionToPreview };
+//# sourceMappingURL=_internal.d.ts.map

package/dist/_exports/_internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_internal.d.ts","names":[],"sources":["../../src/telemetry/telemetryManager.ts","../../src/telemetry/initTelemetry.ts","../../src/utils/object.ts"],"mappings":";;;;;;;;;;;;;UAgCiB;;;;;;;EAOf,gBAAgB;;EAGhB,kBAAkB;IAAO;IAAmB;IAAqB;;;EAGjE,iBAAiB;;EAGjB,SAAS,mBAAmB;;EAG5B;;EAGA;;WAGS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCXN,cAAc,UAAU,gBAAgB;;;;;;;iBAoIxC,oBAAoB,UAAU,iBAAiB;;;;;;;;iBAW/C,iBAAiB,UAAU,gBAAgB;;;;;;iBCvJ3C,eAAe,kBAAkB,gBAAgB,GAC/D,OAAO,GACP,eAAe,MACd,KAAK,GAAG;;;;;;;;iBA2DK,YAAY,GAAG,MAAM,GAAG,OAAO"}

package/dist/_exports/_internal.js

@@ -0,0 +1,24 @@
+import { PREVIEW_PROJECTION, createGroqSearchFilter, defineFetcher, defineMutation, getClientErrorApiBody, getClientErrorApiDescription, getClientErrorApiType, getQueryKey, getUsersKey, isDeepEqual, isProjectUserNotFoundClientError, isStudioConfig, parseQueryKey, parseUsersKey, pickProperties, transformProjectionToPreview } from "../_chunks-es/createGroqSearchFilter.js";
+import { getTelemetryManager, initTelemetry, trackHookMounted } from "../_chunks-es/_internal.js";
+export {
+  PREVIEW_PROJECTION,
+  createGroqSearchFilter,
+  defineFetcher,
+  defineMutation,
+  getClientErrorApiBody,
+  getClientErrorApiDescription,
+  getClientErrorApiType,
+  getQueryKey,
+  getTelemetryManager,
+  getUsersKey,
+  initTelemetry,
+  isDeepEqual,
+  isProjectUserNotFoundClientError,
+  isStudioConfig,
+  parseQueryKey,
+  parseUsersKey,
+  pickProperties,
+  trackHookMounted,
+  transformProjectionToPreview
+};
+//# sourceMappingURL=_internal.js.map

package/dist/_exports/_internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_internal.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}