Smart Client Library

@putnami/client runs the clients Putnami generates from a provider declaration. The provider owns the schemas, the typed errors, the credential profiles, the transports and the resilience policy; the consumer injects one binding and calls typed methods.

The happy path has four steps, and none of them is transport code:

declare the provider  →  generate          →  register the binding  →  call
   endpoint(), api()     generatedFrom        register<Service>Client
   clientGenerator()     client-generate      (or DI injection)        items.getItems(input)

typescript/samples/10-service-to-service runs all four end to end.

1. Declare the provider

An endpoint is declared once, in src/api/**. .mayThrow() names the framework errors the operation can return, so they arrive at the consumer as typed errors rather than a formatted string:

import { endpoint } from '@putnami/application';
import { NotFoundException } from '@putnami/runtime';

export const GET = endpoint()
  .params({ id: String })
  .returns(itemSchema)
  .mayThrow('NotFound')
  .handle(async (ctx) => {
    const item = items.get(ctx.params.id);
    if (!item) throw new NotFoundException('item not found');
    return item;
  });

api({ client }) declares the service identity and the credential profiles the generated clients must satisfy. Profiles are names and header placements; credential values stay in consumer configuration and never enter generated source:

api({
  client: {
    service: { id: 'catalog.items', audience: 'api://catalog.items' },
    credentials: { 'catalog-key': { kind: 'api-key', header: CATALOG_KEY_HEADER } },
  },
})

.client({...}) carries the client-facing policy the route cannot express: which credential alternatives satisfy the operation, the resilience policy, the transport preference order, and whether a server stream may be continued.

export const GET = endpoint()
  .params({ id: String })
  .returns(Stream(itemRevisionSchema))
  .mayThrow('NotFound')
  .client({
    security: { alternatives: [{ allOf: [{ profile: 'catalog-key' }] }] },
    transports: ['websocket', 'sse'],
    resume: true,
    resilience: { stream: { handshakeTimeoutMs: 2000, idleTimeoutMs: 5000, reconnect: true } },
  })
  .handle(async (ctx) => {
    const from = ctx.resumeFrom ?? 0n;
    // A continuation is told where the consumer left off.
  });

An SSE server stream continues across a broken connection, on another instance included, when the provider declares how. Cursor mode names the output field that carries the provider's opaque position and the query parameter that receives it on a reopening:

export const GET = endpoint()
  .query({ cursor: Optional(String), until: Number })
  .returns(Stream(itemChangeSchema))
  .mayThrow('NotFound')
  .client({
    transports: ['sse'],
    sseContinuation: { mode: 'cursor', cursor: { outputField: 'cursor', queryParameter: 'cursor' } },
    resilience: { stream: { reconnect: true } },
  })
  .handle(async (ctx) => {
    const { cursor, until } = ctx.queryParams();
    let after = changes.position(cursor);
    // A position this provider never issued is the declared NotFound: the feed
    // never restarts from the beginning.
    if (after === undefined) throw new NotFoundException('unknown position');
    while (after < until) {
      const change = await changes.next(after, ctx.signal);
      if (!change) return; // drained: no terminal, the consumer continues elsewhere
      ctx.send(change);
      after = change.revision;
    }
  });

cursor is a required string of itemChangeSchema and a declared string query parameter, and the handler continues exclusively after the position it is given. typescript/samples/10-service-to-service serves this route, and its generated consumers prove the continuation across an instance change. { mode: 'best-effort' } is the other mode: the reopening sends the original query and no position, and the stream may miss or repeat messages.

Declaration What it produces
.returns(schema) A typed unary result
.returns(Stream(schema)) A server stream
.body(Stream(schema)) + .returns(schema) A client stream with one declared result
.body(Stream(schema)) + .returns(Stream(schema)) A bidirectional stream
.body(Binary({ mediaType, maxBytes })) A raw octet request body, bounded
.returns(Binary({ mediaType, maxBytes })) A raw octet response, bounded
.mayThrow('NotFound') A typed client error carrying that stable code
.mayThrowDetails('Conflict', schema) The same typed error, with its details typed by schema
.client({ transports: [...] }) The dispatch order every generated client follows
.client({ connectEncodings: [...] }) The Connect payload encoding order a generated client dispatches
.client({ resume: true }) A server stream a broken socket may continue
.client({ sseContinuation: { mode: 'cursor', cursor: {...} } }) An SSE server stream a broken connection continues after the last delivered cursor, on any instance; { mode: 'best-effort' } reopens with the original query and may miss or repeat messages
.client({ external: 'OCI Distribution Specification v1.1' }) Nothing: the route stays served and published, and an external authority owns it

The bound on Binary is mandatory. An unbounded octet body is the one shape generation refuses outright, because no consumer could size a buffer for it.

A provider that serves a standard protocol beside its own routes — an OCI registry, a Go module proxy, an npm registry — marks each standard leg with external. The leg stays in the OpenAPI document with x-putnami-external-contract instead of x-putnami-client, and no generated client, proto document or gRPC route includes it; its callers use the standard's own adapters, and its own schemas are published the way a provider without a contract publishes them. external stands alone: blank, beside another client option, or declared without api({ client }), it fails before the route is bound and again at OpenAPI generation.

Finally, declare that the API is a client contract. The generator is a build-time concern, so it comes from the @putnami/client/generator subpath — the package root exports the runtime only:

import { clientGenerator } from '@putnami/client/generator';

.use(clientGenerator())

clientGenerator() names no client: no target, output or package. It records each operation's producer, the project and feature that own it, in the contract. The provider commits that contract as schema/openapi.json.

2. Generate

A client is a project of its own. Its putnami.json names the provider's service in generatedFrom, and its package.json name is the package consumers import:

{
  "name": "@example/items-client",
  "generatedFrom": { "service": "catalog.items", "language": "ts" }
}

putnami client-generate writes the client's src tree from the provider's committed schema/openapi.json. putnami build, test, lint, serve and package run it first, so building the consumer generates the client:

putnami build --projects items-consumer

Generation is strict for a provider-owned contract: a semantic the shared client IR cannot carry fails with the operation named and a remedy, rather than emitting a client that silently loses it. The workspace commands, the guard and the full diagnostic list are in Generated clients.

3. Register the binding

import { registerItemsClient } from '@example/items-client';

registerItemsClient(instance);

Deployment values arrive through the typed clients config block, so the generated package holds no URL, token or key:

clients:
  clientId: orders.api
  services:
    catalog.items:
      url: https://items.internal

An operation that declares a credential is never sent anonymously: an unbound profile fails the call before dispatch instead of reaching the provider anonymously.

4. Call

The client arrives through dependency injection. No base URL, no interceptor and no header is written at the callsite:

export const GET = endpoint()
  .inject({ itemsClient: ItemsClient })
  .returns({ items: ArrayOf(itemSchema) })
  .handle(async (ctx) =>
    ctx.deps.itemsClient.getItems({ query: { search: '', limit: 10 } }),
  );

Every generated method takes the declared input and an optional ClientCallOptions carrying a per-call AbortSignal:

const controller = new AbortController();
await items.getItems({ query: { search: '', limit: 10 } }, { signal: controller.signal });

A declared error arrives as a ClientFrameworkError carrying the stable code, the status, the retry hint and the redacted declared details — the same object a Connect or WebSocket call produces for the same scene.

The shapes a generated client exposes

Declared shape Generated entry point
Unary items.getItems(input, options?)
Raw octets the same method, returning { status, contentType, body } with the octets unchanged
Server stream items.watchItems(input) — SSE, WebSocket or Connect, in declared order
Client stream items.adjustItems(input) — WebSocket, with one declared result
Bidirectional stream items.negotiateItems(input) — WebSocket
Byte stream (provider-owned wire) gateway.connectDatabase(input) — Promise<ByteStream>, a readable and writable pair of Uint8Array; Go: *client.ByteStream, an io.ReadWriteCloser
Provider-owned subprotocol events.subscribeEvents(input) — FrameStream<Send, Message> of the declared JSON frames, no envelope; Go: *client.FrameStream[In, Out]
Connect unary the same method; the transport is chosen from the declared order
const stream = items.watchItems({ path: { id: '123' } });
stream.onMessage((item) => console.log(item));
stream.onError((error) => console.error(error));
stream.onComplete(() => console.log('done'));

The caller never names a transport. Credentials, deadline, retry, circuit breaker, trace propagation and metrics are the same chain on every wire. typescript/framework/client/AI.md and doc/03-transports.md hold the per-transport rules: admission, the five session phases, the four stream budgets, declared fallback and declared resume.

A WebSocket stream is opened the way a browser must open it — new WebSocket(url, 'putnami.service.v1'), no header and no credential in the URL. Identity, credentials, budget and propagation context travel in the init frame.

A provider-owned wire is the exception, declared by the provider with api.ByteStream() / ByteStream() or .Subprotocol() / .subprotocol(): its upgrade request is the admission, so it carries the declared credential and identity headers, and a browser — which cannot set them — refuses to open it rather than dialing anonymously.

Rules, not gaps

These are contract decisions, and they do not change with a later release:

  • A WebSocket transport declaring proto encoding is refused at generation. The wire keeps the encoding in the contract; the client carries JSON messages.
  • A unary call never falls back to another transport. A server stream falls back once, before admission, and only when the provider answered that this wire is not served here.
  • A stream never continues unless the provider declared resume or sseContinuation on a safe server stream and the operation's effective resilience.stream.reconnect is on. A continuation follows a transport break and nothing else: a typed error, an explicit complete, a contract error, a cancellation or an expired budget ends the stream. Five continuations per session is the framework cap.
  • A delivered message is never replayed by resume or by a cursor continuation: the position advances only when the subscribed caller took the value, and the provider continues exclusively after it. A best-effort continuation is the one declared exception — it reopens the original query, and messages may be missing or repeated — and it is never substituted for a cursor continuation that failed.
  • A cursor is a position, not a credential. Every reopening resolves the binding's credentials() again and runs the provider's full security chain, and the provider answers a stale, forged or out-of-scope cursor with a typed error, never by restarting from the beginning.
  • A declared SSE continuation speaks a negotiated wire: the request carries X-Putnami-Stream-Wire: putnami.sse.v1, the provider acknowledges it on the response head and ends a successful stream with event: complete. A provider that does not acknowledge fails the call before any message; a consumer that does not ask reads the legacy framing. Upgrade the provider first, then its consumers.
  • A nullable member over connect+proto is refused: proto3 has one absence, so null and absent would become one value.

Cross-language clients (TS ↔ Go)

One provider has clients in both languages from one contract. Each client is its own project that names the provider in generatedFrom; only the language and the Go options differ:

{
  "name": "go.putnami.dev/examples/ts-items-client",
  "generatedFrom": {
    "service": "catalog.items",
    "language": "go",
    "packageName": "itemsclient",
    "clientName": "ItemsClient"
  }
}

Each client runs its own language's emitter against the provider's committed contract: the TypeScript client gets its src tree, and the Go client gets client.gen.go beside its go.mod. No extension shells out to the other, and no generation builds the provider. A Go provider works the same way: it declares api.Clients(...), commits its contract, and a TypeScript client project names it in generatedFrom.

Generated clients are built, not committed: Git ignores src in a TypeScript client and client.gen.go in a Go one. client-generate is cached, and its key folds the provider contract's digest, so a contract change regenerates every client and any other provider change reuses them.

Resilience and observability

Interceptor chain

Every outgoing request passes through:

Auth → Telemetry → Routing Context → Retry → Transport
Interceptor What it does
Auth Forwards the incoming JWT, or obtains a client-credentials token
Telemetry Records client.{service}.request, .error, .duration metrics
Routing Context Propagates trace ID, request ID, region, experiment headers
Retry Exponential backoff with jitter on transient failures (429, 502, 503, 504)
Circuit Breaker Fail-fast when the downstream is unhealthy, with optional health probing

Circuit breaker

Three states: Closed (normal) → Open (fail-fast) → Half-open (trial requests). When healthCheckUrl is set, the breaker probes it while open and transitions to half-open when the service recovers.

circuitBreakerInterceptor({
  failureThreshold: 5,
  resetTimeoutMs: 30000,
  healthCheckUrl: 'http://users-api:3000/healthz',
});

Spec drift detection

Generated clients embed a spec hash. checkDrift() warns at startup when the live service spec differs. It is a warning, not a gate: every build regenerates the client from the committed contract, so a build never runs a stale client.

Low-level client

ClientBuilder, BaseClient and the transports stay supported for tests and for contracts Putnami does not own. They are not part of the first-party path above, and a handwritten first-party transport fails the workspace guard.

import { ClientBuilder } from '@putnami/client';

const search = await ClientBuilder.for(SearchClient)
  .baseUrl('https://external.example.com')
  .clientId('orders-service')
  .timeout(10_000)
  .build();

ClientBuilder

Method Description
.baseUrl(url) Service base URL (required)
.clientId(id) Client identity for X-Client-Id
.timeout(ms) Request timeout
.retry(config) Retry configuration
.interceptors([...]) Custom interceptors
.checkDrift() Enable spec drift detection
.build() Async build with transport negotiation
.buildSync() Sync build using embedded metadata

ClientConfig

Option Type Default Description
baseUrl string required Service base URL
transport 'http' | 'connect' required Transport protocol
timeoutMs number 30000 Whole-call budget
retry.maxRetries number 3 Max retry attempts
retry.baseDelayMs number 200 Base backoff delay
retry.maxDelayMs number 5000 Max backoff delay
retry.retryableStatuses number[] [429,502,503,504] Retryable HTTP codes
retry.jitter boolean true Randomize delay
interceptors Interceptor[] [] Custom interceptors

generatedFrom

clientGenerator() takes no options. A client project declares its generation in the generatedFrom member of its putnami.json:

Member Type Default Description
service string required The provider's x-putnami-client service id
language 'ts' | 'go' required Language to generate
packageName string — Go only: package name of client.gen.go
clientName string — Go only: generated client struct name
omitOperations string[] — Go only: operations the Go client leaves out, by operationId

The TypeScript package name is the client's package.json name, and the Go import path is the client's go.mod module.

Support and compatibility

@putnami/client is a public, documented, maintained package classified stable. Its service-clients specification and its accepted decision records live next to the package source.

The promise is that a call has one latency budget. timeoutMs bounds the whole call rather than a single attempt: each attempt's timeout is clamped to the budget that remains, a backoff sleep that would overrun the deadline is skipped, and a caller who wants retries to cost more time says so explicitly with maxElapsedMs. Only network errors, per-attempt timeouts, and the statuses you declared retryable are retried, and the retry count is clamped into [0, 10]. A caller's abort signal ends the whole sequence, not just the running attempt. The circuit breaker is a separate interceptor, so it observes the outcome of the retry sequence rather than each attempt, and while half-open it admits at most halfOpenMaxConcurrent trial requests.

Before v1.0.0, minor 0.x releases may still contain documented breaking changes; strict compatibility across every pre-1.0 minor is not promised.