Deterministic, failure-honest SDK for the Secentra Escrow domain
npm install @secentra/escrow-sdkA 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.
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