Node.js / TypeScript SDK

Install

npm install @calvery/sdk

Requires Node 18+ (pakai built-in fetch).

Quick start

import { Calvery } from '@calvery/sdk'

const calvery = new Calvery({
  token: process.env.CVSM_TOKEN!,
  team: 'acme-corp',
})

const dbUrl = await calvery.get('DATABASE_URL')

Constructor options

new Calvery({
  token: string,            // REQUIRED — Personal Access Token (cvsm_...)
  team: string,             // REQUIRED — team slug atau UUID
  baseUrl?: string,         // Default: https://api.calvery.xyz
  environment?: string,     // Default: "production"
  cacheTTL?: number,        // Default: 30000 ms (set 0 untuk disable)
  maxRetries?: number,      // Default: 3
  fetch?: typeof fetch,     // Custom fetch (e.g. node-fetch, undici)
})

Methods

`get(name, opts?)`

Ambil satu secret by name.

const val = await calvery.get('STRIPE_KEY')
const staging = await calvery.get('STRIPE_KEY', { environment: 'staging' })

Throw CalverySecretNotFoundError kalau secret tidak ada.

`getAll(opts?)`

Ambil semua secret untuk environment sebagai object.

const secrets = await calvery.getAll()
for (const [k, v] of Object.entries(secrets)) {
  console.log(k, '=', v)
}

`inject(opts?)`

Inject semua ke process.env. Default tidak overwrite env var yang sudah ada.

await calvery.inject()              // skip yang sudah ada
await calvery.inject({ overwrite: true })   // force overwrite

Return array nama yang di-inject.

`clearCache()`

Manual clear cache. Useful kalau baru push secret baru dan butuh refresh instant.

Errors

import {
  CalveryError,
  CalveryAuthError,
  CalverySecretNotFoundError,
  CalveryNetworkError,
  CalveryServerError,
} from '@calvery/sdk'

Semua turun dari CalveryError. Catch pakai instanceof:

try {
  await calvery.get('FOO')
} catch (err) {
  if (err instanceof CalveryAuthError) {
    // 401/403 — token invalid, expired, atau gak punya akses team
  } else if (err instanceof CalverySecretNotFoundError) {
    // Secret belum dibuat
  } else if (err instanceof CalveryNetworkError) {
    // Network gagal setelah semua retry
  }
}

Framework recipes

Next.js / Vercel

import { Calvery } from '@calvery/sdk'

await new Calvery({
  token: process.env.CVSM_TOKEN!,
  team: 'acme-corp',
}).inject()

export default { /* ... */ }

Express

import express from 'express'
import { Calvery } from '@calvery/sdk'

await new Calvery({ token: process.env.CVSM_TOKEN!, team: 'acme' }).inject()

const app = express()
app.listen(3000)
// process.env.DATABASE_URL sudah tersedia di semua handler

NestJS (App bootstrap)

import { NestFactory } from '@nestjs/core'
import { Calvery } from '@calvery/sdk'
import { AppModule } from './app.module'

async function bootstrap() {
  await new Calvery({
    token: process.env.CVSM_TOKEN!,
    team: 'acme',
  }).inject()

  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}
bootstrap()

AWS Lambda

import { Calvery } from '@calvery/sdk'

const calvery = new Calvery({
  token: process.env.CVSM_TOKEN!,
  team: 'acme',
})

export const handler = async (event: any) => {
  const stripeKey = await calvery.get('STRIPE_KEY')
  // ... kode kamu
}

Cache 30s bikin cold start pertama saja yang fetch, subsequent invocations reuse cache.

Self-host

const calvery = new Calvery({
  token: process.env.CVSM_TOKEN!,
  team: 'internal',
  baseUrl: 'https://vault.mycompany.internal',
})

TypeScript tips

SDK fully-typed. Kalau pakai TypeScript strict mode:

const token = process.env.CVSM_TOKEN
if (!token) throw new Error('CVSM_TOKEN required')

const calvery = new Calvery({ token, team: 'acme' })

Contributing

Bug / feature request: github.com/RenzyArmstrong/calvery-sdks.