@vigilisai/server-sdk

Server-side SDK for Vigilis AI API - Node.js/Vercel compatible

Installation

npm install @vigilisai/server-sdk

Usage

Token Exchange (Recommended)

Exchange Clerk tokens for longer-lived Vigilis AI JWTs (1 hour vs 50 seconds):

import { exchangeToken } from '@vigilisai/server-sdk';
import { auth } from '@clerk/nextjs/server';

// In Next.js API Route or Server Component
const { getToken } = auth();
const clerkToken = await getToken();

const result = await exchangeToken('your-org-slug', clerkToken, {
  expiresIn: 3600, // Optional: 1 hour (default)
});

// Use result.token with all server-sdk functions
const sites = await getSites('your-org-slug', {
  token: result.token,
});

See Token Exchange Guide for:

• Server-side caching patterns
• Next.js API route examples
• Server Components usage
• Production considerations

Get Site Operational Procedures

import { getSiteOperationalProcedures } from '@vigilisai/server-sdk';

// In Next.js API Route or Server Component
const procedures = await getSiteOperationalProcedures(
  'your-org-slug',
  'site-id',
  {
    token: 'your-auth-token', // Use exchanged Vigilis AI JWT
    fullContent: true,
    checkQuota: true,
  }
);

File Upload

import { uploadFileServer } from '@vigilisai/server-sdk';

// Upload a file from a Buffer
const result = await uploadFileServer(fileBuffer, '/org-slug/files', {
  token: 'your-auth-token',
  filename: 'document.pdf',
  contentType: 'application/pdf',
});

Features

• ✅ Node.js/Vercel compatible - No browser or React dependencies
• ✅ TypeScript support - Full type definitions included
• ✅ Lightweight - Only includes server-side functionality
• ✅ Works in Next.js - Server Components, API Routes, and Server Actions

API Reference

exchangeToken(organizationSlug, clerkToken, options?)

Exchange a Clerk token for a Vigilis AI JWT token. Returns a longer-lived token (up to 1 hour).

Parameters:

• organizationSlug (string): Organization slug
• clerkToken (string): Clerk JWT token
• options (object, optional):
  • expiresIn (number): Token expiration in seconds (default: 3600, max: 3600)
  • baseUrl (string): API base URL
  • apiRoot (string): API root path

Returns: Promise<TokenExchangeResponse> with token, expiresAt, and tokenType

Example:

const result = await exchangeToken('acme-security', clerkToken);
// Use result.token with all server-sdk functions

verifyToken(organizationSlug, token, options?)

Verify a Vigilis AI JWT or Clerk token and return its validity and claims.

Parameters:

• organizationSlug (string): Organization slug
• token (string): JWT token to verify
• options (object, optional): API options

Returns: Promise<TokenVerificationResponse> with validity and claims

Example:

const result = await verifyToken('acme-security', token);
if (result.valid) {
  console.log('User:', result.claims.sub);
  console.log('Expires:', result.claims.expiresAt);
}

getSiteOperationalProcedures(organizationSlug, siteId, options?)

Get operational procedures for a site.

Parameters:

• organizationSlug (string): Organization slug
• siteId (string): Site ID
• options (object, optional):
  • token (string): Authentication token
  • baseUrl (string): API base URL (defaults to process.env.VIGILIS_API_URL or https://api.vigilisai.com)
  • apiRoot (string): API root path (defaults to /)
  • fullContent (boolean): Return full content instead of summary
  • checkQuota (boolean): Check quota usage
  • contentLength (number): Content length in tokens
  • contentAllocationType (string): Content allocation type

Returns: Promise<OperationalProcedures>

uploadFileServer(fileBuffer, endpoint, options)

Upload a file from a Buffer.

Parameters:

• fileBuffer (Buffer): File data as Buffer
• endpoint (string): API endpoint (e.g., /{organization}/files)
• options (object):
  • token (string, optional): Authentication token
  • filename (string): Filename
  • contentType (string): Content type (e.g., image/jpeg, application/pdf)
  • additionalFields (object, optional): Additional form fields
  • baseUrl (string, optional): API base URL
  • apiRoot (string, optional): API root path

Returns: Promise<ServerUploadResult>

See the main API documentation for more upload functions and options.

Environment Variables

• VIGILIS_API_URL - API base URL (defaults to https://api.vigilisai.com)
• NEXT_PUBLIC_VIGILIS_API_URL - Alternative env var for Next.js (checked first)

Token Exchange

The server-sdk provides exchangeToken and verifyToken functions for working with Vigilis AI JWTs:

• Exchange tokens: Convert Clerk tokens to longer-lived Vigilis AI JWTs (1 hour vs 50 seconds)
• Verify tokens: Check token validity and extract claims
• Server-side caching: Reduce API calls with in-memory or Redis caching

See the Token Exchange Guide for complete examples and patterns.

License

ISC