@sanity/sdk 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -101,6 +101,16 @@ interface PerspectiveHandle {
  */
 interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string> extends ProjectHandle<TProjectId>, PerspectiveHandle {
   dataset?: TDataset;
+  /**
+   * @beta
+   * The name of the source to use for this operation.
+   */
+  sourceName?: string;
+  /**
+   * @beta
+   * Explicit source object to use for this operation.
+   */
+  source?: DocumentSource;
 }
 /**
  * Identifies a specific document type within a Sanity dataset and project.
@@ -144,40 +154,50 @@ interface SanityConfig extends DatasetHandle, PerspectiveHandle {
   studioMode?: {
     enabled: boolean;
   };
+  /**
+   * @beta
+   * A list of named sources to use for this instance.
+   */
+  sources?: Record<string, DocumentSource>;
 }
-declare const SOURCE_ID = "__sanity_internal_sourceId";
 /**
  * A document source can be used for querying.
+ * This will soon be the default way to identify where you are querying from.
  *
  * @beta
- * @see datasetSource Construct a document source for a given projectId and dataset.
- * @see mediaLibrarySource Construct a document source for a mediaLibraryId.
- * @see canvasSource Construct a document source for a canvasId.
- */
-type DocumentSource = {
-  [SOURCE_ID]: ['media-library', string] | ['canvas', string] | {
-    projectId: string;
-    dataset: string;
-  };
+ */
+type DocumentSource = DatasetSource | MediaLibrarySource | CanvasSource;
+/**
+ * @beta
+ */
+type DatasetSource = {
+  projectId: string;
+  dataset: string;
 };
 /**
- * Returns a document source for a projectId and dataset.
- *
  * @beta
  */
-declare function datasetSource(projectId: string, dataset: string): DocumentSource;
+type MediaLibrarySource = {
+  mediaLibraryId: string;
+};
+/**
+ * @beta
+ */
+type CanvasSource = {
+  canvasId: string;
+};
 /**
- * Returns a document source for a Media Library.
- *
  * @beta
  */
-declare function mediaLibrarySource(id: string): DocumentSource;
+declare function isDatasetSource(source: DocumentSource): source is DatasetSource;
 /**
- * Returns a document source for a Canvas.
- *
  * @beta
  */
-declare function canvasSource(id: string): DocumentSource;
+declare function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource;
+/**
+ * @beta
+ */
+declare function isCanvasSource(source: DocumentSource): source is CanvasSource;
 /**
  * Represents a Sanity.io resource instance with its own configuration and lifecycle
  * @remarks Instances form a hierarchy through parent/child relationships
@@ -675,6 +695,277 @@ declare function createProjectHandle<TProjectId extends string = string>(handle:
  * @public
  */
 declare function createDatasetHandle<TDataset extends string = string, TProjectId extends string = string>(handle: DatasetHandle<TDataset, TProjectId>): DatasetHandle<TDataset, TProjectId>;
+/**
+ * Logging infrastructure for the Sanity SDK
+ *
+ * Provides multi-level, namespace-based logging for both SDK users and maintainers.
+ * In production builds, all logging can be stripped via tree-shaking.
+ *
+ * @example SDK User
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * configureLogging({
+ *   level: 'info',
+ *   namespaces: ['auth', 'document']
+ * })
+ * ```
+ *
+ * @example SDK Maintainer
+ * ```ts
+ * configureLogging({
+ *   level: 'trace',
+ *   namespaces: ['*'],
+ *   internal: true
+ * })
+ * ```
+ */
+/**
+ * Log levels in order of verbosity (least to most)
+ * - error: Critical failures that prevent operation
+ * - warn: Issues that may cause problems but don't stop execution
+ * - info: High-level informational messages (SDK user level)
+ * - debug: Detailed debugging information (maintainer level)
+ * - trace: Very detailed tracing (maintainer level, includes RxJS streams)
+ * @public
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * Log namespaces organize logs by functional domain
+ *
+ * @remarks
+ * This is an extensible string type. As logging is added to more modules,
+ * additional namespaces will be recognized. Currently implemented namespaces
+ * will be documented as they are added.
+ * @internal
+ */
+type LogNamespace = string;
+/**
+ * Configuration for the logging system
+ * @public
+ */
+interface LoggerConfig {
+  /**
+   * Minimum log level to output
+   * @defaultValue 'warn'
+   */
+  level?: LogLevel;
+  /**
+   * Namespaces to enable. Use ['*'] for all namespaces
+   * @defaultValue []
+   * @remarks
+   * Available namespaces depend on which modules have logging integrated.
+   * Check the SDK documentation for the current list of instrumented modules.
+   * @example ['auth', 'document']
+   */
+  namespaces?: string[];
+  /**
+   * Enable internal/maintainer-level logging
+   * Shows RxJS streams, store internals, etc.
+   * @defaultValue false
+   */
+  internal?: boolean;
+  /**
+   * Custom log handler (for testing or custom output)
+   * @defaultValue console methods
+   */
+  handler?: LogHandler;
+  /**
+   * Enable timestamps in log output
+   * @defaultValue true
+   */
+  timestamps?: boolean;
+  /**
+   * Enable in production builds
+   * @defaultValue false
+   */
+  enableInProduction?: boolean;
+}
+/**
+ * Custom log handler interface
+ *
+ * @internal
+ */
+interface LogHandler {
+  error: (message: string, context?: LogContext) => void;
+  warn: (message: string, context?: LogContext) => void;
+  info: (message: string, context?: LogContext) => void;
+  debug: (message: string, context?: LogContext) => void;
+  trace: (message: string, context?: LogContext) => void;
+}
+/**
+ * Context object attached to log messages
+ *
+ * This interface allows you to attach arbitrary contextual data to log messages.
+ * The index signature `[key: string]: unknown` enables you to add any custom
+ * properties relevant to your log entry (e.g., `userId`, `documentId`, `action`, etc.).
+ *
+ * **Sensitive data sanitization:**
+ * Top-level keys containing sensitive names (`token`, `password`, `secret`, `apiKey`,
+ * `authorization`) are automatically redacted to `[REDACTED]` in log output.
+ *
+ * @example
+ * ```ts
+ * logger.info('User logged in', {
+ *   userId: '123',          // Custom context
+ *   action: 'login',        // Custom context
+ *   token: 'secret'         // Will be redacted to [REDACTED]
+ * })
+ * ```
+ *
+ * @internal
+ */
+interface LogContext {
+  /**
+   * Custom context properties that provide additional information about the log entry.
+   * Any key-value pairs can be added here (e.g., userId, documentId, requestId, etc.).
+   * Keys with sensitive names (token, password, secret, apiKey, authorization) are
+   * automatically sanitized.
+   */
+  [key: string]: unknown;
+  /** Error object if logging an error */
+  error?: Error | unknown;
+  /** Duration in milliseconds for timed operations */
+  duration?: number;
+  /** Stack trace for debugging */
+  stack?: string;
+  /** Instance context (automatically added when available) */
+  instanceContext?: InstanceContext;
+}
+/**
+ * Instance context information automatically added to logs
+ * @internal
+ */
+interface InstanceContext {
+  /** Unique instance ID */
+  instanceId?: string;
+  /** Project ID */
+  projectId?: string;
+  /** Dataset name */
+  dataset?: string;
+}
+/**
+ * Logger instance for a specific namespace
+ * @internal
+ */
+interface Logger {
+  readonly namespace: string;
+  error: (message: string, context?: LogContext) => void;
+  warn: (message: string, context?: LogContext) => void;
+  info: (message: string, context?: LogContext) => void;
+  debug: (message: string, context?: LogContext) => void;
+  trace: (message: string, context?: LogContext) => void;
+  /** Check if a log level is enabled (for performance-sensitive code) */
+  isLevelEnabled: (level: LogLevel) => boolean;
+  /** Create a child logger with extended context */
+  child: (context: LogContext) => Logger;
+  /** Get the instance context if available */
+  getInstanceContext: () => InstanceContext | undefined;
+}
+/**
+ * Configure logging for the Sanity SDK
+ *
+ * This function allows you to control what logs are output by the SDK,
+ * making it easier to debug issues in development or production.
+ *
+ * @remarks
+ * **Zero-Config via Environment Variable (Recommended):**
+ *
+ * The SDK automatically reads the `DEBUG` environment variable, making it
+ * easy to enable logging without code changes:
+ *
+ * ```bash
+ * # Enable all SDK logging at debug level
+ * DEBUG=sanity:* npm start
+ *
+ * # Enable specific namespaces
+ * DEBUG=sanity:auth,sanity:document npm start
+ *
+ * # Enable trace level for all namespaces
+ * DEBUG=sanity:trace:* npm start
+ *
+ * # Enable internal/maintainer logs
+ * DEBUG=sanity:*:internal npm start
+ * ```
+ *
+ * This matches the pattern used by Sanity CLI and Studio, making it familiar
+ * and easy for support teams to help troubleshoot issues.
+ *
+ * **Programmatic Configuration (Advanced):**
+ *
+ * For more control (custom handlers, dynamic configuration), call this function
+ * explicitly. Programmatic configuration overrides environment variables.
+ *
+ * **For Application Developers:**
+ * Use `info`, `warn`, or `error` levels to see high-level SDK activity
+ * without being overwhelmed by internal details.
+ *
+ * **For SDK Maintainers:**
+ * Use `debug` or `trace` levels with `internal: true` to see detailed
+ * information about store operations, RxJS streams, and state transitions.
+ *
+ * **Instance Context:**
+ * Logs automatically include instance information (projectId, dataset, instanceId)
+ * when available, making it easier to debug multi-instance scenarios:
+ * ```
+ * [INFO] [auth] [project:abc] [dataset:production] User logged in
+ * ```
+ *
+ * **Available Namespaces:**
+ * - `sdk` - SDK initialization, configuration, and lifecycle
+ * - `auth` - Authentication and authorization (when instrumented in the future)
+ * - And more as logging is added to modules
+ *
+ * @example Zero-config via environment variable (recommended for debugging)
+ * ```bash
+ * # Just set DEBUG and run your app - no code changes needed!
+ * DEBUG=sanity:* npm start
+ * ```
+ *
+ * @example Programmatic configuration (application developer)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * // Log warnings and errors for auth and document operations
+ * configureLogging({
+ *   level: 'warn',
+ *   namespaces: ['auth', 'document']
+ * })
+ * ```
+ *
+ * @example Programmatic configuration (SDK maintainer)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * // Enable all logs including internal traces
+ * configureLogging({
+ *   level: 'trace',
+ *   namespaces: ['*'],
+ *   internal: true
+ * })
+ * ```
+ *
+ * @example Custom handler (for testing)
+ * ```ts
+ * import {configureLogging} from '@sanity/sdk'
+ *
+ * const logs: string[] = []
+ * configureLogging({
+ *   level: 'info',
+ *   namespaces: ['*'],
+ *   handler: {
+ *     error: (msg) => logs.push(msg),
+ *     warn: (msg) => logs.push(msg),
+ *     info: (msg) => logs.push(msg),
+ *     debug: (msg) => logs.push(msg),
+ *     trace: (msg) => logs.push(msg),
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
+declare function configureLogging(config: LoggerConfig): void;
 /** @public */
 declare const getDatasetsState: BoundStoreAction<FetcherStoreState<[options?: ProjectHandle<string> | undefined], _sanity_client12.DatasetsResponse>, [options?: ProjectHandle<string> | undefined], StateSource<_sanity_client12.DatasetsResponse | undefined>>;
 /** @public */
@@ -1938,4 +2229,4 @@ declare const CORE_SDK_VERSION: {};
  * @public
  */
 type SanityProject = SanityProject$1;
-export { type ActionErrorEvent, type ActionsResult, type AgentGenerateOptions, type AgentGenerateResult, type AgentPatchOptions, type AgentPatchResult, type AgentPromptOptions, type AgentPromptResult, type AgentTransformOptions, type AgentTransformResult, type AgentTranslateOptions, type AgentTranslateResult, type ApiErrorBody, type ApplyDocumentActionsOptions, type AuthConfig, type AuthProvider, type AuthState, AuthStateType, type AuthStoreState, CORE_SDK_VERSION, type ClientOptions, type ClientStoreState as ClientState, type ComlinkControllerState, type ComlinkNodeState, type CreateDocumentAction, type CurrentUser, type DatasetHandle, type DeleteDocumentAction, type DiscardDocumentAction, type DisconnectEvent, type DocumentAction, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentDiscardedEvent, type DocumentEditedEvent, type DocumentEvent, type DocumentHandle, type DocumentOptions, type DocumentPermissionsResult, type DocumentPublishedEvent, type DocumentSource, type DocumentTypeHandle, type DocumentUnpublishedEvent, type EditDocumentAction, type ErrorAuthState, type FavoriteStatusResponse, type FetcherStore, type FetcherStoreState, type FrameMessage, type GetPreviewStateOptions, type GetUserOptions, type GetUsersOptions, type Intent, type IntentFilter, type JsonMatch, type LoggedInAuthState, type LoggedOutAuthState, type LoggingInAuthState, type Membership, type NewTokenResponseMessage, type NodeState, type OrgVerificationResult, type PermissionDeniedReason, type PerspectiveHandle, type PresenceLocation, type PreviewStoreState, type PreviewValue, type ProjectHandle, type ProjectionValuePending, type PublishDocumentAction, type QueryOptions, type ReleaseDocument, type ReleasePerspective, type RequestNewTokenMessage, type ResolvePreviewOptions, type ResolveUserOptions, type ResolveUsersOptions, type Role, type RollCallEvent, type SanityConfig, type SanityDocument, type SanityInstance, SanityProject, type SanityUser, type SanityUserResponse, type Selector, type StateEvent, type StateSource, type TransactionAcceptedEvent, type TransactionRevertedEvent, type TransportEvent, type UnpublishDocumentAction, type UserPresence, type UserProfile, type UsersGroupState, type UsersStoreState, type ValidProjection, type ValuePending, type WindowMessage, agentGenerate, agentPatch, agentPrompt, agentTransform, agentTranslate, applyDocumentActions, canvasSource, createDatasetHandle, createDocument, createDocumentHandle, createDocumentTypeHandle, createGroqSearchFilter, createProjectHandle, createSanityInstance, datasetSource, defineIntent, deleteDocument, destroyController, discardDocument, editDocument, getActiveReleasesState, getAuthState, getClient, getClientErrorApiBody, getClientErrorApiDescription, getClientErrorApiType, getClientState, getCorsErrorProjectId, getCurrentUserState, getDashboardOrganizationId, getDatasetsState, getDocumentState, getDocumentSyncStatus, getFavoritesState, getIndexForKey, getIsInDashboardState, getLoginUrlState, getNodeState, getOrCreateChannel, getOrCreateController, getOrCreateNode, getPathDepth, getPermissionsState, getPerspectiveState, getPresence, getPreviewState, getProjectState, getProjectionState, getProjectsState, getQueryKey, getQueryState, getTokenState, getUserState, getUsersKey, getUsersState, handleAuthCallback, isProjectUserNotFoundClientError, joinPaths, jsonMatch, loadMoreUsers, logout, mediaLibrarySource, observeOrganizationVerificationState, parseQueryKey, parseUsersKey, publishDocument, releaseChannel, releaseNode, resolveDatasets, resolveDocument, resolveFavoritesState, resolvePermissions, resolvePreview, resolveProject, resolveProjection, resolveProjects, resolveQuery, resolveUser, resolveUsers, setAuthToken, slicePath, stringifyPath, subscribeDocumentEvents, unpublishDocument };
+export { type ActionErrorEvent, type ActionsResult, type AgentGenerateOptions, type AgentGenerateResult, type AgentPatchOptions, type AgentPatchResult, type AgentPromptOptions, type AgentPromptResult, type AgentTransformOptions, type AgentTransformResult, type AgentTranslateOptions, type AgentTranslateResult, type ApiErrorBody, type ApplyDocumentActionsOptions, type AuthConfig, type AuthProvider, type AuthState, AuthStateType, type AuthStoreState, CORE_SDK_VERSION, type CanvasSource, type ClientOptions, type ClientStoreState as ClientState, type ComlinkControllerState, type ComlinkNodeState, type CreateDocumentAction, type CurrentUser, type DatasetHandle, type DatasetSource, type DeleteDocumentAction, type DiscardDocumentAction, type DisconnectEvent, type DocumentAction, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentDiscardedEvent, type DocumentEditedEvent, type DocumentEvent, type DocumentHandle, type DocumentOptions, type DocumentPermissionsResult, type DocumentPublishedEvent, type DocumentSource, type DocumentTypeHandle, type DocumentUnpublishedEvent, type EditDocumentAction, type ErrorAuthState, type FavoriteStatusResponse, type FetcherStore, type FetcherStoreState, type FrameMessage, type GetPreviewStateOptions, type GetUserOptions, type GetUsersOptions, type InstanceContext, type Intent, type IntentFilter, type JsonMatch, type LogContext, type LogLevel, type LogNamespace, type LoggedInAuthState, type LoggedOutAuthState, type Logger, type LoggerConfig, type LoggingInAuthState, type MediaLibrarySource, type Membership, type NewTokenResponseMessage, type NodeState, type OrgVerificationResult, type PermissionDeniedReason, type PerspectiveHandle, type PresenceLocation, type PreviewStoreState, type PreviewValue, type ProjectHandle, type ProjectionValuePending, type PublishDocumentAction, type QueryOptions, type ReleaseDocument, type ReleasePerspective, type RequestNewTokenMessage, type ResolvePreviewOptions, type ResolveUserOptions, type ResolveUsersOptions, type Role, type RollCallEvent, type SanityConfig, type SanityDocument, type SanityInstance, SanityProject, type SanityUser, type SanityUserResponse, type Selector, type StateEvent, type StateSource, type TransactionAcceptedEvent, type TransactionRevertedEvent, type TransportEvent, type UnpublishDocumentAction, type UserPresence, type UserProfile, type UsersGroupState, type UsersStoreState, type ValidProjection, type ValuePending, type WindowMessage, agentGenerate, agentPatch, agentPrompt, agentTransform, agentTranslate, applyDocumentActions, configureLogging, createDatasetHandle, createDocument, createDocumentHandle, createDocumentTypeHandle, createGroqSearchFilter, createProjectHandle, createSanityInstance, defineIntent, deleteDocument, destroyController, discardDocument, editDocument, getActiveReleasesState, getAuthState, getClient, getClientErrorApiBody, getClientErrorApiDescription, getClientErrorApiType, getClientState, getCorsErrorProjectId, getCurrentUserState, getDashboardOrganizationId, getDatasetsState, getDocumentState, getDocumentSyncStatus, getFavoritesState, getIndexForKey, getIsInDashboardState, getLoginUrlState, getNodeState, getOrCreateChannel, getOrCreateController, getOrCreateNode, getPathDepth, getPermissionsState, getPerspectiveState, getPresence, getPreviewState, getProjectState, getProjectionState, getProjectsState, getQueryKey, getQueryState, getTokenState, getUserState, getUsersKey, getUsersState, handleAuthCallback, isCanvasSource, isDatasetSource, isMediaLibrarySource, isProjectUserNotFoundClientError, joinPaths, jsonMatch, loadMoreUsers, logout, observeOrganizationVerificationState, parseQueryKey, parseUsersKey, publishDocument, releaseChannel, releaseNode, resolveDatasets, resolveDocument, resolveFavoritesState, resolvePermissions, resolvePreview, resolveProject, resolveProjection, resolveProjects, resolveQuery, resolveUser, resolveUsers, setAuthToken, slicePath, stringifyPath, subscribeDocumentEvents, unpublishDocument };