@kapable/sdk (0.15.0)
Installation
@kapable:registry=npm install @kapable/sdk@0.15.0"@kapable/sdk": "0.15.0"About this package
@kapable/sdk
TypeScript SDK for the Kapable v2 platform API. Fetch-based, works in Node, Bun, Deno, and browsers. It is the single, typed, audited mirror of every customer-tier capability on the platform, scoped to the correct security token.
New here? Start at the SDK suite front door:
../docs/sdk.md— which package, which token, the module catalog, and coverage at a glance.
Version 0.2.0 — customer-tier coverage 74.7% (up from 50.6% at the 2026-06-08 audit). 11 modules, 324 TS methods. See CHANGELOG.md.
Install
bun add @kapable/sdk
# or
npm install @kapable/sdk
Quick Start
import { KapableClient } from '@kapable/sdk';
const client = new KapableClient({
baseUrl: 'https://api.kapable.ai',
apiKey: 'sk_live_...',
});
// List active stories
const stories = await client.board.listStories({ status: 'active' });
console.log(`${stories.total} stories found`);
// Auto-paginate through all stories
for await (const story of client.board.paginateStories({ status: 'active' })) {
console.log(story.title);
}
// Create a story
const story = await client.board.createStory({
title: 'Implement login flow',
priority: 'high',
product_id: 'product-uuid',
});
// Upload a file
await client.store.uploadObject(
'uploads',
'reports/q3.pdf',
fileBytes,
'application/pdf',
);
Authentication
// API key (sent as x-api-key header)
const client = new KapableClient({
baseUrl: 'https://api.kapable.ai',
apiKey: 'sk_live_...',
});
// JWT / session token (sent as Authorization: Bearer header)
const client = new KapableClient({
baseUrl: 'https://api.kapable.ai',
token: 'jwt_token_here',
});
Picking the right token
The SDK never enforces authorization — the server does — but it ships a typed
description of the platform's RBAC / token model so you can pick the right
credential up front. Import the security surface to inspect required token
types, permissions, and scopes:
import { Permission, TokenType, Scope, TIER, ownerWith, classifyToken } from '@kapable/sdk/security';
classifyToken('sk_live_abc'); // TokenType.ApiKey
const billingReq = ownerWith(Permission.BillingManage); // AuthRequirement
- Token tiering & contribution rules: CONTRIBUTING.md
- Full RBAC / token-tiering matrix + gap analysis: ../docs/sdk-surface-matrix.md
- Operator/admin endpoints (berth, foreman, host, gateway, …) are deliberately
excluded — they belong in the planned
@kapable/ops-sdk, never this package.
Workspace scoping
Workspace-scoped data (workspaces module, workspace_scoped data tables) is
resolved server-side from the X-Workspace-Id header (membership-validated by
kapable-auth; a workspace-bound credential always wins over the header).
The SDK sets the header natively — no header plumbing needed:
// Constructor scope: every request carries X-Workspace-Id
const client = new KapableClient({
baseUrl: 'https://api.kapable.ai',
token: 'jwt_token_here',
workspaceId: 'a4d3…',
});
// Per-request override (string = different workspace, null = org-wide opt-out)
await client.get('/v1/tables/notes/rows', { workspaceId: 'other-ws' });
await client.get('/v1/tables', { workspaceId: null });
// Derive a re-scoped client — sub-clients carry the new scope
const wsClient = client.withWorkspace('a4d3…');
await wsClient.data.listRows('notes');
Error Handling
All API errors throw KapableError with code, message, and status fields
matching the standard error envelope:
import { KapableError } from '@kapable/sdk';
try {
await client.board.getStory('nonexistent');
} catch (err) {
if (err instanceof KapableError) {
console.log(err.status); // 404
console.log(err.code); // "NOT_FOUND"
console.log(err.message); // "story not found"
}
}
Real-time (SSE)
Several modules expose text/event-stream endpoints (board events, data row
changes, comms room/agent/anomaly feeds, AI proxy streaming). They return an
async iterable of typed events:
for await (const ev of client.board.streamEvents()) {
console.log(ev.operation, ev.data);
}
The low-level SseClient / parseSseBuffer (from @kapable/sdk/sse) back these
streams and can be used directly against any Kapable SSE endpoint.
Modules
11 customer-tier modules. Method counts are TS / Rust (kept at parity by the
drift gate). The lists below are generated from coverage-manifest.json — the
source of truth for the wrapped surface.
ai — kapable-ai (6 / 6)
Provider catalog, per-org provider config, upstream proxy (SSE-capable).
configureProvider, getProvider, listProviders, proxy, proxyStream, removeProviderConfig
auth — kapable-auth (115 / 109)
Login, signup, orgs, members, API keys, apps, deployments, lanes, workspaces, custom domains, invitations, conductor instances, onboarding, consent.
login, signup, logout, logoutEverywhere, refresh, me, validate, validateHeader, sessionInfo, magicLinkRequest, magicLinkVerify, signInEmail, getSessionBetterAuth, jwks, createApiKey, listApiKeys, revokeApiKey, createServiceToken, getOrg, renameOrg, getOrgCaps, adminCreateOrg, adminCreateOrgApiKey, listOrgMembers, assignMemberRole, deactivateMember, reactivateMember, createInvitation, listInvitations, revokeInvitation, acceptInvitation, listRoles, createRole, updateRole, deleteRole, listPermissions, listOrgApps, getAppDetail, getAppChoice, createAppChoice, forkAppChoice, renameApp, deleteApp, pauseApp, resumeApp, abortPendingApp, publishAppAsTemplate, listLaunchpadApps, requestDeploy, rebuildApp, retryDeployment, deploymentStatusCallback, streamAppLogs, appLogs, listAppEnv, upsertAppEnv, deleteAppEnv, listAppEnvironments, createAppEnvironment, getAppEnvironment, deleteAppEnvironment, listAppEnvVars, createAppEnvVar, updateAppEnvVar, deleteAppEnvVar, listCustomDomains, createCustomDomain, checkCustomDomain, setPrimaryDomain, deleteCustomDomain, getAuthConfig, updateAuthConfig, getTraffic, setTraffic, getActivity, postActivity, getOnboarding, markOnboardingProgress, dismissOnboarding, getConsentStatus, getConsentReport, createWorkspace, listWorkspaces, getWorkspace, updateWorkspace, deleteWorkspace, inviteWorkspaceMember, updateWorkspaceMember, revokeWorkspaceMember, bindWorkspaceResource, unbindWorkspaceResource, listWorkspaceResources, createLane, listLanes, getLane, updateLane, deleteLane, deployToLane, promoteLane, drainLane, registerConductorInstance, listConductorInstances, getConductorInstance, conductorHeartbeat, deleteConductorInstance, … (full list in coverage-manifest.json)
billing — kapable-billing (3 / 3)
Org subscription summary, Stripe checkout init, customer portal. Owner-tier.
get, init, portal
board — kapable-board (42 / 41)
Stories, sprints, plans, products, comments, closures, lanes/gates, evidence/verdict, worktrees + agent-report (Routa coordination), story repos, board event stream.
listStories, paginateStories, getStory, createStory, updateStory, deleteStory, transitionStory, searchStories, listSprints, getSprint, createSprint, startSprint, completeSprint, attachStory, detachStory, getClosure, upsertClosure, listPlans, getPlan, createPlan, updatePlan, listRevisions, createRevision, listProducts, getProduct, createProduct, updateProduct, listComments, createComment, updateComment, deleteComment, getLanes, setLanes, postEvidence, getVerdict, listWorktrees, agentReport, listStoryRepos, addStoryRepo, removeStoryRepo, listRepos, streamEvents
comms — kapable-comms (43 / 43)
Agents, agent keys, mailboxes, channels, rooms, messages, email, app tokens, presence/heartbeat, quotas, Telegram bridges, annotations, and SSE feeds (room / agent / anomaly).
createAgent, listAgents, deleteAgent, mintAgentKey, listAgentKeys, revokeAgentKey, createMailbox, listAgentMailboxes, deleteMailbox, listMailboxChannels, createChannel, getMessage, listMessages, sendEmail, createRoom, listRooms, getRoom, roomPresence, heartbeat, joinRoom, inviteAgentToRoom, revokeRoomAgent, createRoomInvite, listRoomInvites, revokeRoomInvite, postRoomMessage, listRoomMessages, mintAppToken, listAppTokens, revokeAppToken, postAnnotations, upsertMailboxQuota, getMailboxQuotas, deleteMailboxQuota, mailboxRateLimitHits, listOrgSendAudit, linkTelegramBridge, telegramSetupUrl, listBridges, revokeBridge, streamRoom, streamAgent, streamAnomalyFeed
data — kapable-data (18 / 17)
Tables CRUD, rows CRUD, search, bulk operations, CSV import/export, and SSE row change streams.
listTables, createTable, dropTable, migrateTable, listRows, paginateRows, getRow, createRows, updateRow, patchRow, deleteRow, searchRows, bulkUpdate, bulkDelete, importCsv, exportData, subscribeChanges, subscribeOrgChanges
harbor — harbor (11 / 11)
Runtime licensing + release store. Public activate/validate/verify/download +
org-scoped license/usage/keypair reads. (Admin product/feature/tier CRUD is
deferred to @kapable/ops-sdk — see IMP-1366.)
activate, validate, verifyRelease, getOrgPublicKey, getReleaseManifest, getLatestReleaseCompat, downloadReleaseArtifact, downloadArtifact, getLicense, getLicenseUsage, listOrgKeys
knowledge — kapable-knowledge (38 / 37)
Claims, claim confidence/meta/derivations, edges, predicates, sources, pages, corpora, perspectives, canonical entities, merge candidates, provenance, invariants, assay runs, and tensions.
createClaim, getClaim, listClaims, searchClaims, listClaimsByPerspective, retractClaim, createClaimConfidenceEvidence, listClaimConfidenceEvidence, listAllClaimConfidenceEvidence, createClaimMeta, listClaimMeta, createClaimDerivations, listClaimDerivations, createEdge, listEdges, listPredicates, predicateOntology, createSource, listSources, deleteSource, createPage, listPages, mergePages, createCorpus, getCorpus, listCorpora, getPerspective, listPerspectives, listCanonicalEntities, resolveCanonicalEntity, listMergeCandidates, decideMergeCandidate, unmergeMergeCandidate, listSourceProvenance, sourceProvenanceGraph, listInvariants, listAssayRuns, detectTensions
secrets — strongbox (7 / 7)
Org-scoped secrets vault: CRUD, rotate, audit log.
create, get, list, update, delete, rotate, audit
store — kapable-store (10 / 10)
Buckets, objects, presigned URLs.
listBuckets, createBucket, listObjects, paginateObjects, uploadObject, downloadObject, headObject, deleteObject, presignUpload, presignDownload
wiki — kv2-wiki (31 / 31)
JSON routes only: pages/collections/tags/projects CRUD, prompt-page generation, and the substrate/wiki agent-tools. HTML-rendering routes and the UI SSE stream are deliberately excluded.
createPage, listPages, updatePage, deletePage, getRawPage, createEntityPage, createPromptPage, updatePrompt, regenerate, generateNarrative, pageGenerationHistory, createCollection, listCollections, getCollection, updateCollection, deleteCollection, addPageToCollection, removePageFromCollection, updatePageInCollection, createTag, listTags, addTagsToPage, removeTagFromPage, deleteTag, createProject, listProjects, searchClaims, getCanonicalEntity, listPredicates, readPageTool, listPagesTool
Tree-Shakeable Imports
Every module is exported both from the root and as a ./<module> subpath:
// Import only the board module
import { BoardClient } from '@kapable/sdk/board';
import type { Story, Sprint } from '@kapable/sdk/board';
// Import only the store module
import { StoreClient } from '@kapable/sdk/store';
import type { Bucket, ObjectInfo } from '@kapable/sdk/store';
// The security model, the SSE primitives
import { Permission } from '@kapable/sdk/security';
import { SseClient } from '@kapable/sdk/sse';
Subpaths: ./ai, ./auth, ./billing, ./board, ./comms, ./data,
./harbor, ./knowledge, ./secrets, ./store, ./wiki, ./security, ./sse.
Coverage & drift gate
Coverage is measured against the customer-tier, SDK-eligible endpoint inventory:
bun run generate-manifest # rebuild coverage-manifest.json from live source + inventory
bun run check-drift # report coverage %, gaps, and any phantom methods (CI gate)
Current: 74.7% customer-tier coverage, 0 phantom methods. The Rust SDK
(kapable-sdk-rs) is kept at method parity by the same manifest.
License
MIT
Dependencies
Development dependencies
| ID | Version |
|---|---|
| @types/bun | ^1.2.0 |
| typescript | ^5.7.0 |