@tabbycat/sdk

SDK for building apps on the Tabbycat platform with authentication and persistent storage.

Installation

npm install @tabbycat/sdk

Quick Start

import { createApp, PlatformStorage } from '@tabbycat/sdk'

// Export the PlatformStorage Durable Object
export { PlatformStorage }

const app = createApp({ appId: 'my-app' })

// All /api/* routes automatically have user auth and storage
app.get('/api/me', (c) => {
  const user = c.get('user')
  return c.json({ user })
})

// Use persistent storage (scoped per user/org)
app.get('/api/data', async (c) => {
  const storage = c.get('storage')
  const data = await storage.get('my-collection', 'my-key')
  return c.json({ data })
})

app.post('/api/data', async (c) => {
  const storage = c.get('storage')
  const body = await c.req.json()
  await storage.set('my-collection', 'my-key', body)
  return c.json({ success: true })
})

// Serve static assets
app.get('*', async (c) => {
  return c.env.ASSETS.fetch(c.req.raw)
})

export default app

Features

Authentication

The SDK automatically handles authentication via:

1. X-User-Context header - Injected by the Tabbycat dispatch worker (W4P mode)
2. PropelAuth tokens - Direct JWT verification (standalone mode)

Access the authenticated user in any /api/* route:

app.get('/api/profile', (c) => {
  const user = c.get('user')
  // user.id, user.email, user.orgId
  return c.json({ user })
})

Persistent Storage

Storage is automatically scoped per user (or per organization if the user belongs to one).

const storage = c.get('storage')

// Get a value
const item = await storage.get<MyType>('collection', 'key')

// Set a value
await storage.set('collection', 'key', { foo: 'bar' })

// Delete a value
await storage.delete('collection', 'key')

// List items in a collection
const result = await storage.list<MyType>('collection', {
  limit: 10,
  cursor: 'optional-cursor'
})
// result.items, result.cursor

Wrangler Configuration

Add the PlatformStorage Durable Object to your wrangler.toml:

name = "my-app"
main = "worker/index.ts"
compatibility_date = "2024-12-18"
compatibility_flags = ["nodejs_compat"]

[assets]
directory = "./dist/client"
binding = "ASSETS"

[[durable_objects.bindings]]
name = "PLATFORM_STORAGE"
class_name = "PlatformStorage"

[[migrations]]
tag = "v1"
new_classes = ["PlatformStorage"]

Environment Variables

| Variable | Description | |----------|-------------| | SIGNING_SECRET | Secret for verifying X-User-Context signatures | | PROPELAUTH_VERIFIER_KEY | PropelAuth public key (standalone mode) | | PROPELAUTH_AUTH_URL | PropelAuth auth URL (standalone mode) |

License

MIT