@bikefinder/api-client 0.0.0-stage → 0.2.0

package/src/http-client.ts

@@ -0,0 +1,31 @@
+import { createClient } from "./generated/client/index.js";
+import type { ResolvedClientOptions } from "./options.js";
+import { createAuthenticatedFetch } from "./transport.js";
+
+export function createHttpClient(options: ResolvedClientOptions) {
+  const authenticatedFetch = createAuthenticatedFetch(options);
+  const client = createClient({
+    baseUrl: options.baseUrl,
+    redirect: "error",
+    credentials: "omit",
+    fetch: authenticatedFetch,
+    responseStyle: "fields",
+  });
+  client.interceptors.request.use((request, requestOptions) => {
+    // A per-call fetch would bypass authentication and transport policy.
+    if (requestOptions.fetch !== authenticatedFetch) {
+      throw new TypeError(
+        "Configure fetch on createBikeFinderClient, not individual requests.",
+      );
+    }
+    return request;
+  });
+  client.interceptors.error.use((error, response) => {
+    // Transport/auth/cancellation failures are exceptions, not HTTP Problem Details.
+    if (!response) throw error;
+    if (response.ok)
+      throw new TypeError("The API returned an invalid response.");
+    return error;
+  });
+  return client;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import { resolveClientOptions, type ApiClientOptions } from "./options.js";
+import { BikeFinderSdk } from "./generated/sdk.gen.js";
+import { createHttpClient } from "./http-client.js";
+import {
+  watch,
+  type StreamOperation,
+  type StreamOptions,
+} from "./realtime/watch.js";
+import type { TrackerPageQuery } from "./types.js";
+
+export { AuthenticationError } from "./errors.js";
+export { ApiStreamError } from "./realtime/api-stream-error.js";
+export type { ApiClientOptions } from "./options.js";
+export type * from "./types.js";
+
+export function createBikeFinderClient(options: ApiClientOptions) {
+  const resolved = resolveClientOptions(options);
+  const requests = new BikeFinderSdk({ client: createHttpClient(resolved) });
+  return {
+    requests,
+    watch: <TOperation extends StreamOperation>(
+      operation: TOperation,
+      options: StreamOptions<TOperation>,
+    ) => watch(requests, operation, options),
+    watchTrackers: (query: TrackerPageQuery = {}) =>
+      watch(requests, "subscribeTrackers", { query }),
+  };
+}
+
+export type BikeFinderClient = ReturnType<typeof createBikeFinderClient>;

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.ts

@@ -0,0 +1,151 @@
+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 type { Options } from "../generated/sdk.gen.js";
+import { ApiStreamError } from "./api-stream-error.js";
+
+type Method = (...args: never[]) => unknown;
+type Result<TKey extends keyof BikeFinderSdk> =
+  BikeFinderSdk[TKey] extends Method
+    ? Awaited<ReturnType<BikeFinderSdk[TKey]>>
+    : never;
+
+export type StreamOperation = {
+  [TKey in keyof BikeFinderSdk]: Result<TKey> extends {
+    stream: AsyncIterable<unknown>;
+  }
+    ? TKey
+    : never;
+}[keyof BikeFinderSdk];
+
+export type StreamPayload<TKey extends StreamOperation> =
+  Result<TKey> extends {
+    stream: AsyncIterable<infer TPayload>;
+  }
+    ? Exclude<TPayload, null>
+    : never;
+
+export type StreamOptions<TKey extends StreamOperation> = Pick<
+  NonNullable<Parameters<BikeFinderSdk[TKey]>[0]>,
+  Extract<
+    keyof NonNullable<Parameters<BikeFinderSdk[TKey]>[0]>,
+    "path" | "query"
+  >
+>;
+/**
+ * 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 watch<TOperation extends StreamOperation>(
+  requests: BikeFinderSdk,
+  operation: TOperation,
+  options: StreamOptions<TOperation>,
+): Observable<StreamPayload<TOperation>> {
+  // The generated SDK supplies paths, arguments and validators for every stream.
+  // This boundary only adds the shared connection lifecycle.
+  const invoke = requests[operation] as (
+    options: Options,
+  ) => Promise<{ stream: AsyncIterable<unknown> }>;
+  return defer(() => {
+    const disconnected = new Subject<undefined>();
+    const snapshots = new Observable<StreamPayload<TOperation>>(
+      (subscriber) => {
+        disconnected.next(undefined);
+        const controller = new AbortController();
+
+        const consume = async () => {
+          try {
+            const { stream } = await invoke.call(requests, {
+              ...options,
+              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 generated transformer validates and normalizes every JSON
+                // payload. Non-JSON SSE strings bypass it and are never snapshots.
+                if (data === null || typeof data !== "object") {
+                  throw new ApiStreamError("protocol");
+                }
+                subscriber.next(data as StreamPayload<TOperation>);
+              },
+            });
+            // 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<StreamPayload<TOperation> | 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 StreamPayload<TOperation> => 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"]>;