effect-browserbase 0.2.0-beta.9 → 0.3.0-beta.10

package/src/BrowserbaseClient.ts

@@ -0,0 +1,559 @@
+/**
+ * A small client for the Browserbase REST API: sessions, stored contexts, extensions, web search
+ * and page fetch.
+ *
+ * It runs on the `HttpClient` the application provides, such as `FetchHttpClient.layer`. The API
+ * key travels only in the `X-BB-API-Key` header and is redacted from logs and traces. Redirects
+ * are refused rather than followed, because following one would send the key wherever it points.
+ *
+ * Every request has a deadline, so a provider that never answers cannot hold a caller's scope open.
+ * Reads are retried twice on transient failures. Writes are not: a session create that fails in
+ * transit or misses its deadline may still have created the session, which then ends at its timeout.
+ *
+ * @since 0.3.0
+ */
+import {
+  Config,
+  Context,
+  Duration,
+  Effect,
+  Exit,
+  flow,
+  identity,
+  Layer,
+  Option,
+  Redacted,
+  Schedule,
+  Schema,
+} from "effect";
+import {
+  FetchHttpClient,
+  Headers,
+  HttpClient,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/http";
+
+import {
+  BrowserbaseError,
+  Decode,
+  InvalidRequest,
+  isTransient,
+  NotFound,
+  RateLimited,
+  type Reason,
+  Status,
+  Transport,
+  Unauthorized,
+} from "./BrowserbaseError.ts";
+
+export const defaultBaseUrl = "https://api.browserbase.com";
+
+export class Session extends Schema.Class<Session>("effect-browserbase/Session")({
+  id: Schema.String,
+  /** `PENDING`, `RUNNING`, `ERROR`, `TIMED_OUT` or `COMPLETED`, kept open for new values. */
+  status: Schema.String,
+  region: Schema.String,
+  keepAlive: Schema.Boolean,
+  createdAt: Schema.String,
+  expiresAt: Schema.String,
+  endedAt: Schema.optional(Schema.String),
+  contextId: Schema.optional(Schema.String),
+  proxyBytes: Schema.optional(Schema.Finite),
+  userMetadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  /** The CDP WebSocket address, a credential. Only create and get return it. */
+  connectUrl: Schema.optional(Schema.RedactedFromValue(Schema.String)),
+}) {}
+
+/** Links that let a person watch and control a running session. They are credentials. */
+export class LiveView extends Schema.Class<LiveView>("effect-browserbase/LiveView")({
+  /** The active tab, without browser chrome: suited to an iframe. */
+  debuggerFullscreenUrl: Schema.RedactedFromValue(Schema.String),
+  debuggerUrl: Schema.RedactedFromValue(Schema.String),
+  pages: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      url: Schema.String,
+      title: Schema.String,
+      debuggerFullscreenUrl: Schema.RedactedFromValue(Schema.String),
+    }),
+  ),
+}) {}
+
+/** Browser state (cookies, storage, cache) kept by Browserbase for sessions to load and save. */
+export class StoredContext extends Schema.Class<StoredContext>("effect-browserbase/StoredContext")({
+  id: Schema.String,
+  name: Schema.optional(Schema.String),
+  /** `getContext` returns the timestamps; `createContext` does not. */
+  createdAt: Schema.optional(Schema.String),
+  updatedAt: Schema.optional(Schema.String),
+}) {}
+
+/** A Chrome extension uploaded to the project, which sessions load when created with its id. */
+export class Extension extends Schema.Class<Extension>("effect-browserbase/Extension")({
+  id: Schema.String,
+  fileName: Schema.String,
+  createdAt: Schema.String,
+  updatedAt: Schema.String,
+}) {}
+
+export class SearchResult extends Schema.Class<SearchResult>("effect-browserbase/SearchResult")({
+  url: Schema.String,
+  title: Schema.String,
+  author: Schema.optional(Schema.String),
+  publishedDate: Schema.optional(Schema.String),
+}) {}
+
+/** A page fetched without a browser. */
+export class FetchedPage extends Schema.Class<FetchedPage>("effect-browserbase/FetchedPage")({
+  statusCode: Schema.Finite,
+  contentType: Schema.String,
+  headers: Schema.Record(Schema.String, Schema.String),
+  /** Text for the `raw` and `markdown` formats; the extracted object for `json`. */
+  content: Schema.Union([Schema.String, Schema.Record(Schema.String, Schema.Unknown)]),
+}) {}
+
+/** A session create request, as Browserbase's API reference describes it. */
+export interface SessionOptions {
+  /** Defaults to the API key's project. */
+  readonly projectId?: string | undefined;
+  /** An uploaded extension for the browser to load. It makes the session slower to start. */
+  readonly extensionId?: string | undefined;
+  /** Seconds until Browserbase ends the session, from 60 to 21,600. Defaults to the project's. */
+  readonly timeout?: number | undefined;
+  /** Keep the session running after every client disconnects, until released or timed out. */
+  readonly keepAlive?: boolean | undefined;
+  readonly region?: "us-west-2" | "us-east-1" | "eu-central-1" | "ap-southeast-1" | undefined;
+  /** `true` for Browserbase's proxies, or rules per domain. */
+  readonly proxies?: boolean | ReadonlyArray<ProxyRule> | undefined;
+  /** Labels that `listSessions` can query. */
+  readonly userMetadata?: Readonly<Record<string, unknown>> | undefined;
+  readonly browserSettings?: BrowserSettings | undefined;
+}
+
+/** Browser settings. Left unset, each takes Browserbase's default. */
+export interface BrowserSettings {
+  /**
+   * Load a stored context. With `persist`, Browserbase saves the session's changes back to it once
+   * the session ends; `Browserbase.open` lets one such session at a time write to each context.
+   */
+  readonly context?: { readonly id: string; readonly persist?: boolean | undefined } | undefined;
+  readonly viewport?: { readonly width: number; readonly height: number } | undefined;
+  readonly blockAds?: boolean | undefined;
+  /** Browserbase solves captchas unless this is false. */
+  readonly solveCaptchas?: boolean | undefined;
+  /** Browserbase records the session for replay unless this is false. */
+  readonly recordSession?: boolean | undefined;
+  /** Browserbase keeps the session's logs unless this is false. */
+  readonly logSession?: boolean | undefined;
+  /** Verified browser mode, on plans that include it. */
+  readonly verified?: boolean | undefined;
+  readonly os?: "windows" | "mac" | "linux" | "mobile" | "tablet" | undefined;
+  /** Restrict top-level navigation to these domains and their subdomains. */
+  readonly allowedDomains?: ReadonlyArray<string> | undefined;
+  readonly ignoreCertificateErrors?: boolean | undefined;
+}
+
+export type ProxyRule =
+  | {
+      readonly type: "browserbase";
+      readonly geolocation?:
+        | {
+            readonly country: string;
+            readonly state?: string | undefined;
+            readonly city?: string | undefined;
+          }
+        | undefined;
+      readonly domainPattern?: string | undefined;
+    }
+  | {
+      readonly type: "external";
+      readonly server: string;
+      readonly username?: string | undefined;
+      readonly password?: string | undefined;
+      readonly domainPattern?: string | undefined;
+    }
+  | { readonly type: "none"; readonly domainPattern?: string | undefined };
+
+export interface FetchOptions {
+  /** `raw` (the default) returns the body as is; `json` needs `schema`. */
+  readonly format?: "raw" | "markdown" | "json" | undefined;
+  /** JSON Schema of the object to extract with the `json` format. */
+  readonly schema?: Readonly<Record<string, unknown>> | undefined;
+  readonly allowRedirects?: boolean | undefined;
+  readonly allowInsecureSsl?: boolean | undefined;
+  readonly proxies?: boolean | undefined;
+}
+
+export interface Service {
+  readonly createSession: (options?: SessionOptions) => Effect.Effect<Session, BrowserbaseError>;
+  readonly getSession: (id: string) => Effect.Effect<Session, BrowserbaseError>;
+  /** Sessions with the given status, or all. `query` filters on user metadata, in Browserbase's syntax. */
+  readonly listSessions: (options?: {
+    readonly status?: string | undefined;
+    readonly query?: string | undefined;
+  }) => Effect.Effect<ReadonlyArray<Session>, BrowserbaseError>;
+  /** End the session now, which stops its billing. Ending an ended session succeeds. */
+  readonly releaseSession: (id: string) => Effect.Effect<void, BrowserbaseError>;
+  /** Live view links. They last `expiresInSeconds`, or as long as the session. */
+  readonly liveView: (
+    id: string,
+    options?: { readonly expiresInSeconds?: number | undefined },
+  ) => Effect.Effect<LiveView, BrowserbaseError>;
+  readonly createContext: (options?: {
+    readonly name?: string | undefined;
+  }) => Effect.Effect<StoredContext, BrowserbaseError>;
+  readonly getContext: (id: string) => Effect.Effect<StoredContext, BrowserbaseError>;
+  /** Delete a stored context for good. Sessions can no longer load it. */
+  readonly deleteContext: (id: string) => Effect.Effect<void, BrowserbaseError>;
+  /**
+   * Upload a Chrome extension: a zip of at most 100 MB with `manifest.json` at its root. Create a
+   * session with the returned id as `extensionId` to load it.
+   */
+  readonly uploadExtension: (
+    archive: Uint8Array,
+    options?: { readonly fileName?: string | undefined },
+  ) => Effect.Effect<Extension, BrowserbaseError>;
+  readonly getExtension: (id: string) => Effect.Effect<Extension, BrowserbaseError>;
+  readonly deleteExtension: (id: string) => Effect.Effect<void, BrowserbaseError>;
+  /** Search the web for up to `results` hits, from 1 to 25. Defaults to 10. */
+  readonly search: (
+    query: string,
+    options?: { readonly results?: number | undefined },
+  ) => Effect.Effect<ReadonlyArray<SearchResult>, BrowserbaseError>;
+  readonly fetch: (
+    url: string,
+    options?: FetchOptions,
+  ) => Effect.Effect<FetchedPage, BrowserbaseError>;
+}
+
+export class BrowserbaseClient extends Context.Service<BrowserbaseClient, Service>()(
+  "effect-browserbase/BrowserbaseClient",
+) {}
+
+export interface Options {
+  readonly apiKey: Redacted.Redacted<string>;
+  /** Defaults to `https://api.browserbase.com`. */
+  readonly baseUrl?: string | undefined;
+  /** Bound on each request attempt, including reading its answer. Defaults to 60 seconds. */
+  readonly requestTimeout?: Duration.Input | undefined;
+}
+
+const ids = /^[A-Za-z0-9_-]{1,128}$/;
+const maxExtensionBytes = 100 * 1024 * 1024;
+const ErrorBody = Schema.fromJsonString(Schema.Struct({ message: Schema.String }));
+const SearchResponse = Schema.Struct({ results: Schema.Array(SearchResult) });
+const CreatedId = Schema.Struct({ id: Schema.String.check(Schema.isPattern(ids)) });
+
+const statusReason = (status: number, detail: string): Reason => {
+  if (status < 200 || (status >= 300 && status < 400)) {
+    return new Status({
+      status,
+      detail: "redirected; redirects are refused so the API key stays with Browserbase",
+    });
+  }
+  if (status === 400) return new InvalidRequest({ detail });
+  if (status === 401 || status === 403) return new Unauthorized({ detail });
+  if (status === 404) return new NotFound({ detail });
+  if (status === 429) return new RateLimited({ detail });
+
+  return new Status({ status, detail });
+};
+
+/** A create's answer that did not decode though it named session `id`, released or not since. */
+const undecoded = (detail: string, id: string, released: boolean) =>
+  new Decode({
+    detail: `${detail}; session ${id} ${released ? "was released" : "could not be released and ends at its timeout"}`,
+    released,
+  });
+
+/** Run the request with fetch's redirect mode set to manual, keeping any other fetch options. */
+const refuseRedirects = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.contextWith((context: Context.Context<never>) =>
+    Effect.provideService(effect, FetchHttpClient.RequestInit, {
+      ...Context.getOrUndefined(context, FetchHttpClient.RequestInit),
+      redirect: "manual",
+    }),
+  );
+
+export const make = Effect.fnUntraced(function* (options: Options) {
+  const http = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.mapRequest(
+      flow(
+        HttpClientRequest.prependUrl(options.baseUrl ?? defaultBaseUrl),
+        HttpClientRequest.setHeader("x-bb-api-key", Redacted.value(options.apiKey)),
+        HttpClientRequest.acceptJson,
+      ),
+    ),
+    HttpClient.transformResponse(
+      flow(
+        refuseRedirects,
+        Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, "x-bb-api-key"]),
+      ),
+    ),
+  );
+
+  const failure = (operation: string, reason: Reason) =>
+    new BrowserbaseError({ operation, reason });
+
+  const requestTimeout = Duration.fromInputUnsafe(options.requestTimeout ?? Duration.seconds(60));
+
+  /** Send one request; on a success status, read the answer with `read`. */
+  const send = <A>(
+    operation: string,
+    request: HttpClientRequest.HttpClientRequest,
+    read: (response: HttpClientResponse.HttpClientResponse) => Effect.Effect<A, BrowserbaseError>,
+  ): Effect.Effect<A, BrowserbaseError> =>
+    http.execute(request).pipe(
+      Effect.mapError((error) => failure(operation, new Transport({ detail: error.message }))),
+      Effect.flatMap((response) =>
+        response.status >= 200 && response.status < 300
+          ? read(response)
+          : response.text.pipe(
+              Effect.map((text) =>
+                Option.getOrElse(
+                  Option.map(Schema.decodeOption(ErrorBody)(text), (body) => body.message),
+                  () => text.slice(0, 300),
+                ),
+              ),
+              Effect.orElseSucceed(() => ""),
+              Effect.flatMap((detail) =>
+                Effect.fail(failure(operation, statusReason(response.status, detail))),
+              ),
+            ),
+      ),
+      // The deadline also applies inside a caller's uninterruptible acquisition, such as the
+      // session create in Browserbase.open, so that acquisition always settles.
+      Effect.timeoutOrElse({
+        duration: requestTimeout,
+        orElse: () =>
+          Effect.fail(
+            failure(
+              operation,
+              new Transport({
+                detail: `no answer within ${Duration.format(requestTimeout)}`,
+              }),
+            ),
+          ),
+      }),
+      request.method === "GET"
+        ? Effect.retry({
+            while: isTransient,
+            times: 2,
+            schedule: Schedule.exponential("250 millis").pipe(Schedule.jittered),
+          })
+        : identity,
+      Effect.withSpan(`Browserbase.${operation}`),
+    );
+
+  const json =
+    <A>(operation: string, schema: Schema.Decoder<A>) =>
+    (response: HttpClientResponse.HttpClientResponse) =>
+      HttpClientResponse.schemaBodyJson(schema)(response).pipe(
+        Effect.mapError((error) =>
+          failure(operation, new Decode({ detail: error.message.split("\n")[0] ?? "" })),
+        ),
+      );
+
+  const ignoreBody = () => Effect.void;
+
+  const withBody = (
+    operation: string,
+    request: HttpClientRequest.HttpClientRequest,
+    body: unknown,
+  ) =>
+    HttpClientRequest.bodyJson(request, body).pipe(
+      Effect.mapError((error) => failure(operation, new InvalidRequest({ detail: error.message }))),
+    );
+
+  const checkId = (operation: string, id: string): Effect.Effect<string, BrowserbaseError> =>
+    ids.test(id)
+      ? Effect.succeed(id)
+      : Effect.fail(
+          failure(
+            operation,
+            new InvalidRequest({ detail: `${JSON.stringify(id)} is not a Browserbase id` }),
+          ),
+        );
+
+  const releaseSession = (id: string) =>
+    checkId("releaseSession", id).pipe(
+      Effect.flatMap(() =>
+        withBody("releaseSession", HttpClientRequest.post(`/v1/sessions/${id}`), {
+          status: "REQUEST_RELEASE",
+        }),
+      ),
+      Effect.flatMap((request) => send("releaseSession", request, ignoreBody)),
+    );
+
+  // A success answer means the session exists even if the rest of it does not decode. Only an id
+  // lets anyone end it early, so release it here before reporting the unexpected answer.
+  const createSession = (body: SessionOptions) =>
+    withBody("createSession", HttpClientRequest.post("/v1/sessions"), body).pipe(
+      Effect.flatMap((request) =>
+        send("createSession", request, json("createSession", Schema.Unknown)),
+      ),
+      Effect.flatMap((answer) =>
+        Schema.decodeUnknownEffect(Session)(answer).pipe(
+          Effect.catch((error) => {
+            const detail = error.message.split("\n")[0] ?? "";
+
+            return Option.match(Schema.decodeUnknownOption(CreatedId)(answer), {
+              onNone: () => Effect.fail(failure("createSession", new Decode({ detail }))),
+              onSome: ({ id }) =>
+                releaseSession(id).pipe(
+                  Effect.exit,
+                  Effect.flatMap((release) =>
+                    Effect.fail(
+                      failure("createSession", undecoded(detail, id, Exit.isSuccess(release))),
+                    ),
+                  ),
+                ),
+            });
+          }),
+        ),
+      ),
+    );
+
+  return BrowserbaseClient.of({
+    createSession: (body = {}) => createSession(body),
+    getSession: (id) =>
+      checkId("getSession", id).pipe(
+        Effect.flatMap(() =>
+          send(
+            "getSession",
+            HttpClientRequest.get(`/v1/sessions/${id}`),
+            json("getSession", Session),
+          ),
+        ),
+      ),
+    listSessions: (filter = {}) =>
+      send(
+        "listSessions",
+        HttpClientRequest.get("/v1/sessions", {
+          urlParams: {
+            ...(filter.status === undefined ? {} : { status: filter.status }),
+            ...(filter.query === undefined ? {} : { q: filter.query }),
+          },
+        }),
+        json("listSessions", Schema.Array(Session)),
+      ),
+    releaseSession,
+    liveView: (id, options = {}) =>
+      checkId("liveView", id).pipe(
+        Effect.flatMap(() =>
+          send(
+            "liveView",
+            HttpClientRequest.get(`/v1/sessions/${id}/debug`, {
+              urlParams:
+                options.expiresInSeconds === undefined
+                  ? {}
+                  : { expiresIn: options.expiresInSeconds },
+            }),
+            json("liveView", LiveView),
+          ),
+        ),
+      ),
+    createContext: (body = {}) =>
+      withBody("createContext", HttpClientRequest.post("/v1/contexts"), body).pipe(
+        Effect.flatMap((request) =>
+          send("createContext", request, json("createContext", StoredContext)),
+        ),
+      ),
+    getContext: (id) =>
+      checkId("getContext", id).pipe(
+        Effect.flatMap(() =>
+          send(
+            "getContext",
+            HttpClientRequest.get(`/v1/contexts/${id}`),
+            json("getContext", StoredContext),
+          ),
+        ),
+      ),
+    deleteContext: (id) =>
+      checkId("deleteContext", id).pipe(
+        Effect.flatMap(() =>
+          send("deleteContext", HttpClientRequest.delete(`/v1/contexts/${id}`), ignoreBody),
+        ),
+      ),
+    uploadExtension: (archive, options = {}) =>
+      archive.byteLength === 0 || archive.byteLength > maxExtensionBytes
+        ? Effect.fail(
+            failure(
+              "uploadExtension",
+              new InvalidRequest({
+                detail: `the archive has ${archive.byteLength} bytes; Browserbase takes 1 byte to 100 MB`,
+              }),
+            ),
+          )
+        : Effect.suspend(() => {
+            const form = new FormData();
+
+            form.append(
+              "file",
+              new Blob([new Uint8Array(archive)], { type: "application/zip" }),
+              options.fileName ?? "extension.zip",
+            );
+
+            return send(
+              "uploadExtension",
+              HttpClientRequest.post("/v1/extensions").pipe(HttpClientRequest.bodyFormData(form)),
+              json("uploadExtension", Extension),
+            );
+          }),
+    getExtension: (id) =>
+      checkId("getExtension", id).pipe(
+        Effect.flatMap(() =>
+          send(
+            "getExtension",
+            HttpClientRequest.get(`/v1/extensions/${id}`),
+            json("getExtension", Extension),
+          ),
+        ),
+      ),
+    deleteExtension: (id) =>
+      checkId("deleteExtension", id).pipe(
+        Effect.flatMap(() =>
+          send("deleteExtension", HttpClientRequest.delete(`/v1/extensions/${id}`), ignoreBody),
+        ),
+      ),
+    search: (query, options = {}) =>
+      withBody("search", HttpClientRequest.post("/v1/search"), {
+        query,
+        ...(options.results === undefined ? {} : { numResults: options.results }),
+      }).pipe(
+        Effect.flatMap((request) => send("search", request, json("search", SearchResponse))),
+        Effect.map((response) => response.results),
+      ),
+    fetch: (url, options = {}) =>
+      withBody("fetch", HttpClientRequest.post("/v1/fetch"), { url, ...options }).pipe(
+        Effect.flatMap((request) => send("fetch", request, json("fetch", FetchedPage))),
+      ),
+  });
+});
+
+export const layer = (
+  options: Options,
+): Layer.Layer<BrowserbaseClient, never, HttpClient.HttpClient> =>
+  Layer.effect(BrowserbaseClient, make(options));
+
+/** The client configured from `BROWSERBASE_API_KEY` and, optionally, `BROWSERBASE_BASE_URL`. */
+export const layerConfig = (
+  options: {
+    readonly apiKey?: Config.Config<Redacted.Redacted<string>> | undefined;
+    readonly baseUrl?: Config.Config<string> | undefined;
+  } = {},
+): Layer.Layer<BrowserbaseClient, Config.ConfigError, HttpClient.HttpClient> =>
+  Layer.effect(
+    BrowserbaseClient,
+    Effect.gen(function* () {
+      const apiKey = yield* options.apiKey ?? Config.Redacted("BROWSERBASE_API_KEY");
+
+      const baseUrl = yield* (
+        options.baseUrl ??
+          Config.String("BROWSERBASE_BASE_URL").pipe(Config.withDefault(defaultBaseUrl))
+      );
+
+      return yield* make({ apiKey, baseUrl });
+    }),
+  );

package/src/BrowserbaseError.ts

@@ -0,0 +1,108 @@
+/**
+ * The one error every Browserbase API call fails with. `reason` says what went wrong.
+ *
+ * @since 0.3.0
+ */
+import { Schema } from "effect";
+
+/** The API key is missing, wrong or not allowed to do this (401 or 403). */
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()("Unauthorized", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `unauthorized: ${this.detail}`;
+  }
+}
+
+/** No session, context or other resource has that id (404). */
+export class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `not found: ${this.detail}`;
+  }
+}
+
+/** Too many concurrent sessions or requests for the plan (429). Wait, then try again. */
+export class RateLimited extends Schema.TaggedError<RateLimited>()("RateLimited", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `rate limited: ${this.detail}`;
+  }
+}
+
+/** Any other answer that is not a success, including a redirect, which is never followed. */
+export class Status extends Schema.TaggedError<Status>()("Status", {
+  status: Schema.Finite,
+  detail: Schema.String,
+}) {
+  override get message() {
+    return `status ${this.status}: ${this.detail}`;
+  }
+}
+
+/**
+ * No answer arrived: the request could not be sent, or the connection failed. A request that
+ * creates something may still have created it.
+ */
+export class Transport extends Schema.TaggedError<Transport>()("Transport", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+/**
+ * The answer did not have the expected shape. For a create whose answer named its session,
+ * `released` says whether the client then released that session; without it, a session may be
+ * left running.
+ */
+export class Decode extends Schema.TaggedError<Decode>()("Decode", {
+  detail: Schema.String,
+  released: Schema.optional(Schema.Boolean),
+}) {
+  override get message() {
+    return `unexpected response: ${this.detail}`;
+  }
+}
+
+/**
+ * Not a request Browserbase takes, such as an id that is not one: Browserbase refused it (400), or
+ * it was refused before sending.
+ */
+export class InvalidRequest extends Schema.TaggedError<InvalidRequest>()("InvalidRequest", {
+  detail: Schema.String,
+}) {
+  override get message() {
+    return this.detail;
+  }
+}
+
+export const Reason = Schema.Union([
+  Unauthorized,
+  NotFound,
+  RateLimited,
+  Status,
+  Transport,
+  Decode,
+  InvalidRequest,
+]);
+
+export type Reason = typeof Reason.Type;
+
+export class BrowserbaseError extends Schema.TaggedError<BrowserbaseError>()("BrowserbaseError", {
+  operation: Schema.String,
+  reason: Reason,
+}) {
+  override get message() {
+    return `Browserbase ${this.operation} failed: ${this.reason.message}`;
+  }
+}
+
+/** True for failures worth retrying after a pause: no answer, a rate limit or a server error. */
+export const isTransient = (error: BrowserbaseError): boolean =>
+  error.reason._tag === "Transport" ||
+  error.reason._tag === "RateLimited" ||
+  (error.reason._tag === "Status" && (error.reason.status >= 500 || error.reason.status === 408));