@secretenvs/sdk 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ankit Yadav
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @secretenvs/sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Node client for reading SecretEnvs variables. It uses the built-in `fetch`
4
+ (Node 18+), ships ESM, CommonJS and type declarations, and depends only on
5
+ `@secretenvs/contracts`.
6
+
7
+ ```ts
8
+ import { SecretEnvs } from '@secretenvs/sdk';
9
+
10
+ const secretenvs = new SecretEnvs({
11
+ token: process.env.SECRETENVS_TOKEN, // required
12
+ baseUrl: process.env.SECRETENVS_URL, // required, e.g. http://localhost:3000 in dev
13
+ });
14
+
15
+ // 1. All variables as an object
16
+ const vars = await secretenvs.getVariables({
17
+ project: 'my-app',
18
+ environment: 'production',
19
+ });
20
+
21
+ // 2. One value
22
+ const apiKey = await secretenvs.get({
23
+ project: 'my-app',
24
+ environment: 'production',
25
+ key: 'API_KEY',
26
+ });
27
+
28
+ // 3. Inject into process.env (existing variables win unless { override: true })
29
+ await secretenvs.load({ project: 'my-app', environment: 'production' });
30
+ ```
31
+
32
+ Projects and environments are addressed by **slug**. Tokens are created in the
33
+ web app (Settings → Tokens) or by `secretenvs login`; `READ` access is enough.
34
+
35
+ ## Options
36
+
37
+ | Option | Fallback env var | Default | Notes |
38
+ | -------------- | -------------------- | ------------- | -------------------------------------------------- |
39
+ | `token` | `SECRETENVS_TOKEN` | — | Required. |
40
+ | `baseUrl` | `SECRETENVS_URL` | — | Required. `https` only, `http` for localhost only. |
41
+ | `project` | `SECRETENVS_PROJECT` | — | Default for every call. |
42
+ | `environment` | `SECRETENVS_ENV` | — | Default for every call. |
43
+ | `timeoutMs` | | `10000` | Per attempt. |
44
+ | `retries` | | `2` | Network errors and 5xx only, exponential backoff. |
45
+ | `retryDelayMs` | | `200` | Base delay; doubles on each retry. |
46
+ | `cacheTtlMs` | | `0` | In-memory cache; `0` disables it. |
47
+ | `fetch` | | global | Custom implementation (for tests). |
48
+ | `env` | | `process.env` | Source of fallbacks and target of `load()`. |
49
+
50
+ With those variables set, `new SecretEnvs()` and `await secretenvs.load()` need
51
+ no arguments.
52
+
53
+ ## Other methods
54
+
55
+ - `getResolved(target)` returns `{ project, environment, variables[] }` where each
56
+ variable has `{ key, value, source: 'environment' | 'shared' }`.
57
+ - `listProjects()` returns the projects and environments visible to the token.
58
+ - `clearCache()` empties the in-memory cache.
59
+
60
+ ## Errors
61
+
62
+ All errors extend `SecretEnvsError`.
63
+
64
+ | Error | When |
65
+ | ------------------------- | ---------------------------------------------------------- |
66
+ | `SecretEnvsAuthError` | 401 / 403: bad, revoked or expired token, or no access. |
67
+ | `SecretEnvsNotFoundError` | 404, or a `get()` key that is not defined. |
68
+ | `SecretEnvsApiError` | Any other error status or unexpected response (`.status`). |
69
+ | `SecretEnvsNetworkError` | Connection failure or timeout (after retries). |
70
+
71
+ ## Security notes
72
+
73
+ - HTTPS is required; plain `http://` is accepted only for `localhost`,
74
+ `127.0.0.1` and `[::1]`. TLS verification is never disabled and redirects are
75
+ not followed.
76
+ - The client never logs values, and `toString()`, `toJSON()` and `util.inspect`
77
+ do not expose the token.
78
+ - The SDK always returns **current** values. Reading older versions is a
79
+ management feature of the web app and the CLI.
80
+
81
+ ## Development
82
+
83
+ ```bash
84
+ yarn workspace @secretenvs/sdk build
85
+ yarn workspace @secretenvs/sdk test
86
+ ```
87
+
88
+ `examples/basic-usage.ts` at the repository root is an integration script that
89
+ runs against a local API; see its header for the required environment variables.
package/dist/index.cjs ADDED
@@ -0,0 +1,319 @@
1
+ "use strict";
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
6
+ var __export = (target, all) => {
7
+ for (var name in all)
8
+ __defProp(target, name, { get: all[name], enumerable: true });
9
+ };
10
+ var __copyProps = (to, from, except, desc) => {
11
+ if (from && typeof from === "object" || typeof from === "function") {
12
+ for (let key of __getOwnPropNames(from))
13
+ if (!__hasOwnProp.call(to, key) && key !== except)
14
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
+ }
16
+ return to;
17
+ };
18
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
+
20
+ // src/index.ts
21
+ var index_exports = {};
22
+ __export(index_exports, {
23
+ SecretEnvs: () => SecretEnvs,
24
+ SecretEnvsApiError: () => SecretEnvsApiError,
25
+ SecretEnvsAuthError: () => SecretEnvsAuthError,
26
+ SecretEnvsError: () => SecretEnvsError,
27
+ SecretEnvsNetworkError: () => SecretEnvsNetworkError,
28
+ SecretEnvsNotFoundError: () => SecretEnvsNotFoundError,
29
+ normalizeBaseUrl: () => normalizeBaseUrl
30
+ });
31
+ module.exports = __toCommonJS(index_exports);
32
+
33
+ // src/errors.ts
34
+ var SecretEnvsError = class extends Error {
35
+ constructor(message, options) {
36
+ super(message, options);
37
+ this.name = "SecretEnvsError";
38
+ }
39
+ };
40
+ var SecretEnvsNetworkError = class extends SecretEnvsError {
41
+ constructor(message, options) {
42
+ super(message, options);
43
+ this.name = "SecretEnvsNetworkError";
44
+ }
45
+ };
46
+ var SecretEnvsApiError = class extends SecretEnvsError {
47
+ constructor(message, status, code) {
48
+ super(message);
49
+ this.status = status;
50
+ this.code = code;
51
+ this.name = "SecretEnvsApiError";
52
+ }
53
+ status;
54
+ code;
55
+ };
56
+ var SecretEnvsAuthError = class extends SecretEnvsApiError {
57
+ constructor(message, status, code) {
58
+ super(message, status, code);
59
+ this.name = "SecretEnvsAuthError";
60
+ }
61
+ };
62
+ var SecretEnvsNotFoundError = class extends SecretEnvsApiError {
63
+ constructor(message, status = 404, code) {
64
+ super(message, status, code);
65
+ this.name = "SecretEnvsNotFoundError";
66
+ }
67
+ };
68
+
69
+ // src/client.ts
70
+ var import_contracts = require("@secretenvs/contracts");
71
+ var DEFAULT_TIMEOUT_MS = 1e4;
72
+ var DEFAULT_RETRIES = 2;
73
+ var DEFAULT_RETRY_DELAY_MS = 200;
74
+ var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
75
+ var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
76
+ function nonEmpty(value) {
77
+ return value === void 0 || value === "" ? void 0 : value;
78
+ }
79
+ function normalizeBaseUrl(raw) {
80
+ let url;
81
+ try {
82
+ url = new URL(raw);
83
+ } catch {
84
+ throw new SecretEnvsError("baseUrl is not a valid URL");
85
+ }
86
+ if (url.username || url.password) {
87
+ throw new SecretEnvsError("baseUrl must not contain credentials");
88
+ }
89
+ const isLocalHttp = url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
90
+ if (url.protocol !== "https:" && !isLocalHttp) {
91
+ throw new SecretEnvsError(
92
+ "baseUrl must use https (http is only allowed for localhost)"
93
+ );
94
+ }
95
+ return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
96
+ }
97
+ function integerOption(name, value, fallback, min) {
98
+ if (value === void 0) return fallback;
99
+ if (!Number.isInteger(value) || value < min) {
100
+ throw new SecretEnvsError(`${name} must be an integer >= ${min}`);
101
+ }
102
+ return value;
103
+ }
104
+ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
105
+ var SecretEnvs = class {
106
+ #token;
107
+ #baseUrl;
108
+ #project;
109
+ #environment;
110
+ #timeoutMs;
111
+ #retries;
112
+ #retryDelayMs;
113
+ #cacheTtlMs;
114
+ #fetch;
115
+ #env;
116
+ #cache = /* @__PURE__ */ new Map();
117
+ constructor(options = {}) {
118
+ const env = options.env ?? process.env;
119
+ const token = nonEmpty(options.token) ?? nonEmpty(env.SECRETENVS_TOKEN);
120
+ const baseUrl = nonEmpty(options.baseUrl) ?? nonEmpty(env.SECRETENVS_URL);
121
+ if (!token) {
122
+ throw new SecretEnvsError(
123
+ 'A token is required (option "token" or SECRETENVS_TOKEN)'
124
+ );
125
+ }
126
+ if (!baseUrl) {
127
+ throw new SecretEnvsError(
128
+ 'A base URL is required (option "baseUrl" or SECRETENVS_URL)'
129
+ );
130
+ }
131
+ const fetchImpl = options.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
132
+ if (!fetchImpl) {
133
+ throw new SecretEnvsError("fetch is not available (Node 18+ required)");
134
+ }
135
+ this.#token = token;
136
+ this.#baseUrl = normalizeBaseUrl(baseUrl);
137
+ this.#project = nonEmpty(options.project) ?? nonEmpty(env.SECRETENVS_PROJECT);
138
+ this.#environment = nonEmpty(options.environment) ?? nonEmpty(env.SECRETENVS_ENV);
139
+ this.#timeoutMs = integerOption(
140
+ "timeoutMs",
141
+ options.timeoutMs,
142
+ DEFAULT_TIMEOUT_MS,
143
+ 1
144
+ );
145
+ this.#retries = integerOption(
146
+ "retries",
147
+ options.retries,
148
+ DEFAULT_RETRIES,
149
+ 0
150
+ );
151
+ this.#retryDelayMs = integerOption(
152
+ "retryDelayMs",
153
+ options.retryDelayMs,
154
+ DEFAULT_RETRY_DELAY_MS,
155
+ 0
156
+ );
157
+ this.#cacheTtlMs = integerOption("cacheTtlMs", options.cacheTtlMs, 0, 0);
158
+ this.#fetch = fetchImpl;
159
+ this.#env = env;
160
+ }
161
+ /** Projects visible to the token, with their environments. */
162
+ async listProjects() {
163
+ return this.#get(
164
+ "/api/v1/sdk/projects",
165
+ (body) => import_contracts.SdkProjectDto.array().parse(body)
166
+ );
167
+ }
168
+ /** Resolved variables including where each value comes from. */
169
+ async getResolved(target = {}) {
170
+ const { project, environment } = this.#target(target);
171
+ const key = `${project}/${environment}`;
172
+ if (this.#cacheTtlMs > 0) {
173
+ const cached = this.#cache.get(key);
174
+ if (cached && cached.expiresAt > Date.now()) {
175
+ return structuredClone(cached.data);
176
+ }
177
+ }
178
+ const data = await this.#get(
179
+ `/api/v1/sdk/projects/${encodeURIComponent(project)}/environments/${encodeURIComponent(environment)}/variables`,
180
+ (body) => import_contracts.ResolvedVariablesResponse.parse(body)
181
+ );
182
+ if (this.#cacheTtlMs > 0) {
183
+ this.#cache.set(key, {
184
+ expiresAt: Date.now() + this.#cacheTtlMs,
185
+ data: structuredClone(data)
186
+ });
187
+ }
188
+ return data;
189
+ }
190
+ /** All variables of an environment as a plain object. */
191
+ async getVariables(target = {}) {
192
+ const { variables } = await this.getResolved(target);
193
+ return Object.fromEntries(variables.map(({ key, value }) => [key, value]));
194
+ }
195
+ /** A single value; throws SecretEnvsNotFoundError when the key is not defined. */
196
+ async get(target) {
197
+ const { variables } = await this.getResolved(target);
198
+ const found = variables.find((variable) => variable.key === target.key);
199
+ if (!found) {
200
+ throw new SecretEnvsNotFoundError(`Variable ${target.key} was not found`);
201
+ }
202
+ return found.value;
203
+ }
204
+ /** Injects variables into the environment; existing values win unless override is set. */
205
+ async load(target = {}) {
206
+ const variables = await this.getVariables(target);
207
+ for (const [key, value] of Object.entries(variables)) {
208
+ if (target.override || this.#env[key] === void 0) {
209
+ this.#env[key] = value;
210
+ }
211
+ }
212
+ }
213
+ clearCache() {
214
+ this.#cache.clear();
215
+ }
216
+ toString() {
217
+ return `SecretEnvs(${this.#baseUrl})`;
218
+ }
219
+ toJSON() {
220
+ return { baseUrl: this.#baseUrl };
221
+ }
222
+ [INSPECT]() {
223
+ return this.toString();
224
+ }
225
+ #target(target) {
226
+ const project = target.project ?? this.#project;
227
+ const environment = target.environment ?? this.#environment;
228
+ if (!project) {
229
+ throw new SecretEnvsError(
230
+ 'A project is required (argument "project" or SECRETENVS_PROJECT)'
231
+ );
232
+ }
233
+ if (!environment) {
234
+ throw new SecretEnvsError(
235
+ 'An environment is required (argument "environment" or SECRETENVS_ENV)'
236
+ );
237
+ }
238
+ return { project, environment };
239
+ }
240
+ // Retries only network errors and 5xx responses, with exponential backoff.
241
+ async #get(path, parse) {
242
+ const url = `${this.#baseUrl}${path}`;
243
+ for (let attempt = 0; ; attempt += 1) {
244
+ const canRetry = attempt < this.#retries;
245
+ try {
246
+ const { status, body } = await this.#attempt(url);
247
+ if (status >= 500 && canRetry) {
248
+ await sleep(this.#retryDelayMs * 2 ** attempt);
249
+ continue;
250
+ }
251
+ return this.#handle(status, body, parse);
252
+ } catch (error) {
253
+ if (error instanceof SecretEnvsNetworkError && canRetry) {
254
+ await sleep(this.#retryDelayMs * 2 ** attempt);
255
+ continue;
256
+ }
257
+ throw error;
258
+ }
259
+ }
260
+ }
261
+ async #attempt(url) {
262
+ const controller = new AbortController();
263
+ const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
264
+ try {
265
+ const response = await this.#fetch(url, {
266
+ method: "GET",
267
+ headers: {
268
+ Authorization: `Bearer ${this.#token}`,
269
+ Accept: "application/json"
270
+ },
271
+ signal: controller.signal,
272
+ redirect: "error"
273
+ });
274
+ let body;
275
+ try {
276
+ body = await response.json();
277
+ } catch (error) {
278
+ if (controller.signal.aborted) throw error;
279
+ body = void 0;
280
+ }
281
+ return { status: response.status, body };
282
+ } catch (error) {
283
+ throw new SecretEnvsNetworkError(
284
+ controller.signal.aborted ? `Request timed out after ${this.#timeoutMs}ms` : "Network request failed",
285
+ { cause: error }
286
+ );
287
+ } finally {
288
+ clearTimeout(timer);
289
+ }
290
+ }
291
+ #handle(status, body, parse) {
292
+ if (status >= 200 && status < 300) {
293
+ try {
294
+ return parse(body);
295
+ } catch {
296
+ throw new SecretEnvsApiError("Unexpected response from server", status);
297
+ }
298
+ }
299
+ const parsed = import_contracts.ApiErrorBody.safeParse(body);
300
+ const message = parsed.success ? parsed.data.error.message : `Request failed with status ${status}`;
301
+ const code = parsed.success ? parsed.data.error.code : void 0;
302
+ if (status === 401 || status === 403) {
303
+ throw new SecretEnvsAuthError(message, status, code);
304
+ }
305
+ if (status === 404)
306
+ throw new SecretEnvsNotFoundError(message, status, code);
307
+ throw new SecretEnvsApiError(message, status, code);
308
+ }
309
+ };
310
+ // Annotate the CommonJS export names for ESM import in node:
311
+ 0 && (module.exports = {
312
+ SecretEnvs,
313
+ SecretEnvsApiError,
314
+ SecretEnvsAuthError,
315
+ SecretEnvsError,
316
+ SecretEnvsNetworkError,
317
+ SecretEnvsNotFoundError,
318
+ normalizeBaseUrl
319
+ });
@@ -0,0 +1,96 @@
1
+ import { ResolvedVariablesResponse } from '@secretenvs/contracts';
2
+ export { ResolvedVariableDto, ResolvedVariablesResponse, SdkProjectDto } from '@secretenvs/contracts';
3
+
4
+ declare class SecretEnvsError extends Error {
5
+ constructor(message: string, options?: {
6
+ cause?: unknown;
7
+ });
8
+ }
9
+ declare class SecretEnvsNetworkError extends SecretEnvsError {
10
+ constructor(message: string, options?: {
11
+ cause?: unknown;
12
+ });
13
+ }
14
+ declare class SecretEnvsApiError extends SecretEnvsError {
15
+ readonly status: number;
16
+ readonly code?: string | undefined;
17
+ constructor(message: string, status: number, code?: string | undefined);
18
+ }
19
+ declare class SecretEnvsAuthError extends SecretEnvsApiError {
20
+ constructor(message: string, status: number, code?: string);
21
+ }
22
+ declare class SecretEnvsNotFoundError extends SecretEnvsApiError {
23
+ constructor(message: string, status?: number, code?: string);
24
+ }
25
+
26
+ interface FetchInit {
27
+ method: 'GET';
28
+ headers: Record<string, string>;
29
+ signal: AbortSignal;
30
+ redirect: 'error';
31
+ }
32
+ type FetchLike = (url: string, init: FetchInit) => Promise<Response>;
33
+ interface SecretEnvsOptions {
34
+ /** API token. Falls back to SECRETENVS_TOKEN. */
35
+ token?: string;
36
+ /** Server origin, e.g. https://vault.example.com. Falls back to SECRETENVS_URL. */
37
+ baseUrl?: string;
38
+ /** Default project slug. Falls back to SECRETENVS_PROJECT. */
39
+ project?: string;
40
+ /** Default environment slug. Falls back to SECRETENVS_ENV. */
41
+ environment?: string;
42
+ /** Per-attempt timeout in milliseconds. Default 10000. */
43
+ timeoutMs?: number;
44
+ /** Retries for network errors and 5xx responses. Default 2. */
45
+ retries?: number;
46
+ /** Base delay for exponential backoff between retries. Default 200. */
47
+ retryDelayMs?: number;
48
+ /** In-memory cache lifetime in milliseconds. 0 (default) disables caching. */
49
+ cacheTtlMs?: number;
50
+ /** Custom fetch implementation; defaults to the global fetch. */
51
+ fetch?: FetchLike;
52
+ /** Environment used for option fallbacks and by load(). Defaults to process.env. */
53
+ env?: Record<string, string | undefined>;
54
+ }
55
+ interface TargetOptions {
56
+ project?: string;
57
+ environment?: string;
58
+ }
59
+ declare const INSPECT: unique symbol;
60
+ declare function normalizeBaseUrl(raw: string): string;
61
+ declare class SecretEnvs {
62
+ #private;
63
+ constructor(options?: SecretEnvsOptions);
64
+ /** Projects visible to the token, with their environments. */
65
+ listProjects(): Promise<{
66
+ id: string;
67
+ slug: string;
68
+ name: string;
69
+ role: "OWNER" | "ADMIN" | "EDITOR" | "VIEWER";
70
+ environments: {
71
+ id: string;
72
+ slug: string;
73
+ name: string;
74
+ }[];
75
+ }[]>;
76
+ /** Resolved variables including where each value comes from. */
77
+ getResolved(target?: TargetOptions): Promise<ResolvedVariablesResponse>;
78
+ /** All variables of an environment as a plain object. */
79
+ getVariables(target?: TargetOptions): Promise<Record<string, string>>;
80
+ /** A single value; throws SecretEnvsNotFoundError when the key is not defined. */
81
+ get(target: TargetOptions & {
82
+ key: string;
83
+ }): Promise<string>;
84
+ /** Injects variables into the environment; existing values win unless override is set. */
85
+ load(target?: TargetOptions & {
86
+ override?: boolean;
87
+ }): Promise<void>;
88
+ clearCache(): void;
89
+ toString(): string;
90
+ toJSON(): {
91
+ baseUrl: string;
92
+ };
93
+ [INSPECT](): string;
94
+ }
95
+
96
+ export { type FetchInit, type FetchLike, SecretEnvs, SecretEnvsApiError, SecretEnvsAuthError, SecretEnvsError, SecretEnvsNetworkError, SecretEnvsNotFoundError, type SecretEnvsOptions, type TargetOptions, normalizeBaseUrl };
@@ -0,0 +1,96 @@
1
+ import { ResolvedVariablesResponse } from '@secretenvs/contracts';
2
+ export { ResolvedVariableDto, ResolvedVariablesResponse, SdkProjectDto } from '@secretenvs/contracts';
3
+
4
+ declare class SecretEnvsError extends Error {
5
+ constructor(message: string, options?: {
6
+ cause?: unknown;
7
+ });
8
+ }
9
+ declare class SecretEnvsNetworkError extends SecretEnvsError {
10
+ constructor(message: string, options?: {
11
+ cause?: unknown;
12
+ });
13
+ }
14
+ declare class SecretEnvsApiError extends SecretEnvsError {
15
+ readonly status: number;
16
+ readonly code?: string | undefined;
17
+ constructor(message: string, status: number, code?: string | undefined);
18
+ }
19
+ declare class SecretEnvsAuthError extends SecretEnvsApiError {
20
+ constructor(message: string, status: number, code?: string);
21
+ }
22
+ declare class SecretEnvsNotFoundError extends SecretEnvsApiError {
23
+ constructor(message: string, status?: number, code?: string);
24
+ }
25
+
26
+ interface FetchInit {
27
+ method: 'GET';
28
+ headers: Record<string, string>;
29
+ signal: AbortSignal;
30
+ redirect: 'error';
31
+ }
32
+ type FetchLike = (url: string, init: FetchInit) => Promise<Response>;
33
+ interface SecretEnvsOptions {
34
+ /** API token. Falls back to SECRETENVS_TOKEN. */
35
+ token?: string;
36
+ /** Server origin, e.g. https://vault.example.com. Falls back to SECRETENVS_URL. */
37
+ baseUrl?: string;
38
+ /** Default project slug. Falls back to SECRETENVS_PROJECT. */
39
+ project?: string;
40
+ /** Default environment slug. Falls back to SECRETENVS_ENV. */
41
+ environment?: string;
42
+ /** Per-attempt timeout in milliseconds. Default 10000. */
43
+ timeoutMs?: number;
44
+ /** Retries for network errors and 5xx responses. Default 2. */
45
+ retries?: number;
46
+ /** Base delay for exponential backoff between retries. Default 200. */
47
+ retryDelayMs?: number;
48
+ /** In-memory cache lifetime in milliseconds. 0 (default) disables caching. */
49
+ cacheTtlMs?: number;
50
+ /** Custom fetch implementation; defaults to the global fetch. */
51
+ fetch?: FetchLike;
52
+ /** Environment used for option fallbacks and by load(). Defaults to process.env. */
53
+ env?: Record<string, string | undefined>;
54
+ }
55
+ interface TargetOptions {
56
+ project?: string;
57
+ environment?: string;
58
+ }
59
+ declare const INSPECT: unique symbol;
60
+ declare function normalizeBaseUrl(raw: string): string;
61
+ declare class SecretEnvs {
62
+ #private;
63
+ constructor(options?: SecretEnvsOptions);
64
+ /** Projects visible to the token, with their environments. */
65
+ listProjects(): Promise<{
66
+ id: string;
67
+ slug: string;
68
+ name: string;
69
+ role: "OWNER" | "ADMIN" | "EDITOR" | "VIEWER";
70
+ environments: {
71
+ id: string;
72
+ slug: string;
73
+ name: string;
74
+ }[];
75
+ }[]>;
76
+ /** Resolved variables including where each value comes from. */
77
+ getResolved(target?: TargetOptions): Promise<ResolvedVariablesResponse>;
78
+ /** All variables of an environment as a plain object. */
79
+ getVariables(target?: TargetOptions): Promise<Record<string, string>>;
80
+ /** A single value; throws SecretEnvsNotFoundError when the key is not defined. */
81
+ get(target: TargetOptions & {
82
+ key: string;
83
+ }): Promise<string>;
84
+ /** Injects variables into the environment; existing values win unless override is set. */
85
+ load(target?: TargetOptions & {
86
+ override?: boolean;
87
+ }): Promise<void>;
88
+ clearCache(): void;
89
+ toString(): string;
90
+ toJSON(): {
91
+ baseUrl: string;
92
+ };
93
+ [INSPECT](): string;
94
+ }
95
+
96
+ export { type FetchInit, type FetchLike, SecretEnvs, SecretEnvsApiError, SecretEnvsAuthError, SecretEnvsError, SecretEnvsNetworkError, SecretEnvsNotFoundError, type SecretEnvsOptions, type TargetOptions, normalizeBaseUrl };
package/dist/index.js ADDED
@@ -0,0 +1,290 @@
1
+ // src/errors.ts
2
+ var SecretEnvsError = class extends Error {
3
+ constructor(message, options) {
4
+ super(message, options);
5
+ this.name = "SecretEnvsError";
6
+ }
7
+ };
8
+ var SecretEnvsNetworkError = class extends SecretEnvsError {
9
+ constructor(message, options) {
10
+ super(message, options);
11
+ this.name = "SecretEnvsNetworkError";
12
+ }
13
+ };
14
+ var SecretEnvsApiError = class extends SecretEnvsError {
15
+ constructor(message, status, code) {
16
+ super(message);
17
+ this.status = status;
18
+ this.code = code;
19
+ this.name = "SecretEnvsApiError";
20
+ }
21
+ status;
22
+ code;
23
+ };
24
+ var SecretEnvsAuthError = class extends SecretEnvsApiError {
25
+ constructor(message, status, code) {
26
+ super(message, status, code);
27
+ this.name = "SecretEnvsAuthError";
28
+ }
29
+ };
30
+ var SecretEnvsNotFoundError = class extends SecretEnvsApiError {
31
+ constructor(message, status = 404, code) {
32
+ super(message, status, code);
33
+ this.name = "SecretEnvsNotFoundError";
34
+ }
35
+ };
36
+
37
+ // src/client.ts
38
+ import {
39
+ ApiErrorBody,
40
+ ResolvedVariablesResponse,
41
+ SdkProjectDto
42
+ } from "@secretenvs/contracts";
43
+ var DEFAULT_TIMEOUT_MS = 1e4;
44
+ var DEFAULT_RETRIES = 2;
45
+ var DEFAULT_RETRY_DELAY_MS = 200;
46
+ var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
47
+ var INSPECT = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
48
+ function nonEmpty(value) {
49
+ return value === void 0 || value === "" ? void 0 : value;
50
+ }
51
+ function normalizeBaseUrl(raw) {
52
+ let url;
53
+ try {
54
+ url = new URL(raw);
55
+ } catch {
56
+ throw new SecretEnvsError("baseUrl is not a valid URL");
57
+ }
58
+ if (url.username || url.password) {
59
+ throw new SecretEnvsError("baseUrl must not contain credentials");
60
+ }
61
+ const isLocalHttp = url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
62
+ if (url.protocol !== "https:" && !isLocalHttp) {
63
+ throw new SecretEnvsError(
64
+ "baseUrl must use https (http is only allowed for localhost)"
65
+ );
66
+ }
67
+ return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
68
+ }
69
+ function integerOption(name, value, fallback, min) {
70
+ if (value === void 0) return fallback;
71
+ if (!Number.isInteger(value) || value < min) {
72
+ throw new SecretEnvsError(`${name} must be an integer >= ${min}`);
73
+ }
74
+ return value;
75
+ }
76
+ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
77
+ var SecretEnvs = class {
78
+ #token;
79
+ #baseUrl;
80
+ #project;
81
+ #environment;
82
+ #timeoutMs;
83
+ #retries;
84
+ #retryDelayMs;
85
+ #cacheTtlMs;
86
+ #fetch;
87
+ #env;
88
+ #cache = /* @__PURE__ */ new Map();
89
+ constructor(options = {}) {
90
+ const env = options.env ?? process.env;
91
+ const token = nonEmpty(options.token) ?? nonEmpty(env.SECRETENVS_TOKEN);
92
+ const baseUrl = nonEmpty(options.baseUrl) ?? nonEmpty(env.SECRETENVS_URL);
93
+ if (!token) {
94
+ throw new SecretEnvsError(
95
+ 'A token is required (option "token" or SECRETENVS_TOKEN)'
96
+ );
97
+ }
98
+ if (!baseUrl) {
99
+ throw new SecretEnvsError(
100
+ 'A base URL is required (option "baseUrl" or SECRETENVS_URL)'
101
+ );
102
+ }
103
+ const fetchImpl = options.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
104
+ if (!fetchImpl) {
105
+ throw new SecretEnvsError("fetch is not available (Node 18+ required)");
106
+ }
107
+ this.#token = token;
108
+ this.#baseUrl = normalizeBaseUrl(baseUrl);
109
+ this.#project = nonEmpty(options.project) ?? nonEmpty(env.SECRETENVS_PROJECT);
110
+ this.#environment = nonEmpty(options.environment) ?? nonEmpty(env.SECRETENVS_ENV);
111
+ this.#timeoutMs = integerOption(
112
+ "timeoutMs",
113
+ options.timeoutMs,
114
+ DEFAULT_TIMEOUT_MS,
115
+ 1
116
+ );
117
+ this.#retries = integerOption(
118
+ "retries",
119
+ options.retries,
120
+ DEFAULT_RETRIES,
121
+ 0
122
+ );
123
+ this.#retryDelayMs = integerOption(
124
+ "retryDelayMs",
125
+ options.retryDelayMs,
126
+ DEFAULT_RETRY_DELAY_MS,
127
+ 0
128
+ );
129
+ this.#cacheTtlMs = integerOption("cacheTtlMs", options.cacheTtlMs, 0, 0);
130
+ this.#fetch = fetchImpl;
131
+ this.#env = env;
132
+ }
133
+ /** Projects visible to the token, with their environments. */
134
+ async listProjects() {
135
+ return this.#get(
136
+ "/api/v1/sdk/projects",
137
+ (body) => SdkProjectDto.array().parse(body)
138
+ );
139
+ }
140
+ /** Resolved variables including where each value comes from. */
141
+ async getResolved(target = {}) {
142
+ const { project, environment } = this.#target(target);
143
+ const key = `${project}/${environment}`;
144
+ if (this.#cacheTtlMs > 0) {
145
+ const cached = this.#cache.get(key);
146
+ if (cached && cached.expiresAt > Date.now()) {
147
+ return structuredClone(cached.data);
148
+ }
149
+ }
150
+ const data = await this.#get(
151
+ `/api/v1/sdk/projects/${encodeURIComponent(project)}/environments/${encodeURIComponent(environment)}/variables`,
152
+ (body) => ResolvedVariablesResponse.parse(body)
153
+ );
154
+ if (this.#cacheTtlMs > 0) {
155
+ this.#cache.set(key, {
156
+ expiresAt: Date.now() + this.#cacheTtlMs,
157
+ data: structuredClone(data)
158
+ });
159
+ }
160
+ return data;
161
+ }
162
+ /** All variables of an environment as a plain object. */
163
+ async getVariables(target = {}) {
164
+ const { variables } = await this.getResolved(target);
165
+ return Object.fromEntries(variables.map(({ key, value }) => [key, value]));
166
+ }
167
+ /** A single value; throws SecretEnvsNotFoundError when the key is not defined. */
168
+ async get(target) {
169
+ const { variables } = await this.getResolved(target);
170
+ const found = variables.find((variable) => variable.key === target.key);
171
+ if (!found) {
172
+ throw new SecretEnvsNotFoundError(`Variable ${target.key} was not found`);
173
+ }
174
+ return found.value;
175
+ }
176
+ /** Injects variables into the environment; existing values win unless override is set. */
177
+ async load(target = {}) {
178
+ const variables = await this.getVariables(target);
179
+ for (const [key, value] of Object.entries(variables)) {
180
+ if (target.override || this.#env[key] === void 0) {
181
+ this.#env[key] = value;
182
+ }
183
+ }
184
+ }
185
+ clearCache() {
186
+ this.#cache.clear();
187
+ }
188
+ toString() {
189
+ return `SecretEnvs(${this.#baseUrl})`;
190
+ }
191
+ toJSON() {
192
+ return { baseUrl: this.#baseUrl };
193
+ }
194
+ [INSPECT]() {
195
+ return this.toString();
196
+ }
197
+ #target(target) {
198
+ const project = target.project ?? this.#project;
199
+ const environment = target.environment ?? this.#environment;
200
+ if (!project) {
201
+ throw new SecretEnvsError(
202
+ 'A project is required (argument "project" or SECRETENVS_PROJECT)'
203
+ );
204
+ }
205
+ if (!environment) {
206
+ throw new SecretEnvsError(
207
+ 'An environment is required (argument "environment" or SECRETENVS_ENV)'
208
+ );
209
+ }
210
+ return { project, environment };
211
+ }
212
+ // Retries only network errors and 5xx responses, with exponential backoff.
213
+ async #get(path, parse) {
214
+ const url = `${this.#baseUrl}${path}`;
215
+ for (let attempt = 0; ; attempt += 1) {
216
+ const canRetry = attempt < this.#retries;
217
+ try {
218
+ const { status, body } = await this.#attempt(url);
219
+ if (status >= 500 && canRetry) {
220
+ await sleep(this.#retryDelayMs * 2 ** attempt);
221
+ continue;
222
+ }
223
+ return this.#handle(status, body, parse);
224
+ } catch (error) {
225
+ if (error instanceof SecretEnvsNetworkError && canRetry) {
226
+ await sleep(this.#retryDelayMs * 2 ** attempt);
227
+ continue;
228
+ }
229
+ throw error;
230
+ }
231
+ }
232
+ }
233
+ async #attempt(url) {
234
+ const controller = new AbortController();
235
+ const timer = setTimeout(() => controller.abort(), this.#timeoutMs);
236
+ try {
237
+ const response = await this.#fetch(url, {
238
+ method: "GET",
239
+ headers: {
240
+ Authorization: `Bearer ${this.#token}`,
241
+ Accept: "application/json"
242
+ },
243
+ signal: controller.signal,
244
+ redirect: "error"
245
+ });
246
+ let body;
247
+ try {
248
+ body = await response.json();
249
+ } catch (error) {
250
+ if (controller.signal.aborted) throw error;
251
+ body = void 0;
252
+ }
253
+ return { status: response.status, body };
254
+ } catch (error) {
255
+ throw new SecretEnvsNetworkError(
256
+ controller.signal.aborted ? `Request timed out after ${this.#timeoutMs}ms` : "Network request failed",
257
+ { cause: error }
258
+ );
259
+ } finally {
260
+ clearTimeout(timer);
261
+ }
262
+ }
263
+ #handle(status, body, parse) {
264
+ if (status >= 200 && status < 300) {
265
+ try {
266
+ return parse(body);
267
+ } catch {
268
+ throw new SecretEnvsApiError("Unexpected response from server", status);
269
+ }
270
+ }
271
+ const parsed = ApiErrorBody.safeParse(body);
272
+ const message = parsed.success ? parsed.data.error.message : `Request failed with status ${status}`;
273
+ const code = parsed.success ? parsed.data.error.code : void 0;
274
+ if (status === 401 || status === 403) {
275
+ throw new SecretEnvsAuthError(message, status, code);
276
+ }
277
+ if (status === 404)
278
+ throw new SecretEnvsNotFoundError(message, status, code);
279
+ throw new SecretEnvsApiError(message, status, code);
280
+ }
281
+ };
282
+ export {
283
+ SecretEnvs,
284
+ SecretEnvsApiError,
285
+ SecretEnvsAuthError,
286
+ SecretEnvsError,
287
+ SecretEnvsNetworkError,
288
+ SecretEnvsNotFoundError,
289
+ normalizeBaseUrl
290
+ };
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@secretenvs/sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.1.0",
4
+ "description": "Node client for loading SecretEnvs variables into process.env.",
5
+ "license": "MIT",
6
+ "homepage": "https://github.com/ankityadavpurson/secretenvs#readme",
7
+ "bugs": {
8
+ "url": "https://github.com/ankityadavpurson/secretenvs/issues"
9
+ },
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/ankityadavpurson/secretenvs.git",
13
+ "directory": "packages/sdk"
14
+ },
15
+ "keywords": [
16
+ "secretenvs",
17
+ "secrets",
18
+ "environment-variables",
19
+ "env",
20
+ "sdk"
21
+ ],
22
+ "type": "module",
23
+ "main": "./dist/index.cjs",
24
+ "module": "./dist/index.js",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "import": {
29
+ "types": "./dist/index.d.ts",
30
+ "default": "./dist/index.js"
31
+ },
32
+ "require": {
33
+ "types": "./dist/index.d.cts",
34
+ "default": "./dist/index.cjs"
35
+ }
36
+ }
37
+ },
38
+ "files": [
39
+ "dist"
40
+ ],
41
+ "publishConfig": {
42
+ "access": "public"
43
+ },
44
+ "scripts": {
45
+ "build": "tsup src/index.ts --format esm,cjs --dts --clean",
46
+ "typecheck": "tsc --noEmit && yarn build",
47
+ "test": "vitest run --passWithNoTests"
48
+ },
49
+ "dependencies": {
50
+ "@secretenvs/contracts": "1.1.0"
51
+ },
52
+ "devDependencies": {
53
+ "tsup": "^8.5.0",
54
+ "typescript": "~5.9.3",
55
+ "vitest": "^3.2.4"
56
+ }
6
57
  }