@fatagnus/dink-sdk 2.13.1 → 2.14.0

package/README.md

@@ -81,6 +81,51 @@ const result = await center.call({
 console.log(result); // { temperature: 22.5 }
 ```
 
+## Loading Credentials
+
+Use `loadDinkEnv()` to load credentials from the `.dink/` directory (managed by the `dink env` CLI) with automatic fallback to `DINK_SERVER` / `DINK_API_KEY` environment variables.
+
+> **Note:** This is Node.js only (uses `node:fs`, `node:path`). Available via subpath import `@fatagnus/dink-sdk/env` or from the main entry point.
+
+```typescript
+import { loadDinkEnv } from '@fatagnus/dink-sdk/env';
+import { CenterClient, EdgeClient } from '@fatagnus/dink-sdk';
+
+// Load current environment (from .dink/.current) or fall back to env vars
+const env = await loadDinkEnv();
+
+const center = new CenterClient({ serverUrl: env.server, apiKey: env.apiKey });
+const edge = new EdgeClient({ apiKey: env.apiKey });
+```
+
+Load a specific named environment:
+
+```typescript
+const env = await loadDinkEnv('staging'); // reads .dink/staging.yaml
+```
+
+Credential resolution order:
+1. **Named env** — `.dink/<name>.yaml` (when a name is passed)
+2. **Current env** — `.dink/.current` → `.dink/<current>.yaml`
+3. **Env vars** — `DINK_SERVER` / `DINK_API_KEY` (CI/Docker fallback)
+
+Error handling:
+
+```typescript
+import { DinkEnvError } from '@fatagnus/dink-sdk/env';
+
+try {
+  const env = await loadDinkEnv();
+} catch (e) {
+  if (e instanceof DinkEnvError) {
+    // e.code === 'NO_ENVIRONMENT' — no .dink/ dir and no env vars set
+    // e.code === 'NOT_FOUND'      — named env file missing
+  }
+}
+```
+
+This integrates with `dink env` CLI commands for managing environments. In CI/Docker where no `.dink/` directory exists, set `DINK_SERVER` and `DINK_API_KEY` as environment variables — the same code works without changes.
+
 ## API Key Formats
 
 Dink supports two API key formats for edge authentication:
@@ -188,6 +233,7 @@ You can also import specific clients directly:
 ```typescript
 import { EdgeClient } from '@fatagnus/dink-sdk/edge';
 import { CenterClient } from '@fatagnus/dink-sdk/center';
+import { loadDinkEnv } from '@fatagnus/dink-sdk/env';
 ```
 
 ## Naming Rules

package/dist/env/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Credentials loaded from a .dink/ environment or env vars.
+ */
+export interface DinkEnv {
+    name: string;
+    server: string;
+    apiKey: string;
+}
+/**
+ * Error thrown when environment resolution fails.
+ */
+export declare class DinkEnvError extends Error {
+    readonly code: 'NO_ENVIRONMENT' | 'NOT_FOUND';
+    constructor(message: string, code: 'NO_ENVIRONMENT' | 'NOT_FOUND');
+}
+/**
+ * Load Dink credentials.
+ *
+ * Resolution order:
+ * 1. If `name` provided: find `.dink/` dir, read `.dink/<name>.yaml`
+ * 2. If no `name`: find `.dink/` dir, read `.dink/.current` for active env name
+ * 3. Fall back to `DINK_SERVER` / `DINK_API_KEY` environment variables
+ * 4. Throw `DinkEnvError` with code `'NO_ENVIRONMENT'` if nothing found
+ */
+export declare function loadDinkEnv(name?: string): Promise<DinkEnv>;
+//# sourceMappingURL=index.d.ts.map

package/dist/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAAC;gBAElC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,WAAW;CAKlE;AAyCD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAiCjE"}

package/dist/env/index.js

@@ -0,0 +1,114 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+/**
+ * Error thrown when environment resolution fails.
+ */
+export class DinkEnvError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'DinkEnvError';
+        this.code = code;
+    }
+}
+/**
+ * Walk up from cwd looking for a .dink/ directory.
+ * Returns the absolute path to the .dink/ dir, or null if none found.
+ */
+async function findDinkDir() {
+    let dir = process.cwd();
+    for (;;) {
+        const candidate = join(dir, '.dink');
+        try {
+            const info = await stat(candidate);
+            if (info.isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // not found, keep walking
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            // Reached filesystem root.
+            return null;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Parse a trivial YAML file containing `server` and `api_key` fields.
+ * No dependency — files are always simple key: value pairs.
+ */
+function parseEnvYaml(content) {
+    const serverMatch = content.match(/^server:\s*["']?(.*?)["']?\s*$/m);
+    const apiKeyMatch = content.match(/^api_key:\s*["']?(.*?)["']?\s*$/m);
+    const server = serverMatch ? serverMatch[1] : '';
+    const apiKey = apiKeyMatch ? apiKeyMatch[1] : '';
+    return { server, apiKey };
+}
+/**
+ * Load Dink credentials.
+ *
+ * Resolution order:
+ * 1. If `name` provided: find `.dink/` dir, read `.dink/<name>.yaml`
+ * 2. If no `name`: find `.dink/` dir, read `.dink/.current` for active env name
+ * 3. Fall back to `DINK_SERVER` / `DINK_API_KEY` environment variables
+ * 4. Throw `DinkEnvError` with code `'NO_ENVIRONMENT'` if nothing found
+ */
+export async function loadDinkEnv(name) {
+    const dinkDir = await findDinkDir();
+    // If a name is explicitly provided, we require a .dink/ directory.
+    if (name !== undefined) {
+        if (!dinkDir) {
+            throw new DinkEnvError(`no .dink/ directory found while looking for environment "${name}"`, 'NOT_FOUND');
+        }
+        return loadFromFile(dinkDir, name);
+    }
+    // Try .dink/.current
+    if (dinkDir) {
+        const currentName = await readCurrentEnv(dinkDir);
+        if (currentName) {
+            return loadFromFile(dinkDir, currentName);
+        }
+    }
+    // Fall back to env vars
+    const server = process.env['DINK_SERVER'];
+    const apiKey = process.env['DINK_API_KEY'];
+    if (server) {
+        return { name: '', server, apiKey: apiKey ?? '' };
+    }
+    throw new DinkEnvError('no dink environment found: no .dink/ directory, no .current file, and DINK_SERVER is not set', 'NO_ENVIRONMENT');
+}
+/**
+ * Read the .dink/.current file. Returns the trimmed env name, or null.
+ */
+async function readCurrentEnv(dinkDir) {
+    try {
+        const data = await readFile(join(dinkDir, '.current'), 'utf-8');
+        const trimmed = data.trim();
+        return trimmed || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load and validate a named environment file from `.dink/<name>.yaml`.
+ */
+async function loadFromFile(dinkDir, name) {
+    const filePath = join(dinkDir, `${name}.yaml`);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch {
+        throw new DinkEnvError(`environment "${name}" not found (expected ${filePath})`, 'NOT_FOUND');
+    }
+    const { server, apiKey } = parseEnvYaml(content);
+    if (!server) {
+        throw new Error(`environment "${name}": server field is empty or missing`);
+    }
+    return { name, server, apiKey };
+}
+//# sourceMappingURL=index.js.map

package/dist/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAS,MAAM,WAAW,CAAC;AAWjD;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAiC;IAE9C,YAAY,OAAe,EAAE,IAAoC;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,KAAK,UAAU,WAAW;IACxB,IAAI,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACxB,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC;YACnC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;gBACvB,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,0BAA0B;QAC5B,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,2BAA2B;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrE,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAEtE,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAa;IAC7C,MAAM,OAAO,GAAG,MAAM,WAAW,EAAE,CAAC;IAEpC,mEAAmE;IACnE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,YAAY,CACpB,4DAA4D,IAAI,GAAG,EACnE,WAAW,CACZ,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,qBAAqB;IACrB,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,YAAY,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,IAAI,YAAY,CACpB,8FAA8F,EAC9F,gBAAgB,CACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,cAAc,CAAC,OAAe;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,OAAO,OAAO,IAAI,IAAI,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,YAAY,CAAC,OAAe,EAAE,IAAY;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,YAAY,CACpB,gBAAgB,IAAI,yBAAyB,QAAQ,GAAG,EACxD,WAAW,CACZ,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAEjD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,qCAAqC,CAAC,CAAC;IAC7E,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export { extractPayload, wrapResponse } from './types.js';
 export { EdgeClient, parseEdgeKey, type ParsedEdgeKey } from './edge/client.js';
 export { ServiceBuilder } from './edge/service-builder.js';
 export { CenterClient } from './center/index.js';
+export { loadDinkEnv, DinkEnvError, type DinkEnv } from './env/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EAEZ,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EAEZ,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -7,4 +7,6 @@ export { EdgeClient, parseEdgeKey } from './edge/client.js';
 export { ServiceBuilder } from './edge/service-builder.js';
 // Export center client for connecting to dinkd from the center/cloud
 export { CenterClient } from './center/index.js';
+// Export environment/credential loader (Node.js only)
+export { loadDinkEnv, DinkEnvError } from './env/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,2EAA2E;AAiB3E,0BAA0B;AAC1B,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,0DAA0D;AAC1D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAsB,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,2EAA2E;AAiB3E,0BAA0B;AAC1B,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,0DAA0D;AAC1D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAsB,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,qEAAqE;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,sDAAsD;AACtD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAgB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatagnus/dink-sdk",
-  "version": "2.13.1",
+  "version": "2.14.0",
   "description": "TypeScript SDK for Dink edge mesh platform",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,10 @@
     "./center": {
       "types": "./dist/center/index.d.ts",
       "import": "./dist/center/index.js"
+    },
+    "./env": {
+      "types": "./dist/env/index.d.ts",
+      "import": "./dist/env/index.js"
     }
   },
   "scripts": {