@dream-api/sdk 0.1.0 → 0.1.2

package/README.md

@@ -13,10 +13,18 @@ npm install @dream-api/sdk
 ```typescript
 import { DreamAPI } from '@dream-api/sdk';
 
+// FRONTEND (React, Vue, browser) - PK only, safe to expose
+const api = new DreamAPI({
+  publishableKey: 'pk_test_xxx',
+});
+// Can access: tiers, products, usage (with JWT), billing (with JWT)
+
+// BACKEND (Node, Workers, API routes) - Full access
 const api = new DreamAPI({
   secretKey: process.env.DREAM_API_SECRET_KEY,
   publishableKey: process.env.DREAM_API_PUBLISHABLE_KEY,
 });
+// Can access: everything including customers, dashboard
 ```
 
 ## Backend Operations (SK Only)
@@ -183,8 +191,8 @@ DREAM_API_PUBLISHABLE_KEY=pk_test_xxx
 import { DreamAPI } from '@dream-api/sdk';
 import { useAuth } from '@clerk/clerk-react';
 
+// Frontend: PK only (secret key stays on your backend!)
 const api = new DreamAPI({
-  secretKey: import.meta.env.VITE_DREAM_API_SECRET_KEY,
   publishableKey: import.meta.env.VITE_DREAM_API_PUBLISHABLE_KEY,
 });
 

package/dist/index.d.mts

@@ -2,9 +2,17 @@
  * Dream API SDK - Type Definitions
  */
 interface DreamAPIConfig {
-    /** Your secret key (sk_test_xxx or sk_live_xxx) */
-    secretKey: string;
-    /** Your publishable key (pk_test_xxx or pk_live_xxx) - used for auth URL helpers */
+    /**
+     * Your secret key (sk_test_xxx or sk_live_xxx)
+     * Required for backend/admin operations (customers, dashboard)
+     * Optional for frontend operations (tiers, products, usage with JWT)
+     */
+    secretKey?: string;
+    /**
+     * Your publishable key (pk_test_xxx or pk_live_xxx)
+     * Required for frontend-only mode (when no secretKey provided)
+     * Also used for auth URL helpers
+     */
     publishableKey?: string;
     /** Base URL override (for testing) */
     baseUrl?: string;
@@ -53,13 +61,18 @@ interface Tier {
     popular?: boolean;
 }
 interface Product {
+    id?: string;
     name: string;
+    displayName?: string;
+    description?: string;
     price: number;
+    currency?: string;
     priceId: string;
     productId: string;
-    description?: string;
     imageUrl?: string;
-    inventory?: number;
+    inventory?: number | null;
+    soldOut?: boolean;
+    features?: string[];
 }
 interface CheckoutResult {
     url: string;
@@ -132,7 +145,16 @@ declare class DreamClient {
     private clerkUrl;
     private userToken;
     private tokenRefresher;
+    /**
+     * Frontend-only mode: When only publishableKey is provided (no secretKey)
+     * In this mode, only public endpoints and JWT-authenticated endpoints work
+     */
+    private readonly frontendOnly;
     constructor(config: DreamAPIConfig);
+    /**
+     * Check if running in frontend-only mode
+     */
+    isFrontendOnly(): boolean;
     /**
      * Set the end-user JWT token for user-specific operations.
      * Call this after the user signs in via Clerk.
@@ -481,13 +503,24 @@ declare class ProductAPI {
     }>;
     /**
      * Create a cart checkout (guest checkout for store)
+     *
+     * @example
+     * ```typescript
+     * const { url } = await api.products.cartCheckout({
+     *   items: [{ priceId: 'price_xxx', quantity: 1 }],
+     *   customerEmail: 'customer@example.com',
+     *   successUrl: '/success',
+     *   cancelUrl: '/cart',
+     * });
+     * window.location.href = url;
+     * ```
      */
     cartCheckout(params: {
         items: Array<{
             priceId: string;
             quantity: number;
         }>;
-        customerEmail: string;
+        customerEmail?: string;
         customerName?: string;
         successUrl?: string;
         cancelUrl?: string;

package/dist/index.d.ts

@@ -2,9 +2,17 @@
  * Dream API SDK - Type Definitions
  */
 interface DreamAPIConfig {
-    /** Your secret key (sk_test_xxx or sk_live_xxx) */
-    secretKey: string;
-    /** Your publishable key (pk_test_xxx or pk_live_xxx) - used for auth URL helpers */
+    /**
+     * Your secret key (sk_test_xxx or sk_live_xxx)
+     * Required for backend/admin operations (customers, dashboard)
+     * Optional for frontend operations (tiers, products, usage with JWT)
+     */
+    secretKey?: string;
+    /**
+     * Your publishable key (pk_test_xxx or pk_live_xxx)
+     * Required for frontend-only mode (when no secretKey provided)
+     * Also used for auth URL helpers
+     */
     publishableKey?: string;
     /** Base URL override (for testing) */
     baseUrl?: string;
@@ -53,13 +61,18 @@ interface Tier {
     popular?: boolean;
 }
 interface Product {
+    id?: string;
     name: string;
+    displayName?: string;
+    description?: string;
     price: number;
+    currency?: string;
     priceId: string;
     productId: string;
-    description?: string;
     imageUrl?: string;
-    inventory?: number;
+    inventory?: number | null;
+    soldOut?: boolean;
+    features?: string[];
 }
 interface CheckoutResult {
     url: string;
@@ -132,7 +145,16 @@ declare class DreamClient {
     private clerkUrl;
     private userToken;
     private tokenRefresher;
+    /**
+     * Frontend-only mode: When only publishableKey is provided (no secretKey)
+     * In this mode, only public endpoints and JWT-authenticated endpoints work
+     */
+    private readonly frontendOnly;
     constructor(config: DreamAPIConfig);
+    /**
+     * Check if running in frontend-only mode
+     */
+    isFrontendOnly(): boolean;
     /**
      * Set the end-user JWT token for user-specific operations.
      * Call this after the user signs in via Clerk.
@@ -481,13 +503,24 @@ declare class ProductAPI {
     }>;
     /**
      * Create a cart checkout (guest checkout for store)
+     *
+     * @example
+     * ```typescript
+     * const { url } = await api.products.cartCheckout({
+     *   items: [{ priceId: 'price_xxx', quantity: 1 }],
+     *   customerEmail: 'customer@example.com',
+     *   successUrl: '/success',
+     *   cancelUrl: '/cart',
+     * });
+     * window.location.href = url;
+     * ```
      */
     cartCheckout(params: {
         items: Array<{
             priceId: string;
             quantity: number;
         }>;
-        customerEmail: string;
+        customerEmail?: string;
         customerName?: string;
         successUrl?: string;
         cancelUrl?: string;

package/dist/index.js

@@ -44,14 +44,24 @@ var DreamClient = class {
   constructor(config) {
     this.userToken = null;
     this.tokenRefresher = null;
-    if (!config.secretKey) {
-      throw new Error("DreamAPI: secretKey is required");
+    if (!config.secretKey && !config.publishableKey) {
+      throw new Error("DreamAPI: Either secretKey or publishableKey is required");
     }
     this.secretKey = config.secretKey;
     this.publishableKey = config.publishableKey;
     this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
     this.signupUrl = config.signupUrl || DEFAULT_SIGNUP_URL;
     this.clerkUrl = config.clerkBaseUrl || DEFAULT_CLERK_URL;
+    this.frontendOnly = !config.secretKey && !!config.publishableKey;
+    if (this.frontendOnly) {
+      console.log("[DreamAPI] Running in frontend-only mode (PK auth)");
+    }
+  }
+  /**
+   * Check if running in frontend-only mode
+   */
+  isFrontendOnly() {
+    return this.frontendOnly;
   }
   /**
    * Set the end-user JWT token for user-specific operations.
@@ -107,11 +117,15 @@ var DreamClient = class {
   async request(method, endpoint, options = {}) {
     const { body, requiresUserToken = false } = options;
     const headers = {
-      "Authorization": `Bearer ${this.secretKey}`,
       "Content-Type": "application/json"
     };
-    if (this.publishableKey) {
+    if (this.frontendOnly) {
       headers["X-Publishable-Key"] = this.publishableKey;
+    } else {
+      headers["Authorization"] = `Bearer ${this.secretKey}`;
+      if (this.publishableKey) {
+        headers["X-Publishable-Key"] = this.publishableKey;
+      }
     }
     if (requiresUserToken) {
       if (!this.userToken) {
@@ -562,9 +576,27 @@ var ProductAPI = class {
   }
   /**
    * Create a cart checkout (guest checkout for store)
+   *
+   * @example
+   * ```typescript
+   * const { url } = await api.products.cartCheckout({
+   *   items: [{ priceId: 'price_xxx', quantity: 1 }],
+   *   customerEmail: 'customer@example.com',
+   *   successUrl: '/success',
+   *   cancelUrl: '/cart',
+   * });
+   * window.location.href = url;
+   * ```
    */
   async cartCheckout(params) {
-    return this.client.post("/api/cart/checkout", params);
+    const apiParams = {
+      items: params.items,
+      email: params.customerEmail,
+      name: params.customerName,
+      successUrl: params.successUrl,
+      cancelUrl: params.cancelUrl
+    };
+    return this.client.post("/api/cart/checkout", apiParams);
   }
 };
 var DashboardAPI = class {

package/dist/index.mjs

@@ -16,14 +16,24 @@ var DreamClient = class {
   constructor(config) {
     this.userToken = null;
     this.tokenRefresher = null;
-    if (!config.secretKey) {
-      throw new Error("DreamAPI: secretKey is required");
+    if (!config.secretKey && !config.publishableKey) {
+      throw new Error("DreamAPI: Either secretKey or publishableKey is required");
     }
     this.secretKey = config.secretKey;
     this.publishableKey = config.publishableKey;
     this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
     this.signupUrl = config.signupUrl || DEFAULT_SIGNUP_URL;
     this.clerkUrl = config.clerkBaseUrl || DEFAULT_CLERK_URL;
+    this.frontendOnly = !config.secretKey && !!config.publishableKey;
+    if (this.frontendOnly) {
+      console.log("[DreamAPI] Running in frontend-only mode (PK auth)");
+    }
+  }
+  /**
+   * Check if running in frontend-only mode
+   */
+  isFrontendOnly() {
+    return this.frontendOnly;
   }
   /**
    * Set the end-user JWT token for user-specific operations.
@@ -79,11 +89,15 @@ var DreamClient = class {
   async request(method, endpoint, options = {}) {
     const { body, requiresUserToken = false } = options;
     const headers = {
-      "Authorization": `Bearer ${this.secretKey}`,
       "Content-Type": "application/json"
     };
-    if (this.publishableKey) {
+    if (this.frontendOnly) {
       headers["X-Publishable-Key"] = this.publishableKey;
+    } else {
+      headers["Authorization"] = `Bearer ${this.secretKey}`;
+      if (this.publishableKey) {
+        headers["X-Publishable-Key"] = this.publishableKey;
+      }
     }
     if (requiresUserToken) {
       if (!this.userToken) {
@@ -534,9 +548,27 @@ var ProductAPI = class {
   }
   /**
    * Create a cart checkout (guest checkout for store)
+   *
+   * @example
+   * ```typescript
+   * const { url } = await api.products.cartCheckout({
+   *   items: [{ priceId: 'price_xxx', quantity: 1 }],
+   *   customerEmail: 'customer@example.com',
+   *   successUrl: '/success',
+   *   cancelUrl: '/cart',
+   * });
+   * window.location.href = url;
+   * ```
    */
   async cartCheckout(params) {
-    return this.client.post("/api/cart/checkout", params);
+    const apiParams = {
+      items: params.items,
+      email: params.customerEmail,
+      name: params.customerName,
+      successUrl: params.successUrl,
+      cancelUrl: params.cancelUrl
+    };
+    return this.client.post("/api/cart/checkout", apiParams);
   }
 };
 var DashboardAPI = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dream-api/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Official SDK for Dream API - Auth, billing, and usage tracking in one API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",