opencloud-platform-sdk

Official SDK for OpenCloud - Monetize your AI apps with ease.

You control the AI, we handle the payments.

What's New in v3.0

• 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

npm install opencloud-platform-sdk

Quick Start

import { opencloud } from 'opencloud-platform-sdk';

// 1. Initialize with your app ID (slug)
opencloud.init({ appId: 'your-app-slug' });

// 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;
}

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

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

opencloud.init(config)

Initialize the SDK.

opencloud.init({
  appId: 'your-app-slug',  // Required - your app's slug
  apiUrl: 'https://opencloud.app'  // Optional - defaults to production
});

opencloud.charge(action?, metadata?)

Charge the user. Opens login popup if not authenticated.

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.withCharge(fn, options)

Execute a function and charge the user. Handles auth and balance checks automatically.

const image = await opencloud.withCharge(async () => {
  return await myAIService.generateImage(prompt);
}, { action: 'generate_image' });

opencloud.isAuthenticated()

Check if user is logged in.

if (opencloud.isAuthenticated()) {
  console.log('User is logged in');
}

opencloud.login()

Open login popup manually.

const session = await opencloud.login();
if (session) {
  console.log('Logged in as:', session.user.email);
}

opencloud.logout()

Log out the current user.

opencloud.logout();

opencloud.getUser()

Get current user info (synchronous).

const user = opencloud.getUser();
// { id, email, username, balance }

opencloud.getBalance()

Get user's current balance (async, fetches from server).

const balance = await opencloud.getBalance();
console.log(`Balance: $${balance}`);

opencloud.canAfford()

Check if user can afford to use the app.

const canUse = await opencloud.canAfford();
if (!canUse) {
  opencloud.openTopUp();
}

opencloud.openTopUp()

Open top-up popup for user to add credits.

opencloud.openTopUp();

opencloud.getAppPrice()

Get your app's price per use.

const price = await opencloud.getAppPrice();
console.log(`Price: $${price}`);

opencloud.isPreview()

Check if running in development mode.

if (opencloud.isPreview()) {
  console.log('Preview mode - no real charges');
}

Revenue Model

85/15 split - You keep most of what you earn!

User pays:     $0.10 per use
├─ You get:    $0.085 (85%)
└─ Platform:   $0.015 (15%)

Preview Mode

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

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
2. Go to opencloud.app/publish
3. Create a new app with your deployed URL
4. Set name, description, and price per use
5. Get your app slug
6. Use the slug in opencloud.init({ appId: 'your-slug' })

TypeScript Support

Full TypeScript definitions included:

import {
  opencloud,
  OpenCloudSDK,
  ChargeResult,
  UserSession,
  UserInfo
} from 'opencloud-platform-sdk';

Support

• Docs: opencloud.app/docs
• Issues: github.com/opencloud/sdk

License

MIT