@omnistreamai/data-core/skills/initialize-sync-system/SKILL.md

---
name: initialize-sync-system
description: >
  Set up the data-sync system. Use createSyncManager, createStore, initStore in
  the correct order. Configure IndexedDBAdapter version for schema changes.
  Pass localAdapter and remoteAdapter to SyncManager. Call setService on
  WebDAVAdapter before any operations.
type: core
library: '@omnistreamai/data-sync'
library_version: '0.4.1'
sources:
  - 'omni-stream-ai/data-sync:packages/core/src/sync-manager.ts'
  - 'omni-stream-ai/data-sync:packages/core/src/store.ts'
  - 'omni-stream-ai/data-sync:packages/adapter-indexeddb/src/indexeddb-adapter.ts'
---

# Initialize the Data Sync System

Set up SyncManager, create stores with proper configuration, and initialize everything in the correct order.

## Setup

```typescript
import { createSyncManager } from '@omnistreamai/data-core';
import { IndexedDBAdapter } from '@omnistreamai/data-adapter-indexeddb';
import { WebDAVAdapter } from '@omnistreamai/data-adapter-webdav';

// 1. Create SyncManager with adapters
const syncManager = createSyncManager({
  localAdapter: new IndexedDBAdapter({ dbName: 'my-app', version: 1 }),
  remoteAdapter: new WebDAVAdapter(),
});

// 2. Create all stores BEFORE initStore()
const userStore = syncManager.createStore<User>('users', {
  idKey: 'id',
  indexes: ['email'],
});

const todoStore = syncManager.createStore<Todo>('todos', {
  idKey: 'id',
  indexes: ['status'],
  maxLocalEntries: 1000,
});

// 3. Configure remote adapter AFTER createStore but BEFORE operations
const webdavAdapter = syncManager.getRemoteAdapter() as WebDAVAdapter;
webdavAdapter.setService({
  endpoint: 'https://webdav.example.com/data',
  basePath: 'app-data',
  authentication: {
    authType: 'bearer',
    bearer: 'your-token',
  },
});

// 4. Initialize all stores at once — AFTER all createStore() calls
await syncManager.initStore();
```

## Core Patterns

### Configure IndexedDB with version for schema changes

```typescript
// Initial setup
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 });

// Later, when adding a new store 'settings', bump the version
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 2 });
syncManager.createStore('settings', { idKey: 'id' });
// Version 2 triggers onupgradeneeded, creating the 'settings' object store
```

### Configure WebDAV adapter with authentication

```typescript
const adapter = new WebDAVAdapter();
adapter.setService({
  endpoint: 'https://webdav.example.com/dav',
  basePath: 'my-app',
  authentication: {
    authType: 'bearer', // or 'basic' or 'token'
    bearer: 'token-value',
  },
});
```

### Set up stores with local-only mode

```typescript
// Local-only: no remote sync
const syncManager = createSyncManager({
  localAdapter: new IndexedDBAdapter({ dbName: 'offline-app', version: 1 }),
  remoteAdapter: null,
});

const store = syncManager.createStore('cache', { idKey: 'id' });
```

## Common Mistakes

### CRITICAL Call initStore before createStore

Wrong:

```typescript
const syncManager = createSyncManager({ localAdapter, remoteAdapter });
await syncManager.initStore(); // ❌ No stores registered yet
const store = syncManager.createStore('todos', { idKey: 'id' });
// store is NOT initialized
```

Correct:

```typescript
const syncManager = createSyncManager({ localAdapter, remoteAdapter });
const store = syncManager.createStore('todos', { idKey: 'id' });
// ... create all stores ...
await syncManager.initStore(); // ✅ All stores initialized
```

`initStore()` iterates over stores already registered via `createStore()`. Calling it before creates an empty store list.

Source: maintainer interview

---

### CRITICAL Forget to bump IndexedDB version when adding stores

Wrong:

```typescript
// Day 1
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 });
syncManager.createStore('users', { idKey: 'id' });

// Day 30 — adding a new store
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 }); // ❌ Same version
syncManager.createStore('settings', { idKey: 'id' }); // 'settings' store never created!
```

Correct:

```typescript
// Day 30 — bump version to trigger IndexedDB upgrade
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 2 }); // ✅
syncManager.createStore('settings', { idKey: 'id' });
// Version 2 upgrade runs onupgradeneeded, creating 'settings' object store
```

IndexedDB schema is versioned. New object stores are only created during a version upgrade. The `onupgradeneeded` event only fires when `version` increases.

Source: maintainer interview

---

### HIGH Call WebDAV adapter methods before setService

Wrong:

```typescript
const adapter = new WebDAVAdapter();
await adapter.add('todos', { id: '1', title: 'Test' }); // ❌ Throws: Service not configured
```

Correct:

```typescript
const adapter = new WebDAVAdapter();
adapter.setService({ endpoint: 'https://webdav.example.com/data' });
await adapter.add('todos', { id: '1', title: 'Test' }); // ✅
```

`buildUrl()` requires `service` to be configured. Always call `setService()` before any read/write operation.

Source: packages/adapter-webdav/src/webdav-adapter.ts:68-76