@vettly/supabase 0.1.0 → 0.1.2

package/README.md

@@ -1,266 +1,464 @@
 # @vettly/supabase
 
-Vettly content moderation for Supabase Edge Functions. Deno-compatible, fetch-based client.
+Vettly decision infrastructure for Supabase Edge Functions. Deno-compatible client with fetch-based transport for serverless environments.
+
+## Why Edge-Native?
+
+Supabase Edge Functions run on Deno at the edge. This package provides:
+
+- **Deno-compatible** - Pure fetch-based transport, no Node.js dependencies
+- **Edge-optimized** - Minimal cold start, works in Supabase's 2ms startup
+- **Handler utilities** - One-liner Edge Function moderation
+- **Full audit trail** - Every decision recorded with unique ID
 
 ## Installation
 
+### npm (for bundling)
+
 ```bash
 npm install @vettly/supabase
 ```
 
-Or with Deno in your Edge Function:
+### Deno (direct import)
 
 ```typescript
 import { moderate } from 'npm:@vettly/supabase'
 ```
 
-## Quick Start
+---
+
+## Quick Start - One-Liner
 
-### One-liner Edge Function
+The fastest way to add moderation to an Edge Function:
 
 ```typescript
+// supabase/functions/comments/index.ts
 import { createModerationHandler } from '@vettly/supabase'
 
-// Moderate all incoming content
 Deno.serve(createModerationHandler({
-  policyId: 'default',
-  onBlock: (result) => new Response(JSON.stringify({
-    error: 'Content blocked',
-    reason: result.categories.filter(c => c.flagged)
-  }), { status: 403, headers: { 'Content-Type': 'application/json' } })
+  policyId: 'community-safe',
+  onBlock: (result) => new Response(
+    JSON.stringify({
+      error: 'Content blocked',
+      decisionId: result.decisionId,
+      categories: result.categories.filter(c => c.triggered)
+    }),
+    { status: 403, headers: { 'Content-Type': 'application/json' } }
+  )
 }))
 ```
 
-### Manual Control
+---
+
+## Quick Start - Manual Integration
+
+For more control:
 
 ```typescript
-import { moderate } from '@vettly/supabase'
+// supabase/functions/posts/index.ts
+import { createClient } from '@vettly/supabase'
+
+const vettly = createClient({
+  apiKey: Deno.env.get('VETTLY_API_KEY')!
+})
 
 Deno.serve(async (req) => {
   const { content, userId } = await req.json()
 
-  // Moderate content first
-  const result = await moderate(content, { policyId: 'strict' })
+  // Check content
+  const result = await vettly.check(content, {
+    policyId: 'community-safe',
+    metadata: { userId }
+  })
 
   if (result.action === 'block') {
-    return new Response('Content blocked', { status: 403 })
+    return new Response(
+      JSON.stringify({
+        error: 'Content blocked',
+        decisionId: result.decisionId
+      }),
+      { status: 403, headers: { 'Content-Type': 'application/json' } }
+    )
   }
 
-  // Content is safe, continue with your logic
-  // await supabase.from('posts').insert({ content, userId })
+  // Content allowed - proceed with your logic
+  // Store result.decisionId for audit trail
 
-  return new Response(JSON.stringify({ success: true }), {
-    headers: { 'Content-Type': 'application/json' }
-  })
+  return new Response(
+    JSON.stringify({ success: true, decisionId: result.decisionId }),
+    { headers: { 'Content-Type': 'application/json' } }
+  )
 })
 ```
 
-### Middleware Pattern
-
-```typescript
-import { withModeration } from '@vettly/supabase'
+---
 
-const handler = withModeration(
-  async (req, moderationResult) => {
-    // Content already passed moderation
-    const { content, userId } = await req.json()
-
-    // Insert into database...
-    // await supabase.from('posts').insert({ content, userId })
-
-    return new Response(JSON.stringify({
-      success: true,
-      moderation: {
-        decisionId: moderationResult.decisionId,
-        safe: moderationResult.safe
-      }
-    }), { headers: { 'Content-Type': 'application/json' } })
-  },
-  { policyId: 'user-content' }
-)
-
-Deno.serve(handler)
-```
+## API Reference
 
-## Configuration
+### `createClient(config)`
 
-### Environment Variable
+Create a configured Vettly client.
 
-Set `VETTLY_API_KEY` in your Supabase project secrets:
+```typescript
+import { createClient } from '@vettly/supabase'
 
-```bash
-supabase secrets set VETTLY_API_KEY=your_api_key
+const client = createClient({
+  apiKey: Deno.env.get('VETTLY_API_KEY')!,
+  apiUrl: 'https://api.vettly.dev'  // optional
+})
 ```
 
-### Programmatic Configuration
+#### `client.check(content, options)`
 
-```typescript
-import { createClient } from '@vettly/supabase'
+Check text content against a policy.
 
-const vettly = createClient({
-  apiKey: Deno.env.get('VETTLY_API_KEY')!,
-  apiUrl: 'https://api.vettly.dev', // optional
-  timeout: 30000 // optional, in ms
+```typescript
+const result = await client.check('User-generated text', {
+  policyId: 'community-safe',
+  metadata: { userId: 'user_123' }
 })
 
-const result = await vettly.check('Hello world', { policyId: 'default' })
+console.log(result.action)      // 'allow' | 'warn' | 'flag' | 'block'
+console.log(result.decisionId)  // UUID for audit trail
+console.log(result.categories)  // Array of { category, score, triggered }
 ```
 
-## API Reference
-
-### `moderate(content, options?)`
+#### `client.checkImage(imageUrl, options)`
 
-Moderate text content using the default client.
+Check an image against a policy.
 
 ```typescript
-const result = await moderate('User generated content', {
-  policyId: 'strict',      // Policy to use (default: 'default')
-  contentType: 'text',     // 'text' | 'image' | 'video'
-  language: 'en',          // ISO 639-1 language code
-  metadata: { userId: '123' }
-})
+// From URL
+const result = await client.checkImage(
+  'https://cdn.example.com/image.jpg',
+  { policyId: 'strict' }
+)
 
-// Result:
-// {
-//   decisionId: 'dec_123',
-//   safe: true,
-//   flagged: false,
-//   action: 'allow',
-//   categories: [{ category: 'hate_speech', score: 0.01, flagged: false }],
-//   provider: 'openai',
-//   latency: 150,
-//   cost: 0.0001
-// }
+// From base64
+const result = await client.checkImage(
+  'data:image/jpeg;base64,/9j/4AAQ...',
+  { policyId: 'strict' }
+)
 ```
 
-### `moderateImage(imageUrl, options?)`
+---
 
-Moderate an image by URL.
+### `moderate(content, options)`
+
+Quick moderation without creating a client. Uses `VETTLY_API_KEY` environment variable.
 
 ```typescript
-const result = await moderateImage('https://example.com/image.jpg', {
-  policyId: 'images'
-})
+import { moderate } from '@vettly/supabase'
+
+const result = await moderate('User content', { policyId: 'default' })
+
+if (result.action === 'block') {
+  // Handle blocked content
+}
 ```
 
+---
+
 ### `createModerationHandler(config)`
 
-Create an Edge Function handler that moderates incoming requests.
+Create an Edge Function handler with built-in moderation.
 
 ```typescript
 import { createModerationHandler } from '@vettly/supabase'
 
 Deno.serve(createModerationHandler({
-  apiKey: Deno.env.get('VETTLY_API_KEY'),  // Optional, uses env var by default
-  policyId: 'default',
+  // Required
+  policyId: 'community-safe',
 
-  // Custom content extraction (default: reads req.json().content)
-  getContent: async (req) => {
-    const { message } = await req.json()
-    return message
-  },
+  // Optional: field path in JSON body (default: 'content')
+  field: 'content',
 
-  // Handle blocked content
-  onBlock: (result, req) => {
-    return new Response(JSON.stringify({ blocked: true }), { status: 403 })
-  },
-
-  // Handle flagged content (logged but allowed)
-  onFlag: (result, req) => {
-    console.log('Flagged content:', result.decisionId)
-  },
-
-  // Handle warnings
-  onWarn: (result, req) => {
-    console.log('Warning:', result.categories)
-  },
-
-  // Handle allowed content
-  onAllow: (result, req) => {
-    return new Response(JSON.stringify({ success: true }))
-  },
-
-  // Handle errors
-  onError: (error, req) => {
-    console.error('Moderation error:', error)
-    return new Response('Error', { status: 500 })
+  // Optional: custom block response
+  onBlock: (result) => new Response(
+    JSON.stringify({ error: 'Blocked', decisionId: result.decisionId }),
+    { status: 403, headers: { 'Content-Type': 'application/json' } }
+  ),
+
+  // Optional: handler for allowed content
+  onAllow: async (req, result) => {
+    const body = await req.json()
+
+    // Your business logic here
+    // result.decisionId available for audit trail
+
+    return new Response(JSON.stringify({ success: true }), {
+      headers: { 'Content-Type': 'application/json' }
+    })
   }
 }))
 ```
 
+---
+
 ### `withModeration(handler, config)`
 
-Middleware-style handler that moderates content before passing to your handler.
+Wrap an existing Edge Function with moderation.
 
 ```typescript
 import { withModeration } from '@vettly/supabase'
 
-const handler = withModeration(
-  async (req, moderationResult) => {
-    // Your handler receives the moderation result
-    console.log('Decision ID:', moderationResult.decisionId)
-    console.log('Safe:', moderationResult.safe)
+async function myHandler(req: Request): Promise<Response> {
+  const body = await req.json()
 
-    // Process the request...
-    return new Response(JSON.stringify({ success: true }))
-  },
-  { policyId: 'user-content' }
-)
+  // Your existing logic
+  await db.posts.create({ content: body.content })
 
-Deno.serve(handler)
+  return new Response(JSON.stringify({ success: true }), {
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+
+Deno.serve(withModeration(myHandler, {
+  policyId: 'community-safe',
+  field: 'content'
+}))
 ```
 
-### `createClient(config)`
+---
 
-Create a configured Vettly client for more control.
+## Response Format
+
+All moderation methods return:
 
 ```typescript
-const client = createClient({
-  apiKey: 'vettly_...',
-  apiUrl: 'https://api.vettly.dev',
-  timeout: 30000
+interface ModerationResult {
+  decisionId: string              // UUID for audit trail
+  safe: boolean                   // True if content passes
+  flagged: boolean                // True if flagged for review
+  action: 'allow' | 'warn' | 'flag' | 'block'
+  categories: Array<{
+    category: string              // e.g., 'hate_speech', 'harassment'
+    score: number                 // 0.0 to 1.0
+    triggered: boolean            // True if threshold exceeded
+  }>
+  latency: number                 // Response time in ms
+}
+```
+
+---
+
+## Environment Setup
+
+### Supabase Dashboard
+
+1. Go to your project settings
+2. Navigate to Edge Functions > Secrets
+3. Add `VETTLY_API_KEY` with your API key
+
+### Local Development
+
+Create `.env.local` in your Supabase project:
+
+```bash
+VETTLY_API_KEY=sk_live_...
+```
+
+Or set in `supabase/functions/.env`:
+
+```bash
+VETTLY_API_KEY=sk_live_...
+```
+
+---
+
+## Examples
+
+### Comments API
+
+```typescript
+// supabase/functions/comments/index.ts
+import { createClient } from '@vettly/supabase'
+import { createClient as createSupabase } from '@supabase/supabase-js'
+
+const vettly = createClient({ apiKey: Deno.env.get('VETTLY_API_KEY')! })
+const supabase = createSupabase(
+  Deno.env.get('SUPABASE_URL')!,
+  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+)
+
+Deno.serve(async (req) => {
+  if (req.method !== 'POST') {
+    return new Response('Method not allowed', { status: 405 })
+  }
+
+  const { content, postId, userId } = await req.json()
+
+  // Moderate content
+  const result = await vettly.check(content, {
+    policyId: 'comments',
+    metadata: { postId, userId }
+  })
+
+  if (result.action === 'block') {
+    return new Response(
+      JSON.stringify({
+        error: 'Comment blocked',
+        decisionId: result.decisionId
+      }),
+      { status: 403, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  // Save comment with audit trail
+  const { data, error } = await supabase
+    .from('comments')
+    .insert({
+      content,
+      post_id: postId,
+      user_id: userId,
+      moderation_decision_id: result.decisionId,
+      moderation_action: result.action
+    })
+    .select()
+    .single()
+
+  if (error) {
+    return new Response(
+      JSON.stringify({ error: error.message }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  return new Response(
+    JSON.stringify(data),
+    { headers: { 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+### Image Upload Moderation
+
+```typescript
+// supabase/functions/upload-image/index.ts
+import { createClient } from '@vettly/supabase'
+
+const vettly = createClient({ apiKey: Deno.env.get('VETTLY_API_KEY')! })
+
+Deno.serve(async (req) => {
+  const formData = await req.formData()
+  const file = formData.get('file') as File
+
+  // Convert to base64 for moderation
+  const buffer = await file.arrayBuffer()
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)))
+  const dataUri = `data:${file.type};base64,${base64}`
+
+  // Check image
+  const result = await vettly.checkImage(dataUri, { policyId: 'images' })
+
+  if (result.action === 'block') {
+    return new Response(
+      JSON.stringify({
+        error: 'Image rejected',
+        decisionId: result.decisionId,
+        categories: result.categories.filter(c => c.triggered)
+      }),
+      { status: 403, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+
+  // Proceed with upload...
+  // Store result.decisionId with the image record
+
+  return new Response(
+    JSON.stringify({ success: true, decisionId: result.decisionId }),
+    { headers: { 'Content-Type': 'application/json' } }
+  )
 })
+```
+
+### Webhook Handler
+
+```typescript
+// supabase/functions/moderation-webhook/index.ts
+Deno.serve(async (req) => {
+  const signature = req.headers.get('x-vettly-signature')
+  const payload = await req.text()
+
+  // Verify webhook signature
+  // (implement verification as shown in main SDK docs)
 
-// Text moderation
-const textResult = await client.check('Hello world', { policyId: 'default' })
+  const event = JSON.parse(payload)
 
-// Image moderation
-const imageResult = await client.checkImage('https://...', { policyId: 'images' })
+  switch (event.type) {
+    case 'decision.blocked':
+      // Notify moderators
+      await notifySlack(`Content blocked: ${event.data.decisionId}`)
+      break
+
+    case 'decision.flagged':
+      // Add to review queue
+      await addToReviewQueue(event.data)
+      break
+  }
+
+  return new Response('OK')
+})
 ```
 
+---
+
 ## Error Handling
 
 ```typescript
-import { moderate, VettlyError, VettlyAuthError, VettlyRateLimitError } from '@vettly/supabase'
-
-try {
-  const result = await moderate('content')
-} catch (error) {
-  if (error instanceof VettlyAuthError) {
-    console.error('Invalid API key')
-  } else if (error instanceof VettlyRateLimitError) {
-    console.error('Rate limited, retry after:', error.retryAfter)
-  } else if (error instanceof VettlyError) {
-    console.error('Vettly error:', error.code, error.message)
+import { createClient } from '@vettly/supabase'
+
+const vettly = createClient({ apiKey: Deno.env.get('VETTLY_API_KEY')! })
+
+Deno.serve(async (req) => {
+  try {
+    const { content } = await req.json()
+    const result = await vettly.check(content, { policyId: 'default' })
+
+    return new Response(JSON.stringify(result), {
+      headers: { 'Content-Type': 'application/json' }
+    })
+  } catch (error) {
+    // Log error but fail open (allow content through)
+    console.error('Moderation error:', error)
+
+    return new Response(
+      JSON.stringify({ warning: 'Moderation unavailable', allowed: true }),
+      { headers: { 'Content-Type': 'application/json' } }
+    )
   }
-}
+})
 ```
 
-## TypeScript Types
+---
+
+## TypeScript Support
+
+Full TypeScript support with Deno:
 
 ```typescript
-import type {
-  ModerationResult,
-  ModerationOptions,
-  Action,
-  Category,
-  CategoryScore,
-  VettlyConfig,
-  EdgeHandlerOptions,
-  ModerationHandlerConfig
-} from '@vettly/supabase'
+import { createClient, type ModerationResult } from '@vettly/supabase'
+
+const vettly = createClient({ apiKey: Deno.env.get('VETTLY_API_KEY')! })
+
+Deno.serve(async (req: Request): Promise<Response> => {
+  const { content }: { content: string } = await req.json()
+
+  const result: ModerationResult = await vettly.check(content, {
+    policyId: 'community-safe'
+  })
+
+  return new Response(JSON.stringify(result), {
+    headers: { 'Content-Type': 'application/json' }
+  })
+})
 ```
 
-## License
+---
+
+## Links
 
-MIT
+- [vettly.dev](https://vettly.dev) - Sign up
+- [docs.vettly.dev](https://docs.vettly.dev) - Documentation
+- [Supabase Edge Functions](https://supabase.com/docs/guides/functions) - Supabase docs
+- [@vettly/sdk](https://www.npmjs.com/package/@vettly/sdk) - Core SDK

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@vettly/supabase",
-  "version": "0.1.0",
-  "description": "Vettly content moderation for Supabase Edge Functions",
+  "version": "0.1.2",
+  "description": "Vettly decision infrastructure for Supabase Edge Functions. Deno-compatible, fetch-based client.",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -21,25 +22,19 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts src/edge.ts --format esm,cjs --dts --clean",
-    "test": "bun test",
-    "prepublishOnly": "bun run build"
-  },
   "keywords": [
+    "vettly",
     "supabase",
     "edge-functions",
     "deno",
-    "content-moderation",
-    "moderation",
-    "vettly",
-    "trust-safety"
+    "decision-infrastructure",
+    "policy-governance"
   ],
   "author": "Vettly",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brian-nextaura/vettly-docs.git",
+    "url": "https://github.com/nextauralabs/vettly-docs.git",
     "directory": "packages/supabase"
   },
   "homepage": "https://vettly.dev",
@@ -47,11 +42,6 @@
     "access": "public"
   },
   "bugs": {
-    "url": "https://github.com/brian-nextaura/vettly-docs/issues"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "tsup": "^8.0.0",
-    "typescript": "^5"
+    "url": "https://github.com/nextauralabs/vettly-docs/issues"
   }
 }