Skip to content
NovaVMS Manual

Your first SDK call

By the end of this tutorial you will have installed the TypeScript SDK, authenticated with a service-account key, called cameras.list(), and printed the response. The SDK is @novavms/sdk and works in Node.js, Deno, Bun, and browsers (with the usual caveat that a browser bundle exposes the key to anyone who opens DevTools — see Step 10).

What you will need

  • Node.js 20 LTS or newer (or Deno 1.40+, or Bun 1.0+)
  • An API key sk_live_abc123 — see Your first curl Step 1 if you do not have one
  • A terminal and a text editor

Step 1 — Create a project

Terminal window
mkdir novavms-demo && cd novavms-demo
npm init -y
npm install @novavms/sdk
npm install -D typescript tsx @types/node
npx tsc --init

Step 2 — Store the key out of source control

Terminal window
echo 'NOVAVMS_KEY=sk_live_abc123' > .env
echo '.env' >> .gitignore

Step 3 — Create index.ts

// index.ts — @novavms/sdk >= 1.0.0
import 'dotenv/config';
import { createClient } from '@novavms/sdk';


const novavms = createClient({
  apiKey: process.env.NOVAVMS_KEY!,
  baseUrl: 'https://novavms.novalien.com/api/v1',
});


const { cameras, total } = await novavms.cameras.list();
console.log(`Found ${total} camera(s):`);
for (const cam of cameras) {
  console.log(`  ${cam.id}  ${cam.name}  [${cam.status}]`);
}

Step 4 — Run it

Terminal window
npx tsx index.ts

Expected output:

Found 1 camera(s):
  550e8400-e29b-41d4-a716-446655440000  Lobby Camera  [online]

Step 5 — Filter by site

cameras.list() accepts the same query parameters as the REST endpoint (since v1.0):

const online = await novavms.cameras.list({
  site_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
  status: 'online',
  limit: 50,
});

Step 6 — Fetch one camera

const cam = await novavms.cameras.get('550e8400-e29b-41d4-a716-446655440000');
console.log(cam.codec, cam.resolution_width, cam.resolution_height);

Step 7 — Handle errors

SDK errors subclass NovaVMSError and carry the HTTP status plus the server’s error code:

import { NovaVMSError } from '@novavms/sdk';


try {
  await novavms.cameras.get('00000000-0000-0000-0000-000000000000');
} catch (err) {
  if (err instanceof NovaVMSError && err.status === 404) {
    console.log('No such camera');
  } else {
    throw err;
  }
}

Step 8 — Respect rate limits

The SDK automatically retries on 429 using the Retry-After header, up to 3 times. Tune with maxRetries on the client.

Step 9 — Python equivalent

If you prefer Python, the novavms package (3.10+) exposes the same method names (since v1.0):

from novavms import Client
novavms = Client(api_key="sk_live_abc123")
page = novavms.cameras.list()
print(f"Found {page.total} camera(s)")
for cam in page.cameras:
    print(f"  {cam.id}  {cam.name}  [{cam.status}]")

Step 10 — What next

You have authenticated, listed cameras, and handled errors in both TypeScript and Python. Next: