@vettly/react 0.1.14 → 0.1.16

package/README.md

@@ -1,6 +1,16 @@
 # @vettly/react
 
-React components for content decisions. Real-time feedback as users type.
+React components with real-time policy feedback and decision tracking. Same policies as your backend, instant user feedback.
+
+## Why Client-Side Moderation?
+
+**Immediate feedback** - Users see policy violations as they type, not after submission.
+
+**Same policies** - The React SDK uses your Vettly policies, ensuring consistent enforcement between client preview and server validation.
+
+**Decision tracking** - Every client-side check returns a `decisionId` for your audit trail, just like server-side calls.
+
+**Always validate server-side** - Client-side moderation improves UX but is not a security boundary. Always validate on the server before persisting content.
 
 ## Installation
 
@@ -15,76 +25,561 @@ import { ModeratedTextarea } from '@vettly/react'
 import '@vettly/react/styles.css'
 
 function CommentForm() {
+  const handleSubmit = async (content: string, decisionId: string) => {
+    // Submit to your API with the decision ID for audit trail
+    await api.createComment({
+      content,
+      moderationDecisionId: decisionId
+    })
+  }
+
   return (
     <ModeratedTextarea
       apiKey={process.env.NEXT_PUBLIC_VETTLY_API_KEY}
-      policy="community-safe"
+      policyId="community-safe"
       placeholder="Write a comment..."
       onModerationResult={(result) => {
-        if (result.action === 'block') {
-          // Content blocked
-        }
+        console.log(`Decision: ${result.action} (${result.decisionId})`)
       }}
     />
   )
 }
 ```
 
+---
+
 ## Components
 
 ### ModeratedTextarea
 
+A textarea with real-time content moderation and visual feedback.
+
 ```tsx
 <ModeratedTextarea
-  apiKey="sk_live_..."
-  policy="community-safe"
+  // Required
+  apiKey="pk_live_..."
+  policyId="community-safe"
+
+  // Content
+  value={content}
+  onChange={(value, result) => {
+    setContent(value)
+    console.log(`Action: ${result.action}`)
+  }}
   placeholder="Type something..."
-  debounceMs={500}
-  onModerationResult={(result) => console.log(result)}
+
+  // Behavior
+  debounceMs={500}        // Delay before checking (default: 500ms)
+  blockUnsafe={false}     // Prevent typing when content is unsafe
+  useFast={true}          // Use fast endpoint (<100ms responses)
+  disabled={false}
+
+  // Feedback
+  showFeedback={true}     // Show built-in feedback UI
+  customFeedback={(result) => (
+    <MyCustomFeedback
+      action={result.action}
+      isChecking={result.isChecking}
+      error={result.error}
+    />
+  )}
+
+  // Callbacks
+  onModerationResult={(result) => {
+    // Full CheckResponse with decisionId
+    console.log(result.decisionId)
+  }}
+  onModerationError={(error) => {
+    console.error('Moderation failed:', error)
+  }}
+
+  // Standard textarea props
+  className="my-textarea"
+  rows={4}
+  maxLength={1000}
 />
 ```
 
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | required | Your Vettly API key |
+| `policyId` | `string` | required | Policy ID to apply |
+| `value` | `string` | `''` | Controlled value |
+| `onChange` | `(value, result) => void` | - | Called on value change with current moderation state |
+| `debounceMs` | `number` | `500` | Milliseconds to wait before checking |
+| `showFeedback` | `boolean` | `true` | Show built-in feedback component |
+| `blockUnsafe` | `boolean` | `false` | Prevent additional input when content is unsafe |
+| `useFast` | `boolean` | `false` | Use fast endpoint for sub-100ms responses |
+| `customFeedback` | `(result) => ReactNode` | - | Custom feedback component |
+| `onModerationResult` | `(result) => void` | - | Called with full moderation response |
+| `onModerationError` | `(error) => void` | - | Called on moderation errors |
+
+---
+
 ### ModeratedImageUpload
 
+Image upload component with pre-upload moderation.
+
 ```tsx
 <ModeratedImageUpload
-  apiKey="sk_live_..."
-  policy="strict"
+  // Required
+  apiKey="pk_live_..."
+  policyId="strict"
+
+  // Callbacks
   onUpload={(file, result) => {
     if (result.action !== 'block') {
       uploadToServer(file)
     }
+    console.log(`Decision: ${result.action}`)
+  }}
+  onReject={(file, reason) => {
+    console.log(`Rejected: ${reason}`)
+  }}
+
+  // Constraints
+  maxSizeMB={10}
+  acceptedFormats={['image/jpeg', 'image/png', 'image/gif', 'image/webp']}
+
+  // Behavior
+  showPreview={true}
+  blockUnsafe={true}      // Prevent upload if content violates policy
+  disabled={false}
+
+  // Custom preview
+  customPreview={({ file, preview, result, onRemove }) => (
+    <div>
+      <img src={preview} alt={file.name} />
+      <p>{result.action}</p>
+      <button onClick={onRemove}>Remove</button>
+    </div>
+  )}
+
+  // Callbacks
+  onModerationResult={(result) => {
+    console.log(`Image decision: ${result.decisionId}`)
+  }}
+  onModerationError={(error) => {
+    console.error('Image moderation failed:', error)
+  }}
+
+  className="my-upload"
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | required | Your Vettly API key |
+| `policyId` | `string` | required | Policy ID to apply |
+| `onUpload` | `(file, result) => void` | - | Called when image passes moderation and user confirms |
+| `onReject` | `(file, reason) => void` | - | Called when image is rejected (validation or policy) |
+| `maxSizeMB` | `number` | `10` | Maximum file size in MB |
+| `acceptedFormats` | `string[]` | `['image/jpeg', 'image/png', 'image/gif', 'image/webp']` | Accepted MIME types |
+| `showPreview` | `boolean` | `true` | Show image preview after selection |
+| `blockUnsafe` | `boolean` | `true` | Prevent upload if content violates policy |
+| `customPreview` | `(props) => ReactNode` | - | Custom preview component |
+| `onModerationResult` | `(result) => void` | - | Called with full moderation response |
+| `onModerationError` | `(error) => void` | - | Called on moderation errors |
+
+---
+
+### ModeratedVideoUpload
+
+Video upload with frame extraction and moderation.
+
+```tsx
+<ModeratedVideoUpload
+  // Required
+  apiKey="pk_live_..."
+  policyId="video-policy"
+
+  // Callbacks
+  onUpload={(file, result) => {
+    uploadVideoToServer(file)
+    console.log(`Video approved: ${result.action}`)
+  }}
+  onReject={(file, reason) => {
+    console.log(`Video rejected: ${reason}`)
+  }}
+
+  // Constraints
+  maxSizeMB={100}
+  maxDurationSeconds={300}  // 5 minutes
+  acceptedFormats={['video/mp4', 'video/webm', 'video/quicktime']}
+
+  // Frame extraction
+  extractFramesCount={3}    // Number of frames to extract for analysis
+
+  // Behavior
+  showPreview={true}
+  blockUnsafe={true}
+  disabled={false}
+
+  // Custom preview
+  customPreview={({ file, preview, duration, result, onRemove }) => (
+    <div>
+      <video src={preview} controls />
+      <p>Duration: {duration}s</p>
+      <p>Status: {result.action}</p>
+      <button onClick={onRemove}>Remove</button>
+    </div>
+  )}
+
+  // Callbacks
+  onModerationResult={(result) => {
+    console.log(`Video decision: ${result.decisionId}`)
+  }}
+  onModerationError={(error) => {
+    console.error('Video moderation failed:', error)
   }}
+
+  className="my-video-upload"
 />
 ```
 
-### useModeration Hook
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | required | Your Vettly API key |
+| `policyId` | `string` | required | Policy ID to apply |
+| `onUpload` | `(file, result) => void` | - | Called when video passes moderation |
+| `onReject` | `(file, reason) => void` | - | Called when video is rejected |
+| `maxSizeMB` | `number` | `100` | Maximum file size in MB |
+| `maxDurationSeconds` | `number` | `300` | Maximum video duration in seconds |
+| `acceptedFormats` | `string[]` | `['video/mp4', 'video/webm', 'video/quicktime']` | Accepted MIME types |
+| `extractFramesCount` | `number` | `3` | Number of frames to extract for moderation |
+| `showPreview` | `boolean` | `true` | Show video preview with thumbnail |
+| `blockUnsafe` | `boolean` | `true` | Prevent upload if content violates policy |
+| `customPreview` | `(props) => ReactNode` | - | Custom preview component |
+| `onModerationResult` | `(result) => void` | - | Called with full moderation response |
+| `onModerationError` | `(error) => void` | - | Called on moderation errors |
+
+#### Features
+
+- **Drag and drop** - Drop videos directly onto the upload area
+- **Thumbnail generation** - Automatically generates video thumbnail
+- **Progress tracking** - Shows frame extraction and analysis progress
+- **Duration validation** - Rejects videos exceeding maximum duration
+
+---
+
+## useModeration Hook
+
+For custom components, use the `useModeration` hook directly:
 
 ```tsx
 import { useModeration } from '@vettly/react'
 
-function CustomInput() {
-  const { check, result, isLoading } = useModeration({
-    apiKey: 'sk_live_...',
-    policy: 'community-safe'
+function CustomModerationUI() {
+  const { result, check } = useModeration({
+    apiKey: 'pk_live_...',
+    policyId: 'community-safe',
+    debounceMs: 500,
+    enabled: true,
+    useFast: false,
+    onCheck: (response) => {
+      console.log(`Decision: ${response.decisionId}`)
+    },
+    onError: (error) => {
+      console.error('Check failed:', error)
+    }
   })
 
   return (
-    <input onChange={(e) => check(e.target.value)} />
+    <div>
+      <textarea
+        onChange={(e) => check(e.target.value)}
+        style={{
+          borderColor: result.action === 'block' ? 'red' :
+                       result.action === 'flag' ? 'yellow' :
+                       result.action === 'warn' ? 'orange' : 'green'
+        }}
+      />
+
+      {result.isChecking && <span>Checking...</span>}
+
+      {result.error && <span className="error">{result.error}</span>}
+
+      {!result.isChecking && !result.error && (
+        <div>
+          <strong>Action:</strong> {result.action}
+          <ul>
+            {result.categories
+              .filter(c => c.triggered)
+              .map(c => (
+                <li key={c.category}>
+                  {c.category}: {(c.score * 100).toFixed(0)}%
+                </li>
+              ))
+            }
+          </ul>
+        </div>
+      )}
+    </div>
   )
 }
 ```
 
-## Pricing
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | required | Your Vettly API key |
+| `policyId` | `string` | required | Policy ID to apply |
+| `debounceMs` | `number` | `500` | Milliseconds to debounce checks |
+| `enabled` | `boolean` | `true` | Enable/disable moderation |
+| `useFast` | `boolean` | `false` | Use fast endpoint for sub-100ms responses |
+| `onCheck` | `(response) => void` | - | Called with full `CheckResponse` |
+| `onError` | `(error) => void` | - | Called on errors |
+
+### Return Value
+
+```typescript
+interface UseModerationReturn {
+  result: {
+    safe: boolean           // True if content passes policy
+    flagged: boolean        // True if content is flagged for review
+    action: 'allow' | 'warn' | 'flag' | 'block'
+    categories: Array<{
+      category: string
+      score: number         // 0-1 confidence score
+      triggered: boolean    // True if threshold exceeded
+    }>
+    isChecking: boolean     // True while check is in progress
+    error: string | null    // Error message if check failed
+  }
+  check: (content: string | CheckRequest) => Promise<void>
+}
+```
+
+### Advanced Usage: Full Request Object
+
+```tsx
+const { check } = useModeration({ apiKey, policyId })
+
+// Check with full request object
+check({
+  content: imageBase64,
+  contentType: 'image',
+  policyId: 'strict-images',
+  metadata: {
+    userId: 'user_123',
+    context: 'profile_photo'
+  }
+})
+```
+
+---
+
+## Styling & Customization
+
+### Default Styles
+
+Import the default stylesheet:
+
+```tsx
+import '@vettly/react/styles.css'
+```
+
+### CSS Classes
+
+All components use semantic CSS classes for easy customization:
+
+```css
+/* Textarea wrapper */
+.moderated-textarea-wrapper { }
+.moderated-textarea { }
+
+/* Feedback states */
+.moderation-feedback { }
+.feedback-checking { }
+.feedback-safe { }
+.feedback-warn { }
+.feedback-flag { }
+.feedback-block { }
+.feedback-error { }
+
+/* Image upload */
+.moderated-image-upload { }
+.upload-area { }
+.upload-icon { }
+.upload-text { }
+.upload-hint { }
+.upload-error { }
+.image-preview { }
+.preview-container { }
+.preview-image { }
+.preview-overlay { }
+.preview-info { }
+.moderation-status { }
+.status-allow { }
+.status-warn { }
+.status-flag { }
+.status-block { }
+.preview-actions { }
+.btn-remove { }
+.btn-confirm { }
+
+/* Video upload */
+.moderated-video-upload { }
+.drag-over { }
+.thumbnail-container { }
+.video-thumbnail { }
+.play-overlay { }
+.play-button { }
+.duration-badge { }
+.processing-overlay { }
+.progress-bar { }
+.progress-fill { }
+```
+
+### Border Colors by Action
+
+The default styles use border colors to indicate moderation status:
+
+| Action | Border Color |
+|--------|--------------|
+| Checking | Blue (`border-blue-300`) |
+| Allow | Green (`border-green-400`) |
+| Warn | Orange (`border-orange-400`) |
+| Flag | Yellow (`border-yellow-400`) |
+| Block | Red (`border-red-400`) |
+| Error | Red (`border-red-400`) |
+
+### Custom Feedback Component
+
+```tsx
+<ModeratedTextarea
+  apiKey={apiKey}
+  policyId={policyId}
+  showFeedback={false}  // Disable default feedback
+  customFeedback={(result) => (
+    <div className="my-feedback">
+      {result.isChecking ? (
+        <Spinner />
+      ) : result.error ? (
+        <ErrorBanner message={result.error} />
+      ) : result.action === 'block' ? (
+        <BlockedMessage categories={result.categories} />
+      ) : (
+        <SafeIndicator />
+      )}
+    </div>
+  )}
+/>
+```
+
+---
+
+## Accessibility
+
+All components follow accessibility best practices:
+
+### Keyboard Navigation
+
+- **Tab** - Navigate between components
+- **Enter/Space** - Activate upload buttons
+- **Escape** - Cancel previews (when implemented)
+
+### ARIA Attributes
+
+- Upload areas have `role="button"` and proper focus handling
+- Error messages use appropriate ARIA live regions
+- Progress indicators announce status changes
+
+### Screen Reader Support
+
+- Feedback messages are announced as they change
+- Upload areas have descriptive labels
+- Error states provide clear explanations
+
+---
+
+## Server-Side Validation
+
+Client-side moderation is for **user experience only**. Always validate on the server:
+
+```tsx
+// Client-side (React)
+function CommentForm() {
+  const [content, setContent] = useState('')
+  const [clientResult, setClientResult] = useState(null)
+
+  return (
+    <form onSubmit={async (e) => {
+      e.preventDefault()
+
+      // Server validates again - don't trust client-side result
+      const response = await fetch('/api/comments', {
+        method: 'POST',
+        body: JSON.stringify({
+          content,
+          clientDecisionId: clientResult?.decisionId  // Optional: for correlation
+        })
+      })
+
+      if (response.ok) {
+        // Success
+      } else if (response.status === 403) {
+        // Server blocked content
+        const error = await response.json()
+        showError(error.message)
+      }
+    }}>
+      <ModeratedTextarea
+        apiKey={process.env.NEXT_PUBLIC_VETTLY_API_KEY}
+        policyId="community-safe"
+        value={content}
+        onChange={setContent}
+        onModerationResult={setClientResult}
+      />
+      <button type="submit">Post</button>
+    </form>
+  )
+}
+
+// Server-side (API route)
+import { createClient } from '@vettly/sdk'
+
+const vettly = createClient(process.env.VETTLY_API_KEY)
+
+export async function POST(req) {
+  const { content, clientDecisionId } = await req.json()
+
+  // Always validate server-side
+  const result = await vettly.check({
+    content,
+    policyId: 'community-safe',
+    metadata: { clientDecisionId }  // Optional: for correlation
+  })
+
+  if (result.action === 'block') {
+    return Response.json(
+      { error: 'Content blocked', decisionId: result.decisionId },
+      { status: 403 }
+    )
+  }
+
+  // Store with decision ID for audit trail
+  await db.comments.create({
+    content,
+    moderationDecisionId: result.decisionId,
+    action: result.action
+  })
+
+  return Response.json({ success: true })
+}
+```
 
-| Plan | Price | Text | Images | Videos |
-|------|-------|------|--------|--------|
-| Developer | Free | 2,000/mo | 100/mo | 25/mo |
-| Growth | $49/mo | 50,000/mo | 5,000/mo | 1,000/mo |
-| Pro | $149/mo | 250,000/mo | 25,000/mo | 5,000/mo |
-| Enterprise | Custom | Unlimited | Unlimited | Unlimited |
+---
 
 ## Links
 
 - [vettly.dev](https://vettly.dev) - Sign up
 - [docs.vettly.dev](https://docs.vettly.dev) - Documentation
+- [@vettly/sdk](https://www.npmjs.com/package/@vettly/sdk) - Server-side SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vettly/react",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "React components for Vettly decision infrastructure. Content decisions with real-time feedback.",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/brian-nextaura/vettly-docs.git",
+    "url": "https://github.com/nextauralabs/vettly-docs.git",
     "directory": "packages/react"
   },
   "homepage": "https://vettly.dev",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "bugs": {
-    "url": "https://github.com/brian-nextaura/vettly-docs/issues"
+    "url": "https://github.com/nextauralabs/vettly-docs/issues"
   },
   "peerDependencies": {
     "react": "^18.0.0",