cognia-sdk 0.1.2 → 0.1.3

package/README.md

@@ -33,6 +33,22 @@ const proposals = await session.end();
 Injecting something never counts as using it. Only `outcome()` creates evidence, and only for items this context
 returned. Dogfood, canary and operator traffic is classified server-side and never counts.
 
+
+## Auth: key or delegated token
+
+```ts
+// a developer credential or an SDK credential (cognia_sk_…)
+new Cognia({ apiKey: process.env.COGNIA_API_KEY })
+
+// delegated auth: the host already holds a Cognia bearer (e.g. the MCP OAuth access token)
+new Cognia({ tokenProvider: async () => await getCogniaToken() })   // called on every request, never cached, never in errors
+```
+
+If your identity lives in a connected client (Claude, ChatGPT, OpenClaw…) and the host hides its token, ask the connected
+Cognia to run `sdk_link_start`: it shows a one-time code and a Cloud link; you approve on the website and receive an
+**SDK credential** — a separate, narrow credential that can read context and report outcomes only. Details:
+`docs/SDK_CREDENTIALS.md` in the Cognia repository.
+
 ## Scope
 
 `mine` = the identity's own memories and Skills. `organization` (default) = plus everything its organizations share

package/dist/cjs/client.js

@@ -59,12 +59,14 @@ class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -76,7 +78,11 @@ class Cognia {
         const ac = new AbortController();
         const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request; its answer is used once and never stored on the client
+            const token = this.tokenProvider ? await this.tokenProvider() : this.key;
+            if (!token)
+                throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.3" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();

package/dist/esm/client.d.ts

@@ -1,7 +1,10 @@
 import type { ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
 export interface CogniaOptions {
-    /** the agent's credential (cognia_sk_…); never logged, never put in a URL */
-    apiKey: string;
+    /** the agent's credential (cognia_sk_…, a developer or SDK credential); never logged, never put in a URL */
+    apiKey?: string;
+    /** Delegated auth: called at REQUEST time to obtain the bearer (e.g. an MCP OAuth access token the host already
+     *  holds); async so the host can refresh. The SDK never caches the token and never puts it in errors or onError. */
+    tokenProvider?: () => Promise<string> | string;
     baseUrl?: string;
     /** default scope for context(); the identity's grants decide what that means */
     scope?: Scope;
@@ -33,6 +36,7 @@ export declare class Cognia {
     } | undefined;
     readonly timeoutMs: number;
     private readonly key;
+    private readonly tokenProvider;
     private readonly f;
     private readonly onError;
     constructor(o: CogniaOptions);

package/dist/esm/client.js

@@ -54,12 +54,14 @@ export class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -71,7 +73,11 @@ export class Cognia {
         const ac = new AbortController();
         const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request; its answer is used once and never stored on the client
+            const token = this.tokenProvider ? await this.tokenProvider() : this.key;
+            if (!token)
+                throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.3" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognia-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Cognia for your model calls: one line gives any agent the Memories and Skills it may use, with provenance and honest receipts. Fails open.",
   "license": "MIT",
   "author": "Cognia",