@qm-hub/sync-client-types 0.2.1

package/README.md

@@ -0,0 +1,83 @@
+# @qm-hub/sync-client-types
+
+TypeScript types for qm-sync-client - generated from Rust with Specta.
+
+## Installation
+
+```bash
+npm install @qm-hub/sync-client-types
+# or for local development
+npm link
+```
+
+## Usage
+
+```typescript
+import {
+  AuthHeaders,
+  HttpRequest,
+  HttpResponse,
+  Checkpoint,
+  SyncRecord,
+  PushRequest,
+  PullResponse,
+  DeltaRequest,
+  DeltaResponse,
+  createSyncClientConfig,
+  createAuthHeaders,
+  withBearer,
+} from '@qm-hub/sync-client-types';
+
+// Create config
+const config = createSyncClientConfig(
+  'https://sync.example.com',
+  'my-app-id',
+  'my-api-key'
+);
+
+// Create headers
+const headers = withBearer(
+  createAuthHeaders(config.apiKey, config.appId),
+  accessToken
+);
+
+// Build request
+const request: HttpRequest = {
+  method: 'POST',
+  url: `${config.serverUrl}/api/v1/sync/${config.appId}/delta`,
+  headers,
+  body: JSON.stringify(deltaRequest),
+};
+```
+
+## Regenerating Types
+
+Types are generated from Rust using Specta. To regenerate:
+
+```bash
+cd ../qm-sync-client
+GENERATE_TS_TYPES=1 cargo build
+```
+
+Then update `src/index.ts` with the generated types.
+
+## Local Development
+
+To use in a local project without publishing:
+
+```bash
+# In this directory
+npm install
+npm run build
+npm link
+
+# In your project
+npm link @qm-hub/sync-client-types
+```
+
+## Public package on NPM
+```bash
+npm publish --access public
+
+npm view @qm-hub/sync-client-types 
+```

package/dist/index.d.mts

@@ -0,0 +1,227 @@
+/**
+ * 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
+ */
+
+/**
+ * HTTP client function type.
+ * Implement this to provide custom HTTP transport.
+ */
+type HttpClientFn = (request: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Default fetch-based HTTP client implementation.
+ */
+declare function fetchHttpClient(request: HttpRequest): Promise<HttpResponse>;
+/**
+ * Sync client for communicating with qm-hub-server.
+ * TypeScript implementation matching the Rust SyncClient API.
+ */
+declare class QmSyncClient {
+    readonly config: SyncClientConfig;
+    private readonly http;
+    private _accessToken;
+    private _refreshToken;
+    private _userId;
+    constructor(config: SyncClientConfig, http?: HttpClientFn);
+    /**
+     * Register a new user.
+     */
+    register(username: string, email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Login with email and password.
+     */
+    login(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Refresh the access token.
+     * Note: Named `refreshToken` to match Rust API (singular).
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Logout and clear tokens.
+     */
+    logout(): void;
+    /**
+     * Check if the client is authenticated.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Set tokens directly (for restoring from storage).
+     */
+    setTokens(accessToken: string, refreshToken: string, userId?: string): void;
+    /**
+     * Get current tokens (for persisting to storage).
+     */
+    getTokens(): {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    /**
+     * Get current user ID.
+     */
+    getUserId(): string | null;
+    /**
+     * Push local changes to the server.
+     */
+    push(records: SyncRecord[]): Promise<PushResponse>;
+    /**
+     * Pull changes from the server.
+     */
+    pull(checkpoint?: Checkpoint, batchSize?: number): Promise<PullResponse>;
+    /**
+     * Perform a delta sync (push + pull in one request).
+     */
+    delta(records: SyncRecord[], checkpoint?: Checkpoint): Promise<DeltaResponse>;
+    private buildHeaders;
+    private storeTokens;
+    private isSuccess;
+    private isUnauthorized;
+    private authenticatedPost;
+    private syncToPushRecord;
+}
+
+/**
+ * @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
+ */
+/** Structured auth headers for sync API requests */
+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 */
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: AuthHeaders;
+    body?: string;
+}
+/** HTTP response from the request */
+interface HttpResponse {
+    status: number;
+    body: string;
+}
+/** Composite checkpoint for deterministic ordering */
+interface Checkpoint {
+    /** ISO 8601 timestamp of the last synced document */
+    updatedAt: string;
+    /** ID of the last synced document (tie-breaker) */
+    id: string;
+}
+/** A sync record representing a document to be synchronized */
+interface SyncRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+}
+/** A sync record with additional server metadata */
+interface SyncRecordWithMeta extends SyncRecord {
+    syncedAt: string;
+    userId: string;
+}
+/** Documents bundled with their checkpoint */
+interface DocumentsWithCheckpoint<T, C> {
+    documents: T[];
+    checkpoint: C;
+}
+interface PushRequest {
+    records: PushRecord[];
+    clientTimestamp?: string;
+}
+interface PushRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+    assumedServerVersion?: number;
+}
+interface PushResponse {
+    synced: number;
+    conflicts: ConflictInfo[];
+    serverTimestamp: string;
+}
+interface PullRequest {
+    checkpoint?: Checkpoint;
+    batchSize: number;
+    tables?: string[];
+}
+interface PullResponse {
+    records: PullRecord[];
+    checkpoint: Checkpoint;
+    serverTimestamp: string;
+    hasMore: boolean;
+}
+interface PullRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    syncedAt: string;
+    deleted: boolean;
+}
+interface DeltaRequest {
+    push?: PushRequest;
+    pull?: PullRequest;
+}
+interface DeltaResponse {
+    push?: PushResponse;
+    pull?: PullResponse;
+}
+interface ConflictInfo {
+    tableName: string;
+    rowId: string;
+    clientVersion: number;
+    serverVersion: number;
+    serverState?: Record<string, unknown>;
+}
+interface AuthResponse {
+    userId: string;
+    accessToken: string;
+    refreshToken: string;
+    apps: string[];
+    isAdmin: boolean;
+}
+interface RefreshResponse {
+    accessToken: string;
+    refreshToken: string;
+}
+interface SyncClientConfig {
+    serverUrl: string;
+    appId: string;
+    apiKey: string;
+    defaultBatchSize: number;
+    timeoutMs: number;
+}
+interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    success: boolean;
+    error?: string;
+}
+/** Create default AuthHeaders */
+declare function createAuthHeaders(apiKey: string, appId: string): AuthHeaders;
+/** Create AuthHeaders with bearer token */
+declare function withBearer(headers: AuthHeaders, token: string): AuthHeaders;
+/** Create default SyncClientConfig */
+declare function createSyncClientConfig(serverUrl: string, appId: string, apiKey: string, options?: Partial<Pick<SyncClientConfig, 'defaultBatchSize' | 'timeoutMs'>>): SyncClientConfig;
+/** Create an initial checkpoint */
+declare function initialCheckpoint(): Checkpoint;
+
+export { type AuthHeaders, type AuthResponse, type Checkpoint, type ConflictInfo, type DeltaRequest, type DeltaResponse, type DocumentsWithCheckpoint, type HttpClientFn, type HttpRequest, type HttpResponse, type PullRecord, type PullRequest, type PullResponse, type PushRecord, type PushRequest, type PushResponse, QmSyncClient, type RefreshResponse, type SyncClientConfig, type SyncRecord, type SyncRecordWithMeta, type SyncResult, createAuthHeaders, createSyncClientConfig, fetchHttpClient, initialCheckpoint, withBearer };

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 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
+ */
+
+/**
+ * HTTP client function type.
+ * Implement this to provide custom HTTP transport.
+ */
+type HttpClientFn = (request: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Default fetch-based HTTP client implementation.
+ */
+declare function fetchHttpClient(request: HttpRequest): Promise<HttpResponse>;
+/**
+ * Sync client for communicating with qm-hub-server.
+ * TypeScript implementation matching the Rust SyncClient API.
+ */
+declare class QmSyncClient {
+    readonly config: SyncClientConfig;
+    private readonly http;
+    private _accessToken;
+    private _refreshToken;
+    private _userId;
+    constructor(config: SyncClientConfig, http?: HttpClientFn);
+    /**
+     * Register a new user.
+     */
+    register(username: string, email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Login with email and password.
+     */
+    login(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Refresh the access token.
+     * Note: Named `refreshToken` to match Rust API (singular).
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Logout and clear tokens.
+     */
+    logout(): void;
+    /**
+     * Check if the client is authenticated.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Set tokens directly (for restoring from storage).
+     */
+    setTokens(accessToken: string, refreshToken: string, userId?: string): void;
+    /**
+     * Get current tokens (for persisting to storage).
+     */
+    getTokens(): {
+        accessToken: string | null;
+        refreshToken: string | null;
+    };
+    /**
+     * Get current user ID.
+     */
+    getUserId(): string | null;
+    /**
+     * Push local changes to the server.
+     */
+    push(records: SyncRecord[]): Promise<PushResponse>;
+    /**
+     * Pull changes from the server.
+     */
+    pull(checkpoint?: Checkpoint, batchSize?: number): Promise<PullResponse>;
+    /**
+     * Perform a delta sync (push + pull in one request).
+     */
+    delta(records: SyncRecord[], checkpoint?: Checkpoint): Promise<DeltaResponse>;
+    private buildHeaders;
+    private storeTokens;
+    private isSuccess;
+    private isUnauthorized;
+    private authenticatedPost;
+    private syncToPushRecord;
+}
+
+/**
+ * @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
+ */
+/** Structured auth headers for sync API requests */
+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 */
+interface HttpRequest {
+    method: string;
+    url: string;
+    headers: AuthHeaders;
+    body?: string;
+}
+/** HTTP response from the request */
+interface HttpResponse {
+    status: number;
+    body: string;
+}
+/** Composite checkpoint for deterministic ordering */
+interface Checkpoint {
+    /** ISO 8601 timestamp of the last synced document */
+    updatedAt: string;
+    /** ID of the last synced document (tie-breaker) */
+    id: string;
+}
+/** A sync record representing a document to be synchronized */
+interface SyncRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+}
+/** A sync record with additional server metadata */
+interface SyncRecordWithMeta extends SyncRecord {
+    syncedAt: string;
+    userId: string;
+}
+/** Documents bundled with their checkpoint */
+interface DocumentsWithCheckpoint<T, C> {
+    documents: T[];
+    checkpoint: C;
+}
+interface PushRequest {
+    records: PushRecord[];
+    clientTimestamp?: string;
+}
+interface PushRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    deleted: boolean;
+    assumedServerVersion?: number;
+}
+interface PushResponse {
+    synced: number;
+    conflicts: ConflictInfo[];
+    serverTimestamp: string;
+}
+interface PullRequest {
+    checkpoint?: Checkpoint;
+    batchSize: number;
+    tables?: string[];
+}
+interface PullResponse {
+    records: PullRecord[];
+    checkpoint: Checkpoint;
+    serverTimestamp: string;
+    hasMore: boolean;
+}
+interface PullRecord {
+    tableName: string;
+    rowId: string;
+    data: Record<string, unknown>;
+    version: number;
+    syncedAt: string;
+    deleted: boolean;
+}
+interface DeltaRequest {
+    push?: PushRequest;
+    pull?: PullRequest;
+}
+interface DeltaResponse {
+    push?: PushResponse;
+    pull?: PullResponse;
+}
+interface ConflictInfo {
+    tableName: string;
+    rowId: string;
+    clientVersion: number;
+    serverVersion: number;
+    serverState?: Record<string, unknown>;
+}
+interface AuthResponse {
+    userId: string;
+    accessToken: string;
+    refreshToken: string;
+    apps: string[];
+    isAdmin: boolean;
+}
+interface RefreshResponse {
+    accessToken: string;
+    refreshToken: string;
+}
+interface SyncClientConfig {
+    serverUrl: string;
+    appId: string;
+    apiKey: string;
+    defaultBatchSize: number;
+    timeoutMs: number;
+}
+interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    success: boolean;
+    error?: string;
+}
+/** Create default AuthHeaders */
+declare function createAuthHeaders(apiKey: string, appId: string): AuthHeaders;
+/** Create AuthHeaders with bearer token */
+declare function withBearer(headers: AuthHeaders, token: string): AuthHeaders;
+/** Create default SyncClientConfig */
+declare function createSyncClientConfig(serverUrl: string, appId: string, apiKey: string, options?: Partial<Pick<SyncClientConfig, 'defaultBatchSize' | 'timeoutMs'>>): SyncClientConfig;
+/** Create an initial checkpoint */
+declare function initialCheckpoint(): Checkpoint;
+
+export { type AuthHeaders, type AuthResponse, type Checkpoint, type ConflictInfo, type DeltaRequest, type DeltaResponse, type DocumentsWithCheckpoint, type HttpClientFn, type HttpRequest, type HttpResponse, type PullRecord, type PullRequest, type PullResponse, type PushRecord, type PushRequest, type PushResponse, QmSyncClient, type RefreshResponse, type SyncClientConfig, type SyncRecord, type SyncRecordWithMeta, type SyncResult, createAuthHeaders, createSyncClientConfig, fetchHttpClient, initialCheckpoint, withBearer };