@bikefinder/api-client 0.1.0 → 0.3.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/index.ts

@@ -1,7 +1,11 @@
 import { resolveClientOptions, type ApiClientOptions } from "./options.js";
 import { BikeFinderSdk } from "./generated/sdk.gen.js";
 import { createHttpClient } from "./http-client.js";
-import { watchTrackers } from "./realtime/watch-trackers.js";
+import {
+  watch,
+  type StreamOperation,
+  type StreamOptions,
+} from "./realtime/watch.js";
 import type { TrackerPageQuery } from "./types.js";
 
 export { AuthenticationError } from "./errors.js";
@@ -14,8 +18,12 @@ export function createBikeFinderClient(options: ApiClientOptions) {
   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 = {}) =>
-      watchTrackers(requests, query),
+      watch(requests, "subscribeTrackers", { query }),
   };
 }
 

package/src/realtime/watch.ts

@@ -0,0 +1,158 @@
+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<TSdk, TKey extends keyof TSdk> = TSdk[TKey] extends Method
+  ? Awaited<ReturnType<TSdk[TKey]>>
+  : never;
+
+export type StreamOperation<TSdk = BikeFinderSdk> = {
+  [TKey in keyof TSdk]: Result<TSdk, TKey> extends {
+    stream: AsyncIterable<unknown>;
+  }
+    ? TKey
+    : never;
+}[keyof TSdk];
+
+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<TSdk>,
+  TSdk = BikeFinderSdk,
+> = Pick<
+  NonNullable<Parameters<Extract<TSdk[TKey], Method>>[0]>,
+  Extract<
+    keyof NonNullable<Parameters<Extract<TSdk[TKey], Method>>[0]>,
+    "path" | "query"
+  >
+>;
+/**
+ * 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<TSdk, TOperation extends StreamOperation<TSdk>>(
+  requests: TSdk,
+  operation: 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 (
+    options: Options,
+  ) => Promise<{ stream: AsyncIterable<unknown> }>;
+  return defer(() => {
+    const disconnected = new Subject<undefined>();
+    const snapshots = new Observable<StreamPayload<TOperation, TSdk>>(
+      (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, TSdk>);
+              },
+            });
+            // 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, 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, TSdk> => page !== undefined,
+    ),
+  );
+}

package/dist/realtime/watch-trackers.d.ts

@@ -1,10 +0,0 @@
-import { Observable } from "rxjs";
-import type { BikeFinderSdk } from "../generated/sdk.gen.js";
-import type { TrackerPage, TrackerPageQuery } from "../types.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 declare function watchTrackers(requests: BikeFinderSdk, query?: TrackerPageQuery): Observable<TrackerPage>;
-//# sourceMappingURL=watch-trackers.d.ts.map

package/dist/realtime/watch-trackers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"watch-trackers.d.ts","sourceRoot":"","sources":["../../src/realtime/watch-trackers.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,UAAU,EAMX,MAAM,MAAM,CAAC;AAId,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EACvB,KAAK,GAAE,gBAAqB,GAC3B,UAAU,CAAC,WAAW,CAAC,CAsFzB"}

package/dist/realtime/watch-trackers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"watch-trackers.js","sourceRoot":"","sources":["../../src/realtime/watch-trackers.ts"],"names":[],"mappings":"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"}

package/src/realtime/watch-trackers.ts

@@ -1,114 +0,0 @@
-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),
-  );
-}