@qm-hub/sync-client-types 0.2.1

package/src/client.ts

@@ -0,0 +1,350 @@
+/**
+ * QM Sync Client for Browser/Node.js
+ *
+ * TypeScript implementation of qm-sync-client using fetch for HTTP transport.
+ * Matches the API of the Rust SyncClient from qm-sync-client crate.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AuthHeaders,
+  AuthResponse,
+  Checkpoint,
+  DeltaRequest,
+  DeltaResponse,
+  HttpRequest,
+  HttpResponse,
+  PullRequest,
+  PullResponse,
+  PushRecord,
+  PushRequest,
+  PushResponse,
+  RefreshResponse,
+  SyncClientConfig,
+  SyncRecord,
+} from "./index";
+
+/**
+ * HTTP client function type.
+ * Implement this to provide custom HTTP transport.
+ */
+export type HttpClientFn = (request: HttpRequest) => Promise<HttpResponse>;
+
+/**
+ * Default fetch-based HTTP client implementation.
+ */
+export async function fetchHttpClient(
+  request: HttpRequest
+): Promise<HttpResponse> {
+  const headers: HeadersInit = {
+    "Content-Type": request.headers.contentType,
+    "X-API-Key": request.headers.apiKey,
+    "X-App-Id": request.headers.appId,
+  };
+
+  if (request.headers.authorization) {
+    headers["Authorization"] = request.headers.authorization;
+  }
+
+  try {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers,
+      body: request.body,
+    });
+
+    return {
+      status: response.status,
+      body: await response.text(),
+    };
+  } catch (error) {
+    throw new Error(
+      `HTTP request failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Sync client for communicating with qm-hub-server.
+ * TypeScript implementation matching the Rust SyncClient API.
+ */
+export class QmSyncClient {
+  private _accessToken: string | null = null;
+  private _refreshToken: string | null = null;
+  private _userId: string | null = null;
+
+  constructor(
+    public readonly config: SyncClientConfig,
+    private readonly http: HttpClientFn = fetchHttpClient
+  ) {}
+
+  // =========================================================================
+  // Authentication
+  // =========================================================================
+
+  /**
+   * Register a new user.
+   */
+  async register(
+    username: string,
+    email: string,
+    password: string
+  ): Promise<AuthResponse> {
+    const url = `${this.config.serverUrl}/api/v1/auth/register`;
+    const headers = this.buildHeaders();
+    const body = JSON.stringify({ username, email, password });
+
+    const response = await this.http({ method: "POST", url, headers, body });
+
+    if (!this.isSuccess(response)) {
+      throw new Error(
+        `Registration failed: ${response.status} - ${response.body}`
+      );
+    }
+
+    const auth: AuthResponse = JSON.parse(response.body);
+    this.storeTokens(auth);
+    console.log("Registered user:", auth.userId);
+    return auth;
+  }
+
+  /**
+   * Login with email and password.
+   */
+  async login(email: string, password: string): Promise<AuthResponse> {
+    const url = `${this.config.serverUrl}/api/v1/auth/login`;
+    const headers = this.buildHeaders();
+    const body = JSON.stringify({ email, password });
+
+    const response = await this.http({ method: "POST", url, headers, body });
+
+    if (!this.isSuccess(response)) {
+      throw new Error(`Login failed: ${response.status} - ${response.body}`);
+    }
+
+    const auth: AuthResponse = JSON.parse(response.body);
+    this.storeTokens(auth);
+    console.log("Logged in user:", auth.userId);
+    return auth;
+  }
+
+  /**
+   * Refresh the access token.
+   * Note: Named `refreshToken` to match Rust API (singular).
+   */
+  async refreshToken(): Promise<void> {
+    if (!this._refreshToken) {
+      throw new Error("Not authenticated - please login first");
+    }
+
+    const url = `${this.config.serverUrl}/api/v1/auth/refresh`;
+    const headers = this.buildHeaders();
+    const body = JSON.stringify({ refreshToken: this._refreshToken });
+
+    const response = await this.http({ method: "POST", url, headers, body });
+
+    if (!this.isSuccess(response)) {
+      throw new Error(
+        `Token refresh failed: ${response.status} - ${response.body}`
+      );
+    }
+
+    const refresh: RefreshResponse = JSON.parse(response.body);
+    this._accessToken = refresh.accessToken;
+    this._refreshToken = refresh.refreshToken;
+    console.log("Token refreshed successfully");
+  }
+
+  /**
+   * Logout and clear tokens.
+   */
+  logout(): void {
+    this._accessToken = null;
+    this._refreshToken = null;
+    this._userId = null;
+    console.log("Logged out");
+  }
+
+  /**
+   * Check if the client is authenticated.
+   */
+  isAuthenticated(): boolean {
+    return this._accessToken !== null;
+  }
+
+  /**
+   * Set tokens directly (for restoring from storage).
+   */
+  setTokens(accessToken: string, refreshToken: string, userId?: string): void {
+    this._accessToken = accessToken;
+    this._refreshToken = refreshToken;
+    this._userId = userId ?? null;
+  }
+
+  /**
+   * Get current tokens (for persisting to storage).
+   */
+  getTokens(): { accessToken: string | null; refreshToken: string | null } {
+    return { accessToken: this._accessToken, refreshToken: this._refreshToken };
+  }
+
+  /**
+   * Get current user ID.
+   */
+  getUserId(): string | null {
+    return this._userId;
+  }
+
+  // =========================================================================
+  // Sync Operations
+  // =========================================================================
+
+  /**
+   * Push local changes to the server.
+   */
+  async push(records: SyncRecord[]): Promise<PushResponse> {
+    const request: PushRequest = {
+      records: records.map(this.syncToPushRecord),
+      clientTimestamp: new Date().toISOString(),
+    };
+
+    const url = `${this.config.serverUrl}/api/v1/sync/${this.config.appId}/push`;
+    return this.authenticatedPost<PushRequest, PushResponse>(url, request);
+  }
+
+  /**
+   * Pull changes from the server.
+   */
+  async pull(
+    checkpoint?: Checkpoint,
+    batchSize?: number
+  ): Promise<PullResponse> {
+    const request: PullRequest = {
+      checkpoint,
+      batchSize: batchSize ?? this.config.defaultBatchSize,
+    };
+
+    const url = `${this.config.serverUrl}/api/v1/sync/${this.config.appId}/pull`;
+    return this.authenticatedPost<PullRequest, PullResponse>(url, request);
+  }
+
+  /**
+   * Perform a delta sync (push + pull in one request).
+   */
+  async delta(
+    records: SyncRecord[],
+    checkpoint?: Checkpoint
+  ): Promise<DeltaResponse> {
+    const request: DeltaRequest = {
+      push:
+        records.length > 0
+          ? {
+              records: records.map(this.syncToPushRecord),
+              clientTimestamp: new Date().toISOString(),
+            }
+          : undefined,
+      pull: {
+        checkpoint,
+        batchSize: this.config.defaultBatchSize,
+      },
+    };
+
+    const url = `${this.config.serverUrl}/api/v1/sync/${this.config.appId}/delta`;
+    return this.authenticatedPost<DeltaRequest, DeltaResponse>(url, request);
+  }
+
+  // =========================================================================
+  // Internal Helpers
+  // =========================================================================
+
+  private buildHeaders(accessToken?: string): AuthHeaders {
+    const headers: AuthHeaders = {
+      apiKey: this.config.apiKey,
+      appId: this.config.appId,
+      contentType: "application/json",
+    };
+
+    if (accessToken) {
+      headers.authorization = `Bearer ${accessToken}`;
+    }
+
+    return headers;
+  }
+
+  private storeTokens(auth: AuthResponse): void {
+    this._accessToken = auth.accessToken;
+    this._refreshToken = auth.refreshToken;
+    this._userId = auth.userId;
+  }
+
+  private isSuccess(response: HttpResponse): boolean {
+    return response.status >= 200 && response.status < 300;
+  }
+
+  private isUnauthorized(response: HttpResponse): boolean {
+    return response.status === 401;
+  }
+
+  private async authenticatedPost<T, R>(url: string, body: T): Promise<R> {
+    if (!this._accessToken) {
+      throw new Error("Not authenticated - please login first");
+    }
+
+    // First attempt
+    const headers = this.buildHeaders(this._accessToken);
+    const bodyJson = JSON.stringify(body);
+
+    let response = await this.http({
+      method: "POST",
+      url,
+      headers,
+      body: bodyJson,
+    });
+
+    // If unauthorized, try to refresh and retry
+    if (this.isUnauthorized(response)) {
+      console.warn("Access token expired, attempting refresh");
+      await this.refreshToken();
+
+      const newHeaders = this.buildHeaders(this._accessToken!);
+      response = await this.http({
+        method: "POST",
+        url,
+        headers: newHeaders,
+        body: bodyJson,
+      });
+
+      if (!this.isSuccess(response)) {
+        console.error(
+          "Request failed after token refresh:",
+          response.status,
+          response.body
+        );
+        throw new Error(
+          `Request failed: ${response.status} - ${response.body}`
+        );
+      }
+
+      return JSON.parse(response.body);
+    }
+
+    if (!this.isSuccess(response)) {
+      console.error("Request failed:", response.status, response.body);
+      throw new Error(`Request failed: ${response.status} - ${response.body}`);
+    }
+
+    return JSON.parse(response.body);
+  }
+
+  private syncToPushRecord(record: SyncRecord): PushRecord {
+    return {
+      tableName: record.tableName,
+      rowId: record.rowId,
+      data: record.data,
+      version: record.version,
+      deleted: record.deleted,
+      assumedServerVersion: undefined, // Match Rust: always None for now
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+/**
+ * @qm-hub/sync-client-types
+ *
+ * TypeScript types for qm-sync-client - generated from Rust with Specta.
+ * These types match the Rust structs with #[derive(specta::Type)].
+ * 
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// HTTP Abstraction (from qm-sync-client/http.rs)
+// =============================================================================
+
+/** Structured auth headers for sync API requests */
+export interface AuthHeaders {
+    /** Bearer token: "Authorization: Bearer {token}" */
+    authorization?: string;
+    /** API key header: "X-API-Key" */
+    apiKey: string;
+    /** App ID header: "X-App-Id" */
+    appId: string;
+    /** Content type (always "application/json") */
+    contentType: string;
+}
+
+/** HTTP request to be executed */
+export interface HttpRequest {
+    method: string;
+    url: string;
+    headers: AuthHeaders;
+    body?: string;
+}
+
+/** HTTP response from the request */
+export interface HttpResponse {
+    status: number;
+    body: string;
+}
+
+// =============================================================================
+// Checkpoint (from qm-sync-engine/checkpoint.rs)
+// =============================================================================
+
+/** Composite checkpoint for deterministic ordering */
+export interface Checkpoint {
+    /** ISO 8601 timestamp of the last synced document */
+    updatedAt: string;
+    /** ID of the last synced document (tie-breaker) */
+    id: string;
+}
+
+// =============================================================================
+// Sync Records (from qm-sync-engine/document.rs)
+// =============================================================================
+
+/** A sync record representing a document to be synchronized */
+export interface SyncRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+}
+
+/** A sync record with additional server metadata */
+export interface SyncRecordWithMeta extends SyncRecord {
+    syncedAt: string;
+    userId: string;
+}
+
+/** Documents bundled with their checkpoint */
+export interface DocumentsWithCheckpoint<T, C> {
+    documents: T[];
+    checkpoint: C;
+}
+
+// =============================================================================
+// Push Sync (from qm-sync-engine/protocol.rs)
+// =============================================================================
+
+export interface PushRequest {
+    records: PushRecord[];
+    clientTimestamp?: string;
+}
+
+export interface PushRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+    assumedServerVersion?: number;
+}
+
+export interface PushResponse {
+    synced: number;
+    conflicts: ConflictInfo[];
+    serverTimestamp: string;
+}
+
+// =============================================================================
+// Pull Sync
+// =============================================================================
+
+export interface PullRequest {
+    checkpoint?: Checkpoint;
+    batchSize: number;
+    tables?: string[];
+}
+
+export interface PullResponse {
+    records: PullRecord[];
+    checkpoint: Checkpoint;
+    serverTimestamp: string;
+    hasMore: boolean;
+}
+
+export interface PullRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    syncedAt: string;
+    deleted: boolean;
+}
+
+// =============================================================================
+// Delta Sync (Push + Pull combined)
+// =============================================================================
+
+export interface DeltaRequest {
+    push?: PushRequest;
+    pull?: PullRequest;
+}
+
+export interface DeltaResponse {
+    push?: PushResponse;
+    pull?: PullResponse;
+}
+
+// =============================================================================
+// Conflict Info (from qm-sync-engine/conflict.rs)
+// =============================================================================
+
+export interface ConflictInfo {
+    tableName: string;
+    rowId: string;
+    clientVersion: number;
+    serverVersion: number;
+    serverState?: Record<string, unknown>;
+}
+
+// =============================================================================
+// Auth Types (from qm-sync-client/client.rs)
+// =============================================================================
+
+export interface AuthResponse {
+    userId: string;
+    accessToken: string;
+    refreshToken: string;
+    apps: string[];
+    isAdmin: boolean;
+}
+
+export interface RefreshResponse {
+    accessToken: string;
+    refreshToken: string;
+}
+
+// =============================================================================
+// Client Config
+// =============================================================================
+
+export interface SyncClientConfig {
+    serverUrl: string;
+    appId: string;
+    apiKey: string;
+    defaultBatchSize: number;
+    timeoutMs: number;
+}
+
+// =============================================================================
+// Sync Result (from qm-sync-engine/handler.rs)
+// =============================================================================
+
+export interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    success: boolean;
+    error?: string;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/** Create default AuthHeaders */
+export function createAuthHeaders(apiKey: string, appId: string): AuthHeaders {
+    return {
+        apiKey,
+        appId,
+        contentType: 'application/json',
+    };
+}
+
+/** Create AuthHeaders with bearer token */
+export function withBearer(headers: AuthHeaders, token: string): AuthHeaders {
+    return {
+        ...headers,
+        authorization: `Bearer ${token}`,
+    };
+}
+
+/** Create default SyncClientConfig */
+export function createSyncClientConfig(
+    serverUrl: string,
+    appId: string,
+    apiKey: string,
+    options?: Partial<Pick<SyncClientConfig, 'defaultBatchSize' | 'timeoutMs'>>
+): SyncClientConfig {
+    return {
+        serverUrl,
+        appId,
+        apiKey,
+        defaultBatchSize: options?.defaultBatchSize ?? 100,
+        timeoutMs: options?.timeoutMs ?? 30000,
+    };
+}
+
+/** Create an initial checkpoint */
+export function initialCheckpoint(): Checkpoint {
+    return {
+        updatedAt: '1970-01-01T00:00:00Z',
+        id: '',
+    };
+}
+
+// =============================================================================
+// Client Implementation
+// =============================================================================
+
+export { QmSyncClient, fetchHttpClient, type HttpClientFn } from './client';