@sentry/api 1.27.0 → 1.29.0

package/README.md

@@ -176,6 +176,29 @@ const sentry = createSentryClient(
 const { data, error } = await sentry.listOrganizations();
 ```
 
+### Routing requests by organization
+
+Set `resolveBaseUrl` to pick each request's base URL from its path before the
+URL is built, such as the region that serves the organization. It receives the
+configured `baseUrl` (`''` when unset), the path and query that follow it, and
+the organization and project the path targets (`parseApiPathScope` from
+`@sentry/api/client`; absent for unscoped paths). Its result replaces `baseUrl`
+for that request only; trailing slashes are removed.
+
+```ts
+const sentry = createSentryClient({
+  baseUrl: "https://sentry.io",
+  resolveBaseUrl: async ({ baseUrl, scope }) =>
+    scope ? await regionUrlFor(scope.organization) : baseUrl,
+});
+// Sent to the organization's region, such as https://us.sentry.io.
+await sentry.listOrganizationIssues({ path: { organization_id_or_slug: "acme" } });
+```
+
+It runs once per request, including `prepareRequest`, after `requestValidator`
+and before request interceptors. A per-call `resolveBaseUrl` replaces the
+configured one. A throw rejects the request unchanged, before `fetch` is called.
+
 ### Preparing a raw request
 
 Use `sentry.client.prepareRequest` when a consumer needs to inspect a request

package/dist/api-client/api-path-scope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reading the organization and project an API path targets. No imports, so
+ * the generated client can use it without pulling in `@sentry/api/client`.
+ */
+/** The organization, and project when present, an API path targets. */
+export type ApiPathScope = {
+    organization: string;
+    project?: string;
+};
+/**
+ * The organization, and project when present, a Sentry API request targets,
+ * read from its path: `/organizations/{org}/`, `/projects/{org}/{project}/`,
+ * `/teams/{org}/`, and `/organizations/{org}/projects/{project}/`.
+ *
+ * Accepts a full URL, whose path must contain `/api/0/` (a self-hosted
+ * install may serve it under a prefix), or a path relative to `/api/0/` with
+ * or without that prefix. Undefined for unscoped paths, list endpoints such
+ * as `/organizations/`, and schema placeholders.
+ *
+ * Hosts with several credentials or regions use it to pick the one that
+ * serves the organization: `createApiTransport` passes it to
+ * `CredentialProvider.current`, and the generated client to
+ * `Config.resolveBaseUrl`.
+ */
+export declare function parseApiPathScope(urlOrPath: string): ApiPathScope | undefined;

package/dist/api-client/api-path.d.ts

@@ -1,3 +1,4 @@
+export { type ApiPathScope, parseApiPathScope } from "./api-path-scope.js";
 /**
  * Encode one Sentry API path identifier without letting it become a URL path.
  *
@@ -30,25 +31,5 @@ export declare function buildSentryApiUrl(baseUrl: string, endpoint: string): st
  * ```
  */
 export declare function apiPath(strings: TemplateStringsArray, ...values: (string | number)[]): string;
-/** The organization, and project when present, an API path targets. */
-export type ApiPathScope = {
-    organization: string;
-    project?: string;
-};
-/**
- * The organization, and project when present, a Sentry API request targets,
- * read from its path: `/organizations/{org}/`, `/projects/{org}/{project}/`,
- * `/teams/{org}/`, and `/organizations/{org}/projects/{project}/`.
- *
- * Accepts a full URL, whose path must contain `/api/0/` (a self-hosted
- * install may serve it under a prefix), or a path relative to `/api/0/` with
- * or without that prefix. Undefined for unscoped paths, list endpoints such
- * as `/organizations/`, and schema placeholders.
- *
- * Hosts with several credentials use it to pick the one that can reach the
- * organization; {@link createApiTransport} passes it to
- * `CredentialProvider.current`.
- */
-export declare function parseApiPathScope(urlOrPath: string): ApiPathScope | undefined;
 /** `path` with `query` appended, or `path` alone when `query` is empty. */
 export declare function withQuery(path: string, query: URLSearchParams): string;

package/dist/api-client/index.js

@@ -212,34 +212,7 @@ function isApiAuthenticationErrorDeep(error) {
   return false;
 }
 
-// src/api-client/api-path.ts
-function encodeApiPathSegment(value) {
-  const text = String(value);
-  return text === "." || text === ".." ? null : encodeURIComponent(text);
-}
-function buildSentryApiUrl(baseUrl, endpoint) {
-  const path = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
-  let end = baseUrl.length;
-  while (end > 0 && baseUrl.charAt(end - 1) === "/") {
-    end -= 1;
-  }
-  return `${baseUrl.slice(0, end)}/api/0/${path}`;
-}
-function apiPath(strings, ...values) {
-  return strings.reduce((acc, literal, index) => {
-    if (index >= values.length) {
-      return acc + literal;
-    }
-    const value = String(values[index]);
-    const encoded = encodeApiPathSegment(value);
-    if (encoded === null) {
-      throw new UserInputError(
-        `Invalid identifier "${value}": relative path segments are not allowed.`
-      );
-    }
-    return acc + literal + encoded;
-  }, "");
-}
+// src/api-client/api-path-scope.ts
 var API_PATH_IDENTIFIER = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 function isApiPathIdentifier(segment) {
   return segment !== void 0 && API_PATH_IDENTIFIER.test(segment);
@@ -275,6 +248,35 @@ function parseApiPathScope(urlOrPath) {
   }
   return;
 }
+
+// src/api-client/api-path.ts
+function encodeApiPathSegment(value) {
+  const text = String(value);
+  return text === "." || text === ".." ? null : encodeURIComponent(text);
+}
+function buildSentryApiUrl(baseUrl, endpoint) {
+  const path = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
+  let end = baseUrl.length;
+  while (end > 0 && baseUrl.charAt(end - 1) === "/") {
+    end -= 1;
+  }
+  return `${baseUrl.slice(0, end)}/api/0/${path}`;
+}
+function apiPath(strings, ...values) {
+  return strings.reduce((acc, literal, index) => {
+    if (index >= values.length) {
+      return acc + literal;
+    }
+    const value = String(values[index]);
+    const encoded = encodeApiPathSegment(value);
+    if (encoded === null) {
+      throw new UserInputError(
+        `Invalid identifier "${value}": relative path segments are not allowed.`
+      );
+    }
+    return acc + literal + encoded;
+  }, "");
+}
 function withQuery(path, query) {
   const queryString = query.toString();
   return queryString ? `${path}?${queryString}` : path;

package/dist/client/index.d.ts

@@ -6,5 +6,5 @@ export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen';
 export type { ServerSentEventsResult } from '../core/serverSentEvents.gen';
 export { createClient } from './client.gen';
 export type { PreparedClient } from './client.gen';
-export type { Client, ClientOptions, Config, CreateClientConfig, Options, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from './types.gen';
+export type { BaseUrlRequest, BaseUrlResolver, Client, ClientOptions, Config, CreateClientConfig, Options, RequestOptions, RequestResult, ResolvedRequestOptions, ResponseStyle, TDataShape, } from './types.gen';
 export { createConfig, mergeHeaders } from './utils.gen';

package/dist/client/types.gen.d.ts

@@ -3,6 +3,21 @@ import type { Auth } from '../core/auth.gen';
 import type { ServerSentEventsOptions, ServerSentEventsResult } from '../core/serverSentEvents.gen';
 import type { Client as CoreClient, Config as CoreConfig } from '../core/types.gen';
 import type { Middleware } from './utils.gen';
+import type { ApiPathScope } from '../api-client/api-path-scope';
+/** The request a base URL is picked for; see {@link Config.resolveBaseUrl}. */
+export type BaseUrlRequest = {
+    /** The configured base URL, or `''` when none is set. */
+    baseUrl: string;
+    /** The request's path and query, as they follow the base URL. */
+    url: string;
+    /**
+     * The organization, and project when present, the path targets
+     * (`parseApiPathScope` in `@sentry/api/client`). Absent for unscoped paths.
+     */
+    scope?: ApiPathScope;
+};
+/** Picks the base URL for one request; see {@link Config.resolveBaseUrl}. */
+export type BaseUrlResolver = (request: BaseUrlRequest) => string | Promise<string>;
 export type ResponseStyle = 'fields';
 export interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, CoreConfig {
     /**
@@ -16,6 +31,13 @@ export interface Config<T extends ClientOptions = ClientOptions> extends Omit<Re
      * @default globalThis.fetch
      */
     fetch?: typeof fetch;
+    /**
+     * Pick the base URL for each request, before its URL is built, such as the
+     * region that serves the organization the path targets. Called once per
+     * request, after `requestValidator` and before request interceptors; its
+     * result replaces `baseUrl` for that request.
+     */
+    resolveBaseUrl?: BaseUrlResolver;
     /**
      * Please don't use the Fetch client for Next.js applications. The `next`
      * options won't have any effect.

package/dist/index.d.ts

@@ -9,4 +9,4 @@ export type * from './query-enums.gen.ts';
 export * from './pagination.gen.ts';
 export { createSentryClient } from './sentry-client.gen.ts';
 export type { SentryClient } from './sentry-client.gen.ts';
-export type { Config } from './client/index.ts';
+export type { BaseUrlRequest, BaseUrlResolver, Config } from './client/index.ts';

package/dist/index.js

@@ -443,6 +443,43 @@ function getValidRequestBody(options) {
   return void 0;
 }
 
+// src/api-client/api-path-scope.ts
+var API_PATH_IDENTIFIER = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function isApiPathIdentifier(segment) {
+  return segment !== void 0 && API_PATH_IDENTIFIER.test(segment);
+}
+function apiPathSegments(urlOrPath) {
+  const isUrl = URL.canParse(urlOrPath);
+  const path = isUrl ? new URL(urlOrPath).pathname : urlOrPath.split(/[?#]/, 1)[0] ?? "";
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    if (segments[index] === "api" && segments[index + 1] === "0") {
+      return segments.slice(index + 2);
+    }
+  }
+  return isUrl ? void 0 : segments;
+}
+function parseApiPathScope(urlOrPath) {
+  const segments = apiPathSegments(urlOrPath);
+  if (!segments) {
+    return;
+  }
+  const [resource, organization, next, project] = segments;
+  if (!isApiPathIdentifier(organization)) {
+    return;
+  }
+  if (resource === "organizations") {
+    return next === "projects" && isApiPathIdentifier(project) ? { organization, project } : { organization };
+  }
+  if (resource === "projects") {
+    return isApiPathIdentifier(next) ? { organization, project: next } : { organization };
+  }
+  if (resource === "teams") {
+    return { organization };
+  }
+  return;
+}
+
 // src/core/auth.gen.ts
 var getAuthToken = async (auth, callback) => {
   const token = typeof callback === "function" ? await callback(auth) : callback;
@@ -677,6 +714,15 @@ var assertFields = (config) => {
     throw new TypeError('@sentry/api only supports responseStyle: "fields". Read result.data instead.');
   }
 };
+var resolveBaseUrl = async (resolve, baseUrl, url) => {
+  const scope = parseApiPathScope(url);
+  const resolved = await resolve(scope ? { baseUrl, url, scope } : { baseUrl, url });
+  let end = resolved.length;
+  while (end > 0 && resolved.charAt(end - 1) === "/") {
+    end -= 1;
+  }
+  return resolved.slice(0, end);
+};
 var createClient = (config = {}) => {
   assertFields(config);
   let _config = mergeConfigs(createConfig(), config);
@@ -709,6 +755,13 @@ var createClient = (config = {}) => {
       opts.headers.delete("Content-Type");
     }
     const resolvedOpts = opts;
+    if (resolvedOpts.resolveBaseUrl) {
+      resolvedOpts.baseUrl = await resolveBaseUrl(
+        resolvedOpts.resolveBaseUrl,
+        resolvedOpts.baseUrl ?? "",
+        buildUrl({ ...resolvedOpts, baseUrl: "" })
+      );
+    }
     const url = buildUrl(resolvedOpts);
     return { opts: resolvedOpts, url };
   };