Node.js SDK

Zero dependencies. Requires Node.js 18+ (uses native fetch).

Install

npm install @vengtoo/sdk

Source: github.com/vengtoo/vengtoo-node

Quick start

import { Vengtoo } from '@vengtoo/sdk'

const vengtoo = new Vengtoo({ apiKey: 'vgt_...' })

const decision = await vengtoo.check(
  { id: 'user-123', type: 'user' },
  'read',
  { id: 'doc-456', type: 'document' }
)

Using with the local agent

const vengtoo = new Vengtoo({ baseUrl: 'http://localhost:8181' })

Full response

const resp = await vengtoo.evaluate({
  subject: { id: 'user-123', type: 'user' },
  resource: { id: 'doc-456', type: 'document' },
  action: { name: 'read' },
  context: { ip: '10.0.0.1' },
})
// resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path

Express middleware

import express from 'express'
import { Vengtoo } from '@vengtoo/sdk'

const app = express()
const vengtoo = new Vengtoo({ apiKey: 'vgt_...' })

app.get('/documents/:id',
  vengtoo.middleware('document', 'read', (req) => ({ external_id: req.auth.userId, type: 'user' })),
  (req, res) => {
    res.json({ ok: true })
  }
)

The third argument resolves the authenticated caller from the request and returns a Subject. Adapt it to your auth layer:

vengtoo.middleware('document', 'read', (req) => ({ external_id: req.auth.userId, type: 'user' }))

Options

new Vengtoo({
  apiKey: 'vgt_...',
  baseUrl: 'http://localhost:8181',
  timeout: 5000,      // ms, default 10000
  maxRetries: 3,      // default 2
})

Error handling

import { Vengtoo, VengtooError } from '@vengtoo/sdk'

try {
  await vengtoo.check(subject, 'read', resource)
} catch (err) {
  if (err instanceof VengtooError) {
    if (err.isAuthError) {
      // 401 — invalid API key
    }
    if (err.isServerError) {
      // 5xx — already retried
    }
  }
}

Types

interface Subject {
  type: string
  id?: string
  external_id?: string
  properties?: Record<string, unknown>
}

interface Resource {
  type: string
  id?: string          // defaults to "*" on the wire if neither id nor external_id set
  external_id?: string
  properties?: Record<string, unknown>
}

interface Action {
  name: string
}

interface EvaluationRequest {
  subject: Subject
  resource: Resource
  action: Action
  context?: Record<string, unknown>
}

interface EvaluationContext {
  reason?: string
  reason_code?: string
  policy_id?: string
  access_path?: string
}

interface EvaluationResponse {
  decision: boolean
  context?: EvaluationContext
}