npm package: @steerprotocol/sync-engine
Description: Background sync engine for Steer Protocol vault and pool analytics.
Latest version: 0.1.2

# Steer Sync Engine

This package publishes `lib/sync/manager.ts` and the internal modules it depends on so the background sync pipeline can be embedded in downstream services.

## Contents
- `index.ts` – barrel that re-exports the manager and helpers for convenience
- `lib/sync/manager.ts` – background sync orchestrator
- `lib/sync/request.ts` and `lib/sync/errors.ts` – Effect-based helpers and error types
- `lib/steer/subgraph.ts` – Steer subgraph queries used to hydrate vault data
- `lib/amm/adapters.ts` – AMM adapter layer for pool metadata and hour data
- `lib/analysis/KPIs.ts` – KPI recomputation logic used by the manager
- `lib/pglite/schema.ts` and `lib/pglite/types.ts` – lightweight PGlite schema helpers
- `tsconfig.json` – preserves the `@/*` alias in this standalone package
- `package.json` – npm metadata plus dependency list and build script

## External Dependencies
- [`effect`](https://github.com/Effect-TS/core) – heavy usage across the manager and helpers
- [`@steerprotocol/sdk`](https://www.npmjs.com/package/@steerprotocol/sdk) – protocol metadata helpers
- A `fetch` implementation available in the runtime (Node 18+ provides a global one)

The database helpers assume an object that implements the `PGliteDb` interface (`query(sql, params)` returning `{ rows: Row[] }`). If you previously relied on `@electric-sql/pglite`, install it where you integrate this package.

## Usage
Install the package from npm and import from the re-export barrel:

```ts
import { makeBackgroundSyncService, backgroundSyncProgram } from '@steerprotocol/sync-engine'
```

From there you can spin up the long-running loop using whatever Effect runtime your host provides. For example, in a Node process:

```ts
import { backgroundSyncProgram } from '@steerprotocol/sync-engine'
import { NodeRuntime } from '@effect/platform-node'

NodeRuntime.runMain(
  backgroundSyncProgram({
    logger: console,
    db,
  }),
)
```

In browsers or workers you would instead supply a web-friendly runtime and logger before running the program.

Direct sub-module entry points are also declared in `package.json` exports should you prefer:

```ts
import { subgraphRequestEffect } from '@steerprotocol/sync-engine/request'
```

## Runtime & Observability

The sync engine does not ship with a built-in Effect runtime or telemetry stack. Supply the services that make sense for your host:

- **Runtime:** Use `NodeRuntime`, `WebRuntime`, Bun, or a custom driver to run `backgroundSyncProgram`.
- **Logging / Tracing:** Pass a `logger` via `BackgroundSyncManagerOptions` and provide tracing layers (see `docs/observability/` for Effect guidance) before you execute the program.

## Next Steps
1. `npm install @steerprotocol/sync-engine` in the target project.
2. Provide concrete implementations for environment integration (logger, database, API keys).
3. Supply a host-specific Effect runtime (e.g. `NodeRuntime.runMain` in Node, a custom runtime in browsers or workers) and wire in your logging/tracing layers.
4. Wire the manager into your service lifecycle and call `triggerSync`/`triggerExecutionForAll` as needed.