@walwarden/sdk

@walwarden/sdk

Dependency-free ESM TypeScript client for the Walwarden public REST API v1.

import { createWalwardenClient } from '@walwarden/sdk';

const walwarden = createWalwardenClient({
  baseUrl: process.env.WALWARDEN_BASE_URL!,
  apiKey: process.env.WALWARDEN_API_KEY!,
  userAgent: 'my-service/1.0',
});

const { databases, pageInfo } = await walwarden.listDatabases({ limit: 25 });
const evidence = await walwarden.getEvidence('<backupJobId>');

Restore semantics

createRestore returns HTTP 202 with a server-issued restore job and the bounded execution coordinates required by the CLI-local execution bridge. getRestore and pollRestore observe that job. This SDK contract does not claim managed or unattended restore execution: the proven end-to-end data-plane step remains the explicit CLI-local restore execute bridge against an operator-selected target.

REST operation inventory

This table is checked against the public OpenAPI document, the runtime client, and the generated SDK reference. Polling and iterator helpers are SDK-only conveniences and therefore do not appear here.

SDK method	Public REST operation
getProfile	getProfile
listDatabases	listDatabases
getDatabase	getDatabase
listDestinations	listDestinations
getDestination	getDestination
listDatabaseBackups	listDatabaseBackups
triggerBackup	triggerBackup
getBackup	getBackup
listEvidence	listEvidence
getEvidence	getEvidence
createRestore	createRestore
getRestore	getRestore
getRecoverySummary	getRecoverySummary
getRecoveryCandidate	getRecoveryCandidate
getRecoveryWindowProof	getRecoveryWindowProof
getMcpToolCatalog	getMcpToolCatalog

Every collection method returns exactly one bounded page. Traverse lazily with iterateDatabases, iterateDestinations, iterateDatabaseBackups, or iterateEvidence; the async iterators retain only the current page and accept an AbortSignal plus a bounded maxPages. Existing pre-0.1 clients receive a valid but partial first page and must upgrade to traverse a complete collection.

Structured failures are returned as WalwardenApiError. The error preserves the HTTP status, stable code, requestId, parsed retryAfterSeconds, and rateLimit metadata. After a 429, wait at least retryAfterSeconds before retrying and add jitter when multiple workers share one API key. Set onResponseMetadata on the client to observe the same metadata on successful responses without changing operation return bodies; observer failures are isolated from request results.

Pagination is a read-committed high-watermark traversal, not snapshot isolation. Continuation cursors expire after 24 hours and can also be invalidated when an old signing key is retired.