feat(browser): add LoaderSentry type

packages/browser/src/exports.ts

@@ -23,6 +23,7 @@ export type {
 } from '@sentry/core';
 
 export type { BrowserOptions } from './client';
+export type { LoaderSentry } from './loader-types';
 
 export {
   addEventProcessor,

packages/browser/src/loader-types.ts

@@ -0,0 +1,46 @@
+import type { addBreadcrumb, captureEvent, captureException, captureMessage, Scope } from '@sentry/core';
+import type { showReportDialog } from './report-dialog';
+import type { forceLoad, init, onLoad } from './sdk';
+
+/** Queued calls are replayed once the SDK loads, so they can't return the SDK method's result. */
+type Queued<Fn> = Fn extends (...args: infer Args) => unknown ? (...args: Args) => void : never;
+
+/**
+ * The subset of the Sentry browser API that is safe to call on the CDN loader's
+ * `window.Sentry` stub before the full SDK has loaded.
+ *
+ * Any other SDK API needs to be wrapped in `Sentry.onLoad()`. Inside the callback, the full SDK is
+ * loaded, so `window.Sentry` can be cast to the full SDK type.
+ *
+ * @example
+ * ```ts
+ * import type * as SentryBrowser from '@sentry/browser';
+ * import type { LoaderSentry } from '@sentry/browser';
+ *
+ * declare global {
+ *   interface Window {
+ *     Sentry: LoaderSentry;
+ *   }
+ * }
+ *
+ * window.Sentry.captureException(new Error('Something went wrong'));
+ *
+ * window.Sentry.onLoad(() => {
+ *   const Sentry = window.Sentry as typeof SentryBrowser;
+ *   Sentry.init({ release: 'my-app@1.0.0' });
+ *   Sentry.addIntegration(Sentry.replayIntegration());
+ * });
+ * ```
+ */
+export interface LoaderSentry {
+  init: Queued<typeof init>;
+  addBreadcrumb: Queued<typeof addBreadcrumb>;
+  captureMessage: Queued<typeof captureMessage>;
+  captureException: Queued<typeof captureException>;
+  captureEvent: Queued<typeof captureEvent>;
+  showReportDialog: Queued<typeof showReportDialog>;
+  // Only the callback overload: there's no way to get hold of a `Scope` before the SDK has loaded.
+  withScope: (callback: (scope: Scope) => void) => void;
+  onLoad: typeof onLoad;
+  forceLoad: typeof forceLoad;
+}

packages/browser/test/loader-types.test-d.ts

@@ -0,0 +1,48 @@
+import { expectTypeOf, it, describe } from 'vitest';
+import type { Scope } from '@sentry/core';
+import type { LoaderSentry } from '../src/loader-types';
+
+describe('LoaderSentry', () => {
+  it('exposes the APIs supported by the loader', () => {
+    expectTypeOf<LoaderSentry>().toHaveProperty('init');
+    expectTypeOf<LoaderSentry>().toHaveProperty('addBreadcrumb');
+    expectTypeOf<LoaderSentry>().toHaveProperty('captureMessage');
+    expectTypeOf<LoaderSentry>().toHaveProperty('captureException');
+    expectTypeOf<LoaderSentry>().toHaveProperty('captureEvent');
+    expectTypeOf<LoaderSentry>().toHaveProperty('withScope');
+    expectTypeOf<LoaderSentry>().toHaveProperty('showReportDialog');
+    expectTypeOf<LoaderSentry>().toHaveProperty('onLoad');
+    expectTypeOf<LoaderSentry>().toHaveProperty('forceLoad');
+  });
+
+  it('does not expose unsupported APIs', () => {
+    expectTypeOf<LoaderSentry>().not.toHaveProperty('addIntegration');
+    expectTypeOf<LoaderSentry>().not.toHaveProperty('captureFeedback');
+    expectTypeOf<LoaderSentry>().not.toHaveProperty('flush');
+    expectTypeOf<LoaderSentry>().not.toHaveProperty('close');
+  });
+
+  it('uses void return types for queued methods', () => {
+    expectTypeOf<LoaderSentry['init']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['addBreadcrumb']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['captureMessage']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['captureException']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['captureEvent']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['withScope']>().returns.toBeVoid();
+    expectTypeOf<LoaderSentry['showReportDialog']>().returns.toBeVoid();
+  });
+
+  it('keeps the parameters of the SDK methods', () => {
+    expectTypeOf<LoaderSentry['init']>().toBeCallableWith({ dsn: 'https://public@dsn.ingest.sentry.io/1337' });
+    expectTypeOf<LoaderSentry['captureException']>().toBeCallableWith(new Error('test'), { tags: { foo: 'bar' } });
+    expectTypeOf<LoaderSentry['captureMessage']>().toBeCallableWith('test', 'warning');
+    expectTypeOf<LoaderSentry['onLoad']>().toBeCallableWith(() => {});
+  });
+
+  it('only exposes the callback overload of withScope', () => {
+    expectTypeOf<LoaderSentry['withScope']>().toBeCallableWith(scope => {
+      scope.setTag('foo', 'bar');
+    });
+    expectTypeOf<LoaderSentry['withScope']>().parameters.toEqualTypeOf<[callback: (scope: Scope) => void]>();
+  });
+});

packages/browser/vite.config.ts

@@ -9,5 +9,10 @@ export default defineConfig({
     fakeTimers: {
       toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'setImmediate', 'clearImmediate', 'Date'],
     },
+    typecheck: {
+      enabled: true,
+      tsconfig: './tsconfig.test.json',
+      ignoreSourceErrors: true,
+    },
   },
 });