@elding/sdk 0.6.2 → 0.6.5

package/README.md

@@ -1,67 +1,95 @@
 # @elding/sdk
 
-Utilise tes clés API sans jamais les écrire dans ton code. Elding garde la clé
-hors de ton app : ton code manipule un placeholder, la vraie valeur est injectée
-au dernier moment et verrouillée à un seul domaine (anti-exfiltration).
+Your API keys are never in your code or in a `.env` file. Elding keeps them, your code calls the API normally, and the real key is injected at the last moment.
+
+**The same code works in dev and in prod.** You change nothing.
 
 ```bash
 npm install @elding/sdk
 ```
 
-## Pour une clé API HTTP : `configure()`
+> ⚠️ **Elding warning:** always use the **scoped** name `@elding/sdk`. `npm install elding` (without the `@elding/` scope) installs an unrelated third-party package, not Elding.
+
+## Quickstart (2 min)
+
+### 1. Sign in and choose your set
+
+```bash
+npx elding login      # opens the browser, signs you in
+npx elding init       # creates .elding.json (links this project to a set)
+```
+
+### 2. Write your code
 
-Utilise `configure()` pour **toute clé d'API HTTP** (OpenAI, Mistral, Stripe,
-Resend, etc.). Retourne de quoi faire un `fetch` normal, sans jamais exposer la clé.
+`configure()` replaces your real key. 1st argument = the secret name in Elding, 2nd = the API domain.
 
 ```ts
+import OpenAI from "openai";
 import { configure } from "@elding/sdk";
 
-// "MISTRAL_KEY" = nom du secret dans ton vault Elding.
-// 2e arg = le domaine de l'API (verrouillage anti-fuite).
-const { apiKey, baseURL } = await configure("MISTRAL_KEY", "https://api.mistral.ai");
+const openai = new OpenAI(
+  await configure("OPENAI_API_KEY", "https://api.openai.com")
+);
 
-const res = await fetch(`${baseURL}/v1/chat/completions`, {
-  method: "POST",
-  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-  body: JSON.stringify({ model: "mistral-small-latest", messages: [...] }),
-});
+// use openai normally, the real key is never in your code
 ```
 
-Important :
-- **Utilise toujours `baseURL`** dans ton `fetch`, jamais l'URL de l'API en dur.
-  En dev, `baseURL` pointe vers le proxy local qui injecte la vraie clé.
-- Mets `apiKey` dans un **header** (`Authorization`, `x-api-key`…), jamais dans l'URL.
-- `configure()` est réservé aux **API HTTP**. Pour autre chose, voir `secret()`.
+### 3. Run
 
-## Pour un secret non-HTTP : `secret()`
+```bash
+npx elding proxy -- npm run dev
+```
 
-`DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`… tout ce qui n'est pas une API HTTP.
-Retourne la valeur brute. Jamais dans `process.env`, effacée de la mémoire après
-5 min (réglable via `ELDING_CACHE_TTL_MS`).
+That's it. The key **never** enters your application.
 
-```ts
-import { secret } from "@elding/sdk";
+## In production (Vercel, server, CI)
 
-const dbUrl = await secret("DATABASE_URL");
+No proxy in prod. Elding fetches the key at runtime. **You don't change your code**, you just add **2 environment variables**:
+
+```bash
+ELDING_REFRESH_TOKEN=eld_rt_...   # generate it in the dashboard → API keys
+ELDING_SET_ID=...                 # your set's id (set page)
 ```
 
-## Plusieurs secrets d'un coup : `client()`
+And... that's all. The same `configure("OPENAI_API_KEY", "https://api.openai.com")` works.
+
+> The SDK reads these 2 variables automatically. Keep these exact names (`ELDING_REFRESH_TOKEN`, `ELDING_SET_ID`) and you have **no option** to pass.
+
+### How to get the 2 keys
+
+| Variable | Where to find it |
+|---|---|
+| `ELDING_REFRESH_TOKEN` | Dashboard → **API keys** → New key (shown only once) |
+| `ELDING_SET_ID` | Open your set in the dashboard, the id is in the URL |
+
+## The 2 functions
+
+**`configure(name, domain)`** — for any **HTTP API** key (OpenAI, Mistral, Stripe, Resend…).
+You pass it directly to the provider's SDK:
 
 ```ts
-import { client } from "@elding/sdk";
+const openai = new OpenAI(await configure("OPENAI_API_KEY", "https://api.openai.com"));
+```
+
+**`secret(name)`** — for everything **else** (`DATABASE_URL`, `JWT_SECRET`, `REDIS_URL`…).
+Returns the raw value, wiped from memory after 5 min.
 
-const elding = await client();
-const dbUrl = elding.secret("DATABASE_URL");
+```ts
+import { secret } from "@elding/sdk";
+const dbUrl = await secret("DATABASE_URL");
 ```
 
-## Règle simple
+## Dev vs prod, at a glance
 
-- Clé qui part dans une **requête HTTP** → `configure(nom, "https://api.exemple.com")`.
-- N'importe quel **autre secret** → `secret(nom)`.
-- **Jamais** de clé en dur, jamais dans `process.env`, jamais dans l'URL.
+| | Dev | Prod |
+|---|---|---|
+| Command | `elding proxy -- npm run dev` | `npm run build && npm start` |
+| Mechanism | local proxy | runtime fetch |
+| To configure | `elding login` + `elding init` | `ELDING_REFRESH_TOKEN` + `ELDING_SET_ID` |
+| Your code | identical | **identical** |
 
-## Dev vs prod
+## Rules
 
-- **Dev** (`elding proxy -- npm run dev`) : la clé n'entre jamais dans ton process.
-- **Prod** (serverless) : la clé est récupérée du vault au runtime. Elle reste
-  verrouillée au domaine, surveillée, révocable en un clic.
+- **Never** hardcode a key, never in `process.env`, never in the URL.
+- A key that goes into an HTTP request → `configure(name, "https://…")`.
+- Any other secret → `secret(name)`.

package/dist/api.js

@@ -8,14 +8,14 @@ const REQUEST_TIMEOUT_MS = 15_000;
 const REFRESH_TOKEN = /^eld_rt_[a-f0-9]{64}$/i;
 async function exchangeToken(refreshToken) {
     if (!REFRESH_TOKEN.test(refreshToken))
-        throw new Error("[elding] Token local invalide.");
+        throw new Error("[elding] Invalid local token.");
     const body = await requestJson("/api/cli/auth/token", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ refreshToken }),
     });
     if (!body.success || !body.accessToken)
-        throw new Error(safeError(body.error) || "Échec d'authentification Elding");
+        throw new Error(safeError(body.error) || "Elding authentication failed");
     return body.accessToken;
 }
 async function fetchSecrets(accessToken, setId) {
@@ -23,7 +23,7 @@ async function fetchSecrets(accessToken, setId) {
         headers: { Authorization: `Bearer ${accessToken}` },
     });
     if (!body.success || !body.secrets || typeof body.secrets !== "object")
-        throw new Error(safeError(body.error) || "Réponse invalide");
+        throw new Error(safeError(body.error) || "Invalid response");
     return sanitizeSecrets(body.secrets);
 }
 const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
@@ -48,9 +48,9 @@ async function requestJson(path, init) {
     });
     const body = (await res.json().catch(() => null));
     if (!res.ok)
-        throw new Error(safeError(body?.error) || `Erreur ${res.status}`);
+        throw new Error(safeError(body?.error) || `Error ${res.status}`);
     if (!body || typeof body !== "object")
-        throw new Error("[elding] Réponse invalide.");
+        throw new Error("[elding] Invalid response.");
     return body;
 }
 function safeError(value) {

package/dist/apiUrl.js

@@ -28,17 +28,17 @@ function resolveBaseUrl(raw = process.env.ELDING_API_URL) {
         url = new URL(input);
     }
     catch {
-        throw new Error("[elding] ELDING_API_URL invalide.");
+        throw new Error("[elding] Invalid ELDING_API_URL.");
     }
     if (url.username || url.password) {
-        throw new Error("[elding] ELDING_API_URL ne doit pas contenir d'identifiants.");
+        throw new Error("[elding] ELDING_API_URL must not contain credentials.");
     }
     if (url.pathname !== "/" || url.search || url.hash) {
-        throw new Error("[elding] ELDING_API_URL doit etre une origine seule.");
+        throw new Error("[elding] ELDING_API_URL must be an origin only.");
     }
     if (url.protocol === "https:")
         return url.origin;
     if (url.protocol === "http:" && isLoopbackHost(url.hostname))
         return url.origin;
-    throw new Error("[elding] ELDING_API_URL doit utiliser HTTPS, sauf pour localhost en developpement.");
+    throw new Error("[elding] ELDING_API_URL must use HTTPS, except for localhost in development.");
 }

package/dist/client.js

@@ -14,11 +14,11 @@ class EldingClient {
         // 1. Resolve setId : option explicite → .elding.json (dev) → ELDING_SET_ID (serverless/CI)
         const setId = options.setId ?? (0, config_js_1.readProjectConfig)()?.setId ?? process.env.ELDING_SET_ID?.trim();
         if (!setId)
-            throw new Error("[elding] setId introuvable. Lancez `elding init`, passez setId en option, ou définissez ELDING_SET_ID.");
+            throw new Error("[elding] setId not found. Run `elding init`, pass setId as an option, or set ELDING_SET_ID.");
         // 2. Resolve refresh token
         const refreshToken = options.refreshToken ?? (0, config_js_1.readGlobalConfig)()?.refreshToken;
         if (!refreshToken)
-            throw new Error("[elding] Token introuvable. Lancez `elding login` ou passez refreshToken en option.");
+            throw new Error("[elding] Token not found. Run `elding login` or pass refreshToken as an option.");
         // 3. Fetch secrets
         const accessToken = await (0, api_js_1.exchangeToken)(refreshToken);
         const secrets = await (0, api_js_1.fetchSecrets)(accessToken, setId);
@@ -33,7 +33,7 @@ class EldingClient {
             if (envValue !== undefined)
                 return envValue;
         }
-        throw new Error(`[elding] Secret "${name}" introuvable dans le set.`);
+        throw new Error(`[elding] Secret "${name}" not found in the set.`);
     }
     // Returns undefined instead of throwing
     secretOrUndefined(name) {

package/dist/configure.d.ts

@@ -1,9 +1,10 @@
-import { type ClientOptions } from "./client.js";
+import { EldingClient, type ClientOptions } from "./client.js";
 export type ProviderConfig = {
     apiKey: string;
     baseURL?: string;
     defaultHeaders?: Record<string, string>;
 };
+export declare function getClient(options: ClientOptions): Promise<EldingClient>;
 /** Efface immédiatement les secrets gardés en mémoire par le SDK. */
 export declare function clearSecretCache(): void;
 export declare function configure(secretName: string, target: string, options?: ClientOptions): Promise<ProviderConfig>;

package/dist/configure.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getClient = getClient;
 exports.clearSecretCache = clearSecretCache;
 exports.configure = configure;
 exports.secret = secret;
@@ -60,12 +61,12 @@ function isHttpTarget(target) {
 }
 async function configure(secretName, target, options = {}) {
     if (!SECRET_NAME.test(secretName))
-        throw new Error("[elding] Nom de secret invalide (A-Z, 0-9, _).");
+        throw new Error("[elding] Invalid secret name (A-Z, 0-9, _).");
     // configure() protège uniquement les API HTTP via le proxy. Pour une valeur
     // non-HTTP (DATABASE_URL, config...), le proxy ne peut rien intercepter :
     // on guide vers secret() plutot que de renvoyer une valeur faussement "protégée".
     if (!isHttpTarget(target))
-        throw new Error(`[elding] configure() attend une API HTTP. Pour "${secretName}" (non-HTTP, ex. DATABASE_URL), utilise secret("${secretName}") — valeur brute, jamais protégée par le proxy.`);
+        throw new Error(`[elding] configure() expects an HTTP API. For "${secretName}" (non-HTTP, e.g. DATABASE_URL), use secret("${secretName}") — raw value, never protected by the proxy.`);
     // Mode proxy (dev) : placeholder, la vraie clé n'entre jamais dans le process.
     if ((0, proxy_js_1.isProxyActive)()) {
         const { baseURL, headers } = (0, proxy_js_1.proxyConfig)(target);
@@ -86,7 +87,7 @@ async function configure(secretName, target, options = {}) {
  */
 async function secret(name, options = {}) {
     if (!SECRET_NAME.test(name))
-        throw new Error("[elding] Nom de secret invalide (A-Z, 0-9, _).");
+        throw new Error("[elding] Invalid secret name (A-Z, 0-9, _).");
     const elding = await getClient(options);
     return elding.secret(name);
 }

package/dist/index.d.ts

@@ -1,16 +1,13 @@
 import { EldingClient, type ClientOptions } from "./client.js";
+import { configure, secret } from "./configure.js";
 export { configure, secret, clearSecretCache, type ProviderConfig } from "./configure.js";
+declare const elding: {
+    configure: typeof configure;
+    secret: typeof secret;
+};
+export default elding;
 export { EldingClient };
 export type { ClientOptions };
 export { isProxyActive } from "./proxy.js";
-/**
- * Crée un client Elding et charge tous les secrets du set configuré.
- *
- * @example
- * const elding = await client();
- * const key = elding.secret("OPENAI_API_KEY");
- *
- * @example avec options
- * const elding = await client({ setId: "xxx", refreshToken: "eld_rt_..." });
- */
+/** Crée un client Elding et charge tous les secrets du set configuré. */
 export declare function client(options?: ClientOptions): Promise<EldingClient>;

package/dist/index.js

@@ -4,25 +4,20 @@ exports.isProxyActive = exports.EldingClient = exports.clearSecretCache = export
 exports.client = client;
 const client_js_1 = require("./client.js");
 Object.defineProperty(exports, "EldingClient", { enumerable: true, get: function () { return client_js_1.EldingClient; } });
+const configure_js_1 = require("./configure.js");
 // ── API principale ──
-var configure_js_1 = require("./configure.js");
-Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return configure_js_1.configure; } });
-Object.defineProperty(exports, "secret", { enumerable: true, get: function () { return configure_js_1.secret; } });
-Object.defineProperty(exports, "clearSecretCache", { enumerable: true, get: function () { return configure_js_1.clearSecretCache; } });
-// ── Avancé : vérifier le mode (proxy actif ou non) ──
+// configure(name, "https://…") pour une clé d'API HTTP (passée au SDK provider
+// ou à fetch), secret(name) pour les secrets non-HTTP (DATABASE_URL, JWT_SECRET…).
+var configure_js_2 = require("./configure.js");
+Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return configure_js_2.configure; } });
+Object.defineProperty(exports, "secret", { enumerable: true, get: function () { return configure_js_2.secret; } });
+Object.defineProperty(exports, "clearSecretCache", { enumerable: true, get: function () { return configure_js_2.clearSecretCache; } });
+// Objet namespace : `import elding from "@elding/sdk"; elding.configure(...)`.
+const elding = { configure: configure_js_1.configure, secret: configure_js_1.secret };
+exports.default = elding;
 var proxy_js_1 = require("./proxy.js");
 Object.defineProperty(exports, "isProxyActive", { enumerable: true, get: function () { return proxy_js_1.isProxyActive; } });
-// proxyConfig reste interne : configure() le supersede (proxy + bascule dev/prod auto).
-/**
- * Crée un client Elding et charge tous les secrets du set configuré.
- *
- * @example
- * const elding = await client();
- * const key = elding.secret("OPENAI_API_KEY");
- *
- * @example avec options
- * const elding = await client({ setId: "xxx", refreshToken: "eld_rt_..." });
- */
+/** Crée un client Elding et charge tous les secrets du set configuré. */
 async function client(options) {
     return client_js_1.EldingClient.create(options);
 }

package/dist/proxy.js

@@ -24,7 +24,7 @@ function proxyConfig(target) {
     const url = validateProxyUrl(process.env.ELDING_PROXY_URL);
     const token = process.env.ELDING_PROXY_TOKEN;
     if (!url || !token || !PROXY_TOKEN.test(token))
-        throw new Error("[elding] Proxy non actif. Lancez via `elding proxy -- <cmd>`.");
+        throw new Error("[elding] Proxy not active. Run via `elding proxy -- <cmd>`.");
     const safeTarget = validateTarget(target);
     return {
         baseURL: url,
@@ -53,14 +53,14 @@ function validateProxyUrl(value) {
         url.pathname !== "/" ||
         url.search ||
         url.hash) {
-        throw new Error("[elding] ELDING_PROXY_URL invalide.");
+        throw new Error("[elding] Invalid ELDING_PROXY_URL.");
     }
     return url.origin;
 }
 function validateTarget(value) {
     const url = new URL(value);
     if (url.protocol !== "https:" || url.username || url.password) {
-        throw new Error("[elding] La cible proxy doit etre une URL HTTPS sans identifiants.");
+        throw new Error("[elding] The proxy target must be an HTTPS URL without credentials.");
     }
     url.hash = "";
     return url.origin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elding/sdk",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "description": "Elding SDK — accès aux secrets depuis le code, zéro .env",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",