@syncular/transport-http 0.0.6-185 → 0.0.6-201

package/src/index.ts

@@ -1,384 +1,64 @@
 /**
  * @syncular/transport-http - HTTP transport for Sync
  *
- * Provides typed API clients using openapi-fetch with auto-generated types.
+ * Provides:
+ * - a lightweight fetch-based SyncTransport for client runtime use
+ * - a separately exported typed API client for advanced/console use
  */
 
 import type {
-  ScopeValues,
-  SyncAuthErrorContext,
-  SyncAuthLifecycle,
-  SyncAuthOperation,
   SyncCombinedRequest,
   SyncCombinedResponse,
   SyncTransport,
-  SyncTransportBlobs,
   SyncTransportOptions,
 } from '@syncular/core';
-import { resolveUrlFromBase, SyncTransportError } from '@syncular/core';
-import createClient from 'openapi-fetch';
-import type { operations, paths } from './generated/api';
+import { SyncTransportError } from '@syncular/core';
+import type { SyncClient } from './api-client';
+import {
+  applySnapshotScopesHeader,
+  bytesToReadableStream,
+  type ClientOptions,
+  executeWithAuthRetry,
+  getErrorMessage,
+  resolveSnapshotChunkRequestUrl,
+  type SyncTransportPath,
+  unwrap,
+} from './shared';
+import {
+  createTransportApiClient,
+  createTransportAuthRetryResolver,
+  HTTP_TRANSPORT_SOURCE,
+  type HttpTransportSource,
+} from './transport-client';
+
+export { type SyncClient, type ClientOptions, type SyncTransportPath, unwrap };
 
 export type {
   SyncAuthErrorContext,
   SyncAuthLifecycle,
   SyncAuthOperation,
   SyncTransport,
-  SyncTransportBlobs,
   SyncTransportOptions,
 } from '@syncular/core';
+export { createApiClient } from './api-client';
+export type { operations } from './generated/api';
 
-/**
- * Error thrown when unwrapping an API response fails.
- */
-class ApiResponseError extends Error {
-  constructor(
-    message: string,
-    public readonly error?: unknown
-  ) {
-    super(message);
-    this.name = 'ApiResponseError';
-  }
-}
-
-/**
- * Helper to unwrap openapi-fetch responses.
- * Throws ApiResponseError if the response contains an error or no data.
- */
-function getErrorMessage(error: unknown): string {
-  if (error && typeof error === 'object' && 'error' in error) {
-    const inner = (error as { error: unknown }).error;
-    if (typeof inner === 'string') return inner;
-  }
-  if (error && typeof error === 'object' && 'message' in error) {
-    const msg = (error as { message: unknown }).message;
-    if (typeof msg === 'string') return msg;
-  }
-  return 'Request failed';
-}
-
-export async function unwrap<T>(
-  promise: Promise<{ data?: T; error?: unknown }>
-): Promise<T> {
-  const { data, error } = await promise;
-  if (error || !data) {
-    throw new ApiResponseError(getErrorMessage(error), error);
-  }
-  return data;
-}
-
-type ApiResult<T> = {
-  data?: T;
-  error?: unknown;
-  response: Response;
-};
-
-type ResolveAuthRetry = (
-  context: SyncAuthErrorContext,
-  options?: SyncTransportOptions
-) => Promise<boolean>;
-
-async function executeWithAuthRetry<T>(
-  execute: (signal?: AbortSignal) => Promise<ApiResult<T>>,
-  options: SyncTransportOptions | undefined,
-  operation: SyncAuthOperation,
-  resolveAuthRetry: ResolveAuthRetry
-): Promise<ApiResult<T>> {
-  const first = await execute(options?.signal);
-  if (first.response.status !== 401 && first.response.status !== 403) {
-    return first;
-  }
-  const shouldRetry = await resolveAuthRetry(
-    { operation, status: first.response.status },
-    options
-  );
-  if (!shouldRetry) {
-    return first;
-  }
-
-  return execute(options?.signal);
-}
-
-// Re-export useful types from the generated API
-export type SyncClient = ReturnType<typeof createClient<paths>>;
-export type SyncTransportPath = 'direct' | 'relay';
-export type { operations };
-
-export interface ClientOptions {
-  /** Base URL for the API (e.g., 'https://api.example.com') */
-  baseUrl: string;
-  /** Function to get headers for requests (e.g., for auth tokens) */
-  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-  /** Shared auth lifecycle for all transport operations. */
-  authLifecycle?: SyncAuthLifecycle;
-  /** Custom fetch implementation (defaults to globalThis.fetch) */
-  fetch?: typeof globalThis.fetch;
-  /**
-   * Transport path telemetry sent to the server.
-   * Defaults to 'direct'.
-   */
-  transportPath?: SyncTransportPath;
-}
-
-const SNAPSHOT_SCOPES_HEADER = 'x-syncular-snapshot-scopes';
-
-function resolveRequestUrl(baseUrl: string, path: string): string {
-  return resolveUrlFromBase(
-    baseUrl,
-    path,
-    typeof location === 'undefined' ? undefined : location.origin
-  );
-}
-
-function bytesToReadableStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
-}
-
-function encodeSnapshotScopes(
-  scopeValues: ScopeValues | undefined
-): string | null {
-  if (!scopeValues) return null;
-  if (Object.keys(scopeValues).length === 0) return null;
-  return JSON.stringify(scopeValues);
-}
-
-function applySnapshotScopesHeader(
-  headers: Headers,
-  scopeValues: ScopeValues | undefined
-): void {
-  const encodedScopes = encodeSnapshotScopes(scopeValues);
-  if (!encodedScopes) return;
-  headers.set(SNAPSHOT_SCOPES_HEADER, encodedScopes);
-}
-
-function resolveSnapshotChunkRequestUrl(
-  baseUrl: string,
-  chunkId: string,
-  scopeValues: ScopeValues | undefined
-): string {
-  const requestUrl = new URL(
-    resolveRequestUrl(
-      baseUrl,
-      `/sync/snapshot-chunks/${encodeURIComponent(chunkId)}`
-    )
-  );
-  const encodedScopes = encodeSnapshotScopes(scopeValues);
-  if (encodedScopes) {
-    requestUrl.searchParams.set('scopes', encodedScopes);
-  }
-  return requestUrl.toString();
-}
-
-/**
- * Create a typed API client for the full Syncular API.
- *
- * Returns an openapi-fetch client with full type safety for all endpoints.
- *
- * @example
- * ```typescript
- * const client = createApiClient({
- *   baseUrl: 'https://api.example.com',
- *   getHeaders: () => ({ Authorization: `Bearer ${token}` }),
- * });
- *
- * // Sync endpoints
- * const { data } = await client.POST('/sync', { body: { clientId: 'c1', pull: { ... } } });
- *
- * // Console endpoints
- * const { data: stats } = await client.GET('/console/stats');
- * const { data: commits } = await client.GET('/console/commits', {
- *   params: { query: { limit: 50 } }
- * });
- * ```
- */
-export function createApiClient(options: ClientOptions): SyncClient {
-  const client = createClient<paths>({
-    baseUrl: options.baseUrl,
-    ...(options.fetch && { fetch: options.fetch }),
-  });
-
-  const getHeaders = options.getHeaders;
-  const transportPath = options.transportPath ?? 'direct';
-
-  client.use({
-    async onRequest({ request }) {
-      if (getHeaders) {
-        const headers = await getHeaders();
-        for (const [key, value] of Object.entries(headers)) {
-          request.headers.set(key, value);
-        }
-      }
-
-      if (!request.headers.has('x-syncular-transport-path')) {
-        request.headers.set('x-syncular-transport-path', transportPath);
-      }
-
-      return request;
-    },
-  });
-
-  return client;
-}
-
-/**
- * Create a SyncTransport from an API client or options.
- *
- * The transport includes both sync and blob operations via the typed OpenAPI client.
- *
- * @example
- * ```typescript
- * // From options (convenience)
- * const transport = createHttpTransport({
- *   baseUrl: 'https://api.example.com',
- *   getHeaders: () => ({ Authorization: `Bearer ${token}` }),
- * });
- *
- * // Or from an existing client
- * const client = createApiClient({ baseUrl: 'https://api.example.com' });
- * const transport = createHttpTransport(client);
- *
- * // Use with Client
- * const syncClient = new Client({ transport, ... });
- * ```
- */
 export function createHttpTransport(
   clientOrOptions: SyncClient | ClientOptions
 ): SyncTransport {
-  const client =
-    'GET' in clientOrOptions
-      ? clientOrOptions
-      : createApiClient(clientOrOptions);
+  const client = createTransportApiClient(clientOrOptions);
+  const resolveAuthRetry = createTransportAuthRetryResolver(clientOrOptions);
   const transportOptions =
-    'GET' in clientOrOptions ? undefined : clientOrOptions;
-  const defaultAuthLifecycle = transportOptions?.authLifecycle;
-
-  let refreshInFlight: Promise<boolean> | null = null;
-
-  const runRefreshSingleFlight = async (
-    lifecycle: SyncAuthLifecycle,
-    context: SyncAuthErrorContext
-  ): Promise<boolean> => {
-    if (!lifecycle.refreshToken) return false;
-
-    if (!refreshInFlight) {
-      refreshInFlight = Promise.resolve(lifecycle.refreshToken(context))
-        .then((result) => Boolean(result))
-        .finally(() => {
-          refreshInFlight = null;
-        });
-    }
-
-    return refreshInFlight;
-  };
-
-  const resolveAuthRetry: ResolveAuthRetry = async (context, options) => {
-    if (options?.onAuthError) {
-      return Boolean(await options.onAuthError());
-    }
-
-    const lifecycle = options?.authLifecycle ?? defaultAuthLifecycle;
-    if (!lifecycle) return false;
-
-    await lifecycle.onAuthExpired?.(context);
-
-    const refreshResult = await runRefreshSingleFlight(lifecycle, context);
-    if (lifecycle.retryWithFreshToken) {
-      return Boolean(
-        await lifecycle.retryWithFreshToken({ ...context, refreshResult })
-      );
-    }
-    return refreshResult;
-  };
-
-  // Create blob operations using the typed OpenAPI client
-  const blobs: SyncTransportBlobs = {
-    async initiateUpload(args) {
-      const { data, error, response } = await executeWithAuthRetry(
-        (signal) =>
-          client.POST('/sync/blobs/upload', {
-            body: args,
-            ...(signal ? { signal } : {}),
-          }),
-        undefined,
-        'blobInitiateUpload',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        throw new SyncTransportError(
-          `Blob upload init failed: ${getErrorMessage(error) || response.statusText}`,
-          response.status
-        );
-      }
-
-      return data;
-    },
+    'baseUrl' in clientOrOptions ? clientOrOptions : undefined;
 
-    async completeUpload(hash) {
-      const { data, error } = await executeWithAuthRetry(
-        (signal) =>
-          client.POST('/sync/blobs/{hash}/complete', {
-            params: { path: { hash } },
-            ...(signal ? { signal } : {}),
-          }),
-        undefined,
-        'blobCompleteUpload',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        return {
-          ok: false,
-          error: getErrorMessage(error) || 'Complete upload failed',
-        };
-      }
-
-      return data;
-    },
-
-    async getDownloadUrl(hash) {
-      const { data, error, response } = await executeWithAuthRetry(
-        (signal) =>
-          client.GET('/sync/blobs/{hash}/url', {
-            params: { path: { hash } },
-            ...(signal ? { signal } : {}),
-          }),
-        undefined,
-        'blobGetDownloadUrl',
-        resolveAuthRetry
-      );
-
-      if (error || !data) {
-        throw new SyncTransportError(
-          `Get download URL failed: ${getErrorMessage(error) || response.statusText}`,
-          response.status
-        );
-      }
-
-      return {
-        url: data.url,
-        expiresAt: data.expiresAt,
-      };
-    },
-  };
-
-  return {
+  const transport: SyncTransport = {
     async sync(
       request: SyncCombinedRequest,
-      transportOptions?: SyncTransportOptions
+      transportRequestOptions?: SyncTransportOptions
     ): Promise<SyncCombinedResponse> {
       const { data, error, response } = await executeWithAuthRetry(
-        (signal) =>
-          client.POST('/sync', {
-            body: request,
-            ...(signal ? { signal } : {}),
-          }),
-        transportOptions,
+        (signal) => client.sync(request, signal),
+        transportRequestOptions,
         'sync',
         resolveAuthRetry
       );
@@ -400,21 +80,14 @@ export function createHttpTransport(
       },
       options?: SyncTransportOptions
     ): Promise<Uint8Array> {
-      const encodedScopes = encodeSnapshotScopes(request.scopeValues);
-
       if (!transportOptions) {
         const { data, error, response } = await executeWithAuthRetry(
           (signal) =>
-            client.GET('/sync/snapshot-chunks/{chunkId}', {
-              params: { path: { chunkId: request.chunkId } },
-              parseAs: 'blob',
-              headers: encodedScopes
-                ? {
-                    [SNAPSHOT_SCOPES_HEADER]: encodedScopes,
-                  }
-                : undefined,
-              ...(signal ? { signal } : {}),
-            }),
+            client.getSnapshotChunk(
+              request.chunkId,
+              request.scopeValues,
+              signal
+            ),
           options,
           'snapshotChunk',
           resolveAuthRetry
@@ -574,8 +247,14 @@ export function createHttpTransport(
 
       return response.body as ReadableStream<Uint8Array>;
     },
-
-    // Include blob operations
-    blobs,
   };
+
+  Object.defineProperty(transport, HTTP_TRANSPORT_SOURCE, {
+    configurable: false,
+    enumerable: false,
+    value: clientOrOptions as HttpTransportSource,
+    writable: false,
+  });
+
+  return transport;
 }

package/src/shared.ts

@@ -0,0 +1,146 @@
+import type {
+  ScopeValues,
+  SyncAuthErrorContext,
+  SyncAuthLifecycle,
+  SyncAuthOperation,
+  SyncTransportOptions,
+} from '@syncular/core';
+import { resolveUrlFromBase } from '@syncular/core';
+
+export type SyncTransportPath = 'direct' | 'relay';
+
+export interface ClientOptions {
+  /** Base URL for the API (e.g., 'https://api.example.com') */
+  baseUrl: string;
+  /** Function to get headers for requests (e.g., for auth tokens) */
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** Shared auth lifecycle for all transport operations. */
+  authLifecycle?: SyncAuthLifecycle;
+  /** Custom fetch implementation (defaults to globalThis.fetch) */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Transport path telemetry sent to the server.
+   * Defaults to 'direct'.
+   */
+  transportPath?: SyncTransportPath;
+}
+
+export type ApiResult<T> = {
+  data?: T;
+  error?: unknown;
+  response: Response;
+};
+
+export type ResolveAuthRetry = (
+  context: SyncAuthErrorContext,
+  options?: SyncTransportOptions
+) => Promise<boolean>;
+
+class ApiResponseError extends Error {
+  constructor(
+    message: string,
+    public readonly error?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiResponseError';
+  }
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error && typeof error === 'object' && 'error' in error) {
+    const inner = (error as { error: unknown }).error;
+    if (typeof inner === 'string') return inner;
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    const msg = (error as { message: unknown }).message;
+    if (typeof msg === 'string') return msg;
+  }
+  return 'Request failed';
+}
+
+export async function unwrap<T>(
+  promise: Promise<{ data?: T; error?: unknown }>
+): Promise<T> {
+  const { data, error } = await promise;
+  if (error || !data) {
+    throw new ApiResponseError(getErrorMessage(error), error);
+  }
+  return data;
+}
+
+export async function executeWithAuthRetry<T>(
+  execute: (signal?: AbortSignal) => Promise<ApiResult<T>>,
+  options: SyncTransportOptions | undefined,
+  operation: SyncAuthOperation,
+  resolveAuthRetry: ResolveAuthRetry
+): Promise<ApiResult<T>> {
+  const first = await execute(options?.signal);
+  if (first.response.status !== 401 && first.response.status !== 403) {
+    return first;
+  }
+  const shouldRetry = await resolveAuthRetry(
+    { operation, status: first.response.status },
+    options
+  );
+  if (!shouldRetry) {
+    return first;
+  }
+
+  return execute(options?.signal);
+}
+
+export const SNAPSHOT_SCOPES_HEADER = 'x-syncular-snapshot-scopes';
+
+export function resolveRequestUrl(baseUrl: string, path: string): string {
+  return resolveUrlFromBase(
+    baseUrl,
+    path,
+    typeof location === 'undefined' ? undefined : location.origin
+  );
+}
+
+export function bytesToReadableStream(
+  bytes: Uint8Array
+): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+export function encodeSnapshotScopes(
+  scopeValues: ScopeValues | undefined
+): string | null {
+  if (!scopeValues) return null;
+  if (Object.keys(scopeValues).length === 0) return null;
+  return JSON.stringify(scopeValues);
+}
+
+export function applySnapshotScopesHeader(
+  headers: Headers,
+  scopeValues: ScopeValues | undefined
+): void {
+  const encodedScopes = encodeSnapshotScopes(scopeValues);
+  if (!encodedScopes) return;
+  headers.set(SNAPSHOT_SCOPES_HEADER, encodedScopes);
+}
+
+export function resolveSnapshotChunkRequestUrl(
+  baseUrl: string,
+  chunkId: string,
+  scopeValues: ScopeValues | undefined
+): string {
+  const requestUrl = new URL(
+    resolveRequestUrl(
+      baseUrl,
+      `/sync/snapshot-chunks/${encodeURIComponent(chunkId)}`
+    )
+  );
+  const encodedScopes = encodeSnapshotScopes(scopeValues);
+  if (encodedScopes) {
+    requestUrl.searchParams.set('scopes', encodedScopes);
+  }
+  return requestUrl.toString();
+}