@syncular/client 0.0.3-3 → 0.0.3-7

package/src/engine/types.ts

@@ -15,6 +15,7 @@ import type { Kysely } from 'kysely';
 import type { ClientTableRegistry } from '../handlers/registry';
 import type { SyncClientPlugin } from '../plugins/types';
 import type { SyncClientDb } from '../schema';
+import type { SubscriptionState } from '../subscription-state';
 
 /**
  * Connection state for the sync engine
@@ -30,6 +31,8 @@ export type SyncConnectionState =
  */
 export type SyncTransportMode = 'polling' | 'realtime';
 
+export type TransportFallbackReason = 'network' | 'auth' | 'server' | 'manual';
+
 /**
  * Sync engine state
  */
@@ -54,18 +57,78 @@ export interface SyncEngineState {
   isRetrying: boolean;
 }
 
+export interface TransportHealth {
+  mode: 'realtime' | 'polling' | 'disconnected';
+  connected: boolean;
+  lastSuccessfulPollAt: number | null;
+  lastRealtimeMessageAt: number | null;
+  fallbackReason: TransportFallbackReason | null;
+}
+
+export type SubscriptionProgressPhase =
+  | 'idle'
+  | 'bootstrapping'
+  | 'catching_up'
+  | 'live'
+  | 'error';
+
+export type SyncChannelPhase =
+  | 'idle'
+  | 'starting'
+  | 'bootstrapping'
+  | 'catching_up'
+  | 'live'
+  | 'error';
+
+export interface SubscriptionProgress {
+  stateId: string;
+  id: string;
+  table?: string;
+  phase: SubscriptionProgressPhase;
+  progressPercent: number;
+  rowsProcessed?: number;
+  rowsTotal?: number;
+  tablesProcessed?: number;
+  tablesTotal?: number;
+  startedAt?: number;
+  completedAt?: number;
+  lastErrorCode?: string;
+  lastErrorMessage?: string;
+}
+
+export interface SyncProgress {
+  channelPhase: SyncChannelPhase;
+  progressPercent: number;
+  subscriptions: SubscriptionProgress[];
+}
+
 /**
  * Sync error with context
  */
 export interface SyncError {
   /** Error code */
-  code: 'NETWORK_ERROR' | 'SYNC_ERROR' | 'CONFLICT' | 'UNKNOWN';
+  code:
+    | 'NETWORK_ERROR'
+    | 'AUTH_FAILED'
+    | 'SNAPSHOT_CHUNK_NOT_FOUND'
+    | 'MIGRATION_FAILED'
+    | 'CONFLICT'
+    | 'SYNC_ERROR'
+    | 'UNKNOWN';
   /** Error message */
   message: string;
   /** Original error if available */
   cause?: Error;
   /** Timestamp when error occurred */
   timestamp: number;
+  /** Whether retrying this error is expected to succeed */
+  retryable: boolean;
+  /** HTTP status code when available */
+  httpStatus?: number;
+  /** Related subscription id when available */
+  subscriptionId?: string;
+  /** Related state id when available */
+  stateId?: string;
 }
 
 /**
@@ -75,7 +138,11 @@ export type SyncEventType =
   | 'state:change'
   | 'sync:start'
   | 'sync:complete'
+  | 'sync:live'
   | 'sync:error'
+  | 'bootstrap:start'
+  | 'bootstrap:progress'
+  | 'bootstrap:complete'
   | 'connection:change'
   | 'outbox:change'
   | 'data:change'
@@ -103,7 +170,25 @@ export interface SyncEventPayloads {
     pullRounds: number;
     pullResponse: SyncPullResponse;
   };
+  'sync:live': { timestamp: number };
   'sync:error': SyncError;
+  'bootstrap:start': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+  };
+  'bootstrap:progress': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+    progress: SubscriptionProgress;
+  };
+  'bootstrap:complete': {
+    timestamp: number;
+    stateId: string;
+    subscriptionId: string;
+    durationMs: number;
+  };
   'connection:change': {
     previous: SyncConnectionState;
     current: SyncConnectionState;
@@ -268,3 +353,67 @@ export interface OutboxStats {
   acked: number;
   total: number;
 }
+
+export type SyncResetScope = 'state' | 'subscription' | 'all';
+
+export interface SyncResetOptions {
+  scope: SyncResetScope;
+  stateId?: string;
+  subscriptionIds?: string[];
+  clearOutbox?: boolean;
+  clearConflicts?: boolean;
+  clearSyncedTables?: boolean;
+}
+
+export interface SyncResetResult {
+  deletedSubscriptionStates: number;
+  deletedOutboxCommits: number;
+  deletedConflicts: number;
+  clearedTables: string[];
+}
+
+export interface SyncRepairOptions {
+  mode: 'rebootstrap-missing-chunks';
+  stateId?: string;
+  subscriptionIds?: string[];
+  clearOutbox?: boolean;
+  clearConflicts?: boolean;
+}
+
+export interface SyncAwaitPhaseOptions {
+  timeoutMs?: number;
+}
+
+export interface SyncAwaitBootstrapOptions {
+  timeoutMs?: number;
+  stateId?: string;
+  subscriptionId?: string;
+}
+
+export interface SyncDiagnostics {
+  timestamp: number;
+  state: SyncEngineState;
+  transport: TransportHealth;
+  progress: SyncProgress;
+  outbox: OutboxStats;
+  conflictCount: number;
+  subscriptions: SubscriptionState[];
+}
+
+export interface SyncInspectorEvent {
+  id: number;
+  event: SyncEventType;
+  timestamp: number;
+  payload: Record<string, unknown>;
+}
+
+export interface SyncInspectorOptions {
+  eventLimit?: number;
+}
+
+export interface SyncInspectorSnapshot {
+  version: 1;
+  generatedAt: number;
+  diagnostics: Record<string, unknown>;
+  recentEvents: SyncInspectorEvent[];
+}

package/src/index.ts

@@ -21,5 +21,6 @@ export * from './pull-engine';
 export * from './push-engine';
 export * from './query';
 export * from './schema';
+export * from './subscription-state';
 export * from './sync-loop';
 export * from './utils/id';

package/src/subscription-state.ts

@@ -0,0 +1,259 @@
+/**
+ * @syncular/client - Subscription state helpers
+ *
+ * Stable accessors for sync subscription metadata.
+ */
+
+import type { ScopeValues, SyncBootstrapState } from '@syncular/core';
+import { isRecord } from '@syncular/core';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type {
+  SubscriptionStatus,
+  SyncClientDb,
+  SyncSubscriptionStateTable,
+} from './schema';
+
+export const DEFAULT_SYNC_STATE_ID = 'default';
+
+export interface SubscriptionState {
+  stateId: string;
+  subscriptionId: string;
+  table: string;
+  scopes: ScopeValues;
+  params: Record<string, unknown>;
+  cursor: number;
+  bootstrapState: SyncBootstrapState | null;
+  status: SubscriptionStatus;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface ListSubscriptionStatesOptions {
+  stateId?: string;
+  table?: string;
+  status?: SubscriptionStatus;
+}
+
+export interface GetSubscriptionStateOptions {
+  stateId?: string;
+  subscriptionId: string;
+}
+
+export interface UpsertSubscriptionStateInput {
+  stateId?: string;
+  subscriptionId: string;
+  table: string;
+  scopes: ScopeValues;
+  params?: Record<string, unknown>;
+  cursor: number;
+  bootstrapState?: SyncBootstrapState | null;
+  status?: SubscriptionStatus;
+  nowMs?: number;
+}
+
+function isScopeValues(value: unknown): value is ScopeValues {
+  if (!isRecord(value)) return false;
+
+  for (const entry of Object.values(value)) {
+    if (typeof entry === 'string') continue;
+    if (Array.isArray(entry) && entry.every((v) => typeof v === 'string')) {
+      continue;
+    }
+    return false;
+  }
+
+  return true;
+}
+
+export function parseBootstrapState(
+  value: string | object | null | undefined
+): SyncBootstrapState | null {
+  if (!value) return null;
+
+  try {
+    const parsed: unknown =
+      typeof value === 'string' ? JSON.parse(value) : value;
+
+    if (!isRecord(parsed)) return null;
+    if (typeof parsed.asOfCommitSeq !== 'number') return null;
+    if (!Array.isArray(parsed.tables)) return null;
+    if (!parsed.tables.every((table) => typeof table === 'string')) return null;
+    if (typeof parsed.tableIndex !== 'number') return null;
+    if (parsed.rowCursor !== null && typeof parsed.rowCursor !== 'string') {
+      return null;
+    }
+
+    return {
+      asOfCommitSeq: parsed.asOfCommitSeq,
+      tables: parsed.tables,
+      tableIndex: parsed.tableIndex,
+      rowCursor: parsed.rowCursor,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseScopes(value: string): ScopeValues {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return isScopeValues(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function parseParams(value: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function mapSubscriptionState(
+  row: SyncSubscriptionStateTable
+): SubscriptionState {
+  return {
+    stateId: row.state_id,
+    subscriptionId: row.subscription_id,
+    table: row.table,
+    scopes: parseScopes(row.scopes_json),
+    params: parseParams(row.params_json),
+    cursor: row.cursor,
+    bootstrapState: parseBootstrapState(row.bootstrap_state_json),
+    status: row.status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export async function listSubscriptionStates<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  options: ListSubscriptionStatesOptions = {}
+): Promise<SubscriptionState[]> {
+  const filters: Array<ReturnType<typeof sql>> = [];
+  if (options.stateId) {
+    filters.push(sql`${sql.ref('state_id')} = ${sql.val(options.stateId)}`);
+  }
+  if (options.table) {
+    filters.push(sql`${sql.ref('table')} = ${sql.val(options.table)}`);
+  }
+  if (options.status) {
+    filters.push(sql`${sql.ref('status')} = ${sql.val(options.status)}`);
+  }
+
+  const whereClause =
+    filters.length > 0 ? sql`where ${sql.join(filters, sql` and `)}` : sql``;
+
+  const rows = await sql<SyncSubscriptionStateTable>`
+    select
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    from ${sql.table('sync_subscription_state')}
+    ${whereClause}
+    order by ${sql.ref('state_id')} asc, ${sql.ref('subscription_id')} asc
+  `.execute(db);
+
+  return rows.rows.map((row) => mapSubscriptionState(row));
+}
+
+export async function getSubscriptionState<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  options: GetSubscriptionStateOptions
+): Promise<SubscriptionState | null> {
+  const stateId = options.stateId ?? DEFAULT_SYNC_STATE_ID;
+
+  const rows = await sql<SyncSubscriptionStateTable>`
+    select
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    from ${sql.table('sync_subscription_state')}
+    where
+      ${sql.ref('state_id')} = ${sql.val(stateId)}
+      and ${sql.ref('subscription_id')} = ${sql.val(options.subscriptionId)}
+    limit 1
+  `.execute(db);
+
+  const row = rows.rows[0];
+  return row ? mapSubscriptionState(row) : null;
+}
+
+export async function upsertSubscriptionState<DB extends SyncClientDb>(
+  db: Kysely<DB>,
+  input: UpsertSubscriptionStateInput
+): Promise<SubscriptionState> {
+  const now = input.nowMs ?? Date.now();
+  const stateId = input.stateId ?? DEFAULT_SYNC_STATE_ID;
+
+  const bootstrapStateJson =
+    input.bootstrapState === null || input.bootstrapState === undefined
+      ? null
+      : JSON.stringify(input.bootstrapState);
+
+  await sql`
+    insert into ${sql.table('sync_subscription_state')} (
+      ${sql.ref('state_id')},
+      ${sql.ref('subscription_id')},
+      ${sql.ref('table')},
+      ${sql.ref('scopes_json')},
+      ${sql.ref('params_json')},
+      ${sql.ref('cursor')},
+      ${sql.ref('bootstrap_state_json')},
+      ${sql.ref('status')},
+      ${sql.ref('created_at')},
+      ${sql.ref('updated_at')}
+    ) values (
+      ${sql.val(stateId)},
+      ${sql.val(input.subscriptionId)},
+      ${sql.val(input.table)},
+      ${sql.val(JSON.stringify(input.scopes ?? {}))},
+      ${sql.val(JSON.stringify(input.params ?? {}))},
+      ${sql.val(input.cursor)},
+      ${sql.val(bootstrapStateJson)},
+      ${sql.val(input.status ?? 'active')},
+      ${sql.val(now)},
+      ${sql.val(now)}
+    )
+    on conflict (${sql.join([sql.ref('state_id'), sql.ref('subscription_id')])})
+    do update set
+      ${sql.ref('table')} = ${sql.val(input.table)},
+      ${sql.ref('scopes_json')} = ${sql.val(JSON.stringify(input.scopes ?? {}))},
+      ${sql.ref('params_json')} = ${sql.val(JSON.stringify(input.params ?? {}))},
+      ${sql.ref('cursor')} = ${sql.val(input.cursor)},
+      ${sql.ref('bootstrap_state_json')} = ${sql.val(bootstrapStateJson)},
+      ${sql.ref('status')} = ${sql.val(input.status ?? 'active')},
+      ${sql.ref('updated_at')} = ${sql.val(now)}
+  `.execute(db);
+
+  const next = await getSubscriptionState(db, {
+    stateId,
+    subscriptionId: input.subscriptionId,
+  });
+
+  if (!next) {
+    throw new Error(
+      `[subscription-state] Failed to load upserted state for "${input.subscriptionId}"`
+    );
+  }
+
+  return next;
+}

package/src/utils/id.ts

@@ -18,3 +18,38 @@ export function randomUUID(): string {
     return v.toString(16);
   });
 }
+
+/**
+ * Build a stable state id from meaningful segments.
+ * Empty/undefined segments are ignored.
+ */
+export function buildStateId(
+  ...segments: Array<string | null | undefined>
+): string {
+  const normalized = segments
+    .map((segment) => segment?.trim())
+    .filter((segment): segment is string => !!segment && segment.length > 0);
+
+  if (normalized.length === 0) return 'default';
+  return normalized.join(':');
+}
+
+/**
+ * Create a deterministic fingerprint string for scope values.
+ */
+export function createScopeFingerprint(
+  scopes: Record<string, string | string[]>
+): string {
+  const entries = Object.entries(scopes)
+    .map(([key, value]) => {
+      const encodedValues = (Array.isArray(value) ? [...value] : [value])
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0)
+        .sort();
+
+      return `${key}:${encodedValues.join('|')}`;
+    })
+    .sort();
+
+  return entries.join(';');
+}