eric-sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,235 +1,301 @@
-📘 Eric SDK (JavaScript + TypeScript)
+# 📘 Eric SDK (JavaScript + TypeScript)
 
-Official SDK for interacting with the Eric AI Policy Engine.
-Eric routes user input to the correct AI flow (or a restricted subset of flows) and returns structured, domain-aware results.
+**Official SDK for interacting with Eric AI — a governed, deterministic routing layer for AI systems.**
 
-🚀 Features
+Eric evaluates incoming requests, applies routing constraints, selects the appropriate AI flow, and returns **structured, auditable outputs**.
+Used in **Ingomu**, **EventInterface**, and early enterprise pilots.
 
-Agentic routing with eric.decide()
+---
 
-Manual flow calls with eric.call(flowName, data)
+## 🚀 Features
 
-Restricted routing with allowedFlows
+* 🔁 **Governed routing** via `eric.decide()`
+* 🧭 Deterministic flow selection using the **decisionRouter**
+* 🎯 Restricted auto-routing with `allowedFlows`
+* 🔧 Direct flow execution with `eric.call()`
+* 🔒 Public vs Private API key security model
+* 🧠 Domain-aware tone and behavior (events, wellness, business)
+* 🛡️ Domain whitelisting + rate limiting (public keys)
+* 🧱 Strong TypeScript typing
+* 🧰 Production-ready SDK backed by Firebase Cloud Functions
 
-Flow-specific structured responses
+---
 
-Domain-aware behavior (wellness, events, workplace)
+## 📦 Installation
 
-Full TypeScript typing
+```bash
+npm install eric-sdk
+```
 
-Production-ready — used in Ingomu, EventInterface, and enterprise pilots
+---
 
-📦 Installation
-npm install eric-sdk
+## 🔑 API Keys (Important)
+
+Eric supports **two types of API keys**, similar to Stripe or OpenAI.
+
+### 🔓 Public Key (`pub_xxx`)
+
+Safe for browser usage (Vue, React, etc.)
+
+* Rate-limited
+* Domain-whitelisted
+* Restricted to **safe flows only**
+
+Allowed flows with a public key:
+
+* `decisionRouter`
+* `shortTextSummary`
+* `announcementRewriter`
+
+Public keys **cannot** execute admin or sensitive flows.
+
+---
+
+### 🔐 Private Key (`priv_xxx`)
+
+Server-to-server only.
+
+* Full access to all flows
+* No domain restriction
+* Higher rate limits
+* Intended for trusted backend workloads
+
+⚠️ If a private key leaks, anyone can trigger billable flows — **the owning client is billed**.
+This is the same model used by Stripe, OpenAI, Twilio, and AWS.
+
+---
 
-🔑 Quick Start — Automatic Flow Selection
+## 🔧 Quick Start — Governed Auto-Routing
+
+```ts
 import { EricSDK } from "eric-sdk";
 
 const eric = new EricSDK({
-  apiKey: process.env.ERIC_API_KEY!,
+  apiKey: process.env.ERIC_API_KEY!, // pub_ or priv_
   client: "eventinterface",
 });
 
 const result = await eric.decide({
   text: "I'm overwhelmed today.",
 });
+```
 
-Example output:
+### Example response
 
+```json
 {
   "flow": "dailyNudgeGenerator",
   "type": "structured",
   "data": {
     "nudge": "You're building momentum — take a breath and trust your progress."
+  },
+  "meta": {
+    "routingMode": "llm",
+    "reason": "Detected emotional distress language"
   }
 }
+```
 
-🎯 Auto-Routing (Advanced)
-🔹 Decide automatically
-const result = await eric.decide({
-  text: "Can you rewrite this announcement?",
-});
-
+The `meta` field explains **why** a particular flow was chosen.
 
-Eric chooses the correct flow (announcementRewriter, shortTextSummary, etc.)
+---
 
-🔒 Restricting Auto-Routing (allowedFlows)
-
-You can force Eric to only pick from certain flows.
-
-Example: only allow announcement rewriting:
+## 🎯 Auto-Routing with Restrictions
 
+```ts
 const result = await eric.decide({
   text: this.form.body,
   allowedFlows: ["announcementRewriter"],
   userState: {
     tone: "energetic",
-    length: 150
-  }
+    length: 150,
+  },
 });
+```
 
+### Guarantees
 
-This guarantees:
+* Eric **must** choose `announcementRewriter`
+* No unrelated flows can be selected
+* Predictable, safe behavior for admin tools
 
-Eric does not pick shortTextSummary
+---
 
-Eric must choose announcementRewriter
+## 🔧 Manual Flow Execution (Private Key Only)
 
-If allowedFlows has only one item, it will always choose that one
+```ts
+const result = await eric.call("speakerPerformanceAnalyzer", {
+  speakerName: "Jane Doe",
+  feedbackComments: ["Loved the energy!", "Slides were unclear"],
+});
+```
 
-Example output:
+Use `eric.call()` when:
 
-{
-  "flow": "announcementRewriter",
-  "type": "structured",
-  "data": {
-    "rewritten": "Heads up! The pool party is now at the yacht club...",
-    "toneUsed": "energetic"
-  }
-}
+* You already know the exact flow
+* Running batch jobs or scheduled tasks
+* Executing admin or restricted operations
+* Using private server keys
 
-🔧 Manual Flow Execution
+---
 
-Use .call() to skip routing and directly invoke any flow:
+## 🧠 When to Use `decide()` vs `call()`
 
-const result = await eric.call("announcementRewriter", {
-  announcement: "We moved the meeting.",
-  tone: "friendly",
-  length: 200
-});
+| Method                          | Use Case                                       |
+| ------------------------------- | ---------------------------------------------- |
+| `eric.decide()`                 | Let Eric select the correct flow automatically |
+| `eric.decide({ allowedFlows })` | Auto-routing restricted to a safe list         |
+| `eric.call()`                   | Direct execution when flow is already known    |
 
+---
 
-Useful for admin panels, batch processing, and scheduled tasks.
+## 🧱 Full SDK API
 
-🧠 When to Use What
-Method	Use When
-eric.decide()	You want Eric to choose the correct flow automatically
-eric.decide({ allowedFlows: [...] })	You want Eric to choose, but only within a safe controlled list
-eric.call()	You already know which flow to use (like admin tools, backend tasks)
-🧱 Full SDK API
-eric.decide(options)
-eric.decide({
+### `eric.decide(options)`
+
+```ts
+{
   text?: string;
   userState?: Record<string, any>;
   topic?: string;
   allowedFlows?: string[];
-});
-
+}
+```
 
 Returns:
 
+```ts
 {
   flow: string;
   type: "structured" | "text";
   data: any;
+  meta?: {
+    routingMode: "direct" | "requestType" | "signature" | "llm" | "forced";
+    reason: string;
+  };
 }
+```
 
-eric.call(flowName, data)
-const out = await eric.call("shortTextSummary", {
-  text: "Make this clearer."
-});
-
-
-Equivalent to:
-
-eric.runFlow({ flow: "shortTextSummary", data: {...} })
-
-💬 Examples
-Example 1 — Clean up an announcement (EventInterface admin)
-const result = await eric.decide({
-  text: this.form.body,
-  allowedFlows: ["announcementRewriter"],
-  userState: {
-    tone: "energetic",
-    length: 150,
-  }
-});
+---
 
-this.aiSummary = result.data.rewritten;
+### `eric.call(flow, data)`
 
-Example 2 — Generate a summary (default)
-const result = await eric.decide({
-  text: "Here is a long announcement, please make it shorter."
-});
+Direct execution of a known flow.
 
+---
 
-May produce:
+## 🧩 Supported Flows
 
-shortTextSummary
+### Common
 
-announcementRewriter
-(depends on the text)
+* `decisionRouter`
+* `shortTextSummary`
+* `questionAnswerHelper`
+* `dailyNudgeGenerator`
 
-Example 3 — Force a specific flow
-await eric.call("speakerPerformanceAnalyzer", {
-  speakerName: "Jane Doe",
-  feedbackComments: ["Loved the energy!", "Slides were unclear"]
-});
+### Wellness
 
-🧩 Supported Flows
-Common
+* `aiCoachFeedback`
+* `personalizedSessionRecommender`
+* `wellnessProgressReporter`
+* `trendInsightReporter`
 
-shortTextSummary
+### Events
 
-questionAnswerHelper
+* `eventSummaryDigest`
+* `speakerPerformanceAnalyzer`
+* `networkingMatchmaker`
+* `attendeeEngagementReporter`
+* `eventPulseReport`
+* `sessionRecapGenerator`
+* `sponsorValueSummary`
+* `announcementRewriter`
 
-dailyNudgeGenerator
+### Business
 
-Wellness
+* `leadershipInsight`
+* `feedbackInsightAnalyzer`
+* `performanceReviewAssistant`
+* `teamDynamicsAnalyzer`
+* `productivityCoach`
 
-aiCoachFeedback
+---
 
-personalizedSessionRecommender
+## 🌐 Public Key Security Model
 
-wellnessProgressReporter
+Eric’s backend enforces:
 
-trendInsightReporter
+### ✔ Allowed Flows
 
-Events
+Public keys may only call:
 
-eventSummaryDigest
+* `decisionRouter`
+* `shortTextSummary`
+* `announcementRewriter`
 
-speakerPerformanceAnalyzer
+---
 
-networkingMatchmaker
+### ✔ Domain Whitelisting
 
-attendeeEngagementReporter
+Only approved origins can access public keys:
 
-eventPulseReport
+```json
+[
+  "http://localhost:5173",
+  "https://eventinterface.com",
+  "https://www.eventinterface.com",
+  "https://ingomu.com",
+  "https://www.ingomu.com"
+]
+```
 
-sessionRecapGenerator
+---
 
-sponsorValueSummary
+### ✔ Rate Limiting
 
-announcementRewriter
+* Default: **60 requests per minute per IP**
+* Applies only to public keys
+* Enforced automatically by the backend
 
-Business / Workplace
+---
 
-leadershipInsight
+## 🛡️ Private Key Rules
 
-feedbackInsightAnalyzer
+Private keys:
 
-performanceReviewAssistant
+* Must be used server-side only
+* Are not domain-restricted
+* Can execute all flows
+* Should be stored in environment variables
+* Are billed per usage
 
-teamDynamicsAnalyzer
+---
 
-productivityCoach
+## ⚙️ Configuration
 
-🌐 Configuration
+```ts
 new EricSDK({
-  apiKey: "YOUR_API_KEY",
-  client: "your-client-id",
-  baseUrl: "https://us-central1-eric-ai-prod.cloudfunctions.net/runFlow"
+  apiKey: "pub_xxx" | "priv_xxx",
+  client: "eventinterface",
+  baseUrl: "https://us-central1-eric-ai-prod.cloudfunctions.net/runFlow",
 });
+```
 
-🔧 Local Development
-npm link
+> **Note:**
+> Domain context (events, wellness, business) is derived server-side from the client identity and is not required in the SDK configuration.
 
+---
 
-In your other project:
+## 🧪 Local Development
 
+```bash
+npm link
+# then in consuming project:
 npm link eric-sdk
+```
+
+---
 
-📄 License
+## 📄 License
 
-MIT © 2025
+MIT © 2025

package/dist/index.cjs

@@ -60,7 +60,6 @@ var EricSDK = class {
   constructor(options) {
     this.apiKey = options.apiKey;
     this.client = options.client;
-    this.appId = options.appId;
     this.baseUrl = options.baseUrl ?? "https://us-central1-eric-ai-prod.cloudfunctions.net/runFlow";
   }
   /* -------------------------------------------------------------
@@ -71,8 +70,7 @@ var EricSDK = class {
       flow: flowName,
       data: {
         ...data,
-        client: this.client,
-        appId: this.appId
+        client: this.client
       }
     };
     const res = await import_axios.default.post(this.baseUrl, payload, {
@@ -90,11 +88,10 @@ var EricSDK = class {
   async decide(data) {
     const { allowedFlows, ...rest } = data;
     const payload = {
-      flow: "policyDecisionMaker",
+      flow: "decisionRouter",
       data: {
         ...rest,
-        client: this.client,
-        appId: this.appId
+        client: this.client
       }
     };
     if (allowedFlows) {

package/dist/index.d.cts

@@ -1,7 +1,6 @@
 interface EricClientOptions {
     apiKey: string;
     client: string;
-    appId: "wellness" | "events" | "business";
     baseUrl?: string;
 }
 interface EricResponse {
@@ -12,7 +11,6 @@ interface EricResponse {
 declare class EricSDK {
     private apiKey;
     private client;
-    private appId;
     private baseUrl;
     constructor(options: EricClientOptions);
     call(flowName: string, data: any): Promise<EricResponse>;

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 interface EricClientOptions {
     apiKey: string;
     client: string;
-    appId: "wellness" | "events" | "business";
     baseUrl?: string;
 }
 interface EricResponse {
@@ -12,7 +11,6 @@ interface EricResponse {
 declare class EricSDK {
     private apiKey;
     private client;
-    private appId;
     private baseUrl;
     constructor(options: EricClientOptions);
     call(flowName: string, data: any): Promise<EricResponse>;

package/dist/index.js

@@ -4,7 +4,6 @@ var EricSDK = class {
   constructor(options) {
     this.apiKey = options.apiKey;
     this.client = options.client;
-    this.appId = options.appId;
     this.baseUrl = options.baseUrl ?? "https://us-central1-eric-ai-prod.cloudfunctions.net/runFlow";
   }
   /* -------------------------------------------------------------
@@ -15,8 +14,7 @@ var EricSDK = class {
       flow: flowName,
       data: {
         ...data,
-        client: this.client,
-        appId: this.appId
+        client: this.client
       }
     };
     const res = await axios.post(this.baseUrl, payload, {
@@ -34,11 +32,10 @@ var EricSDK = class {
   async decide(data) {
     const { allowedFlows, ...rest } = data;
     const payload = {
-      flow: "policyDecisionMaker",
+      flow: "decisionRouter",
       data: {
         ...rest,
-        client: this.client,
-        appId: this.appId
+        client: this.client
       }
     };
     if (allowedFlows) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eric-sdk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Official SDK for interacting with the Eric AI Policy Engine",
   "author": "Rod Bridges",
   "license": "MIT",

package/src/client.ts

@@ -3,7 +3,6 @@ import axios from "axios";
 export interface EricClientOptions {
   apiKey: string;
   client: string;               // ingomu, eventinterface, etc.
-  appId: "wellness" | "events" | "business"; // REQUIRED for policy engine
   baseUrl?: string;
 }
 
@@ -16,13 +15,11 @@ export interface EricResponse {
 export class EricSDK {
   private apiKey: string;
   private client: string;
-  private appId: string;
   private baseUrl: string;
 
   constructor(options: EricClientOptions) {
     this.apiKey = options.apiKey;
     this.client = options.client;
-    this.appId = options.appId;   // <-- FIXED: needed for policy input
     this.baseUrl =
       options.baseUrl ??
       "https://us-central1-eric-ai-prod.cloudfunctions.net/runFlow";
@@ -37,7 +34,6 @@ export class EricSDK {
       data: {
         ...data,
         client: this.client,
-        appId: this.appId
       }
     };
 
@@ -64,11 +60,10 @@ export class EricSDK {
     const { allowedFlows, ...rest } = data;
 
     const payload: any = {
-      flow: "policyDecisionMaker",
+      flow: "decisionRouter",
       data: {
         ...rest,
         client: this.client,
-        appId: this.appId
       }
     };