@bikefinder/api-client 0.2.0 → 0.4.0

package/src/http-client.ts

@@ -2,9 +2,12 @@ import { createClient } from "./generated/client/index.js";
 import type { ResolvedClientOptions } from "./options.js";
 import { createAuthenticatedFetch } from "./transport.js";
 
-export function createHttpClient(options: ResolvedClientOptions) {
+export function createHttpClient(
+  options: ResolvedClientOptions,
+  clientFactory = createClient,
+) {
   const authenticatedFetch = createAuthenticatedFetch(options);
-  const client = createClient({
+  const client = clientFactory({
     baseUrl: options.baseUrl,
     redirect: "error",
     credentials: "omit",
@@ -15,7 +18,7 @@ export function createHttpClient(options: ResolvedClientOptions) {
     // A per-call fetch would bypass authentication and transport policy.
     if (requestOptions.fetch !== authenticatedFetch) {
       throw new TypeError(
-        "Configure fetch on createBikeFinderClient, not individual requests.",
+        "Configure fetch on the client factory, not individual requests.",
       );
     }
     return request;

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

@@ -4,8 +4,13 @@ export type ApiStreamErrorCode = "http" | "protocol" | "network";
 export class ApiStreamError extends Error {
   readonly code: ApiStreamErrorCode;
   readonly status: number | undefined;
+  readonly retryAfterMs: number | undefined;
 
-  constructor(code: ApiStreamErrorCode, status?: number) {
+  constructor(
+    code: ApiStreamErrorCode,
+    status?: number,
+    retryAfterMs?: number,
+  ) {
     super(
       code === "http"
         ? `The tracker stream returned HTTP ${status}.`
@@ -16,5 +21,11 @@ export class ApiStreamError extends Error {
     this.name = "ApiStreamError";
     this.code = code;
     this.status = status;
+    this.retryAfterMs =
+      retryAfterMs !== undefined &&
+      Number.isFinite(retryAfterMs) &&
+      retryAfterMs >= 0
+        ? Math.min(retryAfterMs, 300_000)
+        : undefined;
   }
 }

package/src/realtime/watch.ts

@@ -17,43 +17,48 @@ 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;
+type Result<TSdk, TKey extends keyof TSdk> = TSdk[TKey] extends Method
+  ? Awaited<ReturnType<TSdk[TKey]>>
+  : never;
 
-export type StreamOperation = {
-  [TKey in keyof BikeFinderSdk]: Result<TKey> extends {
+export type StreamOperation<TSdk = BikeFinderSdk> = {
+  [TKey in keyof TSdk]: Result<TSdk, TKey> extends {
     stream: AsyncIterable<unknown>;
   }
     ? TKey
     : never;
-}[keyof BikeFinderSdk];
+}[keyof TSdk];
 
-export type StreamPayload<TKey extends StreamOperation> =
-  Result<TKey> extends {
+export type StreamPayload<
+  TKey extends StreamOperation<TSdk>,
+  TSdk = BikeFinderSdk,
+> =
+  Result<TSdk, TKey> extends {
     stream: AsyncIterable<infer TPayload>;
   }
     ? Exclude<TPayload, null>
     : never;
 
-export type StreamOptions<TKey extends StreamOperation> = Pick<
-  NonNullable<Parameters<BikeFinderSdk[TKey]>[0]>,
+export type StreamOptions<
+  TKey extends StreamOperation<TSdk>,
+  TSdk = BikeFinderSdk,
+> = Pick<
+  NonNullable<Parameters<Extract<TSdk[TKey], Method>>[0]>,
   Extract<
-    keyof NonNullable<Parameters<BikeFinderSdk[TKey]>[0]>,
+    keyof NonNullable<Parameters<Extract<TSdk[TKey], Method>>[0]>,
     "path" | "query"
   >
 >;
 /**
- * Observe complete snapshots of one tracker page, shared by this observable's consumers.
+ * Observe complete snapshots of a generated view, 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,
+export function watch<TSdk, TOperation extends StreamOperation<TSdk>>(
+  requests: TSdk,
   operation: TOperation,
-  options: StreamOptions<TOperation>,
-): Observable<StreamPayload<TOperation>> {
+  options: StreamOptions<TOperation, TSdk>,
+): Observable<StreamPayload<TOperation, TSdk>> {
   // The generated SDK supplies paths, arguments and validators for every stream.
   // This boundary only adds the shared connection lifecycle.
   const invoke = requests[operation] as (
@@ -61,7 +66,7 @@ export function watch<TOperation extends StreamOperation>(
   ) => Promise<{ stream: AsyncIterable<unknown> }>;
   return defer(() => {
     const disconnected = new Subject<undefined>();
-    const snapshots = new Observable<StreamPayload<TOperation>>(
+    const snapshots = new Observable<StreamPayload<TOperation, TSdk>>(
       (subscriber) => {
         disconnected.next(undefined);
         const controller = new AbortController();
@@ -88,7 +93,7 @@ export function watch<TOperation extends StreamOperation>(
                 if (data === null || typeof data !== "object") {
                   throw new ApiStreamError("protocol");
                 }
-                subscriber.next(data as StreamPayload<TOperation>);
+                subscriber.next(data as StreamPayload<TOperation, TSdk>);
               },
             });
             // Event callbacks retain SSE event names; consuming drives the generated
@@ -131,7 +136,12 @@ export function watch<TOperation extends StreamOperation>(
                     (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));
+            return timer(
+              Math.max(
+                maximum * (0.5 + Math.random() * 0.5),
+                error.retryAfterMs ?? 0,
+              ),
+            );
           },
         }),
       ),
@@ -139,13 +149,15 @@ export function watch<TOperation extends StreamOperation>(
   }).pipe(
     share({
       connector: () =>
-        new ReplaySubject<StreamPayload<TOperation> | undefined>(1),
+        new ReplaySubject<StreamPayload<TOperation, TSdk> | 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),
+    filter(
+      (page): page is StreamPayload<TOperation, TSdk> => page !== undefined,
+    ),
   );
 }

package/src/transport.ts

@@ -60,7 +60,7 @@ export function createAuthenticatedFetch(
       if (response.status !== 200) {
         await response.body?.cancel().catch(() => {});
         if (response.status === 401) throw new AuthenticationError();
-        throw new ApiStreamError("http", response.status);
+        throw new ApiStreamError("http", response.status, retryAfter(response));
       }
       const contentType = response.headers
         .get("Content-Type")
@@ -86,6 +86,15 @@ export function createAuthenticatedFetch(
   };
 }
 
+function retryAfter(response: Response): number | undefined {
+  const value = response.headers.get("Retry-After")?.trim();
+  if (!value) return undefined;
+  const delay = /^\d+$/.test(value)
+    ? Number(value) * 1_000
+    : Date.parse(value) - Date.now();
+  return Number.isFinite(delay) ? Math.max(0, delay) : undefined;
+}
+
 function throwIfAborted(signal?: AbortSignal): void {
   // Expo's React Native AbortSignal supports aborted, but not throwIfAborted().
   if (signal?.aborted) {