@shelvia/sdk

TypeScript SDK for Shelvia — the project memory and context-control layer for AI-native work.

Agents propose. Humans approve. Shelvia keeps the trusted memory.

This SDK wraps the documented /api/v1/project-memory/* routes with typed methods, structured errors, retries on safe reads, and 429 Retry-After handling.

Install

npm install @shelvia/sdk

Quick start

import { ShelviaClient } from "@shelvia/sdk";

const client = new ShelviaClient({
  apiKey: process.env.SHELVIA_API_KEY!,
  baseUrl: "https://shelvia.net",
});

const ctx = await client.projects.getContext("proj_123");
console.log(ctx.health.memory?.summary);

What this SDK is

• A typed wrapper over Shelvia's stable read + generation + candidate endpoints.
• Safe for agent runs: writes always create candidates that enter the human review queue.
• Designed to coexist with MCP clients — the same backend serves both surfaces.

What this SDK is NOT

• Not a Browser Work Capture client (Stage 12, gated).
• Not an MCP transport client — use @modelcontextprotocol/sdk for that. client.mcp.getManifest() is a doc helper only.
• Not a token-management surface. Create / rotate / revoke tokens in the Shelvia UI under Settings → API.
• Not a connector management surface. Connector secrets stay in the app.
• Never exposes raw embedding vectors or raw similarity scores. The ranking field uses human-friendly match reasons only.

Surfaces

| Group | Methods | |-----------|---| | projects | list() · getContext(id) · getHealth(id) · getBulkContext(input) | | memory | search(input) · createCandidate(projectId, input) | | context | generatePack(projectId, input) | | handoff | create(projectId, input) | | webhooks | list() · create(input) · revoke(id) · test(id) | | mcp | getManifest() (docs helper) |

Safety properties

• No API-key logging. The key ships only via Authorization.
• Retries apply ONLY to safe reads (GET, POST /search, POST /context, POST /context-pack, POST /handoff) and skip writes. Override with idempotencyKey if you want at-most-once behaviour on writes.
• 429 honored. Retry-After parsed and surfaced as ShelviaError.retryAfterSeconds.
• Timeouts. Default 30s per call. Override via timeoutMs on ShelviaClientConfig or per-call opts.timeoutMs.
• Custom fetch. Node 18+, edge, browser, deno — pass your runtime's fetch via config.fetch.
• Review-before-save preserved. memory.createCandidate(...) always produces status: "pending". The candidate becomes trusted memory only when a workspace member approves it.

Errors

import { ShelviaError } from "@shelvia/sdk";

try {
  await client.context.generatePack("proj_123", { purpose: "ship v2" });
} catch (e) {
  if (e instanceof ShelviaError) {
    if (e.code === "rate_limited") {
      await sleep(e.retryAfterSeconds * 1000);
    }
    // e.code: bad_request | unauthorized | forbidden | not_found |
    //         rate_limited | backend_error | network_error | timeout |
    //         abort | unknown
  }
}

Examples

See examples/ for runnable snippets:

1. 01-project-context.ts — fetch a project's current state.
2. 02-semantic-search.ts — search trusted memory across a project.
3. 03-context-pack.ts — generate a ranked context pack for Claude Code.
4. 04-create-candidate.ts — propose a memory candidate after an agent run.
5. 05-webhook-test.ts — register and test-deliver a webhook destination.
6. 06-agent-recipe.ts — docs-only recipe for using Shelvia from an agent runtime (OpenAI Agents SDK / LangGraph). No runtime dependency.

Running the examples

cp packages/shelvia-sdk/examples/.env.example \
   packages/shelvia-sdk/examples/.env.local
# fill in SHELVIA_API_KEY + SHELVIA_PROJECT_ID

# Read-only examples:
node --env-file=packages/shelvia-sdk/examples/.env.local \
     packages/shelvia-sdk/examples/01-project-context.ts

# Write examples (04, 05, 06) are DRY-RUN by default. Set
# SHELVIA_ALLOW_WRITE=1 in your env to actually send writes.

OpenAPI contract

The SDK ships an OpenAPI 3.1 spec at ./openapi.json (also exported via the ./openapi.json subpath). Generate a typed client in another language or hand it to your platform team:

import openapi from "@shelvia/sdk/openapi.json";

Publishing

This package is publish-ready but the actual npm publish is an owner-controlled action. Confirm @shelvia namespace ownership first.

cd packages/shelvia-sdk
npm run pack:check    # show the tarball contents (no secrets, no src)
npm run publish:dry   # npm publish --dry-run --access public
# When ready for real:
npm publish --access public

The files allowlist limits what ships: dist/, README.md, openapi.json, LICENSE. Source, examples, and node_modules NEVER ship to npm.

Versioning

Pre-1.0. The shape of ContextPackRankingSignals and the top_reasons union may grow (additive only). Breaking changes will bump major.

License

UNLICENSED for redistribution. See LICENSE. Reach out via shelvia.net/contact before republishing.