@bikefinder/api-client 0.0.0-stage → 0.1.0

package/src/options.ts

@@ -0,0 +1,61 @@
+import { AuthenticationError } from "./errors.js";
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  getToken: (forceRefresh?: boolean) => Promise<string>;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface ResolvedClientOptions {
+  baseUrl: string;
+  getToken: ApiClientOptions["getToken"];
+  fetch: typeof globalThis.fetch;
+}
+
+export function resolveClientOptions(
+  options: ApiClientOptions,
+): ResolvedClientOptions {
+  let url: URL;
+  try {
+    url = new URL(options.baseUrl);
+  } catch {
+    throw new TypeError("baseUrl must be an absolute HTTP or HTTPS URL.");
+  }
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new TypeError(
+      "baseUrl must be HTTP or HTTPS without credentials, query or fragment.",
+    );
+  }
+
+  const fetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetch) {
+    throw new TypeError("Supply a Fetch API implementation for this runtime.");
+  }
+  return {
+    baseUrl: url.href.replace(/\/+$/, ""),
+    getToken: options.getToken,
+    fetch,
+  };
+}
+
+export async function getAuthorization(
+  options: Pick<ApiClientOptions, "getToken">,
+  forceRefresh = false,
+): Promise<string> {
+  try {
+    const token = await options.getToken(forceRefresh);
+    if (typeof token !== "string" || !token || /[^\x21-\x7e]/.test(token)) {
+      throw new AuthenticationError();
+    }
+    return `Bearer ${token}`;
+  } catch {
+    // Identity-provider errors can contain credentials. Expose no original cause.
+    throw new AuthenticationError();
+  }
+}

package/src/realtime/api-stream-error.ts

@@ -0,0 +1,20 @@
+export type ApiStreamErrorCode = "http" | "protocol" | "network";
+
+/** A safe stream error. Response bodies, bearer tokens and transport errors are omitted. */
+export class ApiStreamError extends Error {
+  readonly code: ApiStreamErrorCode;
+  readonly status: number | undefined;
+
+  constructor(code: ApiStreamErrorCode, status?: number) {
+    super(
+      code === "http"
+        ? `The tracker stream returned HTTP ${status}.`
+        : code === "protocol"
+          ? "The tracker stream returned an invalid response."
+          : "The tracker stream connection was interrupted.",
+    );
+    this.name = "ApiStreamError";
+    this.code = code;
+    this.status = status;
+  }
+}

package/src/realtime/watch-trackers.ts

@@ -0,0 +1,114 @@
+import {
+  defer,
+  filter,
+  merge,
+  Observable,
+  ReplaySubject,
+  retry,
+  share,
+  Subject,
+  timer,
+} from "rxjs";
+import { ZodError } from "zod";
+
+import { AuthenticationError } from "../errors.js";
+import type { BikeFinderSdk } from "../generated/sdk.gen.js";
+import { zTrackerPage } from "../generated/zod.gen.js";
+import type { TrackerPage, TrackerPageQuery } from "../types.js";
+import { ApiStreamError } from "./api-stream-error.js";
+
+/**
+ * Observe complete snapshots of one tracker page, shared by this observable's consumers.
+ * Unsubscribe when leaving the view or changing accounts. Re-subscribe after an error
+ * to start a fresh retry budget. Reconnects never request historical event replay.
+ */
+export function watchTrackers(
+  requests: BikeFinderSdk,
+  query: TrackerPageQuery = {},
+): Observable<TrackerPage> {
+  return defer(() => {
+    const disconnected = new Subject<undefined>();
+    const snapshots = new Observable<TrackerPage>((subscriber) => {
+      disconnected.next(undefined);
+      const controller = new AbortController();
+
+      const consume = async () => {
+        try {
+          const { stream } = await requests.subscribeTrackers({
+            query,
+            signal: controller.signal,
+            headers: { Accept: "text/event-stream" },
+            // Each RxJS retry starts a new generated stream with fresh credentials.
+            // The generated transport must not reconnect with an old token itself.
+            sseMaxRetryAttempts: 1,
+            onSseError: (error) => {
+              throw error;
+            },
+            onSseEvent: ({ event, data }) => {
+              if (subscriber.closed || event === "keepalive") return;
+              // A comment-only frame is a transport heartbeat, not an observation.
+              if (event === undefined && data === undefined) return;
+              if (event !== "snapshot") throw new ApiStreamError("protocol");
+              // The generator permits non-JSON SSE data; validate every snapshot
+              // with its generated schema, including malformed JSON strings.
+              const result = zTrackerPage.safeParse(data);
+              if (!result.success) throw new ApiStreamError("protocol");
+              subscriber.next(result.data);
+            },
+          });
+          // Event callbacks retain SSE event names; consuming drives the generated
+          // async iterator. There is no handwritten URL, query serializer or parser.
+          for await (const _ of stream) {
+            if (subscriber.closed) break;
+          }
+          if (!subscriber.closed) throw new ApiStreamError("network");
+        } catch (error) {
+          if (subscriber.closed) return;
+          disconnected.next(undefined);
+          subscriber.error(
+            error instanceof AuthenticationError ||
+              error instanceof ApiStreamError
+              ? error
+              : new ApiStreamError(
+                  error instanceof ZodError ? "protocol" : "network",
+                ),
+          );
+        }
+      };
+      void consume();
+      return () => controller.abort();
+    });
+
+    return merge(
+      disconnected,
+      snapshots.pipe(
+        retry({
+          count: 8,
+          resetOnSuccess: true,
+          delay: (error: unknown, attempt) => {
+            const retryable =
+              error instanceof ApiStreamError &&
+              (error.code === "network" ||
+                (error.code === "http" &&
+                  (error.status === 408 ||
+                    error.status === 429 ||
+                    (error.status ?? 0) >= 500)));
+            if (!retryable) throw error;
+            const maximum = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
+            return timer(maximum * (0.5 + Math.random() * 0.5));
+          },
+        }),
+      ),
+    );
+  }).pipe(
+    share({
+      connector: () => new ReplaySubject<TrackerPage | undefined>(1),
+      resetOnError: true,
+      resetOnComplete: true,
+      resetOnRefCountZero: true,
+    }),
+    // An internal disconnect marker replaces the cached page during backoff, so a
+    // new subscriber never receives an old snapshot as though it were current.
+    filter((page): page is TrackerPage => page !== undefined),
+  );
+}

package/src/transport.ts

@@ -0,0 +1,99 @@
+import { AuthenticationError } from "./errors.js";
+import { getAuthorization, type ResolvedClientOptions } from "./options.js";
+import { ApiStreamError } from "./realtime/api-stream-error.js";
+
+/** Shared bearer authentication and transport policy for generated REST and SSE calls. */
+export function createAuthenticatedFetch(
+  options: ResolvedClientOptions,
+): typeof globalThis.fetch {
+  const origin = new URL(options.baseUrl).origin;
+  return async (input, init) => {
+    const request = new Request(input, {
+      ...init,
+      redirect: "error",
+      credentials: "omit",
+    });
+    const streaming =
+      request.headers
+        .get("Accept")
+        ?.split(",")
+        .some(
+          (value) =>
+            value.split(";")[0]?.trim().toLowerCase() === "text/event-stream",
+        ) ?? false;
+
+    try {
+      throwIfAborted(request.signal);
+      // Generated clients allow per-call base URLs; credentials belong only to
+      // the API origin configured on the factory.
+      if (new URL(request.url).origin !== origin) {
+        throw new TypeError(
+          "Authenticated requests must target the configured API origin.",
+        );
+      }
+      request.headers.set("Authorization", await getAuthorization(options));
+      throwIfAborted(request.signal);
+      const retry = request.clone();
+      // RN's Request polyfill drops redirect. Expo fetch accepts that Request,
+      // but needs the redirect policy explicitly in its second argument.
+      let response = await options.fetch(request, {
+        redirect: "error",
+        credentials: "omit",
+        signal: request.signal,
+      });
+      if (response.status === 401) {
+        throwIfAborted(request.signal);
+        await response.body?.cancel().catch(() => {});
+        retry.headers.set(
+          "Authorization",
+          await getAuthorization(options, true),
+        );
+        throwIfAborted(retry.signal);
+        response = await options.fetch(retry, {
+          redirect: "error",
+          credentials: "omit",
+          signal: retry.signal,
+        });
+      }
+      if (!streaming) return response;
+
+      if (response.status !== 200) {
+        await response.body?.cancel().catch(() => {});
+        if (response.status === 401) throw new AuthenticationError();
+        throw new ApiStreamError("http", response.status);
+      }
+      const contentType = response.headers
+        .get("Content-Type")
+        ?.split(";")[0]
+        ?.trim()
+        .toLowerCase();
+      if (contentType !== "text/event-stream" || !response.body) {
+        await response.body?.cancel().catch(() => {});
+        throw new ApiStreamError("protocol");
+      }
+      return response;
+    } catch (error) {
+      if (
+        !streaming ||
+        error instanceof AuthenticationError ||
+        error instanceof ApiStreamError
+      ) {
+        throw error;
+      }
+      throwIfAborted(request.signal);
+      throw new ApiStreamError("network");
+    }
+  };
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  // Expo's React Native AbortSignal supports aborted, but not throwIfAborted().
+  if (signal?.aborted) {
+    throw (
+      signal.reason ??
+      Object.assign(new Error("The request was cancelled."), {
+        name: "AbortError",
+      })
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+import type { SubscribeTrackersData } from "./generated/types.gen.js";
+
+export type * from "./generated/types.gen.js";
+export type { ProblemDetails as ApiProblem } from "./generated/types.gen.js";
+export type TrackerPageQuery = NonNullable<SubscribeTrackersData["query"]>;