@proappstore/sdk 1.1.1 → 1.2.0

package/README.md

@@ -1,11 +1,13 @@
 # @proappstore/sdk
 
-Unified SDK for paid apps on **proappstore.online**. Includes everything from `@freeappstore/sdk` (auth, kv, counters, rooms, proxy) plus subscription management and license keys.
+Unified SDK for paid apps on **proappstore.online**. Includes everything from `@freeappstore/sdk` (auth, kv, counters, rooms, proxy) plus subscription management, license keys, and a per-app SQL database.
 
 ## Installation
 
 ```bash
 npm i @proappstore/sdk
+# or
+pnpm add @proappstore/sdk
 ```
 
 ## Usage
@@ -14,52 +16,163 @@ npm i @proappstore/sdk
 import { initPro } from '@proappstore/sdk'
 
 const app = initPro({ appId: 'my-app' })
+```
+
+Options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `appId` | (required) | Your app's unique identifier |
+| `fasApiBase` | `https://api.freeappstore.online` | Free-tier backend URL |
+| `proApiBase` | `https://api.proappstore.online` | Pro-tier backend URL |
+| `dataApiBase` | `https://data-{appId}.proappstore.online` | Per-app data worker URL |
+
+## Modules
+
+### Auth
+
+GitHub OAuth — shared identity across all FreeAppStore and ProAppStore apps.
 
-// Auth (GitHub OAuth — same identity as FreeAppStore)
+```ts
 await app.auth.init()
 app.auth.onChange((user) => console.log(user))
 app.auth.signIn()
+app.auth.signOut()
+```
 
-// Per-user KV storage
+### KV (Per-user key-value storage)
+
+```ts
 await app.kv.set('profile', { name: 'Alice' })
+const profile = await app.kv.get('profile')
 const keys = await app.kv.list({ prefix: 'note:' })
+await app.kv.delete('profile')
+```
+
+### Counters (Shared atomic counters)
+
+Cross-user counters for votes, views, leaderboards.
 
-// Shared counters (cross-user)
+```ts
 await app.counters.increment('views')
+await app.counters.decrement('likes')
 const all = await app.counters.list()
+```
 
-// Real-time rooms
+### Rooms (Real-time WebSocket)
+
+```ts
 const room = app.rooms.join('lobby')
 room.send({ text: 'hello' })
 room.onMessage((msg) => console.log(msg))
+room.onPeers((peers) => console.log(peers))
+room.leave()
+```
+
+### Proxy (Secret-injecting API proxy)
+
+Call third-party APIs without exposing keys to the client.
+
+```ts
+const response = await app.proxy.fetch('/openai/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ model: 'gpt-4', messages: [...] }),
+})
+```
+
+### Database (Per-app SQL)
+
+Each Pro app gets its own D1 SQL database accessed through a dedicated data worker at `data-{appId}.proappstore.online`.
+
+```ts
+// Query rows
+const { rows } = await app.db.query('SELECT * FROM users WHERE active = ?', [true])
 
-// Subscriptions (Stripe-powered)
+// Execute writes
+const { meta } = await app.db.execute('INSERT INTO users (name) VALUES (?)', ['Alice'])
+console.log(meta.last_row_id) // auto-increment id
+
+// Batch (transactional)
+const results = await app.db.batch([
+  { sql: 'INSERT INTO orders (user_id, total) VALUES (?, ?)', params: [1, 99.99] },
+  { sql: 'UPDATE users SET order_count = order_count + 1 WHERE id = ?', params: [1] },
+])
+
+// List tables
+const tables = await app.db.tables()
+```
+
+### Subscription (Stripe-powered)
+
+```ts
+// Check subscription status
 const sub = await app.subscription.status()
-if (!sub || sub.status !== 'active') {
-  await app.subscription.openCheckout({
-    priceId: 'price_xxx',
-    successUrl: 'https://my-app.proappstore.online/success',
-    cancelUrl: 'https://my-app.proappstore.online/',
-  })
-}
+// Returns: { status, tier, priceId, currentPeriodEnd, cancelAtPeriodEnd } | null
+
+// Open Stripe checkout (navigates away)
+await app.subscription.openCheckout({
+  priceId: 'price_pro_monthly',
+  successUrl: 'https://my-app.proappstore.online/success',
+  cancelUrl: 'https://my-app.proappstore.online/',
+})
+
+// Open Stripe billing portal (navigates away)
 await app.subscription.openPortal('https://my-app.proappstore.online/')
+```
+
+### License
 
-// License keys
+Per-app license key validation.
+
+```ts
+// Get current user's license (requires auth)
 const license = await app.license.current()
-const valid = await app.license.validate('KEY-123')
+// Returns: { key, appId, issuedAt, expiresAt } | null
+
+// Validate any key (no auth required)
+const valid = await app.license.validate('LIC-ABC-123')
 ```
 
-## Modules
+## ProShell Component
+
+A React component that handles auth gates, subscription checks, and renders a platform-level shell with topbar and user menu.
+
+```tsx
+import { initPro } from '@proappstore/sdk'
+import { ProShell } from '@proappstore/sdk/shell'
+
+const app = initPro({ appId: 'meetup' })
+
+export default function App() {
+  return (
+    <ProShell app={app} appName="Meetup">
+      <MeetupApp />
+    </ProShell>
+  )
+}
+```
+
+Props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `app` | `ProAppStore` | SDK instance from `initPro()` |
+| `children` | `ReactNode` | App content (rendered only when gates pass) |
+| `appName` | `string?` | Name shown in the topbar |
+| `allowFree` | `boolean?` | Skip subscription gate (default: `false`) |
+
+ProShell handles:
+- Auth initialization and sign-in gate
+- Subscription check and upgrade wall (unless `allowFree=true`)
+- Topbar with avatar, app name, and user menu (sign out, manage billing, delete account)
+
+## Per-app SQL Database
+
+Each Pro app is provisioned with a dedicated Cloudflare D1 database fronted by a data worker (`data-{appId}.proappstore.online`). The SDK's `db` module provides a typed client for this worker.
+
+The database is per-user isolated at the auth layer — all requests require a valid Bearer token. The data worker validates the token against the FAS auth API before executing queries.
 
-| Module | Source | Description |
-|--------|--------|-------------|
-| `auth` | FAS | GitHub OAuth, SSO across all apps |
-| `kv` | FAS | Per-user key-value store (list, get, set, delete, getMany) |
-| `counters` | FAS | Shared atomic counters (votes, views, leaderboards) |
-| `rooms` | FAS | Real-time WebSocket rooms (presence, chat, collab) |
-| `proxy` | FAS | Secret-injecting API proxy for third-party services |
-| `subscription` | Pro | Stripe checkout, portal, status |
-| `license` | Pro | Per-app license key validation |
+Tables are user-defined (create them via `db.execute('CREATE TABLE IF NOT EXISTS ...')`). The schema is entirely up to the app developer.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proappstore/sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Browser SDK for paid apps on proappstore.online — subscriptions, license keys, premium modules.",
   "license": "MIT",
   "type": "module",