JavaScript / TypeScript SDK

Roadmap feature

The SyVault JavaScript/TypeScript SDK is in alpha (v0.1.0) and not yet published to npm. The package name (@syvault/sdk) will be published when the SDK reaches a stable release. Track progress in sdks/javascript/.

The official SyVault SDK for Node.js, Deno, and edge runtimes. It handles authentication, decryption, and secret retrieval so you can access secrets with a few lines of code.

Installation

npm install @syvault/sdk

Or with Yarn / pnpm:

yarn add @syvault/sdk
pnpm add @syvault/sdk

Authentication

Every SDK operation requires a client that has been bootstrapped. Pass the clientId and clientSecret (the base64-encoded private key created during bootstrap) when constructing the client:

import { SyVaultClient } from "@syvault/sdk";

const sy = new SyVaultClient({
  server: "https://vault.example.com",
  clientId: "c9a1b2d3-4e5f-6789-abcd-ef0123456789",
  clientSecret: process.env.SY_CLIENT_SECRET,
});

The SDK signs each request with an ECDSA P-256 JWT automatically. Tokens are refreshed in the background before they expire.

Fetching Secrets

List all secrets

const secrets = await sy.secrets.list();

for (const secret of secrets) {
  console.log(secret.uid, secret.title);
}

Get a full secret

const secret = await sy.secrets.get("7Kj9mNpQ2xRs");

console.log(secret.fields.host);     // "db.example.com"
console.log(secret.fields.password);  // "s3cret!"

Get a single field by notation

const password = await sy.secrets.notation(
  "sy://Production/Database/field/password"
);

console.log(password); // "s3cret!"

Creating Secrets

Clients with write-enabled folder access can create secrets:

const newSecret = await sy.secrets.create({
  folderId: "folder-uuid-here",
  title: "Stripe API Key",
  fields: {
    key: "sk_live_abc123",
    environment: "production",
  },
});

console.log(newSecret.uid); // "Xp4qRtY8mNwK"

Rotating Secrets

Trigger rotation for a secret that has a rotation policy configured:

const result = await sy.secrets.rotate("7Kj9mNpQ2xRs");

console.log(result.status);    // "completed"
console.log(result.newFields); // { username: "app_prod_a8f3", password: "..." }

Error Handling

The SDK throws typed errors for common failure modes:

import { SyVaultClient, SecretNotFoundError, AuthError } from "@syvault/sdk";

try {
  const secret = await sy.secrets.get("nonexistent");
} catch (err) {
  if (err instanceof SecretNotFoundError) {
    console.error("Secret does not exist:", err.uid);
  } else if (err instanceof AuthError) {
    console.error("Authentication failed — check client credentials");
  } else {
    throw err;
  }
}

Caching

By default the SDK caches decrypted secrets in memory for 60 seconds. You can adjust or disable this:

const sy = new SyVaultClient({
  server: "https://vault.example.com",
  clientId: "...",
  clientSecret: "...",
  cache: {
    ttl: 300,   // 5 minutes
    max: 500,   // max entries
  },
});

// Or disable caching entirely
const vf2 = new SyVaultClient({
  // ...
  cache: false,
});

Deno

The SDK works with Deno out of the box. Import from npm:

import { SyVaultClient } from "npm:@syvault/sdk";

const sy = new SyVaultClient({
  server: "https://vault.example.com",
  clientId: Deno.env.get("SY_CLIENT_ID")!,
  clientSecret: Deno.env.get("SY_CLIENT_SECRET")!,
});

const dbPassword = await sy.secrets.notation(
  "sy://Production/Database/field/password"
);

Express.js Example

A complete example injecting database credentials at startup:

import express from "express";
import pg from "pg";
import { SyVaultClient } from "@syvault/sdk";

const sy = new SyVaultClient({
  server: process.env.SY_SERVER!,
  clientId: process.env.SY_CLIENT_ID!,
  clientSecret: process.env.SY_CLIENT_SECRET!,
});

async function main() {
  const dbSecret = await sy.secrets.get("7Kj9mNpQ2xRs");

  const pool = new pg.Pool({
    host: dbSecret.fields.host,
    port: Number(dbSecret.fields.port),
    user: dbSecret.fields.username,
    password: dbSecret.fields.password,
    database: dbSecret.fields.database,
  });

  const app = express();

  app.get("/health", async (_req, res) => {
    const { rows } = await pool.query("SELECT 1");
    res.json({ ok: true });
  });

  app.listen(3000, () => console.log("Listening on :3000"));
}

main();