Starfish TypeScript Client

@drakkar.software/starfish-client is a TypeScript SDK for document-level cloud sync. It provides end-to-end encryption, automatic conflict resolution, and reactive state management bindings — all with zero production dependencies beyond the protocol package.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Your Application                        │
│                                                             │
│  ┌─────────────────┐     ┌──────────────────────────────┐  │
│  │  State Binding   │     │  SyncManager                 │  │
│  │  (Zustand or     │────▶│  Encryption, conflict retry, │  │
│  │   Legend State)   │     │  signing, checkpoint tracking│  │
│  └─────────────────┘     └──────────┬───────────────────┘  │
│                                      │                      │
│                           ┌──────────▼───────────────────┐  │
│                           │  StarfishClient              │  │
│                           │  Low-level HTTP pull / push  │  │
│                           └──────────┬───────────────────┘  │
└──────────────────────────────────────┼──────────────────────┘
                                       │ HTTPS
                                       ▼
                              ┌──────────────────┐
                              │  Starfish Server  │
                              └──────────────────┘

Three layers, use what you need:

Layer	Class / Function	Purpose
Low-level	StarfishClient	Direct HTTP pull/push with auth
Mid-level	SyncManager	Encryption, conflict resolution, retry
High-level	createStarfishStore / createStarfishObservable	Reactive state with persistence

Reading Paths

Quick start (sync data in 10 minutes)

1. Getting Started — install, first pull/push
2. Zustand Binding or Legend State Binding — reactive state
3. Offline & Connectivity — handle network changes

Full deep dive

1. Getting Started — install, first pull/push
2. StarfishClient — low-level HTTP client API
3. SyncManager — high-level sync orchestrator
4. Encryption — "none" vs "delegated" E2E encryption
5. Conflict Resolution — strategies and retry mechanics
6. Zustand Binding and/or Legend State Binding
7. Offline & Connectivity — offline-first, sync status, polling
8. Integration Patterns — optimistic UI, lifecycle hooks, validation, compression
9. Platform Setup — React Native, custom crypto
10. Identity & Key Derivation — passphrase → root key pair → device keys
11. Schema Versioning — evolving document formats
12. Testing Strategies — mocking, unit tests, integration tests
13. Multi-Tab Sync — BroadcastChannel, cross-tab state
14. Error Classification & Retry — retry, circuit breaker, auth refresh
15. Logging & Observability — structured logging, sync metrics
16. Data Export / Import — GDPR export, account migration
17. Multi-Document Architecture — partitioning, URL design, dynamic docs
18. Collection Patterns — RBAC and access-control patterns
19. Namespaces — tenant-style namespace routing
20. Binary Collections — opaque-blob collections
21. Multi-Recipient Delegated Encryption — keyring, epochs, recipient management
22. Pairing — bootstrap, in-person QR, and server-relay invite flows
23. Capability Certificates — cap-cert schema, validation, minting
24. Identity Models — ed25519-only wire; secp256k1 root bootstrap via signature derivation
25. SSE Subscribe Transport — real-time change notifications via Server-Sent Events
26. Anonymous Append — unauthenticated append-only writes
27. KV Pull Cache — persist pull results in any async KV store
28. WAL Client Adapters — WAL-backed sync adapters
29. Bulk & Multi-Content Sync — batchPull, bundles, projection, fan-out push patterns

Migrating from 2.x? Start with the runbook: Migration: v2 to v3.

Page Index

Page	Description
Getting Started	Install and first sync in under 2 minutes
StarfishClient	Low-level HTTP transport, cap providers, custom fetch
SyncManager	Encryption, conflict retry, signing, incremental sync
Encryption	Two modes: "none" and "delegated" (E2E AES-256-GCM via keyring)
Zustand Binding	Reactive store with persistence, devtools, Immer
Legend State Binding	Fine-grained observable state
Conflict Resolution	Default merge, ID + timestamp strategies, soft-delete-aware merge
Offline & Connectivity	Dirty tracking, flush-on-reconnect, sync status, polling
Integration Patterns	Debounced push, soft delete, local history, optimistic UI, validation, compression
Platform Setup	React Native, Node.js, custom crypto/fetch
Identity & Key Derivation	Root identity Argon2id → HKDF derivation, per-device generated keys
Schema Versioning	Document migrations across app versions
Testing Strategies	Mocking, conflict resolver tests, integration tests
Multi-Tab Sync	BroadcastChannel, cross-tab state consistency
Error Classification & Retry	Retry, circuit breaker, auth token refresh
Logging & Observability	Structured logging, performance metrics
Data Export / Import	GDPR export, account migration, encrypted export
Multi-Document Architecture	Partitioning, URL design, dynamic documents
Collection Patterns	Server-side RBAC and access-control patterns
Namespaces	Tenant-style namespace routing
Binary Collections	Opaque-blob collections
Multi-Recipient Delegated Encryption	Keyring schema, wrap/unwrap, epoch rotation
Pairing	Bootstrap, in-person QR, and server-relay invite flows
Capability Certificates	Cap-cert schema, validation, mint helpers
Identity Models	Ed25519-only wire; secp256k1 root bootstrap via signature derivation
SSE Subscribe Transport	Real-time change notifications, auto-reconnect, backoff
Anonymous Append	Unauthenticated append-only writes
KV Pull Cache	Persist pull results in MMKV, AsyncStorage, localStorage, etc.
WAL Client Adapters	WAL-backed sync adapters
Bulk & Multi-Content Sync	batchPull, bundles, projection, fan-out push patterns, freshness

For migration guidance, see docs/migration/v2-to-v3.md.