@bikefinder/api-client 0.0.0-stage → 0.1.0

package/src/generated/core/utils.gen.ts

@@ -0,0 +1,146 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { BodySerializer, QuerySerializer } from "./bodySerializer.gen.js";
+import {
+  type ArraySeparatorStyle,
+  serializeArrayParam,
+  serializeObjectParam,
+  serializePrimitiveParam,
+} from "./pathSerializer.gen.js";
+
+export interface PathSerializer {
+  path: Record<string, unknown>;
+  url: string;
+}
+
+export const PATH_PARAM_RE: RegExp = /\{[^{}]+\}/g;
+
+export const defaultPathSerializer = ({
+  path,
+  url: _url,
+}: PathSerializer): string => {
+  let url = _url;
+  const matches = _url.match(PATH_PARAM_RE);
+  if (matches) {
+    for (const match of matches) {
+      let explode = false;
+      let name = match.substring(1, match.length - 1);
+      let style: ArraySeparatorStyle = "simple";
+
+      if (name.endsWith("*")) {
+        explode = true;
+        name = name.substring(0, name.length - 1);
+      }
+
+      if (name.startsWith(".")) {
+        name = name.substring(1);
+        style = "label";
+      } else if (name.startsWith(";")) {
+        name = name.substring(1);
+        style = "matrix";
+      }
+
+      const value = path[name];
+
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        url = url.replace(
+          match,
+          serializeArrayParam({ explode, name, style, value }),
+        );
+        continue;
+      }
+
+      if (typeof value === "object") {
+        url = url.replace(
+          match,
+          serializeObjectParam({
+            explode,
+            name,
+            style,
+            value: value as Record<string, unknown>,
+            valueOnly: true,
+          }),
+        );
+        continue;
+      }
+
+      if (style === "matrix") {
+        url = url.replace(
+          match,
+          `;${serializePrimitiveParam({
+            name,
+            value: value as string,
+          })}`,
+        );
+        continue;
+      }
+
+      const replaceValue = encodeURIComponent(
+        style === "label" ? `.${value as string}` : (value as string),
+      );
+      url = url.replace(match, replaceValue);
+    }
+  }
+  return url;
+};
+
+export const getUrl = ({
+  baseUrl,
+  path,
+  query,
+  querySerializer,
+  url: _url,
+}: {
+  baseUrl?: string;
+  path?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  querySerializer: QuerySerializer;
+  url: string;
+}): string => {
+  const pathUrl = _url.startsWith("/") ? _url : `/${_url}`;
+  let url = (baseUrl ?? "") + pathUrl;
+  if (path) {
+    url = defaultPathSerializer({ path, url });
+  }
+  let search = query ? querySerializer(query) : "";
+  if (search.startsWith("?")) {
+    search = search.substring(1);
+  }
+  if (search) {
+    url += `?${search}`;
+  }
+  return url;
+};
+
+export function getValidRequestBody(options: {
+  body?: unknown;
+  bodySerializer?: BodySerializer | null;
+  serializedBody?: unknown;
+}): unknown {
+  const hasBody = options.body !== undefined;
+  const isSerializedBody = hasBody && options.bodySerializer;
+
+  if (isSerializedBody) {
+    if ("serializedBody" in options) {
+      const hasSerializedBody =
+        options.serializedBody !== undefined && options.serializedBody !== "";
+
+      return hasSerializedBody ? options.serializedBody : null;
+    }
+
+    // not all clients implement a serializedBody property (i.e., client-axios)
+    return options.body !== "" ? options.body : null;
+  }
+
+  // plain/text body
+  if (hasBody) {
+    return options.body;
+  }
+
+  // no body was provided
+  return undefined;
+}

package/src/generated/index.ts

@@ -0,0 +1,29 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export { BikeFinderSdk, type Options } from "./sdk.gen.js";
+export type {
+  ClientOptions,
+  GetHealthData,
+  GetHealthResponse,
+  GetHealthResponses,
+  GetTrackerData,
+  GetTrackerError,
+  GetTrackerErrors,
+  GetTrackerResponse,
+  GetTrackerResponses,
+  HealthStatus,
+  ListTrackersData,
+  ListTrackersError,
+  ListTrackersErrors,
+  ListTrackersResponse,
+  ListTrackersResponses,
+  ProblemDetails,
+  SubscribeTrackersData,
+  SubscribeTrackersError,
+  SubscribeTrackersErrors,
+  SubscribeTrackersResponse,
+  SubscribeTrackersResponses,
+  TrackerPage,
+  TrackerSummary,
+  TrackingMode,
+} from "./types.gen.js";

package/src/generated/sdk.gen.ts

@@ -0,0 +1,165 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { client } from "./client.gen.js";
+import type {
+  Client,
+  ClientMeta,
+  Options as Options2,
+  RequestResult,
+  ServerSentEventsResult,
+  TDataShape,
+} from "./client/index.js";
+import type {
+  GetHealthData,
+  GetHealthResponses,
+  GetTrackerData,
+  GetTrackerErrors,
+  GetTrackerResponses,
+  ListTrackersData,
+  ListTrackersErrors,
+  ListTrackersResponses,
+  SubscribeTrackersData,
+  SubscribeTrackersErrors,
+  SubscribeTrackersResponse,
+  SubscribeTrackersResponses,
+} from "./types.gen.js";
+import {
+  zGetHealthResponse,
+  zGetTrackerResponse,
+  zListTrackersResponse,
+  zSubscribeTrackersResponse,
+} from "./zod.gen.js";
+
+export type Options<
+  TData extends TDataShape = TDataShape,
+  ThrowOnError extends boolean = boolean,
+  TResponse = unknown,
+> = Options2<TData, ThrowOnError, TResponse> & {
+  /**
+   * You can provide a client instance returned by `createClient()` instead of
+   * individual options. This might be also useful if you want to implement a
+   * custom client.
+   */
+  client?: Client;
+  /**
+   * You can pass arbitrary values through the `meta` object. This can be
+   * used to access values that aren't defined as part of the SDK function.
+   */
+  meta?: keyof ClientMeta extends never ? Record<string, unknown> : ClientMeta;
+};
+
+class HeyApiClient {
+  protected client: Client;
+
+  constructor(args?: { client?: Client }) {
+    this.client = args?.client ?? client;
+  }
+}
+
+class HeyApiRegistry<T> {
+  private readonly defaultKey = "default";
+
+  private readonly instances: Map<string, T> = new Map();
+
+  get(key?: string): T {
+    const instance = this.instances.get(key ?? this.defaultKey);
+    if (!instance) {
+      throw new Error(
+        `No SDK client found. Create one with "new BikeFinderSdk()" to fix this error.`,
+      );
+    }
+    return instance;
+  }
+
+  set(value: T, key?: string): void {
+    this.instances.set(key ?? this.defaultKey, value);
+  }
+}
+
+export class BikeFinderSdk extends HeyApiClient {
+  public static readonly __registry: HeyApiRegistry<BikeFinderSdk> =
+    new HeyApiRegistry<BikeFinderSdk>();
+
+  constructor(args?: { client?: Client; key?: string }) {
+    super(args);
+    BikeFinderSdk.__registry.set(this, args?.key);
+  }
+
+  public getHealth<ThrowOnError extends boolean = false>(
+    options?: Options<GetHealthData, ThrowOnError>,
+  ): RequestResult<GetHealthResponses, unknown, ThrowOnError> {
+    return (options?.client ?? this.client).get<
+      GetHealthResponses,
+      unknown,
+      ThrowOnError
+    >({
+      responseValidator: async (data) =>
+        await zGetHealthResponse.parseAsync(data),
+      url: "/health",
+      ...options,
+    });
+  }
+
+  /**
+   * List the caller's active trackers
+   */
+  public listTrackers<ThrowOnError extends boolean = false>(
+    options?: Options<ListTrackersData, ThrowOnError>,
+  ): RequestResult<ListTrackersResponses, ListTrackersErrors, ThrowOnError> {
+    return (options?.client ?? this.client).get<
+      ListTrackersResponses,
+      ListTrackersErrors,
+      ThrowOnError
+    >({
+      responseValidator: async (data) =>
+        await zListTrackersResponse.parseAsync(data),
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/v1/trackers",
+      ...options,
+    });
+  }
+
+  /**
+   * Subscribe to the caller's tracker page
+   *
+   * SSE. snapshot events contain a TrackerPage JSON payload; keepalive events contain null. Reconnect with a fresh bearer token after closure. Each connection lasts at most 15 minutes and never beyond token expiry. Every reconnect starts with a complete snapshot; Last-Event-ID is not used.
+   */
+  public subscribeTrackers<ThrowOnError extends boolean = false>(
+    options?: Options<
+      SubscribeTrackersData,
+      ThrowOnError,
+      SubscribeTrackersResponse
+    >,
+  ): Promise<ServerSentEventsResult<SubscribeTrackersResponses>> {
+    return (options?.client ?? this.client).sse.get<
+      SubscribeTrackersResponses,
+      SubscribeTrackersErrors,
+      ThrowOnError
+    >({
+      responseValidator: async (data) =>
+        await zSubscribeTrackersResponse.parseAsync(data),
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/v1/trackers/stream",
+      ...options,
+    });
+  }
+
+  /**
+   * Get an actively shared tracker
+   */
+  public getTracker<ThrowOnError extends boolean = false>(
+    options: Options<GetTrackerData, ThrowOnError>,
+  ): RequestResult<GetTrackerResponses, GetTrackerErrors, ThrowOnError> {
+    return (options.client ?? this.client).get<
+      GetTrackerResponses,
+      GetTrackerErrors,
+      ThrowOnError
+    >({
+      responseValidator: async (data) =>
+        await zGetTrackerResponse.parseAsync(data),
+      security: [{ scheme: "bearer", type: "http" }],
+      url: "/v1/trackers/{trackerId}",
+      ...options,
+    });
+  }
+}

package/src/generated/types.gen.ts

@@ -0,0 +1,179 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type ClientOptions = {
+  baseUrl: `${string}://${string}` | (string & {});
+};
+
+export type HealthStatus = {
+  status: string;
+};
+
+export type ProblemDetails = {
+  type?: null | string;
+  title?: null | string;
+  status?: null | number;
+  detail?: null | string;
+  instance?: null | string;
+};
+
+export type TrackerPage = {
+  items: Array<TrackerSummary>;
+  nextCursor: null | string;
+};
+
+export type TrackerSummary = {
+  id: string;
+  nickname: null | string;
+  requestedMode: null | TrackingMode;
+  subscriptionActive: null | boolean;
+};
+
+export type TrackingMode = "standard" | "security" | "tracking";
+
+export type GetHealthData = {
+  body?: never;
+  path?: never;
+  query?: never;
+  url: "/health";
+};
+
+export type GetHealthResponses = {
+  /**
+   * OK
+   */
+  200: HealthStatus;
+};
+
+export type GetHealthResponse = GetHealthResponses[keyof GetHealthResponses];
+
+export type ListTrackersData = {
+  body?: never;
+  path?: never;
+  query?: {
+    cursor?: string;
+    /**
+     * Page size, from 1 to 100. Defaults to 50.
+     */
+    limit?: number;
+  };
+  url: "/v1/trackers";
+};
+
+export type ListTrackersErrors = {
+  /**
+   * Bad Request
+   */
+  400: ProblemDetails;
+  /**
+   * Unauthorized
+   */
+  401: ProblemDetails;
+  /**
+   * Internal Server Error
+   */
+  500: ProblemDetails;
+  /**
+   * Service Unavailable
+   */
+  503: ProblemDetails;
+};
+
+export type ListTrackersError = ListTrackersErrors[keyof ListTrackersErrors];
+
+export type ListTrackersResponses = {
+  /**
+   * OK
+   */
+  200: TrackerPage;
+};
+
+export type ListTrackersResponse =
+  ListTrackersResponses[keyof ListTrackersResponses];
+
+export type SubscribeTrackersData = {
+  body?: never;
+  path?: never;
+  query?: {
+    cursor?: string;
+    /**
+     * Page size, from 1 to 100. Defaults to 50.
+     */
+    limit?: number;
+  };
+  url: "/v1/trackers/stream";
+};
+
+export type SubscribeTrackersErrors = {
+  /**
+   * Bad Request
+   */
+  400: ProblemDetails;
+  /**
+   * Unauthorized
+   */
+  401: ProblemDetails;
+  /**
+   * Internal Server Error
+   */
+  500: ProblemDetails;
+  /**
+   * Service Unavailable
+   */
+  503: ProblemDetails;
+};
+
+export type SubscribeTrackersError =
+  SubscribeTrackersErrors[keyof SubscribeTrackersErrors];
+
+export type SubscribeTrackersResponses = {
+  /**
+   * OK
+   */
+  200: TrackerPage | null;
+};
+
+export type SubscribeTrackersResponse =
+  SubscribeTrackersResponses[keyof SubscribeTrackersResponses];
+
+export type GetTrackerData = {
+  body?: never;
+  path: {
+    trackerId: string;
+  };
+  query?: never;
+  url: "/v1/trackers/{trackerId}";
+};
+
+export type GetTrackerErrors = {
+  /**
+   * Bad Request
+   */
+  400: ProblemDetails;
+  /**
+   * Unauthorized
+   */
+  401: ProblemDetails;
+  /**
+   * Not Found
+   */
+  404: ProblemDetails;
+  /**
+   * Internal Server Error
+   */
+  500: ProblemDetails;
+  /**
+   * Service Unavailable
+   */
+  503: ProblemDetails;
+};
+
+export type GetTrackerError = GetTrackerErrors[keyof GetTrackerErrors];
+
+export type GetTrackerResponses = {
+  /**
+   * OK
+   */
+  200: TrackerSummary;
+};
+
+export type GetTrackerResponse = GetTrackerResponses[keyof GetTrackerResponses];

package/src/generated/zod.gen.ts

@@ -0,0 +1,85 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import * as z from "zod";
+
+export const zHealthStatus = z.object({
+  status: z.string(),
+});
+
+export const zProblemDetails = z.object({
+  type: z.string().nullish(),
+  title: z.string().nullish(),
+  status: z
+    .int()
+    .min(-2147483648, {
+      error: "Invalid value: Expected int32 to be >= -2147483648",
+    })
+    .max(2147483647, {
+      error: "Invalid value: Expected int32 to be <= 2147483647",
+    })
+    .nullish(),
+  detail: z.string().nullish(),
+  instance: z.string().nullish(),
+});
+
+export const zTrackingMode = z.enum(["standard", "security", "tracking"]);
+
+export const zTrackerSummary = z.object({
+  id: z.string(),
+  nickname: z.string().nullable(),
+  requestedMode: zTrackingMode.nullable(),
+  subscriptionActive: z.boolean().nullable(),
+});
+
+export const zTrackerPage = z.object({
+  items: z.array(zTrackerSummary),
+  nextCursor: z.string().nullable(),
+});
+
+/**
+ * OK
+ */
+export const zGetHealthResponse = zHealthStatus;
+
+export const zListTrackersQuery = z.object({
+  cursor: z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_-]+$/)
+    .optional(),
+  limit: z.int().gte(1).lte(100).optional().default(50),
+});
+
+/**
+ * OK
+ */
+export const zListTrackersResponse = zTrackerPage;
+
+export const zSubscribeTrackersQuery = z.object({
+  cursor: z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_-]+$/)
+    .optional(),
+  limit: z.int().gte(1).lte(100).optional().default(50),
+});
+
+/**
+ * OK
+ */
+export const zSubscribeTrackersResponse = zTrackerPage.nullable();
+
+export const zGetTrackerPath = z.object({
+  trackerId: z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_-]+$/),
+});
+
+/**
+ * OK
+ */
+export const zGetTrackerResponse = zTrackerSummary;

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,22 @@
+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 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,
+    watchTrackers: (query: TrackerPageQuery = {}) =>
+      watchTrackers(requests, query),
+  };
+}
+
+export type BikeFinderClient = ReturnType<typeof createBikeFinderClient>;