Skip to content
BLACKLAKE
Sign up free
Docs▾ docs nav
<!-- BL-ENT-17 · written 2026-05-07 · update when commitments change -->

SDK quality bar — public commitments

When a buyer evaluates SDKs across vendors, the things that matter are hover-doc quality, error-message specificity, retry behaviour, and test-mock support. Most vendors verbally claim these; few back the claim with a written bar that ships with the SDK and runs in CI.

This doc is the public bar BlackLake commits to. It also lives at https://www.blacklake.systems/docs/sdk-quality-bar so customers evaluating us can read it without an NDA. Mirror the table to the packages/blacklake/README.md so the commitment travels with the package.

Commitments#

CommitmentWhat it meansHow it's enforced
100% JSDoc with @example blocks on every public functionHover in any IDE shows what the call does, what it returns, and one runnable snippet. No "use the docs" stubs.BL-FND-22 sweep ships full coverage; CI guard (planned) fails the build if any export function/class lacks @example.
Typed errors per failure classBlackLakeError, GovernDeniedError, GovernApprovalRequiredError, RateLimitError, IdempotencyKeyReusedError, NetworkError etc. — discriminated by error.code. Callers can if (err instanceof GovernDeniedError) ... instead of regexing messages.packages/sdk/src/index.ts exports the error classes; per-class @example block shows the discriminator pattern.
Network-error retries by defaultTransient failures (5xx, ECONNRESET, ETIMEDOUT) auto-retry with exponential backoff + jitter. Configurable via new BlackLake({ retry: { maxAttempts, ... } }).Built-in retry policy in BlackLakeClient.request(); tests cover transient + permanent failures.
Idempotent retries for mutationsSDK auto-attaches Idempotency-Key on retried POST/PATCH/DELETE so a retry doesn't double-create.BL-FND-19 middleware on the API + auto-keying in the SDK retry path.
Drop-in test mocksA test fixture that runs against the SDK without hitting the network. Returns canned responses for every documented call.@blacklake-systems/test-fixtures (planned package) or in-package mock factory; cookbook in docs/sdk-testing.md.
Stable typesTypes follow semver — minor versions add fields; majors break shape. Callers can pin a major safely.packages/sdk/src/version.ts + docs/VERSION-COMPATIBILITY.md.
Deprecation warnings via console.warn, not silent removalEvery deprecated export emits a one-time runtime warning pointing at the migration. Sunset dates published 6 months ahead.docs/VERSION-COMPATIBILITY.md deprecation playbook + JSDoc @deprecated.

How customers verify the bar#

  • @example coverage — call any public function from your editor; hover shows a working snippet.
  • Typed errors — write a test that catches GovernDeniedError specifically and asserts error.response.decision === 'deny'.
  • Retries — point the SDK at a server that returns 503 once, 200 on retry; the SDK should succeed without app-level retry code.
  • Idempotency — retry a bl.agents.create({ name: 'x' }) call; the second attempt should return the same ID (200 instead of 409).
  • Mocks — install the test-fixtures package, write a unit test with no network. The cookbook walks the pattern.

Where the bar is enforced#

This isn't just a marketing page; it's wired into CI:

  • pnpm --filter @blacklake-systems/surface-sdk test runs the per-class typed-error tests.
  • scripts/check-jsdoc-examples.mjs (planned, BL-ENT-17 follow-up) asserts every export function/export class in packages/sdk/src/index.ts has a JSDoc @example.
  • packages/govern-action/dist/ is rebuilt and runs the SDK against the live API on every release; covers the typed-error path.
  • The contract tests (BL-FND-9) replay error scenarios across TypeScript + (future) Python SDKs.

What the bar doesn't promise#

To stay honest about boundaries:

  • No streaming response support today. Streaming JSON arrives in v2 (planned).
  • No browser SDK today. The SDK assumes a Node-like runtime (server / CI / local CLI). A browser version would need different auth and is gated on a customer ask.
  • No offline mode. SDK calls require network; there's no background-queue + sync pattern. Air-gapped receipt verification exists separately (BL-DIF-5).
  • Best-effort logging on retries. A retried call's debug log shows the attempt count but not every internal request — the successful response is what's returned.

Comparison view#

The site exposes a comparison table at https://www.blacklake.systems/compare/sdk-quality-bar showing how this bar lines up against published claims from peer vendors. The table is updated quarterly to keep it honest as the bar evolves.

When this doc is wrong#

If a public claim above fails on a real customer ("the docs say it retries but mine didn't"), that's a P1 bug — the SDK shouldn't drift from the bar. File against packages/sdk/ with the sdk-quality-bar label.