opencloud-platform-sdk 2.0.0 → 3.0.0

package/README.md

@@ -4,11 +4,12 @@ Official SDK for **OpenCloud** - Monetize your AI apps with ease.
 
 **You control the AI, we handle the payments.**
 
-## What's New in v2.0
+## What's New in v3.0
 
-- **Use your own AI** - OpenAI, Anthropic, your own model, whatever you want
-- **Set your own price** - Charge what you want per use
-- **85/15 split** - You keep 85%, platform takes 15%
+- **Standalone Mode** - Works on any domain, no iframe required
+- **Popup Authentication** - Secure OAuth-style login via popup
+- **Automatic Login** - SDK prompts for login when charging
+- **Cross-Domain Support** - Full CORS support for external apps
 
 ## Installation
 
@@ -21,30 +22,64 @@ npm install opencloud-platform-sdk
 ```typescript
 import { opencloud } from 'opencloud-platform-sdk';
 
-// 1. Initialize with your app ID
+// 1. Initialize with your app ID (slug)
 opencloud.init({ appId: 'your-app-slug' });
 
-// 2. Check if user can afford
-const canUse = await opencloud.canAfford();
-if (!canUse) {
-  opencloud.requestTopUp();
-  return;
+// 2. Charge the user (opens login popup if needed)
+async function handleAIFeature() {
+  const result = await opencloud.charge('generate_image');
+
+  if (!result.success) {
+    if (result.error === 'CANCELLED') {
+      // User closed the login popup
+      return;
+    }
+    if (result.error === 'INSUFFICIENT_BALANCE') {
+      // SDK already opened top-up popup
+      return;
+    }
+  }
+
+  // Charge successful! Now run your AI logic
+  const image = await myAIService.generate(prompt);
+  return image;
 }
+```
 
-// 3. Call YOUR OWN AI (you control this)
-const response = await fetch('https://api.openai.com/v1/chat/completions', {
-  method: 'POST',
-  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
-  body: JSON.stringify({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: 'Hello!' }]
-  })
-});
+## How It Works
+
+1. User visits your app (e.g., `https://your-app.vercel.app`)
+2. User clicks "Generate Image" (or any paid feature)
+3. SDK checks if user has OpenCloud session
+4. If not logged in → Opens OpenCloud login popup
+5. User logs in → Popup closes → SDK gets session token
+6. SDK charges user's OpenCloud wallet
+7. Your app continues with the AI feature
 
-// 4. Charge the user
-const result = await opencloud.trackUsage({ action: 'chat' });
-console.log('Charged:', result.charged);
-console.log('User balance:', result.userBalance);
+```
+Your App                          OpenCloud
+   │                                  │
+   │  User clicks "Generate"          │
+   │  ─────────────────────────────>  │
+   │                                  │
+   │  SDK: opencloud.charge()         │
+   │  ─────────────────────────────>  │
+   │                                  │
+   │  No session? Open popup          │
+   │  <─────────────────────────────  │
+   │                                  │
+   │  User logs in via popup          │
+   │  ─────────────────────────────>  │
+   │                                  │
+   │  Session token returned          │
+   │  <─────────────────────────────  │
+   │                                  │
+   │  Charge wallet                   │
+   │  ─────────────────────────────>  │
+   │                                  │
+   │  Success! Continue...            │
+   │  <─────────────────────────────  │
+   │                                  │
 ```
 
 ## API Reference
@@ -55,91 +90,121 @@ Initialize the SDK.
 
 ```typescript
 opencloud.init({
-  appId: 'your-app-slug',  // Required
-  apiUrl: 'https://opencloud.app'  // Optional
+  appId: 'your-app-slug',  // Required - your app's slug
+  apiUrl: 'https://opencloud.app'  // Optional - defaults to production
 });
 ```
 
-### `opencloud.canAfford()`
+### `opencloud.charge(action?, metadata?)`
 
-Check if user has enough balance.
+Charge the user. Opens login popup if not authenticated.
 
 ```typescript
-const canUse = await opencloud.canAfford();
-if (!canUse) {
-  opencloud.requestTopUp();
-  return;
+const result = await opencloud.charge('chat_message', { model: 'gpt-4' });
+
+// Result:
+{
+  success: true,
+  charged: 0.10,
+  balance: 4.90,
+  transactionId: 'tx_abc123'
+}
+
+// Or on error:
+{
+  success: false,
+  error: 'INSUFFICIENT_BALANCE' | 'CANCELLED' | 'UNKNOWN'
 }
 ```
 
-### `opencloud.trackUsage(options)`
+### `opencloud.withCharge(fn, options)`
 
-Charge the user. This is the main method to monetize your app.
+Execute a function and charge the user. Handles auth and balance checks automatically.
 
 ```typescript
-const result = await opencloud.trackUsage({
-  action: 'chat_message',  // Optional: for analytics
-  metadata: { model: 'gpt-4' }  // Optional: extra data
-});
+const image = await opencloud.withCharge(async () => {
+  return await myAIService.generateImage(prompt);
+}, { action: 'generate_image' });
+```
 
-// Response:
-{
-  success: true,
-  charged: 0.10,
-  userBalance: 4.90,
-  transactionId: 'tx_abc123'
+### `opencloud.isAuthenticated()`
+
+Check if user is logged in.
+
+```typescript
+if (opencloud.isAuthenticated()) {
+  console.log('User is logged in');
 }
 ```
 
-### `opencloud.withUsage(fn, options)` (Optional)
+### `opencloud.login()`
 
-Convenience method that combines canAfford + your code + trackUsage.
+Open login popup manually.
 
 ```typescript
-const response = await opencloud.withUsage(async () => {
-  // Your AI call here - only runs if user can pay
-  return await myAICall();
-}, { action: 'chat' });
+const session = await opencloud.login();
+if (session) {
+  console.log('Logged in as:', session.user.email);
+}
+```
+
+### `opencloud.logout()`
+
+Log out the current user.
+
+```typescript
+opencloud.logout();
+```
+
+### `opencloud.getUser()`
+
+Get current user info (synchronous).
+
+```typescript
+const user = opencloud.getUser();
+// { id, email, username, balance }
 ```
 
 ### `opencloud.getBalance()`
 
-Get user's current balance.
+Get user's current balance (async, fetches from server).
 
 ```typescript
 const balance = await opencloud.getBalance();
 console.log(`Balance: $${balance}`);
 ```
 
-### `opencloud.getAppPrice()`
+### `opencloud.canAfford()`
 
-Get your app's price per use.
+Check if user can afford to use the app.
 
 ```typescript
-const price = await opencloud.getAppPrice();
-console.log(`Price: $${price}`);
+const canUse = await opencloud.canAfford();
+if (!canUse) {
+  opencloud.openTopUp();
+}
 ```
 
-### `opencloud.requestTopUp()`
+### `opencloud.openTopUp()`
 
-Open the payment dialog for user to add credits.
+Open top-up popup for user to add credits.
 
 ```typescript
-opencloud.requestTopUp();
+opencloud.openTopUp();
 ```
 
-### `opencloud.getUserInfo()`
+### `opencloud.getAppPrice()`
 
-Get current user information.
+Get your app's price per use.
 
 ```typescript
-const user = await opencloud.getUserInfo();
-// { id, email, balance, username }
+const price = await opencloud.getAppPrice();
+console.log(`Price: $${price}`);
 ```
 
 ### `opencloud.isPreview()`
 
-Check if running in development mode (localhost, etc).
+Check if running in development mode.
 
 ```typescript
 if (opencloud.isPreview()) {
@@ -157,35 +222,44 @@ User pays:     $0.10 per use
 └─ Platform:   $0.015 (15%)
 ```
 
-## Error Handling
-
-```typescript
-try {
-  await opencloud.trackUsage({ action: 'chat' });
-} catch (error) {
-  if (error.message === 'INSUFFICIENT_BALANCE') {
-    opencloud.requestTopUp();
-  }
-}
-```
-
 ## Preview Mode
 
-When running locally (localhost, etc), the SDK automatically enters preview mode:
-- `trackUsage()` doesn't charge real money
+When running locally (localhost), the SDK automatically enters preview mode:
+- `charge()` doesn't charge real money
 - `getBalance()` returns 999.99
 - `canAfford()` always returns true
 
 This lets you develop without worrying about charges.
 
+## Error Handling
+
+```typescript
+const result = await opencloud.charge('chat');
+
+if (!result.success) {
+  switch (result.error) {
+    case 'CANCELLED':
+      // User closed the login popup
+      showMessage('Please log in to use this feature');
+      break;
+    case 'INSUFFICIENT_BALANCE':
+      // SDK already opened top-up popup
+      showMessage('Please add credits to continue');
+      break;
+    default:
+      showMessage('Something went wrong');
+  }
+}
+```
+
 ## Publishing Your App
 
-1. Deploy your app to Vercel via [opencloud.app/deploy](/deploy)
+1. Deploy your app to Vercel
 2. Go to [opencloud.app/publish](/publish)
-3. Select your deployed project
+3. Create a new app with your deployed URL
 4. Set name, description, and **price per use**
-5. Sign the creator agreement (85/15 split)
-6. Publish!
+5. Get your app slug
+6. Use the slug in `opencloud.init({ appId: 'your-slug' })`
 
 ## TypeScript Support
 
@@ -195,8 +269,8 @@ Full TypeScript definitions included:
 import {
   opencloud,
   OpenCloudSDK,
-  TrackUsageParams,
-  TrackUsageResponse,
+  ChargeResult,
+  UserSession,
   UserInfo
 } from 'opencloud-platform-sdk';
 ```

package/dist/cli.d.mts

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

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var VERCEL_HEADERS = {
+  headers: [
+    {
+      source: "/(.*)",
+      headers: [
+        { key: "X-Frame-Options", value: "ALLOWALL" },
+        { key: "Content-Security-Policy", value: "frame-ancestors *" }
+      ]
+    }
+  ]
+};
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+function setupVercelJson(projectRoot) {
+  const vercelJsonPath = path.join(projectRoot, "vercel.json");
+  try {
+    let config = {};
+    if (fs.existsSync(vercelJsonPath)) {
+      const content = fs.readFileSync(vercelJsonPath, "utf-8");
+      config = JSON.parse(content);
+      console.log("  Found existing vercel.json");
+    } else {
+      console.log("  Creating vercel.json");
+    }
+    if (config.headers) {
+      const hasFrameHeaders = config.headers.some(
+        (h) => h.headers?.some(
+          (header) => header.key === "X-Frame-Options" || header.key === "Content-Security-Policy"
+        )
+      );
+      if (hasFrameHeaders) {
+        console.log("  \u2713 Headers already configured in vercel.json");
+        return true;
+      }
+      config.headers.push(...VERCEL_HEADERS.headers);
+    } else {
+      config.headers = VERCEL_HEADERS.headers;
+    }
+    fs.writeFileSync(vercelJsonPath, JSON.stringify(config, null, 2));
+    console.log("  \u2713 Added iframe headers to vercel.json");
+    return true;
+  } catch (error) {
+    console.error("  \u2717 Failed to update vercel.json:", error);
+    return false;
+  }
+}
+function printManualInstructions() {
+  console.log(`
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  Manual Configuration Required                          \u2502
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502                                                         \u2502
+\u2502  Add this to your vercel.json:                          \u2502
+\u2502                                                         \u2502
+\u2502  {                                                      \u2502
+\u2502    "headers": [                                         \u2502
+\u2502      {                                                  \u2502
+\u2502        "source": "/(.*)",                               \u2502
+\u2502        "headers": [                                     \u2502
+\u2502          { "key": "X-Frame-Options", "value": "ALLOWALL" },
+\u2502          { "key": "Content-Security-Policy",            \u2502
+\u2502            "value": "frame-ancestors *" }               \u2502
+\u2502        ]                                                \u2502
+\u2502      }                                                  \u2502
+\u2502    ]                                                    \u2502
+\u2502  }                                                      \u2502
+\u2502                                                         \u2502
+\u2502  Or add headers() to next.config.js:                    \u2502
+\u2502                                                         \u2502
+\u2502  async headers() {                                      \u2502
+\u2502    return [{                                            \u2502
+\u2502      source: '/(.*)',                                   \u2502
+\u2502      headers: [                                         \u2502
+\u2502        { key: 'X-Frame-Options', value: 'ALLOWALL' },   \u2502
+\u2502        { key: 'Content-Security-Policy',                \u2502
+\u2502          value: 'frame-ancestors *' }                   \u2502
+\u2502      ]                                                  \u2502
+\u2502    }];                                                  \u2502
+\u2502  }                                                      \u2502
+\u2502                                                         \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+`);
+}
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  console.log("\n\u{1F680} OpenCloud SDK Setup\n");
+  if (command === "setup" || !command) {
+    const projectRoot = findProjectRoot();
+    console.log(`Project root: ${projectRoot}
+`);
+    console.log("Configuring iframe headers for OpenCloud...\n");
+    const success = setupVercelJson(projectRoot);
+    if (success) {
+      console.log(`
+\u2705 Setup complete!
+
+Your app is now configured to work with OpenCloud.
+After deploying, your app will be embeddable in the OpenCloud marketplace.
+
+Next steps:
+1. Deploy your app: vercel deploy --prod
+2. Publish on OpenCloud: https://opencloud.app/publish
+`);
+    } else {
+      printManualInstructions();
+    }
+  } else if (command === "help" || command === "--help" || command === "-h") {
+    console.log(`
+Usage: opencloud-sdk [command]
+
+Commands:
+  setup     Configure your project for OpenCloud (default)
+  help      Show this help message
+
+Examples:
+  npx opencloud-platform-sdk setup
+  npx opencloud-platform-sdk
+`);
+  } else {
+    console.log(`Unknown command: ${command}`);
+    console.log('Run "opencloud-sdk help" for usage information.');
+  }
+}
+main();

package/dist/cli.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as fs from "fs";
+import * as path from "path";
+var VERCEL_HEADERS = {
+  headers: [
+    {
+      source: "/(.*)",
+      headers: [
+        { key: "X-Frame-Options", value: "ALLOWALL" },
+        { key: "Content-Security-Policy", value: "frame-ancestors *" }
+      ]
+    }
+  ]
+};
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+function setupVercelJson(projectRoot) {
+  const vercelJsonPath = path.join(projectRoot, "vercel.json");
+  try {
+    let config = {};
+    if (fs.existsSync(vercelJsonPath)) {
+      const content = fs.readFileSync(vercelJsonPath, "utf-8");
+      config = JSON.parse(content);
+      console.log("  Found existing vercel.json");
+    } else {
+      console.log("  Creating vercel.json");
+    }
+    if (config.headers) {
+      const hasFrameHeaders = config.headers.some(
+        (h) => h.headers?.some(
+          (header) => header.key === "X-Frame-Options" || header.key === "Content-Security-Policy"
+        )
+      );
+      if (hasFrameHeaders) {
+        console.log("  \u2713 Headers already configured in vercel.json");
+        return true;
+      }
+      config.headers.push(...VERCEL_HEADERS.headers);
+    } else {
+      config.headers = VERCEL_HEADERS.headers;
+    }
+    fs.writeFileSync(vercelJsonPath, JSON.stringify(config, null, 2));
+    console.log("  \u2713 Added iframe headers to vercel.json");
+    return true;
+  } catch (error) {
+    console.error("  \u2717 Failed to update vercel.json:", error);
+    return false;
+  }
+}
+function printManualInstructions() {
+  console.log(`
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502  Manual Configuration Required                          \u2502
+\u251C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524
+\u2502                                                         \u2502
+\u2502  Add this to your vercel.json:                          \u2502
+\u2502                                                         \u2502
+\u2502  {                                                      \u2502
+\u2502    "headers": [                                         \u2502
+\u2502      {                                                  \u2502
+\u2502        "source": "/(.*)",                               \u2502
+\u2502        "headers": [                                     \u2502
+\u2502          { "key": "X-Frame-Options", "value": "ALLOWALL" },
+\u2502          { "key": "Content-Security-Policy",            \u2502
+\u2502            "value": "frame-ancestors *" }               \u2502
+\u2502        ]                                                \u2502
+\u2502      }                                                  \u2502
+\u2502    ]                                                    \u2502
+\u2502  }                                                      \u2502
+\u2502                                                         \u2502
+\u2502  Or add headers() to next.config.js:                    \u2502
+\u2502                                                         \u2502
+\u2502  async headers() {                                      \u2502
+\u2502    return [{                                            \u2502
+\u2502      source: '/(.*)',                                   \u2502
+\u2502      headers: [                                         \u2502
+\u2502        { key: 'X-Frame-Options', value: 'ALLOWALL' },   \u2502
+\u2502        { key: 'Content-Security-Policy',                \u2502
+\u2502          value: 'frame-ancestors *' }                   \u2502
+\u2502      ]                                                  \u2502
+\u2502    }];                                                  \u2502
+\u2502  }                                                      \u2502
+\u2502                                                         \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+`);
+}
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  console.log("\n\u{1F680} OpenCloud SDK Setup\n");
+  if (command === "setup" || !command) {
+    const projectRoot = findProjectRoot();
+    console.log(`Project root: ${projectRoot}
+`);
+    console.log("Configuring iframe headers for OpenCloud...\n");
+    const success = setupVercelJson(projectRoot);
+    if (success) {
+      console.log(`
+\u2705 Setup complete!
+
+Your app is now configured to work with OpenCloud.
+After deploying, your app will be embeddable in the OpenCloud marketplace.
+
+Next steps:
+1. Deploy your app: vercel deploy --prod
+2. Publish on OpenCloud: https://opencloud.app/publish
+`);
+    } else {
+      printManualInstructions();
+    }
+  } else if (command === "help" || command === "--help" || command === "-h") {
+    console.log(`
+Usage: opencloud-sdk [command]
+
+Commands:
+  setup     Configure your project for OpenCloud (default)
+  help      Show this help message
+
+Examples:
+  npx opencloud-platform-sdk setup
+  npx opencloud-platform-sdk
+`);
+  } else {
+    console.log(`Unknown command: ${command}`);
+    console.log('Run "opencloud-sdk help" for usage information.');
+  }
+}
+main();