@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

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:

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:

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 for the intended adapter usage shape.

For the first browser-oriented integration example, see examples/react-connection-preview.tsx.

Current Verification

The package is lightweight enough to verify independently:

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

Local Release Flow

From the repo root:

./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:

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

Installation

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

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