Secentra Escrow SDK

A deterministic, failure-honest SDK for building escrow workflows on top of the Secentra Escrow Engine.

This SDK is intentionally minimal. It exposes a small, explicit public API and enforces correctness over convenience.

What this SDK IS

Deterministic execution model

Explicit, synchronous dispatch

Strict and explicit domain contracts

Production-grade error taxonomy

Type-safe by default (no implicit payload assumptions)

What this SDK is NOT

Not an ORM

Not async or retry-based

Not persistence-aware

Not event sourcing infrastructure

Not forgiving of incorrect usage

Principle: correctness over convenience.

Installation npm install @secentra/escrow-sdk

Quick Example (Happy Path) import { EscrowSDK } from "@secentra/escrow-sdk" import type { Projection } from "@secentra/escrow-sdk"

const sdk = new EscrowSDK({ projections: [ ((ctx) => { if (ctx.event.type !== "payment.received") return console.log("Event received:", ctx.event.type) }) satisfies Projection, ], })

sdk.dispatch({ type: "payment.received", payload: { amount: 1000 }, })

Execution Model (High Level)

dispatch() is synchronous

Projections execute in registration order

Execution stops on the first failure

Re-entrant dispatch is not allowed

Errors are never swallowed

If a projection throws, dispatch fails immediately.

Error Model

All runtime failures surface as explicit domain errors.

Error Types

ProjectionError — a projection failed during execution

ConfigurationError — invalid SDK configuration

DispatchError — invalid dispatch usage

InvariantViolationError — violated core guarantees

Example import { ProjectionError } from "@secentra/escrow-sdk"

try { sdk.dispatch(event) } catch (e) { if (e instanceof ProjectionError) { console.error(e.event.type) console.error(e.cause) } }

Errors always preserve their original cause.

Consumers should treat errors as expected control flow, not exceptional accidents.

Payload Safety

Event payloads are typed as unknown by design.

This forces consumers to:

Validate payloads explicitly

Avoid unsafe assumptions

Fail fast and clearly

function isPaymentPayload(p: unknown): p is { amount: number } { return typeof p === "object" && p !== null && "amount" in p }

Warnings (DX Only)

The SDK may emit non-fatal warnings in development mode (e.g. missing projections).

Warnings:

Never affect execution

Are never thrown

Exist only to surface potential misuse

Versioning Policy

This SDK follows Semantic Versioning.

PATCH — documentation, comments, examples

MINOR — additive, backward-compatible API changes

MAJOR — breaking contracts or semantics

If an existing test breaks, it is a MAJOR change.

Supported Environments

Node.js 18+

TypeScript 5+

Documentation

Extended documentation is available in /docs:

docs/getting-started.md

docs/execution-model.md

docs/error-model.md

docs/faq.md

Stability Promise

Public API is defined only via package exports

No deep imports are supported

Internal structure may change without notice

Exported contracts are stable within a major version

Phase 3 — SDK Hardening & Build Output

This phase focuses on locking contracts and preparing the SDK for safe distribution.

Phase 3.3 — Public API Hardening

This phase formalizes and freezes the public contracts of the SDK. No new features are introduced in this phase.

Public API Freeze

The following exports are considered stable and frozen:

EscrowSDK

Projection

ProjectionError

ConfigurationError

DispatchError

InvariantViolationError

Any change to their signatures, semantics, or throwing behavior constitutes a breaking change and requires a MAJOR version bump.

Error Semantics (Locked)

The SDK throws only the following domain-specific errors:

| Error Type | When It Is Thrown | |----------------------------|---------------------------------------------------------| | ConfigurationError | Invalid SDK construction or configuration | | DispatchError | Invalid dispatch usage or malformedevent | | InvariantViolationError | Violation of core guarantees (e.g. re-entrant dispatch) | | ProjectionError | A projection throws during execution |

No other errors are permitted to escape the SDK.

Invariants (Guaranteed)

The following guarantees are enforced by the SDK:

Dispatch is synchronous

Projections execute in registration order

Re-entrant dispatch is forbidden

Errors are never swallowed

Event payloads are typed as unknown and must be validated by consumers

These guarantees are part of the public contract, not implementation detail.

Misuse Behavior

The SDK distinguishes between hard failures and non-fatal misuse:

Missing or non-matching projections → ignored (may emit warnings in development)

Invalid event object → hard failure (DispatchError)

Projection throws → hard failure (ProjectionError)

There is no silent recovery from invalid execution.

Rules (Enforced Across Phase 3)

SDK is a standalone, consumer-facing library

No assumptions about runtime, storage, or network

No breaking changes without explicit version increment