@beep-it/sdk-core 0.1.2-beta.2 → 0.1.2

package/README.md

@@ -2,36 +2,6 @@
 
 Alright, let's be real. You made something awesome. A game, an app, a digital masterpiece. And now you wanna get paid for it. As you should! But dealing with payments is a whole vibe killer. That's where we come in.
 
-## Table of Contents
-
-- [What is this?](#-so-like-what-even-is-this)
-- [🖥️ Server-Side SDK (BeepClient)](#server-side-sdk-beepclient)
-  - [Server-Side Setup](#server-side-setup)
-  - [Server-Side Making Money](#server-side-making-money)
-  - [Server-Side API Reference](#server-side-api-reference)
-- [📱 Frontend SDK (BeepPublicClient)](#frontend-sdk-beeppublicclient)
-  - [Frontend Setup](#frontend-setup)
-  - [Frontend Making Money](#frontend-making-money)
-  - [Frontend API Reference](#frontend-api-reference)
-- [Token Utilities](#token-utilities)
-- [Resources](#resources)
-
-## Which SDK Should I Use?
-
-**🖥️ Backend/Server Code?** → [Server-Side SDK (BeepClient)](#server-side-sdk-beepclient)
-
-- Full API access with secret keys
-- Server-side only (Node.js, Express, etc.)
-- Complete payment processing capabilities
-- **Streaming payments support** (issuePayment, startStreaming, etc.)
-
-**📱 Frontend/Browser Code?** → [Frontend SDK (BeepPublicClient)](#frontend-sdk-beeppublicclient)
-
-- Safe for client-side code
-- Uses publishable keys (not secret)
-- Perfect for React, Vue, or vanilla JS apps
-- **Limited to widget endpoints only** (no streaming payments)
-
 ## 🤔 So, like, what even _is_ this?
 
 Think of this SDK as your personal cheat code for money. It's a box of pre-written code that you can just drop into your project to handle all the boring payment stuff.
@@ -48,39 +18,56 @@ Basically, we're the ✨ unpaid intern ✨ who handles your finances so you can
 
 ---
 
-## Server-Side SDK (BeepClient)
+## 🚀 Let's Get This Bread: Your 3-Step Setup
 
-Perfect for Node.js, Express servers, Next.js API routes, and any backend code where you can safely store secret keys.
+This is probably easier than picking an Instagram filter. No cap.
 
-### Server-Side Setup
+### Step 1: Download the Magic
 
-#### Step 1: Install the SDK
+In your project's command line thingy (the black box where you type stuff), paste this:
 
 ```bash
 npm install @beep-it/sdk-core
 ```
 
-#### Step 2: Get Your Secret API Key
+This basically downloads our toolkit and puts it in your project's folder.
 
-1. Sign up for a BEEP account at [app.justbeep.it](https://app.justbeep.it)
-2. Go to your account settings and find your secret API key
-3. **Never expose this in client-side code!** Keep it on your server only.
+### Step 2: Get Your Secret Handshake (aka API Key)
 
-#### Step 3: Initialize BeepClient
+An API Key is just a super long, secret password. It's how our system knows it's you. You'll find yours on your BEEP dashboard.
+
+> **Seriously, don't share this.** It's like giving someone the keys to your house. Don't do it.
+
+### Step 3: Wake Up the BEEP-Bot
+
+Time to write, like, one line of code. This tells your project to start using the BEEP toolkit.
 
 ```typescript
+// This line just says, "Hey, I wanna use that beep-sdk thing I just downloaded."
 import { BeepClient, SupportedToken } from '@beep-it/sdk-core';
 
+// This line creates your BEEP-Bot. It's now ready for your commands.
 const beep = new BeepClient({
-  apiKey: 'your_secret_api_key_here', // Keep this secure!
+  // Just paste that secret key you got from the dashboard right here.
+  apiKey: 'your_super_secret_api_key_goes_here',
 });
+
+console.log('Ok, your BEEP-Bot is ready. Slay.');
 ```
 
-### Server-Side Making Money
+Bet. You're all set up. Now for the fun part.
+
+---
+
+## ⚙️ How to Actually Make Money with This
+
+Let's say you want to charge someone 5 USDT for a pack of 100 magic crystals in your game. Here's how to make that money move! 💸
 
-Let's say you want to charge someone 5 USDT for a pack of 100 magic crystals in your game. Here's the complete server-side flow:
+### Step 1: Ask for the Money
 
-#### The Server-Side Payment Flow
+You just need to tell your BEEP-Bot how much you want to charge and in what currency. We'll generate a unique QR code and a payment link for your customer.
+
+#### The Whole Payment Flow Explained (as if you were 5... but like, a cool 5-year-old)
 
 1. **You create an invoice** - This is literally just you telling our servers "hey, I want $X for Y reason"
 2. **We create an invoice** - Think of this as a digital receipt that says "pay this amount pls"
@@ -97,286 +84,309 @@ Let's say you want to charge someone 5 USDT for a pack of 100 magic crystals in
 Seriously, all _you_ need to worry about is step 1. We handle 2-7 because we're nice like that.
 
 ```typescript
-// Server-side invoice creation
+// Just describe what you're charging for.
 const invoiceDetails = {
   description: 'A pack of 100 magic crystals',
-  amount: '5.00',
-  token: SupportedToken.USDT,
-  payerType: 'customer_wallet' as const,
+  amount: '5.00', // Amount as string
+  token: SupportedToken.USDT, // Much cleaner than a long address, right?
+  payerType: 'customer_wallet' as const, // Who's paying
 };
 
 try {
+  // Tell your BEEP-Bot to create an invoice for payment.
+  // This creates a bill and gets everything ready behind the scenes.
   const invoice = await beep.invoices.createInvoice(invoiceDetails);
 
-  // Send this payment info to your frontend
-  res.json({
-    qrCode: invoice.qrCode,
-    paymentUrl: invoice.paymentUrl,
-    referenceKey: invoice.referenceKey,
-    invoiceId: invoice.id,
-  });
-
-  // Later, check if payment completed
-  const updatedInvoice = await beep.invoices.getInvoice(invoice.id!);
-  if (updatedInvoice.status === 'paid') {
-    // Unlock content for the user!
-  }
+  // Now you have everything you need to get paid!
+  console.log('QR Code:', invoice.qrCode);
+  console.log('Payment Link:', invoice.paymentUrl);
+  console.log('Reference Key:', invoice.referenceKey);
+
+  // What you do next is up to you:
+  // 1. Render the `qrCode` in your UI for the user to scan.
+  // 2. Redirect the user to the `paymentUrl`.
+  // BEEP will handle the rest on the backend once the user approves the transaction.
 } catch (error) {
-  console.error('Invoice creation failed:', error.message);
+  console.error('Oof. Something went wrong creating the invoice:', error.message);
 }
 ```
 
-### Server-Side API Reference
+And that's literally it. Once the user pays, the money appears in your account. You just made money.
+
+---
 
-#### Creating Invoices
+## 🤓 For the true DIYers (The API Deets)
+
+If you're the type of person who likes to take things apart just so you can put them back together, this is for you. Here are the technical specs. Everyone else, you can ignore this.
+
+### `BeepClient` (server-side, secret key)
+
+Initializes the client. Takes an `options` object.
 
 ```typescript
-const invoice = await beep.invoices.createInvoice({
-  amount: '19.99',
-  token: SupportedToken.USDT,
-  description: 'VIP Battle Pass',
-  payerType: 'customer_wallet',
-});
+new BeepClient(options: {
+  apiKey: string;       // Required. Your secret API key.
+  serverUrl?: string;   // Optional. For testing. Defaults to production.
+})
 ```
 
-#### Managing Products
+**High-Level Methods:**
+
+#### Creating Invoices for Payment
 
 ```typescript
-// Create a product
-const product = await beep.products.createProduct({
-  name: 'Magic Sword',
-  price: '9.99',
-  token: SupportedToken.USDT,
-  isSubscription: false,
+// The money maker - create an invoice for payment!
+const invoice = await beep.invoices.createInvoice({
+  amount: '19.99', // Amount as string
+  token: SupportedToken.USDT, // Enum magic!
+  description: 'VIP Battle Pass - Summer Season',
+  payerType: 'customer_wallet', // Customer pays
 });
 
-// List all products
-const products = await beep.products.listProducts();
+// Now you have everything you need for the user to pay
+console.log('Payment URL:', invoice.paymentUrl);
+console.log('Reference Key:', invoice.referenceKey);
+console.log('Invoice ID:', invoice.id);
+
+// IMPORTANT PART: What to do with this info!
+// Option 1: Redirect your user to the payment page
+window.location.href = invoice.paymentUrl;
+
+// OR Option 2: Show a QR code on your page
+renderQRCode(invoice.qrCode); // Use your favorite QR library
+
+// OR Option 3: Just give them the link
+displayToUser(`Pay here: ${invoice.paymentUrl}`);
+
+// After payment (could be seconds or minutes later):
+// Check if they've paid yet
+const updatedInvoice = await beep.invoices.getInvoice(invoice.id);
+
+if (updatedInvoice.status === 'paid') {
+  // Woohoo! Give them their digital goodies!
+  unlockAwesomeContent();
+  doHappyDance();
+} else if (updatedInvoice.status === 'pending') {
+  // Still waiting for payment
+  showSpinnyWaitingAnimation();
+} else if (updatedInvoice.status === 'expired') {
+  // Oof, they took too long
+  showSadTromboneSound();
+}
 ```
 
-#### Payment Processing
+#### Health Check
 
 ```typescript
-// Request asset purchase
-const payment = await beep.payments.requestAndPurchaseAsset({
-  assets: [{ assetId: 'product-uuid', quantity: 1 }],
-  generateQrCode: true,
-});
-
-// Wait for payment completion
-const { paid } = await beep.payments.waitForPaymentCompletion({
-  assets: [{ assetId: 'product-uuid', quantity: 1 }],
-  paymentReference: payment.referenceKey,
-});
+// Make sure our servers aren't on fire
+const health = await beep.healthCheck();
+console.log('Server health:', health); // Should return health status
 ```
 
-#### Streaming Payments (BeepClient Only)
+**Low-Level Modules:**
 
-**Important:** Streaming payment methods are only available with `BeepClient` using secret API keys. They do NOT work with `BeepPublicClient` or publishable keys.
+For when you need more control.
 
-```typescript
-// Issue a streaming payment session
-const session = await beep.payments.issuePayment({
-  apiKey: 'your_secret_api_key',
-  assetChunks: [
-    { assetId: 'video-content-uuid', quantity: 1 },
-    { assetId: 'api-access-uuid', quantity: 100 }
-  ],
-  payingMerchantId: 'merchant_who_pays'
-});
+### `SupportedToken`
 
-// Start charging for usage
-await beep.payments.startStreaming({
-  apiKey: 'your_secret_api_key',
-  invoiceId: session.invoiceId
-});
+Our shiny new enum for supported tokens! Way easier than remembering addresses.
 
-// Pause billing temporarily
-await beep.payments.pauseStreaming({
-  apiKey: 'your_secret_api_key',
-  invoiceId: session.invoiceId
-});
+```typescript
+// Import it like this
+import { SupportedToken } from '@beep-it/sdk-core';
 
-// Stop and finalize charges
-const result = await beep.payments.stopStreaming({
-  apiKey: 'your_secret_api_key',
-  invoiceId: session.invoiceId
-});
+// Use it like this
+const token = SupportedToken.USDT; // Currently supported
+// SupportedToken.USDC coming soon!
 ```
 
----
+### `beep.invoices`
 
-## Frontend SDK (BeepPublicClient)
+Handle invoice operations - create, retrieve, and manage payment invoices.
 
-Perfect for React, Vue, vanilla JS, or any client-side code where you can't safely store secret keys.
+```typescript
+// Create invoices for payment
+const invoice = await beep.invoices.createInvoice({
+  description: 'Premium service',
+  amount: '29.99',
+  token: SupportedToken.USDT,
+  payerType: 'customer_wallet',
+});
 
-### Frontend Setup
+// Get all your invoices
+const invoices = await beep.invoices.listInvoices();
 
-#### Step 1: Install the SDK
+// Look up a specific invoice
+const invoice = await beep.invoices.getInvoice('inv_123abc');
 
-```bash
-npm install @beep-it/sdk-core
+// Delete an invoice
+await beep.invoices.deleteInvoice('inv_123abc');
 ```
 
-#### Step 2: Get Your Publishable Key
+### `beep.products`
 
-1. Sign up for a BEEP account at [app.justbeep.it](https://app.justbeep.it)
-2. Go to your account settings and find your publishable key (starts with `beep_pk_`)
-3. This is safe to expose in client-side code!
+Manage your products - create reusable payment configurations with sweet token enum support! 🎉
 
-#### Step 3: Initialize BeepPublicClient
+#### Creating Products
 
 ```typescript
-import { BeepPublicClient, SupportedToken } from '@beep-it/sdk-core';
-
-const publicBeep = new BeepPublicClient({
-  publishableKey: 'beep_pk_your_publishable_key_here', // Safe for browsers!
+// Creating a one-time purchase product
+const product = await beep.products.createProduct({
+  name: 'Magic Sword of Destiny',
+  description: 'Gives +10 attack and looks cool as heck',
+  price: '9.99', // Just regular numbers as strings
+  token: SupportedToken.USDT, // So much cleaner than a crazy address
+  isSubscription: false, // One-time purchase
 });
-```
 
-### Frontend Making Money
+console.log(`Created product with ID: ${product.id}`);
 
-Here's how to create a complete payment flow in your React app:
+// Creating a subscription product
+const subscriptionProduct = await beep.products.createProduct({
+  name: 'Premium Battle Pass',
+  description: 'Monthly subscription with exclusive skins and perks',
+  price: '14.99', // Monthly price
+  token: SupportedToken.USDT,
+  isSubscription: true, // This makes it recurring - monthly subscription!
+});
 
-#### The Frontend Payment Flow
+console.log(`Created subscription with ID: ${subscriptionProduct.id}`);
 
-```typescript
-// Create a payment session with mixed assets
-const handlePurchase = async () => {
-  try {
-    const session = await publicBeep.widget.createPaymentSession({
-      assets: [
-        // Use existing products
-        { assetId: 'existing-product-uuid', quantity: 1 },
-        // Or create items on-the-fly
-        {
-          name: 'Custom Magic Potion',
-          price: '12.50',
-          quantity: 2,
-          description: 'Instant health boost',
-        },
-      ],
-      paymentLabel: 'My Awesome Game Store',
-    });
-
-    // Show payment URL/QR to user
-    setPaymentUrl(session.paymentUrl);
-    setReferenceKey(session.referenceKey);
-
-    // Start polling for payment completion
-    const { paid } = await publicBeep.widget.waitForPaid({
-      referenceKey: session.referenceKey,
-      intervalMs: 5000, // Check every 5 seconds
-      timeoutMs: 5 * 60 * 1000, // 5 minute timeout
-    });
-
-    if (paid) {
-      // Payment successful! Unlock content
-      setShowSuccessMessage(true);
-      unlockPremiumFeatures();
-    }
-  } catch (error) {
-    console.error('Payment failed:', error);
-  }
-};
-```
+// Creating a one-time purchase product (pay-per-use)
+const oneTimeProduct = await beep.products.createProduct({
+  name: 'API Usage Credit',
+  description: 'Credits for API calls',
+  price: '0.001', // Price per credit
+  token: SupportedToken.USDT,
+  isSubscription: false, // One-time purchase
+});
 
-### Frontend API Reference
+console.log(`Created one-time product with ID: ${oneTimeProduct.id}`);
+```
 
-#### Creating Payment Sessions
+#### Getting a Product
 
 ```typescript
-const session = await publicBeep.widget.createPaymentSession({
-  assets: [
-    { assetId: 'existing-product', quantity: 1 },
-    { name: 'Custom Item', price: '5.99', quantity: 1 },
-  ],
-  paymentLabel: 'Your Store Name',
-});
+// Fetch a product by ID
+const product = await beep.products.getProduct('prod_123abc456def');
+console.log(`Found product: ${product.name} for ${product.price}`);
 ```
 
-#### Checking Payment Status
+#### Listing All Products
 
 ```typescript
-const status = await publicBeep.widget.getPaymentStatus(referenceKey);
-console.log('Payment completed:', status.paid);
+// Get all your amazing products
+const products = await beep.products.listProducts();
+console.log(`You have ${products.length} products`);
+
+// Loop through them if you're feeling fancy
+products.forEach((product) => {
+  console.log(`${product.name}: ${product.price} ${product.token || 'tokens'}`);
+});
 ```
 
-#### Waiting for Payment (with polling)
+#### Updating a Product
 
 ```typescript
-const { paid, timedOut } = await publicBeep.widget.waitForPaid({
-  referenceKey: session.referenceKey,
-  intervalMs: 5000,
-  timeoutMs: 300000, // 5 minutes
+// Change your mind about pricing? No problemo!
+const updatedProduct = await beep.products.updateProduct('prod_123abc456def', {
+  price: '14.99', // Price increase! Cha-ching!
+  description: 'Now with extra sparkles ✨',
+  token: SupportedToken.USDT,
 });
-```
 
----
+console.log('Product updated with new price:', updatedProduct.price);
+```
 
-## 🤓 Advanced API Reference
+#### Deleting a Product
 
-## Token Utilities
+```typescript
+// That product is so last season - delete it!
+await beep.products.deleteProduct('prod_123abc456def');
+console.log('Poof! Product deleted.');
+```
 
-### `SupportedToken`
+### `beep.payments`
 
-Clean token enum instead of remembering addresses:
+Handle low-level payment operations like asset purchasing and transaction signing.
 
 ```typescript
-import { SupportedToken } from '@beep-it/sdk-core';
+// Request payment for assets
+const payment = await beep.payments.requestAndPurchaseAsset({
+  paymentReference: 'premium_subscription_123',
+  assetIds: ['asset_1', 'asset_2'],
+});
 
-const token = SupportedToken.USDT; // Much cleaner!
+// Sign Solana transactions directly
+const signedTx = await beep.payments.signSolanaTransaction({
+  senderAddress: 'sender_wallet_address',
+  recipientAddress: 'recipient_wallet_address',
+  tokenMintAddress: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+  amount: 1000000, // 1.0 USDT in base units
+  decimals: 6,
+});
 ```
 
 ### `TokenUtils`
 
-Advanced token utilities:
+For the super nerds who want to play with token addresses:
 
 ```typescript
 import { TokenUtils, SupportedToken } from '@beep-it/sdk-core';
 
 // Get the address from a token enum
 const address = TokenUtils.getTokenAddress(SupportedToken.USDT);
+console.log(address); // 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'
 
 // Check if we support a token
-const isSupported = TokenUtils.isTokenSupported(SupportedToken.USDT);
+const isSupported = TokenUtils.isTokenSupported(SupportedToken.USDT); // true
+const isUsdtSupported = TokenUtils.isTokenSupported('USDT'); // false (coming soon™)
 
 // Get a token enum from an address (reverse lookup)
 const token = TokenUtils.getTokenFromAddress('Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB');
+console.log(token); // SupportedToken.USDT
+
+// Get the default token if none specified
+const defaultToken = TokenUtils.getDefaultToken();
+console.log(defaultToken); // SupportedToken.USDT
 ```
 
----
+### `BeepPublicClient` (browser, publishable key)
 
-## Resources
+Use this in browsers or anywhere you can’t safely keep a secret key. It talks only to the public, CORS-open widget endpoints.
 
-[Beep llms.txt](https://www.justbeep.it/llms.txt)
+```typescript
+import { BeepPublicClient } from '@beep-it/sdk-core';
 
----
+const publicClient = new BeepPublicClient({
+  publishableKey: 'beep_pk_...',
+  serverUrl: 'https://api.justbeep.it', // optional
+});
 
-## License
+// Create a payment session with mixed assets (existing + ephemeral)
+const session = await publicClient.widget.createPaymentSession({
+  assets: [
+    { assetId: 'existing-product-uuid', quantity: 1 },
+    { name: 'Custom Item', price: '12.50', quantity: 2, description: 'On-the-fly item' },
+  ],
+  paymentLabel: 'My Store',
+});
 
-MIT. Go wild.
-#### Payouts (BeepClient Only)
+console.log(session.paymentUrl, session.referenceKey);
 
-Initiate a payout from your treasury wallet to an external address. Requires a secret API key and must be called server-side.
+// Poll payment status
+const status = await publicClient.widget.getPaymentStatus(session.referenceKey);
+console.log('paid:', status.paid);
+```
 
-Notes:
-- The server derives the source wallet from your API key's merchant and the requested chain; you do not provide a walletId.
-- `amount` must be provided in the token's smallest units (integer as a string). For USDC with 6 decimals, 1.00 USDC = "1000000".
-- The response indicates acceptance or rejection. Execution happens asynchronously after treasury funds are reserved.
+---
 
-Example:
-```ts
-import { BeepClient } from '@beep-it/sdk-core';
+## Resources
 
-const beep = new BeepClient({ apiKey: process.env.BEEP_API_KEY! });
+[Beep llms.txt](https://www.justbeep.it/llms.txt)
 
-const result = await beep.createPayout({
-  amount: '1000000', // 1.00 USDC (6 decimals)
-  destinationWalletAddress: 'DESTINATION_ADDRESS',
-  chain: 'SOLANA',
-  token: 'USDC',
-});
+---
 
-console.log(result.status, result.message);
-```
+## License
+
+MIT. Go wild.