@enkryptify/sdk

Official TypeScript SDK for Enkryptify — fetch and manage secrets from the Enkryptify API.

Installation

pnpm add @enkryptify/sdk

npm install @enkryptify/sdk

yarn add @enkryptify/sdk

Quick Start

import Enkryptify from "@enkryptify/sdk";

const client = new Enkryptify({
    auth: Enkryptify.fromEnv(),
    workspace: "my-workspace",
    project: "my-project",
    environment: "env-id",
});

const dbUrl = await client.get("DATABASE_URL");

Usage

Preloading Secrets

When caching is enabled (the default), you can preload all secrets up front. This makes subsequent get() and getFromCache() calls instant.

const client = new Enkryptify({
    auth: Enkryptify.fromEnv(),
    workspace: "my-workspace",
    project: "my-project",
    environment: "env-id",
});

await client.preload();

// Synchronous — no API call needed
const dbHost = client.getFromCache("DB_HOST");
const dbPort = client.getFromCache("DB_PORT");

Eager Caching

By default cache.eager is true. This means the first get() call fetches all secrets and caches them, so subsequent calls are served from the cache without additional API requests.

// First call fetches all secrets from the API
const dbHost = await client.get("DB_HOST");

// Second call is served from cache — no API call
const dbPort = await client.get("DB_PORT");

Set cache.eager to false to fetch secrets individually:

const client = new Enkryptify({
    auth: Enkryptify.fromEnv(),
    workspace: "my-workspace",
    project: "my-project",
    environment: "env-id",
    cache: { eager: false },
});

// Each call fetches only the requested secret
const dbHost = await client.get("DB_HOST");
const dbPort = await client.get("DB_PORT");

Bypassing the Cache

Pass { cache: false } to always fetch a fresh value from the API:

const secret = await client.get("ROTATING_KEY", { cache: false });

Strict vs Non-Strict Mode

By default, get() throws a SecretNotFoundError when a key doesn't exist. Disable strict mode to return an empty string instead:

const client = new Enkryptify({
    auth: Enkryptify.fromEnv(),
    workspace: "my-workspace",
    project: "my-project",
    environment: "env-id",
    options: { strict: false },
});

const value = await client.get("MAYBE_MISSING"); // "" if not found

Personal Values

When usePersonalValues is true (the default), the SDK prefers your personal override for a secret. If no personal value exists, it falls back to the shared value.

const client = new Enkryptify({
    auth: Enkryptify.fromEnv(),
    workspace: "my-workspace",
    project: "my-project",
    environment: "env-id",
    options: { usePersonalValues: false }, // always use shared values
});

Cleanup

Destroy the client when you're done to clear all cached secrets from memory:

client.destroy();

Configuration

| Option | Type | Default | Description | | --------------------------- | ---------------------------------------- | ------------------------------ | ------------------------------------------------ | | auth | EnkryptifyAuthProvider | required | Auth provider created via Enkryptify.fromEnv() | | workspace | string | required | Workspace slug or ID | | project | string | required | Project slug or ID | | environment | string | required | Environment ID | | baseUrl | string | "https://api.enkryptify.com" | API base URL | | options.strict | boolean | true | Throw on missing secrets | | options.usePersonalValues | boolean | true | Prefer personal secret values | | cache.enabled | boolean | true | Enable in-memory caching | | cache.ttl | number | -1 | Cache TTL in ms (-1 = never expire) | | cache.eager | boolean | true | Fetch all secrets on first get() | | logger.level | "debug" \| "info" \| "warn" \| "error" | "info" | Minimum log level |

API Reference

Enkryptify.fromEnv(): EnkryptifyAuthProvider

Creates an auth provider by reading the ENKRYPTIFY_TOKEN environment variable.

client.get(key, options?): Promise<string>

Fetches a secret by key. Uses the cache when available, otherwise calls the API.

• key — the secret name
• options.cache — set to false to bypass the cache (default: true)

client.getFromCache(key): string

Returns a secret from the cache synchronously. Throws if the key is not cached or caching is disabled.

client.preload(): Promise<void>

Fetches all secrets and populates the cache. Throws if caching is disabled.

client.destroy(): void

Clears the cache and marks the client as destroyed. All subsequent method calls will throw.

Error Handling

The SDK provides specific error classes so you can handle different failure modes:

import Enkryptify, { SecretNotFoundError, AuthenticationError, ApiError } from "@enkryptify/sdk";

try {
    const value = await client.get("MY_SECRET");
} catch (error) {
    if (error instanceof SecretNotFoundError) {
        // Secret doesn't exist in the project/environment
    } else if (error instanceof AuthenticationError) {
        // Token is invalid or expired (HTTP 401/403)
    } else if (error instanceof ApiError) {
        // Other API error (500, network issues, etc.)
    }
}

| Error Class | When | | --------------------- | ----------------------------------------------- | | EnkryptifyError | Base class for all SDK errors | | SecretNotFoundError | Secret key not found in the project/environment | | AuthenticationError | HTTP 401 or 403 from the API | | ApiError | Any other non-OK HTTP response |

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Lint
pnpm lint

# Format
pnpm format

# Typecheck
pnpm typecheck

Contributing

Please read our Contributing Guide before submitting a pull request.

License

MIT