learn-secrets-sdk 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,206 @@
+# learn-secrets-sdk
+
+secure api proxy sdk for static sites. call external apis (openai, anthropic, stripe, etc.) without exposing api keys.
+
+## quick start
+
+### 1. setup in dashboard
+
+* 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
+
+### 2. install
+
+```bash
+npm install learn-secrets-sdk
+```
+
+### 3. use in your app
+
+```typescript
+import { SecretsSDK } from 'learn-secrets-sdk';
+
+const sdk = new SecretsSDK({
+  appId: 'your-app-id',
+  token: 'sk_live_...'
+});
+
+// call openai
+const response = await sdk.post('my-openai-key', '/v1/chat/completions', {
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'hello' }]
+});
+```
+
+## features
+
+* **domain-scoped tokens** - tokens only work from configured origins
+* **zero api key exposure** - keys stay server-side, never sent to client
+* **works anywhere** - cloudflare pages, netlify, vercel, any static host
+* **rate limiting** - 100 req/min per domain built-in
+* **typescript support** - full type definitions included
+
+## api methods
+
+```typescript
+// http methods
+await sdk.get(keyName, endpoint, headers?)
+await sdk.post(keyName, endpoint, body, headers?)
+await sdk.put(keyName, endpoint, body, headers?)
+await sdk.delete(keyName, endpoint, headers?)
+await sdk.patch(keyName, endpoint, body, headers?)
+
+// custom request
+await sdk.call(keyName, endpoint, {
+  method: 'POST',
+  body: { },
+  headers: { }
+})
+```
+
+## constructor options
+
+```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)
+})
+```
+
+## error handling
+
+```typescript
+import { SecretsSDK, SecretsSDKError, OriginMismatchError, RateLimitError } from 'learn-secrets-sdk';
+
+try {
+  const response = await sdk.post('key', '/endpoint', data);
+} catch (error) {
+  if (error instanceof OriginMismatchError) {
+    // domain not in allowed origins
+  } else if (error instanceof RateLimitError) {
+    // exceeded 100 req/min
+    console.log('retry after:', error.retryAfter);
+  } else if (error instanceof SecretsSDKError) {
+    // other api errors
+    console.log('status:', error.status);
+  }
+}
+```
+
+## usage tracking
+
+```typescript
+const sdk = new SecretsSDK({ appId, token });
+
+await sdk.post('key', '/endpoint', data);
+
+// check rate limit status
+const usage = sdk.getUsage();
+console.log('remaining:', usage.remaining);  // requests left this minute
+console.log('resets at:', usage.reset);      // unix timestamp
+```
+
+## examples
+
+### vanilla html
+
+```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>
+```
+
+### react
+
+```typescript
+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
+  }), []);
+
+  const handleClick = async () => {
+    const result = await sdk.post('my-openai-key', '/v1/chat/completions', {
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'hello' }]
+    });
+  };
+}
+```
+
+### vue
+
+```typescript
+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
+});
+
+const response = ref('');
+
+async function callAPI() {
+  const result = await sdk.post('my-openai-key', '/v1/chat/completions', {
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'hello' }]
+  });
+  response.value = result.choices[0].message.content;
+}
+```
+
+## supported providers
+
+* openai
+* anthropic
+* stripe
+* any http-based api
+
+## how it works
+
+```
+your static site → sdk token (domain-restricted)
+                ↓
+        proxy server (validates origin)
+                ↓
+        injects api key (server-side)
+                ↓
+        external api (openai, etc.)
+```
+
+## security
+
+* **api keys never exposed** - stored and injected server-side only
+* **domain-scoped tokens** - browser origin header enforced, can't be spoofed
+* **rate limiting** - 100 req/min per domain prevents abuse
+* **instant revocation** - revoke tokens anytime in dashboard
+
+## 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)
+
+## license
+
+mit

package/dist/client.d.ts

@@ -1,9 +1,28 @@
-import type { SecretsSDKOptions, ProxyRequest } from './types';
+import type { SecretsSDKOptions, ProxyRequest, RateLimitInfo } from './types';
 export declare class SecretsSDK {
     private appId;
-    private sessionToken;
+    private token;
     private baseUrl;
+    private timeout;
+    private retryOn429;
+    private rateLimitInfo;
     constructor(options: SecretsSDKOptions);
+    /**
+     * Get current rate limit information
+     */
+    getUsage(): RateLimitInfo | null;
+    /**
+     * Parse rate limit headers from response
+     */
+    private parseRateLimitHeaders;
+    /**
+     * Sleep utility for retry backoff
+     */
+    private sleep;
+    /**
+     * Make fetch request with timeout
+     */
+    private fetchWithTimeout;
     /**
      * Call an external API securely through the proxy
      * @param keyName - Name of the API key to use

package/dist/client.js

@@ -1,9 +1,59 @@
-import { SecretsSDKError } from './types';
+import { SecretsSDKError, OriginMismatchError, RateLimitError, InvalidTokenError } from './types';
 export class SecretsSDK {
     constructor(options) {
+        this.rateLimitInfo = null;
         this.appId = options.appId;
-        this.sessionToken = options.sessionToken;
+        this.token = options.token || options.sessionToken || '';
         this.baseUrl = options.baseUrl || 'https://learn.pages.dev';
+        this.timeout = options.timeout || 30000;
+        this.retryOn429 = options.retryOn429 !== undefined ? options.retryOn429 : true;
+        if (!this.token) {
+            throw new Error('token is required');
+        }
+    }
+    /**
+     * Get current rate limit information
+     */
+    getUsage() {
+        return this.rateLimitInfo;
+    }
+    /**
+     * Parse rate limit headers from response
+     */
+    parseRateLimitHeaders(headers) {
+        const limit = headers.get('X-RateLimit-Limit');
+        const remaining = headers.get('X-RateLimit-Remaining');
+        const reset = headers.get('X-RateLimit-Reset');
+        if (limit && remaining && reset) {
+            this.rateLimitInfo = {
+                limit: parseInt(limit),
+                remaining: parseInt(remaining),
+                reset: parseInt(reset)
+            };
+        }
+    }
+    /**
+     * Sleep utility for retry backoff
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Make fetch request with timeout
+     */
+    async fetchWithTimeout(url, options, timeout) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal
+            });
+            return response;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     /**
      * Call an external API securely through the proxy
@@ -13,35 +63,62 @@ export class SecretsSDK {
      * @returns Promise with the API response
      */
     async call(keyName, endpoint, options = {}) {
-        try {
-            const response = await fetch(`${this.baseUrl}/api/sdk/${this.appId}/proxy`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    Authorization: `Bearer ${this.sessionToken}`
-                },
-                body: JSON.stringify({
-                    keyName,
-                    endpoint,
-                    method: options.method || 'GET',
-                    body: options.body,
-                    headers: options.headers
-                })
-            });
-            const result = await response.json();
-            if (!response.ok) {
-                const errorMessage = result.data?.message ||
-                    result?.message ||
-                    `Request failed with status ${response.status}`;
-                throw new SecretsSDKError(errorMessage, response.status, result);
+        let retries = 0;
+        const maxRetries = this.retryOn429 ? 3 : 0;
+        while (true) {
+            try {
+                const response = await this.fetchWithTimeout(`${this.baseUrl}/api/sdk/${this.appId}/proxy`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.token}`
+                    },
+                    body: JSON.stringify({
+                        keyName,
+                        endpoint,
+                        method: options.method || 'GET',
+                        body: options.body,
+                        headers: options.headers
+                    })
+                }, this.timeout);
+                this.parseRateLimitHeaders(response.headers);
+                const result = await response.json();
+                if (!response.ok) {
+                    const errorMessage = result.data?.message ||
+                        result?.message ||
+                        `Request failed with status ${response.status}`;
+                    if (response.status === 403 && errorMessage.includes('Origin')) {
+                        throw new OriginMismatchError(errorMessage);
+                    }
+                    if (response.status === 401) {
+                        throw new InvalidTokenError(errorMessage);
+                    }
+                    if (response.status === 429) {
+                        const retryAfter = this.rateLimitInfo
+                            ? this.rateLimitInfo.reset - Math.floor(Date.now() / 1000)
+                            : 60;
+                        const error = new RateLimitError(errorMessage, retryAfter, this.rateLimitInfo?.remaining || 0, this.rateLimitInfo?.limit || 100);
+                        if (this.retryOn429 && retries < maxRetries) {
+                            retries++;
+                            const backoffMs = Math.min(1000 * Math.pow(2, retries - 1), 8000);
+                            await this.sleep(backoffMs);
+                            continue;
+                        }
+                        throw error;
+                    }
+                    throw new SecretsSDKError(errorMessage, response.status, result);
+                }
+                return result.data;
             }
-            return result.data;
-        }
-        catch (err) {
-            if (err instanceof SecretsSDKError) {
-                throw err;
+            catch (err) {
+                if (err instanceof SecretsSDKError) {
+                    throw err;
+                }
+                if (err instanceof Error && err.name === 'AbortError') {
+                    throw new SecretsSDKError('Request timeout', 408);
+                }
+                throw new SecretsSDKError(err instanceof Error ? err.message : 'Unknown error occurred', 500);
             }
-            throw new SecretsSDKError(err instanceof Error ? err.message : 'Unknown error occurred', 500);
         }
     }
     /**

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { SecretsSDK } from './client';
-export { SecretsSDKError } from './types';
-export type { SecretsSDKOptions, ProxyRequest, ProxyResponse } from './types';
+export { SecretsSDKError, OriginMismatchError, RateLimitError, InvalidTokenError } from './types';
+export type { SecretsSDKOptions, ProxyRequest, ProxyResponse, RateLimitInfo } from './types';

package/dist/index.js

@@ -1,2 +1,2 @@
 export { SecretsSDK } from './client';
-export { SecretsSDKError } from './types';
+export { SecretsSDKError, OriginMismatchError, RateLimitError, InvalidTokenError } from './types';

package/dist/types.d.ts

@@ -1,7 +1,10 @@
 export interface SecretsSDKOptions {
     appId: string;
-    sessionToken: string;
+    token: string;
+    sessionToken?: string;
     baseUrl?: string;
+    timeout?: number;
+    retryOn429?: boolean;
 }
 export interface ProxyRequest {
     keyName: string;
@@ -15,8 +18,25 @@ export interface ProxyResponse<T = any> {
     status: number;
     data: T;
 }
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+}
 export declare class SecretsSDKError extends Error {
     status: number;
     response?: any | undefined;
     constructor(message: string, status: number, response?: any | undefined);
 }
+export declare class OriginMismatchError extends SecretsSDKError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends SecretsSDKError {
+    retryAfter: number;
+    remaining: number;
+    limit: number;
+    constructor(message?: string, retryAfter?: number, remaining?: number, limit?: number);
+}
+export declare class InvalidTokenError extends SecretsSDKError {
+    constructor(message?: string);
+}

package/dist/types.js

@@ -6,3 +6,24 @@ export class SecretsSDKError extends Error {
         this.name = 'SecretsSDKError';
     }
 }
+export class OriginMismatchError extends SecretsSDKError {
+    constructor(message = 'Origin not allowed for this token') {
+        super(message, 403);
+        this.name = 'OriginMismatchError';
+    }
+}
+export class RateLimitError extends SecretsSDKError {
+    constructor(message = 'Rate limit exceeded', retryAfter = 60, remaining = 0, limit = 100) {
+        super(message, 429);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+        this.remaining = remaining;
+        this.limit = limit;
+    }
+}
+export class InvalidTokenError extends SecretsSDKError {
+    constructor(message = 'Invalid or expired token') {
+        super(message, 401);
+        this.name = 'InvalidTokenError';
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "learn-secrets-sdk",
-	"version": "1.0.0",
-	"description": "Secure API proxy SDK for static sites",
+	"version": "1.2.0",
+	"description": "Secure API proxy SDK for static sites with domain-scoped tokens",
 	"main": "dist/index.js",
 	"module": "dist/index.esm.js",
 	"types": "dist/index.d.ts",