TypeScript SDK

Create databases, manage scopes, and issue tokens. The SDK returns connection URLs. You connect to databases with your own client library (redis, neo4j-driver, fetch, etc.). Zero dependencies.

Install

npm install @cinchdb/sdk

Initialize

import { Cinch } from '@cinchdb/sdk'

// API key mode: full account access
const client = new Cinch({ apiKey: 'ck_live_...', org: 'acme' })

// Scope token mode: scoped access for agents
const agent = new Cinch({ scopeToken: 'cinch_...' })

Configuration

const client = new Cinch({
  apiKey: 'ck_live_...',
  org: 'acme',
  defaultEnvironment: 'production',
  defaultProject: 'api',
  timeout: 30,       // seconds
  maxRetries: 3,
})

Scopes

// Get or create a scope (idempotent)
const scope = await client.scope('my-scope', {
  environment: 'production',
  project: 'api',
})

// List scopes
const scopes = await client.scopes('production', 'api')

// Create a child scope
const child = await scope.createScope('subtask')

// Issue a token
const token = await scope.token('write', 7)
// { token: 'cinch_...', scope_id: '...', permission: 'write' }

// Delete scope and everything in it
await scope.delete()

Databases

// Create a database
const db = await scope.createDatabase('redis', 'cache')
// type: 'redis', 'sql', or 'graph'

// Get an existing database (throws NotFoundError if missing)
const db2 = await scope.database('cache', 'redis')

// List databases
const dbs = await scope.databases()

// Get connection URL
const url = await db.url()
// url.toString() -> full URL (pass to client libraries)
// console.log(url) -> redacted (safe for logs)

// Force refresh
const freshUrl = await db.url(true)

// DB token and env vars
db.dbToken    // 'cinch_...'
db.envVars    // { CINCH_DATABASE_URL: 'https://...', CINCH_DB_TOKEN: 'cinch_...' }

No auto-creation

scope.database('name') only looks up existing databases. It throws NotFoundError if the database does not exist.

Scope token mode

const agent = new Cinch({ scopeToken: 'cinch_...' })

const dbs = await agent.scopeAuthDatabases()
const db = await agent.scopeAuthDatabase('database-id')
const scopes = await agent.scopeAuthScopes()
const scope = await agent.scopeAuthScope('scope-name')

Error handling

import {
  CinchError,             // base class
  AuthenticationError,    // 401
  ForbiddenError,         // 403
  NotFoundError,          // 404
  ValidationError,        // 400
  ConflictError,          // 409
  ApiError,               // 5xx (retried)
  TimeoutError,           // retried
  NetworkError,           // retried
  RetryExhaustedError,
  CircuitBreakerOpenError,
} from '@cinchdb/sdk'

try {
  const db = await scope.database('missing')
} catch (e) {
  if (e instanceof NotFoundError) {
    const db = await scope.createDatabase('redis', 'missing')
  }
}