npm package: @sansavision/sansadb-sdk
Description: SansaDB TypeScript SDK for PLP-backed apps
Author: Sansa
Latest version: 0.1.0

# `@sansavision/sansadb-sdk`

This folder contains the publishable SansaDB-owned TypeScript SDK.

It is intentionally a facade package, not a second PLP implementation.

## Design Goal

This package exists to provide:

- SansaDB-first naming
- SansaDB-first docs and examples
- standalone/local defaults
- service entrypoints for stream, vector, CDN, reactive, KV, and documents

It is expected to sit on top of Pulse's TypeScript PLP runtime rather than reimplementing transport mechanics here.

## Status

What is here now:

- config types
- transport adapter boundary
- service descriptors
- a small `SansaDbClient` facade shape
- a concrete Pulse interop layer
- typed stream client support via `StreamServiceClient`
- generated-client compatibility via `binaryCall` and `streamCall`
- package build output via `dist/`
- public publish metadata for `npm publish`

What is not here yet:

- first-class local wrappers for every generated service binding
- automatic reconnect policy
- browser and node integration tests

## Proposed Usage Shape

```ts
import {
  createPulseBackedClient,
} from "@sansavision/sansadb-sdk";

const client = await createPulseBackedClient(pulseSdk, {
  endpoint: "ws://127.0.0.1:4001",
  tenantId: "default",
  authToken: "root-token-or-jwt",
  autoReconnect: true,
});

const stream = client.stream();
const vector = client.vector();
const cdn = client.cdn();
```

For typed stream flows, the package exposes a local `StreamServiceClient`:

```ts
import { StreamServiceClient } from "@sansavision/sansadb-sdk";

const streamClient = client.generated(StreamServiceClient);
```

If you need both the SansaDB facade and the underlying Pulse connection state, use:

```ts
const { client, connection } = await createPulseBackedSession(pulseSdk, {
  endpoint: "ws://127.0.0.1:4001",
  autoReconnect: true,
});
```

## Why This Package Exists In SansaDB

SansaDB should own its product-facing SDK surface:

- documentation
- examples
- defaults
- versioning
- product-specific helpers

But it should not duplicate PLP transport internals that already exist in Pulse's TypeScript SDK.

## File Layout

- `src/config.ts`
  - facade config and defaults
- `src/transport.ts`
  - transport adapter boundary
- `src/services.ts`
  - service IDs and helper factories
- `src/client.ts`
  - high-level SansaDB client
- `src/pulse.ts`
  - Pulse interop helpers and Pulse-backed client factory
- `src/session.ts`
  - Pulse session snapshot and event-binding helpers for browser code
- `src/stream.ts`
  - local typed stream client and PSL encoders/decoders
- `src/idl-runtime.ts`
  - minimal PSL encoder/decoder runtime used by local typed clients
- `src/index.ts`
  - public exports

## Preview Example

See [examples/pulse-stream-preview.ts](/Users/mohamedahmed/Downloads/Projects/dev/sansadb/sdk/sansadb-sdk/examples/pulse-stream-preview.ts) for the intended adapter usage shape.

For the first browser-oriented integration example, see [examples/react-connection-preview.tsx](/Users/mohamedahmed/Downloads/Projects/dev/sansadb/sdk/sansadb-sdk/examples/react-connection-preview.tsx).

## Current Verification

The package is lightweight enough to verify independently:

```bash
cd sdk/sansadb-sdk
npm install
npm run typecheck
npm run build
npm pack --dry-run
```

## Local Release Flow

From the repo root:

```bash
./scripts/publish-sdks.sh 0.1.0
```

That runs:

- `npm install`
- `npm run typecheck`
- `npm run build`
- `npm pack --dry-run`
- the browser PLP example build against the package boundary

To actually publish:

```bash
./scripts/publish-sdks.sh 0.1.0 --publish
```

## Installation

For the Pulse-backed browser and Node workflow, install the SansaDB package:

```bash
npm install @sansavision/sansadb-sdk
```

`@sansavision/pulse-sdk` is installed automatically as a package dependency. The SansaDB package re-exports `PulseConnection` and ships its own typed stream client so browser PLP applications can stay on the `@sansavision/sansadb-sdk` import surface.

## Expected Integration Direction

The next implementation steps after this package baseline are:

1. add first-class local wrappers for vector, CDN, and reactive clients
2. expand browser examples to depend on the published package instead of local file paths
3. add stronger browser and node integration tests