@enkryptify/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enkryptify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @enkryptify/sdk
+
+[![CI](https://github.com/enkryptify/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/enkryptify/sdk/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@enkryptify/sdk)](https://www.npmjs.com/package/@enkryptify/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official TypeScript SDK for [Enkryptify](https://enkryptify.com) — fetch and manage secrets from the Enkryptify API.
+
+## Installation
+
+```bash
+pnpm add @enkryptify/sdk
+```
+
+```bash
+npm install @enkryptify/sdk
+```
+
+```bash
+yarn add @enkryptify/sdk
+```
+
+## Usage
+
+```typescript
+import Enkryptify from "@enkryptify/sdk";
+
+const client = new Enkryptify({
+  apiKey: "your-api-key",
+  workspaceId: "your-workspace-id",
+  projectId: "your-project-id",
+  environment: "production",
+});
+
+const dbUrl = await client.get("DATABASE_URL");
+console.log(dbUrl);
+```
+
+## API Reference
+
+### `new Enkryptify(config)`
+
+Creates a new Enkryptify client.
+
+| Parameter     | Type     | Description                           |
+| ------------- | -------- | ------------------------------------- |
+| `apiKey`      | `string` | Your Enkryptify API key               |
+| `workspaceId` | `string` | The workspace ID                      |
+| `projectId`   | `string` | The project ID                        |
+| `environment` | `string` | The environment (e.g. `"production"`) |
+
+### `client.get(key): Promise<string>`
+
+Fetches a secret by key. Throws `EnkryptifyError` if the secret is not found.
+
+### `EnkryptifyError`
+
+Custom error class for all SDK errors.
+
+## Development
+
+```bash
+# 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 check
+```
+
+## Contributing
+
+Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a pull request.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,529 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+// src/errors.ts
+var EnkryptifyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnkryptifyError";
+  }
+};
+var SecretNotFoundError = class extends EnkryptifyError {
+  constructor(key, workspace, environment) {
+    super(
+      `Secret "${key}" not found in workspace "${workspace}" (environment: "${environment}"). Verify the secret exists in your Enkryptify dashboard.
+Docs: https://docs.enkryptify.com/sdk/troubleshooting#secret-not-found`
+    );
+    this.name = "SecretNotFoundError";
+  }
+};
+var AuthenticationError = class extends EnkryptifyError {
+  constructor() {
+    super(
+      "Authentication failed (HTTP 401). Token is invalid, expired, or revoked. Generate a new token in your Enkryptify dashboard.\nDocs: https://docs.enkryptify.com/sdk/auth#token-issues"
+    );
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends EnkryptifyError {
+  constructor() {
+    super(
+      "Authorization failed (HTTP 403). Token does not have access to this resource. Check that your token has the required permissions.\nDocs: https://docs.enkryptify.com/sdk/auth#permissions"
+    );
+    this.name = "AuthorizationError";
+  }
+};
+var NotFoundError = class extends EnkryptifyError {
+  constructor(method, endpoint) {
+    super(
+      `Resource not found (HTTP 404) for ${method} ${endpoint}. Workspace, project, or environment not found. Verify your configuration.
+Docs: https://docs.enkryptify.com/sdk/troubleshooting#not-found`
+    );
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends EnkryptifyError {
+  retryAfter;
+  constructor(retryAfter) {
+    const parsed = retryAfter ? parseInt(retryAfter, 10) : null;
+    const retrySeconds = parsed !== null && !Number.isNaN(parsed) ? parsed : null;
+    super(
+      `Rate limited (HTTP 429). ${retrySeconds ? `Retry after ${retrySeconds} seconds.` : "Please retry later."}
+Docs: https://docs.enkryptify.com/sdk/troubleshooting#rate-limiting`
+    );
+    this.name = "RateLimitError";
+    this.retryAfter = retrySeconds;
+  }
+};
+var ApiError = class extends EnkryptifyError {
+  status;
+  constructor(status, statusText, method, endpoint) {
+    super(
+      `API request failed (HTTP ${status}) for ${method} ${endpoint}. ${statusText ? statusText + ". " : ""}This may be a temporary server issue \u2014 retry in a few moments.
+Docs: https://docs.enkryptify.com/sdk/troubleshooting#api-errors`
+    );
+    this.name = "ApiError";
+    this.status = status;
+  }
+};
+
+// src/internal/token-store.ts
+var store = /* @__PURE__ */ new WeakMap();
+function storeToken(provider, token) {
+  store.set(provider, token);
+}
+function retrieveToken(provider) {
+  const token = store.get(provider);
+  if (!token) {
+    throw new EnkryptifyError(
+      "Invalid or destroyed auth provider. Create a new one via Enkryptify.fromEnv().\nDocs: https://docs.enkryptify.com/sdk/auth"
+    );
+  }
+  return token;
+}
+
+// src/auth.ts
+var EnvAuthProvider = class {
+  _brand = "EnkryptifyAuthProvider";
+  constructor() {
+    const token = process.env.ENKRYPTIFY_TOKEN;
+    if (!token) {
+      throw new EnkryptifyError(
+        'ENKRYPTIFY_TOKEN environment variable is not set. Set it before initializing the SDK:\n  export ENKRYPTIFY_TOKEN="ek_..."\nDocs: https://docs.enkryptify.com/sdk/auth#environment-variables'
+      );
+    }
+    storeToken(this, token);
+  }
+};
+var TokenAuthProvider = class {
+  _brand = "EnkryptifyAuthProvider";
+  constructor(token) {
+    storeToken(this, token);
+  }
+};
+
+// src/api.ts
+var EnkryptifyApi = class {
+  #baseUrl;
+  #auth;
+  constructor(baseUrl, auth) {
+    this.#baseUrl = baseUrl;
+    this.#auth = auth;
+  }
+  async fetchSecret(workspace, project, secretName, environmentId) {
+    const path = `/v1/workspace/${encodeURIComponent(workspace)}/project/${encodeURIComponent(project)}/secret/${encodeURIComponent(secretName)}`;
+    const params = new URLSearchParams({ environmentId, resolve: "true" });
+    return this.#request("GET", `${path}?${params.toString()}`);
+  }
+  async fetchAllSecrets(workspace, project, environmentId) {
+    const path = `/v1/workspace/${encodeURIComponent(workspace)}/project/${encodeURIComponent(project)}/secret`;
+    const params = new URLSearchParams({ environmentId, resolve: "true" });
+    return this.#request("GET", `${path}?${params.toString()}`);
+  }
+  async #request(method, endpoint) {
+    const token = retrieveToken(this.#auth);
+    const url = `${this.#baseUrl}${endpoint}`;
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      }
+    });
+    if (response.status === 401) {
+      throw new AuthenticationError();
+    }
+    if (response.status === 403) {
+      throw new AuthorizationError();
+    }
+    if (response.status === 404) {
+      throw new NotFoundError(method, endpoint);
+    }
+    if (response.status === 429) {
+      throw new RateLimitError(response.headers.get("Retry-After"));
+    }
+    if (!response.ok) {
+      throw new ApiError(response.status, response.statusText, method, endpoint);
+    }
+    return response.json();
+  }
+};
+
+// src/cache.ts
+var SecretCache = class {
+  #store = /* @__PURE__ */ new Map();
+  #ttl;
+  constructor(ttl) {
+    this.#ttl = ttl;
+  }
+  get(key) {
+    const entry = this.#store.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+      this.#store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  set(key, value) {
+    this.#store.set(key, {
+      value,
+      expiresAt: this.#ttl === -1 ? null : Date.now() + this.#ttl
+    });
+  }
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+  clear() {
+    this.#store.clear();
+    this.#store = /* @__PURE__ */ new Map();
+  }
+  get size() {
+    return this.#store.size;
+  }
+};
+
+// src/logger.ts
+var LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var Logger = class {
+  #level;
+  constructor(level = "info") {
+    this.#level = LEVELS[level];
+  }
+  debug(message) {
+    if (this.#level <= LEVELS.debug) {
+      console.debug(`[Enkryptify] ${message}`);
+    }
+  }
+  info(message) {
+    if (this.#level <= LEVELS.info) {
+      console.info(`[Enkryptify] ${message}`);
+    }
+  }
+  warn(message) {
+    if (this.#level <= LEVELS.warn) {
+      console.warn(`[Enkryptify] ${message}`);
+    }
+  }
+  error(message) {
+    if (this.#level <= LEVELS.error) {
+      console.error(`[Enkryptify] ${message}`);
+    }
+  }
+};
+
+// src/token-exchange.ts
+var TokenExchangeManager = class {
+  #baseUrl;
+  #staticToken;
+  #auth;
+  #logger;
+  #jwt = null;
+  #refreshTimer = null;
+  #exchangePromise = null;
+  constructor(baseUrl, staticToken, auth, logger) {
+    this.#baseUrl = baseUrl;
+    this.#staticToken = staticToken;
+    this.#auth = auth;
+    this.#logger = logger;
+  }
+  async ensureToken() {
+    if (this.#jwt) return;
+    if (this.#exchangePromise) {
+      return this.#exchangePromise;
+    }
+    this.#exchangePromise = this.#exchange();
+    try {
+      await this.#exchangePromise;
+    } finally {
+      this.#exchangePromise = null;
+    }
+  }
+  async #exchange() {
+    try {
+      const response = await fetch(`${this.#baseUrl}/v1/auth/exchange`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.#staticToken}`,
+          "Content-Type": "application/json"
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Token exchange failed with HTTP ${response.status}`);
+      }
+      const data = await response.json();
+      this.#jwt = data.accessToken;
+      storeToken(this.#auth, this.#jwt);
+      this.#logger.debug("Token exchanged for short-lived JWT");
+      const refreshMs = (data.expiresIn - 60) * 1e3;
+      this.#scheduleRefresh(refreshMs);
+    } catch (error) {
+      this.#jwt = null;
+      storeToken(this.#auth, this.#staticToken);
+      this.#logger.warn(
+        `Token exchange failed, falling back to static token: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  #scheduleRefresh(ms) {
+    if (this.#refreshTimer) {
+      clearTimeout(this.#refreshTimer);
+    }
+    this.#refreshTimer = setTimeout(() => {
+      this.#jwt = null;
+      this.#exchange();
+    }, ms);
+    this.#refreshTimer.unref?.();
+  }
+  destroy() {
+    if (this.#refreshTimer) {
+      clearTimeout(this.#refreshTimer);
+      this.#refreshTimer = null;
+    }
+    this.#jwt = null;
+  }
+};
+
+// src/enkryptify.ts
+var Enkryptify = class _Enkryptify {
+  #api;
+  #cache;
+  #logger;
+  #workspace;
+  #project;
+  #environment;
+  #strict;
+  #usePersonalValues;
+  #cacheEnabled;
+  #eagerCache;
+  #destroyed = false;
+  #eagerLoaded = false;
+  #tokenExchange = null;
+  constructor(config) {
+    if (!config.workspace) {
+      throw new EnkryptifyError(
+        'Missing required config field "workspace". Provide a workspace slug or ID.\nDocs: https://docs.enkryptify.com/sdk/configuration'
+      );
+    }
+    if (!config.project) {
+      throw new EnkryptifyError(
+        'Missing required config field "project". Provide a project slug or ID.\nDocs: https://docs.enkryptify.com/sdk/configuration'
+      );
+    }
+    if (!config.environment) {
+      throw new EnkryptifyError(
+        'Missing required config field "environment". Provide an environment ID.\nDocs: https://docs.enkryptify.com/sdk/configuration'
+      );
+    }
+    let auth;
+    if (config.token) {
+      _Enkryptify.#validateTokenFormat(config.token);
+      auth = new TokenAuthProvider(config.token);
+    } else if (config.auth) {
+      if (config.auth._brand !== "EnkryptifyAuthProvider") {
+        throw new EnkryptifyError(
+          "Invalid auth provider. Use Enkryptify.fromEnv() or pass a token option.\nDocs: https://docs.enkryptify.com/sdk/auth"
+        );
+      }
+      auth = config.auth;
+    } else {
+      const envToken = process.env.ENKRYPTIFY_TOKEN;
+      if (!envToken) {
+        throw new EnkryptifyError(
+          "No token provided. Set ENKRYPTIFY_TOKEN or pass token in options.\nDocs: https://docs.enkryptify.com/sdk/auth"
+        );
+      }
+      _Enkryptify.#validateTokenFormat(envToken);
+      auth = new TokenAuthProvider(envToken);
+    }
+    retrieveToken(auth);
+    this.#workspace = config.workspace;
+    this.#project = config.project;
+    this.#environment = config.environment;
+    this.#strict = config.options?.strict ?? true;
+    this.#usePersonalValues = config.options?.usePersonalValues ?? true;
+    this.#cacheEnabled = config.cache?.enabled ?? true;
+    this.#eagerCache = config.cache?.eager ?? true;
+    const cacheTtl = config.cache?.ttl ?? -1;
+    this.#logger = new Logger(config.logger?.level ?? "info");
+    this.#cache = this.#cacheEnabled ? new SecretCache(cacheTtl) : null;
+    const baseUrl = config.baseUrl ?? "https://api.enkryptify.com";
+    this.#api = new EnkryptifyApi(baseUrl, auth);
+    if (config.useTokenExchange) {
+      const staticToken = retrieveToken(auth);
+      this.#tokenExchange = new TokenExchangeManager(baseUrl, staticToken, auth, this.#logger);
+    }
+    this.#logger.info(
+      `Initialized for workspace "${this.#workspace}", project "${this.#project}", environment "${this.#environment}"`
+    );
+  }
+  static fromEnv() {
+    return new EnvAuthProvider();
+  }
+  static #validateTokenFormat(token) {
+    if (!token) {
+      throw new EnkryptifyError("Token must be a non-empty string.\nDocs: https://docs.enkryptify.com/sdk/auth");
+    }
+    if (token.startsWith("ek_live_")) return;
+    const dotCount = token.split(".").length - 1;
+    if (dotCount === 2) return;
+    throw new EnkryptifyError(
+      "Invalid token format. Expected an ek_live_ token or JWT.\nDocs: https://docs.enkryptify.com/sdk/auth#token-format"
+    );
+  }
+  async get(key, options) {
+    this.#guardDestroyed();
+    const useCache = this.#cacheEnabled && options?.cache !== false;
+    if (useCache && this.#cache) {
+      const cached = this.#cache.get(key);
+      if (cached !== void 0) {
+        this.#logger.debug(`Cache hit for secret "${key}"`);
+        return cached;
+      }
+      this.#logger.debug(`Cache miss for secret "${key}", fetching from API`);
+    }
+    await this.#tokenExchange?.ensureToken();
+    if (useCache && this.#eagerCache && !this.#eagerLoaded) {
+      return this.#fetchAndCacheAll(key);
+    }
+    return this.#fetchAndCacheSingle(key);
+  }
+  getFromCache(key) {
+    this.#guardDestroyed();
+    if (!this.#cacheEnabled || !this.#cache) {
+      throw new EnkryptifyError(
+        "Cache is disabled. Enable caching in the config or use get() to fetch from the API.\nDocs: https://docs.enkryptify.com/sdk/configuration#caching"
+      );
+    }
+    const value = this.#cache.get(key);
+    if (value === void 0) {
+      throw new SecretNotFoundError(key, this.#workspace, this.#environment);
+    }
+    return value;
+  }
+  async preload() {
+    this.#guardDestroyed();
+    if (!this.#cacheEnabled || !this.#cache) {
+      throw new EnkryptifyError(
+        "Cannot preload: caching is disabled. Enable caching in the config.\nDocs: https://docs.enkryptify.com/sdk/configuration#caching"
+      );
+    }
+    await this.#tokenExchange?.ensureToken();
+    const secrets = await this.#api.fetchAllSecrets(this.#workspace, this.#project, this.#environment);
+    let count = 0;
+    for (const secret of secrets) {
+      const value = this.#resolveValue(secret);
+      if (value !== void 0) {
+        this.#cache.set(secret.name, value);
+        count++;
+      }
+    }
+    this.#eagerLoaded = true;
+    this.#logger.info(`Preloaded ${count} secrets into cache`);
+  }
+  destroy() {
+    if (this.#destroyed) return;
+    this.#tokenExchange?.destroy();
+    this.#cache?.clear();
+    this.#destroyed = true;
+    this.#logger.info("Client destroyed, all cached secrets cleared");
+  }
+  #guardDestroyed() {
+    if (this.#destroyed) {
+      throw new EnkryptifyError(
+        "This Enkryptify client has been destroyed. Create a new instance to continue.\nDocs: https://docs.enkryptify.com/sdk/lifecycle"
+      );
+    }
+  }
+  async #fetchAndCacheAll(key) {
+    this.#logger.debug(
+      `Fetching secret(s) from API: GET /v1/workspace/${this.#workspace}/project/${this.#project}/secret`
+    );
+    const start = Date.now();
+    const secrets = await this.#api.fetchAllSecrets(this.#workspace, this.#project, this.#environment);
+    this.#logger.debug(`API responded with ${secrets.length} secret(s) in ${Date.now() - start}ms`);
+    let found;
+    for (const secret of secrets) {
+      const value = this.#resolveValue(secret);
+      if (value !== void 0 && this.#cache) {
+        this.#cache.set(secret.name, value);
+        this.#logger.debug(
+          `Cached secret "${secret.name}" (${this.#cache ? "TTL: cache configured" : "no expiry"})`
+        );
+      }
+      if (secret.name === key) {
+        found = value;
+      }
+    }
+    this.#eagerLoaded = true;
+    if (found !== void 0) {
+      return found;
+    }
+    return this.#handleNotFound(key);
+  }
+  async #fetchAndCacheSingle(key) {
+    this.#logger.debug(
+      `Fetching secret(s) from API: GET /v1/workspace/${this.#workspace}/project/${this.#project}/secret/${key}`
+    );
+    let secret;
+    try {
+      const start = Date.now();
+      secret = await this.#api.fetchSecret(this.#workspace, this.#project, key, this.#environment);
+      this.#logger.debug(`API responded with 1 secret(s) in ${Date.now() - start}ms`);
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        return this.#handleNotFound(key);
+      }
+      throw error;
+    }
+    const value = this.#resolveValue(secret);
+    if (value === void 0) {
+      return this.#handleNotFound(key);
+    }
+    if (this.#cacheEnabled && this.#cache) {
+      this.#cache.set(key, value);
+    }
+    return value;
+  }
+  #handleNotFound(key) {
+    if (this.#strict) {
+      throw new SecretNotFoundError(key, this.#workspace, this.#environment);
+    }
+    this.#logger.warn(`Secret "${key}" not found (strict mode disabled, returning empty string)`);
+    return "";
+  }
+  #resolveValue(secret) {
+    const envValues = secret.values.filter((v) => v.environmentId === this.#environment);
+    if (this.#usePersonalValues) {
+      const personal = envValues.find((v) => v.isPersonal);
+      if (personal) return personal.value;
+      const shared = envValues.find((v) => !v.isPersonal);
+      if (shared) {
+        this.#logger.warn(`No personal value for "${secret.name}", falling back to shared value`);
+        return shared.value;
+      }
+    } else {
+      const shared = envValues.find((v) => !v.isPersonal);
+      if (shared) return shared.value;
+    }
+    return void 0;
+  }
+};
+
+exports.ApiError = ApiError;
+exports.AuthenticationError = AuthenticationError;
+exports.AuthorizationError = AuthorizationError;
+exports.Enkryptify = Enkryptify;
+exports.EnkryptifyError = EnkryptifyError;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;
+exports.SecretNotFoundError = SecretNotFoundError;
+exports.default = Enkryptify;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map