@clicadigital/vault-sdk 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
-
-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.
+# @clicadigital/vault-sdk
+
+SDK e CLI para criar e carregar variáveis de ambiente a partir do **Clica VPN Vault**.
+
+Pensado para uso **entre pods no k3s/k8s**. Sem API key estática.
+
+Segurança em camadas:
+1. **NetworkPolicy** — só pods com `vault.clica.io/access=true` (e o `vault-web`) alcançam a API
+2. **ServiceAccount + TokenReview** — o SDK envia o JWT projetado (`audience: vault`); a API valida e checa allowlist
+3. **Master key** — só no Deployment do vault (`VAULT_MASTER_KEY`), nunca nos apps
+
+Local/dev: API com `VAULT_AUTH=none` (sem token).
+
+## Instalação
+
+```bash
+npm install @clicadigital/vault-sdk
+# ou
+bun add @clicadigital/vault-sdk
+```
+
+## Configuração
+
+| Variável             | Obrigatória | Descrição                                              |
+|----------------------|-------------|--------------------------------------------------------|
+| `VAULT_URL`          | não         | Override da URL. Default: `http://vault-api-service.vault.svc.cluster.local:3001` |
+| `VAULT_SA_TOKEN_PATH`| não         | Path do token SA (default: `/var/run/secrets/tokens/vault/token`) |
+| `VAULT_PROJECT`      | não         | Default de `--project` na CLI                          |
+| `VAULT_ENV`          | não         | Default de `--env` na CLI                              |
+
+Também aceita `VAULT_API_URL` ou `API_URL` no lugar de `VAULT_URL`. Em pods no cluster normalmente **não precisa** setar URL.
+
+No cluster, monte um projected token:
+
+```yaml
+volumeMounts:
+  - name: vault-token
+    mountPath: /var/run/secrets/tokens/vault
+    readOnly: true
+volumes:
+  - name: vault-token
+    projected:
+      sources:
+        - serviceAccountToken:
+            path: token
+            expirationSeconds: 3600
+            audience: vault
+```
+
+O SDK lê o token sozinho e manda `Authorization: Bearer …`.
+
+## CLI
+
+### Garantir projeto + environment
+
+Cria o projeto (se não existir) e o environment (se não existir). Projetos novos já nascem com `production` e `staging` no vault; outros nomes são criados sob demanda.
+
+```bash
+npx vault-sdk ensure --project meu-app --env production
+```
+
+### Criar environment e gravar variáveis
+
+```bash
+npx vault-sdk create \
+  --project meu-app \
+  --env production \
+  --var DATABASE_URL=postgres://... \
+  --var API_TOKEN=secret
+```
+
+### Puxar variáveis no build (gera `.env`)
+
+```bash
+# Dockerfile / CI / init container
+npx vault-sdk pull \
+  --project meu-app \
+  --env production \
+  --out .env \
+  --no-inject
+```
+
+Sem `--no-inject`, as vars também vão para `process.env` do processo da CLI.
+
+### URL explícita
+
+```bash
+npx vault-sdk pull --url http://vault-api.vpn.svc.cluster.local:3001 \
+  --project meu-app --env staging --out .env
+```
+
+## Uso em código (Node / Bun)
+
+### Carregar no boot / build script
+
+```ts
+import { loadVault, pullVault, createEnv, ensureEnvironment } from "@clicadigital/vault-sdk";
+
+// injeta em process.env
+await loadVault({ project: "meu-app", env: "production" });
+
+// ou grava arquivo
+await pullVault({
+  project: "meu-app",
+  env: "production",
+  out: ".env",
+  inject: false,
+});
+```
+
+### Criar environment + vars pela URL da VPN
+
+```ts
+await createEnv({
+  project: "meu-app",
+  env: "production",
+  vars: {
+    DATABASE_URL: "postgres://...",
+    REDIS_URL: "redis://...",
+  },
+});
+```
+
+### Só garantir que o environment existe
+
+```ts
+await ensureEnvironment({ project: "meu-app", env: "qa" });
+```
+
+## Exemplo no pod (boot)
+
+```ts
+import { loadVault } from "@clicadigital/vault-sdk";
+
+// URL default do Service k8s; token SA montado no pod
+await loadVault({ project: "meu-app", env: "production" });
+```
+
+Manifests de referência: [`deploy/k3s/`](../deploy/k3s/) (NetworkPolicy, RBAC TokenReview, SA, exemplos).
+
+```bash
+kubectl apply -k deploy/k3s
+kubectl apply -f deploy/k3s/secrets.yaml   # a partir de secrets.example.yaml
+```
+
+Inclua o SA do app em `VAULT_ALLOWED_SAS` no Deployment do `vault-api`:
+
+```text
+system:serviceaccount:vault:app-demo
+```
+
+## API do vault usada pelo SDK
+
+| Método | Path | Uso |
+|--------|------|-----|
+| `GET` | `/v1/projects` | Árvore projetos + environments |
+| `POST` | `/v1/projects` | Criar projeto |
+| `POST` | `/v1/projects/:id/environments` | Criar environment |
+| `GET` | `/v1/environments/:id/vars` | Listar vars (já descriptografadas) |
+| `PUT` | `/v1/environments/:id/vars` | Upsert var |
+
+## Desenvolvimento local (neste monorepo)
+
+```bash
+cd sdk
+bun install
+bun run build
+
+# fora do cluster, sobrescreva o default k8s
+VAULT_URL=http://localhost:3001 bun run src/cli.ts pull --project demo --env production --out .env
+```
+
+Publicar:
+
+```bash
+cd sdk
+bun run build
+bun publish --access public
+```

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { createClientFromEnv } from "./client.js";
+import { createEnv, ensureEnvironment, pullVault } from "./index.js";
+function parseArgs(argv) {
+    const [cmd = "help", ...rest] = argv;
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (!token?.startsWith("--"))
+            continue;
+        const key = token.slice(2);
+        const next = rest[i + 1];
+        if (!next || next.startsWith("--")) {
+            flags[key] = true;
+            continue;
+        }
+        if (key === "var") {
+            const list = Array.isArray(flags.var) ? flags.var : [];
+            list.push(next);
+            flags.var = list;
+        }
+        else {
+            flags[key] = next;
+        }
+        i++;
+    }
+    return { cmd, flags };
+}
+function str(flags, key, fallback) {
+    const v = flags[key];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    if (fallback !== undefined)
+        return fallback;
+    throw new Error(`Missing --${key}`);
+}
+function printHelp() {
+    console.log(`@clicadigital/vault-sdk — cria e carrega envs via URL do vault na VPN
+
+Usage:
+  vault-sdk create --project <name> --env <name> [--url <vpn-url>] [--var KEY=VAL]...
+  vault-sdk ensure --project <name> --env <name> [--url <vpn-url>]
+  vault-sdk pull   --project <name> --env <name> [--out .env] [--no-inject] [--url <vpn-url>]
+
+Env:
+  VAULT_URL            opcional; default k8s: http://vault-api-service.vault.svc.cluster.local:3001
+  VAULT_PROJECT        default --project
+  VAULT_ENV            default --env
+  VAULT_SA_TOKEN_PATH  path do token SA (default: /var/run/secrets/tokens/vault/token)
+
+Auth no k3s: ServiceAccount token (audience=vault) + NetworkPolicy.
+Local (VAULT_AUTH=none na API): sem token.
+`);
+}
+function applyUrl(flags) {
+    if (typeof flags.url === "string")
+        process.env.VAULT_URL = flags.url;
+}
+function parseVarList(flags) {
+    const out = {};
+    const list = Array.isArray(flags.var) ? flags.var : [];
+    for (const pair of list) {
+        const eq = pair.indexOf("=");
+        if (eq < 1)
+            throw new Error(`Invalid --var ${pair} (use KEY=VALUE)`);
+        out[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return out;
+}
+async function main() {
+    const { cmd, flags } = parseArgs(process.argv.slice(2));
+    if (cmd === "help" || flags.help === true) {
+        printHelp();
+        return;
+    }
+    applyUrl(flags);
+    const project = str(flags, "project", process.env.VAULT_PROJECT);
+    const env = str(flags, "env", process.env.VAULT_ENV);
+    const url = typeof flags.url === "string" ? flags.url : undefined;
+    const client = url
+        ? createClientFromEnv({ ...process.env, VAULT_URL: url })
+        : undefined;
+    if (cmd === "create") {
+        const vars = parseVarList(flags);
+        const result = await createEnv({ project, env, url, vars, client });
+        console.log(JSON.stringify({ project, env, ...result }, null, 2));
+        return;
+    }
+    if (cmd === "ensure") {
+        const result = await ensureEnvironment({ project, env, client });
+        console.log(JSON.stringify({
+            project,
+            env,
+            projectId: result.projectId,
+            environmentId: result.environmentId,
+            createdProject: result.createdProject,
+            createdEnvironment: result.createdEnvironment,
+        }, null, 2));
+        return;
+    }
+    if (cmd === "pull") {
+        const out = typeof flags.out === "string" ? flags.out : undefined;
+        const inject = flags["no-inject"] !== true;
+        const result = await pullVault({ project, env, out, inject, client });
+        console.log(`pulled ${Object.keys(result.vars).length} vars for ${project}/${env}` +
+            (result.out ? ` → ${result.out}` : "") +
+            (inject ? " (injected into process.env)" : ""));
+        return;
+    }
+    printHelp();
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { EnvVar, ProjectTree } from "./types.js";
+/** DNS interno do Service no k3s (namespace `vault`). Override com VAULT_URL. */
+export declare const DEFAULT_VAULT_URL = "http://vault-api-service.vault.svc.cluster.local:3001";
+export type VaultClientOptions = {
+    /** Base URL da API do vault na VPN. Default: DEFAULT_VAULT_URL */
+    baseUrl: string;
+    /** Bearer token (ServiceAccount projected). Se omitido, tenta ler do filesystem do pod. */
+    token?: string;
+    /** Paths para procurar o token SA (ordem de prioridade). */
+    tokenPaths?: string[];
+    fetch?: typeof globalThis.fetch;
+};
+export declare class VaultClient {
+    readonly baseUrl: string;
+    private readonly token;
+    private readonly fetchFn;
+    constructor(opts: VaultClientOptions);
+    private request;
+    listProjects(): Promise<ProjectTree[]>;
+    createProject(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    createEnvironment(projectId: string, name: string): Promise<{
+        ok: boolean;
+    }>;
+    listVars(environmentId: string): Promise<EnvVar[]>;
+    upsertVar(environmentId: string, key: string, value: string): Promise<{
+        ok: boolean;
+    }>;
+}
+export declare function createClientFromEnv(env?: NodeJS.ProcessEnv): VaultClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAOtD,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,0DAC2B,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,CAAC;AAiBF,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,IAAI,EAAE,kBAAkB;YAMtB,OAAO;IAmBrB,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAItC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAO5E,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlD,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;CAMvF;AAED,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,WAAW,CASb"}

package/dist/client.js

@@ -0,0 +1,88 @@
+import { readFileSync, existsSync } from "node:fs";
+const DEFAULT_TOKEN_PATHS = [
+    "/var/run/secrets/tokens/vault/token",
+    "/var/run/secrets/kubernetes.io/serviceaccount/token",
+];
+/** DNS interno do Service no k3s (namespace `vault`). Override com VAULT_URL. */
+export const DEFAULT_VAULT_URL = "http://vault-api-service.vault.svc.cluster.local:3001";
+function resolveToken(opts) {
+    if (opts.token)
+        return opts.token;
+    const paths = opts.tokenPaths ?? DEFAULT_TOKEN_PATHS;
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const token = readFileSync(path, "utf8").trim();
+            if (token)
+                return token;
+        }
+        catch {
+            // ignore unreadable path
+        }
+    }
+    return undefined;
+}
+export class VaultClient {
+    baseUrl;
+    token;
+    fetchFn;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.token = resolveToken(opts);
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async request(path, init) {
+        const headers = {
+            "content-type": "application/json",
+            ...init?.headers,
+        };
+        if (this.token)
+            headers.authorization = `Bearer ${this.token}`;
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => null));
+            throw new Error(body?.error ?? `Vault API ${res.status} ${path}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    listProjects() {
+        return this.request("/v1/projects");
+    }
+    createProject(name) {
+        return this.request("/v1/projects", {
+            method: "POST",
+            body: JSON.stringify({ name }),
+        });
+    }
+    createEnvironment(projectId, name) {
+        return this.request(`/v1/projects/${projectId}/environments`, {
+            method: "POST",
+            body: JSON.stringify({ name }),
+        });
+    }
+    listVars(environmentId) {
+        return this.request(`/v1/environments/${environmentId}/vars`);
+    }
+    upsertVar(environmentId, key, value) {
+        return this.request(`/v1/environments/${environmentId}/vars`, {
+            method: "PUT",
+            body: JSON.stringify({ key, value }),
+        });
+    }
+}
+export function createClientFromEnv(env = process.env) {
+    const baseUrl = env.VAULT_URL ?? env.VAULT_API_URL ?? env.API_URL ?? DEFAULT_VAULT_URL;
+    const tokenPath = env.VAULT_SA_TOKEN_PATH;
+    return new VaultClient({
+        baseUrl,
+        token: env.VAULT_SA_TOKEN,
+        tokenPaths: tokenPath ? [tokenPath, ...DEFAULT_TOKEN_PATHS] : undefined,
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/dotenv.d.ts

@@ -0,0 +1,6 @@
+export declare function toDotEnv(vars: Record<string, string>): string;
+export declare function varsToRecord(rows: {
+    key: string;
+    value: string;
+}[]): Record<string, string>;
+//# sourceMappingURL=dotenv.d.ts.map

package/dist/dotenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"","sources":["../src/dotenv.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAO7D;AAQD,wBAAgB,YAAY,CAC1B,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxB"}

package/dist/dotenv.js

@@ -0,0 +1,20 @@
+export function toDotEnv(vars) {
+    return (Object.entries(vars)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}=${escapeEnvValue(value)}`)
+        .join("\n") + "\n");
+}
+function escapeEnvValue(value) {
+    if (value === "")
+        return '""';
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+export function varsToRecord(rows) {
+    const out = {};
+    for (const row of rows)
+        out[row.key] = row.value;
+    return out;
+}
+//# sourceMappingURL=dotenv.js.map

package/dist/dotenv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.js","sourceRoot":"","sources":["../src/dotenv.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,IAA4B;IACnD,OAAO,CACL,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;SACxD,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CACrB,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACzD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,IAAsC;IAEtC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;IACjD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { createClientFromEnv, DEFAULT_VAULT_URL, VaultClient, type VaultClientOptions } from "./client.js";
+import { toDotEnv, varsToRecord } from "./dotenv.js";
+import type { EnvVar } from "./types.js";
+export type { EnvVar, ProjectTree, ProjectTreeEnv } from "./types.js";
+export { VaultClient, createClientFromEnv, DEFAULT_VAULT_URL, type VaultClientOptions, };
+export { toDotEnv, varsToRecord };
+export type ResolveOptions = {
+    project: string;
+    env: string;
+    client?: VaultClient;
+};
+export type EnsureOptions = ResolveOptions & {
+    createProject?: boolean;
+};
+export type PullOptions = ResolveOptions & {
+    out?: string;
+    inject?: boolean;
+};
+export type CreateEnvOptions = {
+    project: string;
+    env: string;
+    /** URL da API do vault na VPN (cluster-internal) */
+    url?: string;
+    vars?: Record<string, string>;
+    client?: VaultClient;
+};
+export declare function resolveEnvironment(opts: ResolveOptions): Promise<{
+    projectId: string;
+    environmentId: string;
+}>;
+/** Garante projeto + environment na VPN (cria se não existir). */
+export declare function ensureEnvironment(opts: EnsureOptions): Promise<{
+    projectId: string;
+    environmentId: string;
+    createdProject: boolean;
+    createdEnvironment: boolean;
+}>;
+/**
+ * Cria (ou garante) o environment no vault via URL da VPN
+ * e opcionalmente faz upsert das variáveis.
+ */
+export declare function createEnv(opts: CreateEnvOptions): Promise<{
+    projectId: string;
+    environmentId: string;
+    createdProject: boolean;
+    createdEnvironment: boolean;
+    upserted: string[];
+}>;
+export declare function fetchVars(opts: ResolveOptions): Promise<EnvVar[]>;
+export declare function loadVault(opts: ResolveOptions): Promise<Record<string, string>>;
+export declare function pullVault(opts: PullOptions): Promise<{
+    vars: Record<string, string>;
+    out?: string;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACX,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,YAAY,CAAC;AAEtD,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,kBAAkB,GACxB,CAAC;AACF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAElC,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG;IAC3C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAgBF,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CASvD;AAED,kEAAkE;AAClE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC,CAiCD;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC,CAiBD;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIvE;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOjC;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;IAC1D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC,CAgBD"}

package/dist/index.js

@@ -0,0 +1,110 @@
+import { writeFile } from "node:fs/promises";
+import { createClientFromEnv, DEFAULT_VAULT_URL, VaultClient, } from "./client.js";
+import { toDotEnv, varsToRecord } from "./dotenv.js";
+export { VaultClient, createClientFromEnv, DEFAULT_VAULT_URL, };
+export { toDotEnv, varsToRecord };
+async function findProject(client, name) {
+    const tree = await client.listProjects();
+    return tree.find((p) => p.name === name);
+}
+function resolveClient(opts) {
+    if (opts.client)
+        return opts.client;
+    if (opts.url)
+        return new VaultClient({ baseUrl: opts.url });
+    return createClientFromEnv();
+}
+export async function resolveEnvironment(opts) {
+    const client = opts.client ?? createClientFromEnv();
+    const project = await findProject(client, opts.project);
+    if (!project)
+        throw new Error(`Project not found: ${opts.project}`);
+    const environment = project.environments.find((e) => e.name === opts.env);
+    if (!environment) {
+        throw new Error(`Environment "${opts.env}" not found in project "${opts.project}"`);
+    }
+    return { projectId: project.id, environmentId: environment.id };
+}
+/** Garante projeto + environment na VPN (cria se não existir). */
+export async function ensureEnvironment(opts) {
+    const client = opts.client ?? createClientFromEnv();
+    let createdProject = false;
+    let createdEnvironment = false;
+    let project = await findProject(client, opts.project);
+    if (!project) {
+        if (opts.createProject === false) {
+            throw new Error(`Project not found: ${opts.project}`);
+        }
+        await client.createProject(opts.project);
+        createdProject = true;
+        project = await findProject(client, opts.project);
+        if (!project)
+            throw new Error(`Failed to create project: ${opts.project}`);
+    }
+    let environment = project.environments.find((e) => e.name === opts.env);
+    if (!environment) {
+        await client.createEnvironment(project.id, opts.env);
+        createdEnvironment = true;
+        const refreshed = await findProject(client, opts.project);
+        if (!refreshed)
+            throw new Error(`Failed to reload project: ${opts.project}`);
+        project = refreshed;
+        environment = project.environments.find((e) => e.name === opts.env);
+        if (!environment)
+            throw new Error(`Failed to create environment: ${opts.env}`);
+    }
+    return {
+        projectId: project.id,
+        environmentId: environment.id,
+        createdProject,
+        createdEnvironment,
+    };
+}
+/**
+ * Cria (ou garante) o environment no vault via URL da VPN
+ * e opcionalmente faz upsert das variáveis.
+ */
+export async function createEnv(opts) {
+    const client = resolveClient(opts);
+    const ensured = await ensureEnvironment({
+        project: opts.project,
+        env: opts.env,
+        client,
+    });
+    const upserted = [];
+    if (opts.vars) {
+        for (const [key, value] of Object.entries(opts.vars)) {
+            await client.upsertVar(ensured.environmentId, key, value);
+            upserted.push(key);
+        }
+    }
+    return { ...ensured, upserted };
+}
+export async function fetchVars(opts) {
+    const client = opts.client ?? createClientFromEnv();
+    const { environmentId } = await resolveEnvironment({ ...opts, client });
+    return client.listVars(environmentId);
+}
+export async function loadVault(opts) {
+    const rows = await fetchVars(opts);
+    const record = varsToRecord(rows);
+    for (const [key, value] of Object.entries(record)) {
+        process.env[key] = value;
+    }
+    return record;
+}
+export async function pullVault(opts) {
+    const rows = await fetchVars(opts);
+    const vars = varsToRecord(rows);
+    if (opts.inject !== false) {
+        for (const [key, value] of Object.entries(vars)) {
+            process.env[key] = value;
+        }
+    }
+    const out = opts.out;
+    if (out) {
+        await writeFile(out, toDotEnv(vars), "utf8");
+    }
+    return out ? { vars, out } : { vars };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export type ProjectTreeEnv = {
+    id: string;
+    name: string;
+};
+export type ProjectTree = {
+    id: string;
+    name: string;
+    environments: ProjectTreeEnv[];
+};
+export type EnvVar = {
+    id: string;
+    key: string;
+    value: string;
+    updated_at: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,43 @@
-{
-  "name": "@clicadigital/vault-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@clicadigital/vault-sdk",
+  "version": "0.3.0",
+  "description": "SDK + CLI to load vault envs via cluster ServiceAccount (k3s/k8s)",
+  "type": "module",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "vault-sdk": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run build",
+    "vault": "bun run src/cli.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "vault",
+    "env",
+    "secrets",
+    "kubernetes",
+    "clicadigital"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.16.5",
+    "typescript": "^5.8.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { createClientFromEnv } from "./client.js";
+import { createEnv, ensureEnvironment, pullVault } from "./index.js";
+
+type Flags = Record<string, string | boolean | string[]>;
+
+function parseArgs(argv: string[]): { cmd: string; flags: Flags } {
+  const [cmd = "help", ...rest] = argv;
+  const flags: Flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (!token?.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = rest[i + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    if (key === "var") {
+      const list = Array.isArray(flags.var) ? flags.var : [];
+      list.push(next);
+      flags.var = list;
+    } else {
+      flags[key] = next;
+    }
+    i++;
+  }
+  return { cmd, flags };
+}
+
+function str(flags: Flags, key: string, fallback?: string): string {
+  const v = flags[key];
+  if (typeof v === "string" && v.length > 0) return v;
+  if (fallback !== undefined) return fallback;
+  throw new Error(`Missing --${key}`);
+}
+
+function printHelp(): void {
+  console.log(`@clicadigital/vault-sdk — cria e carrega envs via URL do vault na VPN
+
+Usage:
+  vault-sdk create --project <name> --env <name> [--url <vpn-url>] [--var KEY=VAL]...
+  vault-sdk ensure --project <name> --env <name> [--url <vpn-url>]
+  vault-sdk pull   --project <name> --env <name> [--out .env] [--no-inject] [--url <vpn-url>]
+
+Env:
+  VAULT_URL            opcional; default k8s: http://vault-api-service.vault.svc.cluster.local:3001
+  VAULT_PROJECT        default --project
+  VAULT_ENV            default --env
+  VAULT_SA_TOKEN_PATH  path do token SA (default: /var/run/secrets/tokens/vault/token)
+
+Auth no k3s: ServiceAccount token (audience=vault) + NetworkPolicy.
+Local (VAULT_AUTH=none na API): sem token.
+`);
+}
+
+function applyUrl(flags: Flags): void {
+  if (typeof flags.url === "string") process.env.VAULT_URL = flags.url;
+}
+
+function parseVarList(flags: Flags): Record<string, string> {
+  const out: Record<string, string> = {};
+  const list = Array.isArray(flags.var) ? flags.var : [];
+  for (const pair of list) {
+    const eq = pair.indexOf("=");
+    if (eq < 1) throw new Error(`Invalid --var ${pair} (use KEY=VALUE)`);
+    out[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return out;
+}
+
+async function main(): Promise<void> {
+  const { cmd, flags } = parseArgs(process.argv.slice(2));
+
+  if (cmd === "help" || flags.help === true) {
+    printHelp();
+    return;
+  }
+
+  applyUrl(flags);
+
+  const project = str(flags, "project", process.env.VAULT_PROJECT);
+  const env = str(flags, "env", process.env.VAULT_ENV);
+  const url = typeof flags.url === "string" ? flags.url : undefined;
+  const client = url
+    ? createClientFromEnv({ ...process.env, VAULT_URL: url })
+    : undefined;
+
+  if (cmd === "create") {
+    const vars = parseVarList(flags);
+    const result = await createEnv({ project, env, url, vars, client });
+    console.log(JSON.stringify({ project, env, ...result }, null, 2));
+    return;
+  }
+
+  if (cmd === "ensure") {
+    const result = await ensureEnvironment({ project, env, client });
+    console.log(
+      JSON.stringify(
+        {
+          project,
+          env,
+          projectId: result.projectId,
+          environmentId: result.environmentId,
+          createdProject: result.createdProject,
+          createdEnvironment: result.createdEnvironment,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (cmd === "pull") {
+    const out = typeof flags.out === "string" ? flags.out : undefined;
+    const inject = flags["no-inject"] !== true;
+    const result = await pullVault({ project, env, out, inject, client });
+    console.log(
+      `pulled ${Object.keys(result.vars).length} vars for ${project}/${env}` +
+        (result.out ? ` → ${result.out}` : "") +
+        (inject ? " (injected into process.env)" : ""),
+    );
+    return;
+  }
+
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/client.ts

@@ -0,0 +1,109 @@
+import { readFileSync, existsSync } from "node:fs";
+import type { EnvVar, ProjectTree } from "./types.js";
+
+const DEFAULT_TOKEN_PATHS = [
+  "/var/run/secrets/tokens/vault/token",
+  "/var/run/secrets/kubernetes.io/serviceaccount/token",
+];
+
+/** DNS interno do Service no k3s (namespace `vault`). Override com VAULT_URL. */
+export const DEFAULT_VAULT_URL =
+  "http://vault-api-service.vault.svc.cluster.local:3001";
+
+export type VaultClientOptions = {
+  /** Base URL da API do vault na VPN. Default: DEFAULT_VAULT_URL */
+  baseUrl: string;
+  /** Bearer token (ServiceAccount projected). Se omitido, tenta ler do filesystem do pod. */
+  token?: string;
+  /** Paths para procurar o token SA (ordem de prioridade). */
+  tokenPaths?: string[];
+  fetch?: typeof globalThis.fetch;
+};
+
+function resolveToken(opts: VaultClientOptions): string | undefined {
+  if (opts.token) return opts.token;
+  const paths = opts.tokenPaths ?? DEFAULT_TOKEN_PATHS;
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    try {
+      const token = readFileSync(path, "utf8").trim();
+      if (token) return token;
+    } catch {
+      // ignore unreadable path
+    }
+  }
+  return undefined;
+}
+
+export class VaultClient {
+  readonly baseUrl: string;
+  private readonly token: string | undefined;
+  private readonly fetchFn: typeof globalThis.fetch;
+
+  constructor(opts: VaultClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = resolveToken(opts);
+    this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      ...(init?.headers as Record<string, string> | undefined),
+    };
+    if (this.token) headers.authorization = `Bearer ${this.token}`;
+
+    const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+      ...init,
+      headers,
+    });
+    if (!res.ok) {
+      const body = (await res.json().catch(() => null)) as { error?: string } | null;
+      throw new Error(body?.error ?? `Vault API ${res.status} ${path}`);
+    }
+    if (res.status === 204) return undefined as T;
+    return (await res.json()) as T;
+  }
+
+  listProjects(): Promise<ProjectTree[]> {
+    return this.request("/v1/projects");
+  }
+
+  createProject(name: string): Promise<{ id: string; name: string }> {
+    return this.request("/v1/projects", {
+      method: "POST",
+      body: JSON.stringify({ name }),
+    });
+  }
+
+  createEnvironment(projectId: string, name: string): Promise<{ ok: boolean }> {
+    return this.request(`/v1/projects/${projectId}/environments`, {
+      method: "POST",
+      body: JSON.stringify({ name }),
+    });
+  }
+
+  listVars(environmentId: string): Promise<EnvVar[]> {
+    return this.request(`/v1/environments/${environmentId}/vars`);
+  }
+
+  upsertVar(environmentId: string, key: string, value: string): Promise<{ ok: boolean }> {
+    return this.request(`/v1/environments/${environmentId}/vars`, {
+      method: "PUT",
+      body: JSON.stringify({ key, value }),
+    });
+  }
+}
+
+export function createClientFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): VaultClient {
+  const baseUrl =
+    env.VAULT_URL ?? env.VAULT_API_URL ?? env.API_URL ?? DEFAULT_VAULT_URL;
+  const tokenPath = env.VAULT_SA_TOKEN_PATH;
+  return new VaultClient({
+    baseUrl,
+    token: env.VAULT_SA_TOKEN,
+    tokenPaths: tokenPath ? [tokenPath, ...DEFAULT_TOKEN_PATHS] : undefined,
+  });
+}

package/src/dotenv.ts

@@ -0,0 +1,22 @@
+export function toDotEnv(vars: Record<string, string>): string {
+  return (
+    Object.entries(vars)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, value]) => `${key}=${escapeEnvValue(value)}`)
+      .join("\n") + "\n"
+  );
+}
+
+function escapeEnvValue(value: string): string {
+  if (value === "") return '""';
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+export function varsToRecord(
+  rows: { key: string; value: string }[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const row of rows) out[row.key] = row.value;
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,177 @@
+import { writeFile } from "node:fs/promises";
+import {
+  createClientFromEnv,
+  DEFAULT_VAULT_URL,
+  VaultClient,
+  type VaultClientOptions,
+} from "./client.js";
+import { toDotEnv, varsToRecord } from "./dotenv.js";
+import type { EnvVar, ProjectTree } from "./types.js";
+
+export type { EnvVar, ProjectTree, ProjectTreeEnv } from "./types.js";
+export {
+  VaultClient,
+  createClientFromEnv,
+  DEFAULT_VAULT_URL,
+  type VaultClientOptions,
+};
+export { toDotEnv, varsToRecord };
+
+export type ResolveOptions = {
+  project: string;
+  env: string;
+  client?: VaultClient;
+};
+
+export type EnsureOptions = ResolveOptions & {
+  createProject?: boolean;
+};
+
+export type PullOptions = ResolveOptions & {
+  out?: string;
+  inject?: boolean;
+};
+
+export type CreateEnvOptions = {
+  project: string;
+  env: string;
+  /** URL da API do vault na VPN (cluster-internal) */
+  url?: string;
+  vars?: Record<string, string>;
+  client?: VaultClient;
+};
+
+async function findProject(
+  client: VaultClient,
+  name: string,
+): Promise<ProjectTree | undefined> {
+  const tree = await client.listProjects();
+  return tree.find((p) => p.name === name);
+}
+
+function resolveClient(opts: { client?: VaultClient; url?: string }): VaultClient {
+  if (opts.client) return opts.client;
+  if (opts.url) return new VaultClient({ baseUrl: opts.url });
+  return createClientFromEnv();
+}
+
+export async function resolveEnvironment(
+  opts: ResolveOptions,
+): Promise<{ projectId: string; environmentId: string }> {
+  const client = opts.client ?? createClientFromEnv();
+  const project = await findProject(client, opts.project);
+  if (!project) throw new Error(`Project not found: ${opts.project}`);
+  const environment = project.environments.find((e) => e.name === opts.env);
+  if (!environment) {
+    throw new Error(`Environment "${opts.env}" not found in project "${opts.project}"`);
+  }
+  return { projectId: project.id, environmentId: environment.id };
+}
+
+/** Garante projeto + environment na VPN (cria se não existir). */
+export async function ensureEnvironment(opts: EnsureOptions): Promise<{
+  projectId: string;
+  environmentId: string;
+  createdProject: boolean;
+  createdEnvironment: boolean;
+}> {
+  const client = opts.client ?? createClientFromEnv();
+  let createdProject = false;
+  let createdEnvironment = false;
+
+  let project = await findProject(client, opts.project);
+  if (!project) {
+    if (opts.createProject === false) {
+      throw new Error(`Project not found: ${opts.project}`);
+    }
+    await client.createProject(opts.project);
+    createdProject = true;
+    project = await findProject(client, opts.project);
+    if (!project) throw new Error(`Failed to create project: ${opts.project}`);
+  }
+
+  let environment = project.environments.find((e) => e.name === opts.env);
+  if (!environment) {
+    await client.createEnvironment(project.id, opts.env);
+    createdEnvironment = true;
+    const refreshed = await findProject(client, opts.project);
+    if (!refreshed) throw new Error(`Failed to reload project: ${opts.project}`);
+    project = refreshed;
+    environment = project.environments.find((e) => e.name === opts.env);
+    if (!environment) throw new Error(`Failed to create environment: ${opts.env}`);
+  }
+
+  return {
+    projectId: project.id,
+    environmentId: environment.id,
+    createdProject,
+    createdEnvironment,
+  };
+}
+
+/**
+ * Cria (ou garante) o environment no vault via URL da VPN
+ * e opcionalmente faz upsert das variáveis.
+ */
+export async function createEnv(opts: CreateEnvOptions): Promise<{
+  projectId: string;
+  environmentId: string;
+  createdProject: boolean;
+  createdEnvironment: boolean;
+  upserted: string[];
+}> {
+  const client = resolveClient(opts);
+  const ensured = await ensureEnvironment({
+    project: opts.project,
+    env: opts.env,
+    client,
+  });
+
+  const upserted: string[] = [];
+  if (opts.vars) {
+    for (const [key, value] of Object.entries(opts.vars)) {
+      await client.upsertVar(ensured.environmentId, key, value);
+      upserted.push(key);
+    }
+  }
+
+  return { ...ensured, upserted };
+}
+
+export async function fetchVars(opts: ResolveOptions): Promise<EnvVar[]> {
+  const client = opts.client ?? createClientFromEnv();
+  const { environmentId } = await resolveEnvironment({ ...opts, client });
+  return client.listVars(environmentId);
+}
+
+export async function loadVault(
+  opts: ResolveOptions,
+): Promise<Record<string, string>> {
+  const rows = await fetchVars(opts);
+  const record = varsToRecord(rows);
+  for (const [key, value] of Object.entries(record)) {
+    process.env[key] = value;
+  }
+  return record;
+}
+
+export async function pullVault(opts: PullOptions): Promise<{
+  vars: Record<string, string>;
+  out?: string;
+}> {
+  const rows = await fetchVars(opts);
+  const vars = varsToRecord(rows);
+
+  if (opts.inject !== false) {
+    for (const [key, value] of Object.entries(vars)) {
+      process.env[key] = value;
+    }
+  }
+
+  const out = opts.out;
+  if (out) {
+    await writeFile(out, toDotEnv(vars), "utf8");
+  }
+
+  return out ? { vars, out } : { vars };
+}

package/src/types.ts

@@ -0,0 +1,14 @@
+export type ProjectTreeEnv = { id: string; name: string };
+
+export type ProjectTree = {
+  id: string;
+  name: string;
+  environments: ProjectTreeEnv[];
+};
+
+export type EnvVar = {
+  id: string;
+  key: string;
+  value: string;
+  updated_at: string;
+};