learn-secrets-sdk 1.3.0 → 1.5.0

package/README.md

@@ -1,51 +1,102 @@
 # learn-secrets-sdk
 
-secure api proxy sdk for static sites. call external apis (openai, anthropic, stripe, etc.) without exposing api keys.
+secure api proxy for static sites. call external apis (openai, anthropic, stripe, etc.) without exposing api keys.
 
-## quick start
+**zero-config:** no tokens or credentials in your code. authentication via origin header.
 
-### 1. setup in dashboard
+## quick start (cli)
 
-* login at [learn.pages.dev](https://learn.pages.dev)
-* add api key in secrets → api_keys
-* create sdk token in settings → sdk tokens
-* configure allowed origins (e.g., `example.com`, `*.example.com`)
-* copy app id from sidebar
+### 1. install cli
 
-### 2. install
+```bash
+npm install -g learn-secrets-sdk
+```
+
+### 2. authenticate
+
+```bash
+learn-secrets login
+```
+
+### 3. initialize project
+
+```bash
+learn-secrets init --project YOUR_PROJECT_ID --origins yourdomain.com,localhost --env .env
+```
+
+auto-detects api keys from `.env` and uploads them. configures origins for your site.
+
+**get project id:** visit [ctklearn.carsontkempf.workers.dev](https://ctklearn.carsontkempf.workers.dev) → copy from sidebar
+
+### 4. install sdk in project
 
 ```bash
 npm install learn-secrets-sdk
 ```
 
-### 3. use in your app
+### 5. use in code
 
 ```typescript
 import { SecretsSDK } from 'learn-secrets-sdk';
 
-const sdk = new SecretsSDK({
-  appId: 'your-app-id',
-  token: 'sk_live_...'
-});
+// zero-config - no credentials needed
+const sdk = new SecretsSDK();
 
-// call openai
-const response = await sdk.post('my-openai-key', '/v1/chat/completions', {
+// call openai securely
+const response = await sdk.post('openai', '/v1/chat/completions', {
   model: 'gpt-4',
   messages: [{ role: 'user', content: 'hello' }]
 });
 ```
 
+**how it works:**
+* browser sends `Origin` header automatically
+* proxy validates origin matches configured domains
+* api key injected server-side
+* no tokens or credentials in client code
+
 ## features
 
-* **domain-scoped tokens** - tokens only work from configured origins
-* **zero api key exposure** - keys stay server-side, never sent to client
+* **zero-config** - no tokens, appid, or credentials in code
+* **origin-based auth** - automatic browser security via origin header
+* **api keys secured** - stored server-side, never exposed to clients
+* **auto-detection** - cli detects openai, anthropic, stripe, github, google
 * **works anywhere** - cloudflare pages, netlify, vercel, any static host
 * **rate limiting** - 100 req/min per domain built-in
-* **typescript support** - full type definitions included
+* **typescript** - full type definitions included
+
+## cli commands
+
+### login
+```bash
+learn-secrets login
+```
+authenticate via browser oauth. credentials saved to `~/.learn/credentials.json`.
+
+### init
+```bash
+learn-secrets init \
+  --project abc123xyz \           # your project id
+  --origins example.com,localhost \ # allowed domains
+  --env .env                      # path to .env file
+```
+
+reads .env, detects api keys, uploads to project, configures origins.
+
+**auto-detects:**
+* `OPENAI_API_KEY` → openai provider
+* `ANTHROPIC_API_KEY` → anthropic provider
+* `STRIPE_SECRET_KEY` → stripe provider
+* `GITHUB_TOKEN` → github provider
+* `*_API_KEY` → custom provider
+
+full cli docs: [cli reference](https://ctklearn.carsontkempf.workers.dev/docs/sdk/cli)
 
 ## api methods
 
 ```typescript
+const sdk = new SecretsSDK();
+
 // http methods
 await sdk.get(keyName, endpoint, headers?)
 await sdk.post(keyName, endpoint, body, headers?)
@@ -63,14 +114,19 @@ await sdk.call(keyName, endpoint, {
 
 ## constructor options
 
+**zero-config (recommended):**
 ```typescript
-new SecretsSDK({
-  appId: string,              // required - from dashboard
-  token: string,              // required - from settings → sdk tokens
-  baseUrl?: string,           // optional - defaults to https://learn.pages.dev
-  timeout?: number,           // optional - request timeout in ms (default: 30000)
-  retryOn429?: boolean        // optional - auto-retry on rate limit (default: true)
-})
+const sdk = new SecretsSDK();
+```
+uses origin header for authentication. no credentials needed.
+
+**advanced options:**
+```typescript
+const sdk = new SecretsSDK({
+  baseUrl?: string,     // custom proxy url (default: production)
+  timeout?: number,     // request timeout ms (default: 30000)
+  retryOn429?: boolean  // auto-retry on rate limit (default: true)
+});
 ```
 
 ## error handling
@@ -78,17 +134,21 @@ new SecretsSDK({
 ```typescript
 import { SecretsSDK, SecretsSDKError, OriginMismatchError, RateLimitError } from 'learn-secrets-sdk';
 
+const sdk = new SecretsSDK();
+
 try {
-  const response = await sdk.post('key', '/endpoint', data);
+  const response = await sdk.post('openai', '/v1/chat/completions', data);
 } catch (error) {
   if (error instanceof OriginMismatchError) {
-    // domain not in allowed origins
+    // domain not configured in allowed origins
+    console.error('add domain to origins in dashboard');
   } else if (error instanceof RateLimitError) {
     // exceeded 100 req/min
-    console.log('retry after:', error.retryAfter);
+    console.log('retry after:', error.retryAfter, 'seconds');
   } else if (error instanceof SecretsSDKError) {
     // other api errors
     console.log('status:', error.status);
+    console.log('message:', error.message);
   }
 }
 ```
@@ -96,34 +156,46 @@ try {
 ## usage tracking
 
 ```typescript
-const sdk = new SecretsSDK({ appId, token });
+const sdk = new SecretsSDK();
 
-await sdk.post('key', '/endpoint', data);
+await sdk.post('openai', '/v1/chat/completions', data);
 
 // check rate limit status
 const usage = sdk.getUsage();
 console.log('remaining:', usage.remaining);  // requests left this minute
+console.log('limit:', usage.limit);          // 100
 console.log('resets at:', usage.reset);      // unix timestamp
 ```
 
 ## examples
 
-### vanilla html
+### vanilla javascript
 
 ```html
-<script type="module">
-  import { SecretsSDK } from 'https://unpkg.com/learn-secrets-sdk';
-
-  const sdk = new SecretsSDK({
-    appId: 'abc123',
-    token: 'sk_live_...'
-  });
-
-  const result = await sdk.post('my-openai-key', '/v1/chat/completions', {
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: 'hello' }]
-  });
-</script>
+<!DOCTYPE html>
+<html>
+<body>
+  <button onclick="callAPI()">call ai</button>
+  <div id="response"></div>
+
+  <script type="module">
+    import { SecretsSDK } from './node_modules/learn-secrets-sdk/dist/index.js';
+
+    // zero-config
+    const sdk = new SecretsSDK();
+
+    window.callAPI = async function() {
+      const result = await sdk.post('openai', '/v1/chat/completions', {
+        model: 'gpt-4',
+        messages: [{ role: 'user', content: 'hello' }]
+      });
+
+      document.getElementById('response').textContent =
+        result.choices[0].message.content;
+    };
+  </script>
+</body>
+</html>
 ```
 
 ### react
@@ -133,17 +205,18 @@ import { useMemo } from 'react';
 import { SecretsSDK } from 'learn-secrets-sdk';
 
 function App() {
-  const sdk = useMemo(() => new SecretsSDK({
-    appId: import.meta.env.VITE_APP_ID,
-    token: import.meta.env.VITE_SDK_TOKEN
-  }), []);
+  // zero-config sdk
+  const sdk = useMemo(() => new SecretsSDK(), []);
 
   const handleClick = async () => {
-    const result = await sdk.post('my-openai-key', '/v1/chat/completions', {
+    const result = await sdk.post('openai', '/v1/chat/completions', {
       model: 'gpt-4',
       messages: [{ role: 'user', content: 'hello' }]
     });
+    console.log(result.choices[0].message.content);
   };
+
+  return <button onClick={handleClick}>call ai</button>;
 }
 ```
 
@@ -153,15 +226,12 @@ function App() {
 import { ref } from 'vue';
 import { SecretsSDK } from 'learn-secrets-sdk';
 
-const sdk = new SecretsSDK({
-  appId: import.meta.env.VITE_APP_ID,
-  token: import.meta.env.VITE_SDK_TOKEN
-});
-
+// zero-config sdk
+const sdk = new SecretsSDK();
 const response = ref('');
 
 async function callAPI() {
-  const result = await sdk.post('my-openai-key', '/v1/chat/completions', {
+  const result = await sdk.post('openai', '/v1/chat/completions', {
     model: 'gpt-4',
     messages: [{ role: 'user', content: 'hello' }]
   });
@@ -169,37 +239,87 @@ async function callAPI() {
 }
 ```
 
+### next.js
+
+```typescript
+'use client';
+
+import { useCallback, useMemo } from 'react';
+import { SecretsSDK } from 'learn-secrets-sdk';
+
+export default function ChatPage() {
+  // zero-config sdk
+  const sdk = useMemo(() => new SecretsSDK(), []);
+
+  const chat = useCallback(async (message: string) => {
+    const result = await sdk.post('openai', '/v1/chat/completions', {
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: message }]
+    });
+    return result.choices[0].message.content;
+  }, [sdk]);
+
+  // ... rest of component
+}
+```
+
 ## supported providers
 
-* openai
-* anthropic
-* stripe
-* any http-based api
+auto-configured base urls when using cli:
+* openai (`OPENAI_API_KEY`)
+* anthropic (`ANTHROPIC_API_KEY`)
+* stripe (`STRIPE_SECRET_KEY`)
+* github (`GITHUB_TOKEN`)
+* google (`GOOGLE_API_KEY`)
+
+custom providers supported - configure base url in dashboard.
 
 ## how it works
 
 ```
-your static site → sdk token (domain-restricted)
-                ↓
-        proxy server (validates origin)
-                ↓
-        injects api key (server-side)
-                ↓
-        external api (openai, etc.)
+1. cli uploads api keys to proxy server
+2. cli configures allowed origins (yourdomain.com, localhost, etc.)
+3. your static site imports sdk: new SecretsSDK()
+4. browser automatically sends Origin header
+5. proxy validates origin matches configured list
+6. proxy injects api key server-side
+7. external api called with key
+8. response returned to browser
 ```
 
+**security:**
+* api keys never sent to browser
+* origin header enforced by browser (cannot be spoofed)
+* stolen code useless from unauthorized domains
+
 ## security
 
 * **api keys never exposed** - stored and injected server-side only
-* **domain-scoped tokens** - browser origin header enforced, can't be spoofed
+* **origin-based auth** - browser origin header enforced, can't be faked
+* **no credentials in code** - zero-config means no tokens to leak
 * **rate limiting** - 100 req/min per domain prevents abuse
-* **instant revocation** - revoke tokens anytime in dashboard
+* **instant updates** - change origins in dashboard anytime
 
 ## documentation
 
-* [quick start guide](https://learn.pages.dev/docs/sdk/quick-start)
-* [full api reference](https://learn.pages.dev/docs/sdk/secrets-proxy)
-* [dashboard](https://learn.pages.dev)
+* [quick start guide](https://ctklearn.carsontkempf.workers.dev/docs/sdk/quick-start)
+* [cli reference](https://ctklearn.carsontkempf.workers.dev/docs/sdk/cli)
+* [full api reference](https://ctklearn.carsontkempf.workers.dev/docs/sdk/secrets-proxy)
+* [dashboard](https://ctklearn.carsontkempf.workers.dev)
+
+## troubleshooting
+
+**403 origin not allowed:**
+* run `learn-secrets init` with correct `--origins`
+* or update origins in dashboard: settings → sdk tokens
+
+**404 api key not found:**
+* verify key name matches .env variable (e.g., `OPENAI_API_KEY` → `openai`)
+* re-run `learn-secrets init` to upload keys
+
+**429 rate limit:**
+* 100 requests per minute per domain
+* implement throttling or caching in your app
 
 ## license
 

package/bin/learn-secrets.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// Entry point for the learn-secrets CLI
+// This file is executed when running: learn-secrets <command>
+
+// Check Node version
+const nodeVersion = process.versions.node;
+const majorVersion = parseInt(nodeVersion.split('.')[0], 10);
+
+if (majorVersion < 16) {
+	console.error('Error: Node.js 16 or higher is required');
+	console.error(`You are running Node.js ${nodeVersion}`);
+	process.exit(1);
+}
+
+// Run the CLI (ESM module)
+import('../dist/cli/index.mjs').catch((err) => {
+	console.error('Failed to load CLI:', err.message);
+	process.exit(1);
+});

package/dist/chunk-AS6G7JYX.mjs

@@ -0,0 +1 @@
+var f=(e=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(e,{get:(r,t)=>(typeof require<"u"?require:r)[t]}):e)(function(e){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+e+'" is not supported')});function i(e){return e.replace(/\$\{([A-Z0-9_]+)\}|\$([A-Z0-9_]+)/g,(r,t,o)=>{let s=t||o,n=process.env[s];if(n===void 0)throw new Error(`Environment variable ${s} is not defined`);return n})}function c(e){let r={name:i(e.name),provider:i(e.provider),api_key:i(e.api_key)};return e.base_url&&(r.base_url=i(e.base_url)),e.auth_header&&(r.auth_header=i(e.auth_header)),e.auth_prefix&&(r.auth_prefix=i(e.auth_prefix)),r}function p(e){return e.map(c)}function g(e){let r=f("fs"),o=f("path").resolve(e);if(!r.existsSync(o))throw new Error(`Config file not found: ${o}`);let s=r.readFileSync(o,"utf-8"),n=JSON.parse(s);if(!n.version)throw new Error('Config file missing "version" field');if(!n.project)throw new Error('Config file missing "project" field');if(!Array.isArray(n.secrets))throw new Error('Config file missing "secrets" array');let a=p(n.secrets);return{version:n.version,project:n.project,secrets:a}}export{i as a,c as b,p as c,g as d};

package/dist/cli/chunk-Y6FXYEAI.mjs

@@ -0,0 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+export {
+  __require
+};

package/dist/cli/env-resolver-4ASC2IMR.mjs

@@ -0,0 +1,66 @@
+import {
+  __require
+} from "./chunk-Y6FXYEAI.mjs";
+
+// src/env-resolver.ts
+function resolveEnvString(value) {
+  return value.replace(/\$\{([A-Z0-9_]+)\}|\$([A-Z0-9_]+)/g, (match, var1, var2) => {
+    const varName = var1 || var2;
+    const envValue = process.env[varName];
+    if (envValue === void 0) {
+      throw new Error(`Environment variable ${varName} is not defined`);
+    }
+    return envValue;
+  });
+}
+function resolveEnvInSecret(secret) {
+  const resolved = {
+    name: resolveEnvString(secret.name),
+    provider: resolveEnvString(secret.provider),
+    api_key: resolveEnvString(secret.api_key)
+  };
+  if (secret.base_url) {
+    resolved.base_url = resolveEnvString(secret.base_url);
+  }
+  if (secret.auth_header) {
+    resolved.auth_header = resolveEnvString(secret.auth_header);
+  }
+  if (secret.auth_prefix) {
+    resolved.auth_prefix = resolveEnvString(secret.auth_prefix);
+  }
+  return resolved;
+}
+function resolveEnvInSecrets(secrets) {
+  return secrets.map(resolveEnvInSecret);
+}
+function loadSecretsConfig(configPath) {
+  const fs = __require("fs");
+  const path = __require("path");
+  const fullPath = path.resolve(configPath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Config file not found: ${fullPath}`);
+  }
+  const configData = fs.readFileSync(fullPath, "utf-8");
+  const config = JSON.parse(configData);
+  if (!config.version) {
+    throw new Error('Config file missing "version" field');
+  }
+  if (!config.project) {
+    throw new Error('Config file missing "project" field');
+  }
+  if (!Array.isArray(config.secrets)) {
+    throw new Error('Config file missing "secrets" array');
+  }
+  const resolvedSecrets = resolveEnvInSecrets(config.secrets);
+  return {
+    version: config.version,
+    project: config.project,
+    secrets: resolvedSecrets
+  };
+}
+export {
+  loadSecretsConfig,
+  resolveEnvInSecret,
+  resolveEnvInSecrets,
+  resolveEnvString
+};

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node