spine-framework 0.3.16 → 0.3.18

package/docs/dev-guides/01-create-an-app.md

@@ -0,0 +1,183 @@
+# Guide 01: Create a Custom App
+
+## What this guide covers
+
+How to scaffold, configure, and run a new custom app on Spine.
+
+---
+
+## Step 1: Scaffold with the CLI
+
+```bash
+npm run spine-framework create-app my-app -- --name "My App" --role member
+```
+
+This creates:
+```
+custom/apps/my-app/
+  manifest.json      ← app metadata, routes, nav, roles
+  index.tsx          ← React entry point
+  components/        ← your components go here
+```
+
+And inserts a row into the `apps` table in the database.
+
+**Options:**
+```bash
+--name "My App"   # Display name (defaults to title-cased slug)
+--role member     # Required role: member | support | system_admin (default: member)
+--force           # Overwrite if directory already exists
+```
+
+---
+
+## Step 2: Configure manifest.json
+
+`custom/apps/my-app/manifest.json` controls everything about the app.
+
+```json
+{
+  "name": "My App",
+  "slug": "my-app",
+  "description": "What this app does",
+  "version": "1.0.0",
+  "required_roles": ["member"],
+  "routes": [
+    "/my-app",
+    "/my-app/dashboard",
+    "/my-app/settings"
+  ],
+  "nav_items": [
+    {
+      "title": "Dashboard",
+      "path": "/my-app/dashboard",
+      "icon": "LayoutDashboard",
+      "order": 1
+    },
+    {
+      "title": "Settings",
+      "path": "/my-app/settings",
+      "icon": "Settings",
+      "order": 2
+    }
+  ],
+  "features": [],
+  "entry_point": "./index.tsx"
+}
+```
+
+**Key fields:**
+- `required_roles` — array of roles that can access this app. Any match grants access.
+- `routes` — informational; actual routing is handled by `index.tsx`
+- `nav_items` — used by generic app shells; custom apps render their own sidebar
+
+---
+
+## Step 3: Build index.tsx
+
+`index.tsx` is the React entry point. Core mounts it at `/{slug}/*`.
+
+```tsx
+import * as React from 'react'
+import { Routes, Route, Navigate } from 'react-router-dom'
+import { AppShell } from '@core/components/layout/AppShell'
+import { useAuth } from '@core/contexts/AuthContext'
+import MyAppSidebar from './components/MyAppSidebar'
+
+function Dashboard() {
+  const { user } = useAuth()
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold">Dashboard</h1>
+      <p className="text-slate-500">Welcome, {user?.full_name}</p>
+    </div>
+  )
+}
+
+export default function MyApp() {
+  return (
+    <AppShell sidebar={<MyAppSidebar />}>
+      <Routes>
+        <Route index element={<Navigate to="dashboard" replace />} />
+        <Route path="dashboard" element={<Dashboard />} />
+      </Routes>
+    </AppShell>
+  )
+}
+```
+
+**Rules for index.tsx:**
+- Always `export default` the root component
+- Use `@core/...` imports for anything from core — never relative paths to `.framework/`
+- Routes are relative — `/my-app/dashboard` is just `path="dashboard"` here
+
+---
+
+## Step 4: Assemble and run
+
+```bash
+npm run assemble
+netlify dev
+```
+
+Navigate to `http://localhost:8888/my-app`.
+
+---
+
+## Step 5: Verify
+
+```bash
+# App files exist
+ls custom/apps/my-app/
+
+# App is in the database
+# Check: GET /api/apps?action=list should include your slug
+```
+
+---
+
+## File structure reference
+
+```
+custom/apps/my-app/
+  manifest.json              ← required
+  index.tsx                  ← required: default export = root component
+  components/
+    MyAppSidebar.tsx         ← optional: custom sidebar
+    MyFeatureCard.tsx        ← optional: any component
+  pages/
+    DashboardPage.tsx        ← optional: split pages out for readability
+```
+
+---
+
+## Core imports available in custom apps
+
+```tsx
+// Auth
+import { useAuth } from '@core/contexts/AuthContext'
+
+// Layout
+import { AppShell } from '@core/components/layout/AppShell'
+
+// UI primitives
+import { Button } from '@core/components/ui/button'
+import { LoadingSpinner } from '@core/components/ui/LoadingSpinner'
+import { Sidebar, SidebarMenu, SidebarMenuItem } from '@core/components/ui/sidebar'
+
+// Data fetching
+import { apiFetch } from '@core/lib/api'
+
+// Router (re-exported from react-router-dom)
+import { Routes, Route, Navigate, useNavigate, useParams } from 'react-router-dom'
+```
+
+> **Rule:** Always use `@core/...` for core imports. Never use relative paths like `../../../../.framework/src/...`.
+> `@core` resolves to `.assembled/src` in both dev and build.
+
+---
+
+## Next steps
+
+- [02-create-a-function.md](./02-create-a-function.md) — Add a backend API to your app
+- [03-create-a-component.md](./03-create-a-component.md) — Build reusable components

package/docs/dev-guides/02-create-a-function.md

@@ -0,0 +1,178 @@
+# Guide 02: Create a Custom Function
+
+## What this guide covers
+
+How to write a custom Netlify function that uses core authentication, database access, and middleware.
+
+---
+
+## Naming convention
+
+Custom functions live in `custom/functions/` and must be prefixed `custom_`:
+
+```
+custom/functions/custom_my-feature.ts
+```
+
+After assembly, this becomes `.netlify/functions/custom_my-feature` and is callable at:
+```
+GET /api/custom_my-feature?action=list
+```
+
+---
+
+## Step 1: Create the function file
+
+```typescript
+// custom/functions/custom_my-feature.ts
+import { createHandler } from '@core/_shared'
+
+export const handler = createHandler(async (event, ctx) => {
+  const action = ctx.query?.action || 'list'
+
+  switch (action) {
+    case 'list': {
+      const { data, error } = await ctx.db
+        .from('items')
+        .select('*')
+        .eq('type_slug', 'my_type')
+
+      if (error) throw error
+      return { data }
+    }
+
+    case 'get': {
+      const id = ctx.query?.id
+      if (!id) throw new Error('id is required')
+
+      const { data, error } = await ctx.db
+        .from('items')
+        .select('*')
+        .eq('id', id)
+        .single()
+
+      if (error) throw error
+      return { data }
+    }
+
+    default:
+      throw new Error(`Unknown action: ${action}`)
+  }
+})
+```
+
+---
+
+## What createHandler gives you
+
+`createHandler` wraps your function with:
+- **Authentication** — rejects unauthenticated requests with 401
+- **Authorization** — `ctx.principal` has the user's roles and permissions
+- **Database** — `ctx.db` is a Supabase client scoped to the user's account via RLS
+- **Logging** — `ctx.logger` for structured logs
+- **Error handling** — uncaught errors become 500 responses with safe messages
+
+```typescript
+interface CoreContext {
+  db: SupabaseClient        // RLS-scoped to authenticated user's account
+  principal: Principal      // { id, account_id, roles, permissions }
+  query: Record<string, string>  // parsed query string
+  body: any                 // parsed request body
+  logger: Logger            // structured logging
+}
+```
+
+---
+
+## Accessing the authenticated user
+
+```typescript
+export const handler = createHandler(async (event, ctx) => {
+  const { principal } = ctx
+
+  console.log(principal.id)          // user UUID
+  console.log(principal.account_id)  // tenant account UUID
+  console.log(principal.roles)       // e.g. ['member', 'support']
+
+  // Check role
+  if (!principal.roles.includes('support')) {
+    throw new Error('Support role required')
+  }
+
+  return { data: 'ok' }
+})
+```
+
+---
+
+## Admin database access
+
+`ctx.db` is RLS-scoped (safe for user-facing data). For admin operations use `adminDb`:
+
+```typescript
+import { createHandler, adminDb } from '@core/_shared'
+
+export const handler = createHandler(async (event, ctx) => {
+  // adminDb bypasses RLS — use with care
+  const { data } = await adminDb
+    .from('accounts')
+    .select('*')
+
+  return { data }
+})
+```
+
+---
+
+## Calling your function from the frontend
+
+```typescript
+import { apiFetch } from '@core/lib/api'
+
+// apiFetch handles auth headers and the /api → /.netlify/functions proxy
+const response = await apiFetch('/api/custom_my-feature?action=list')
+const { data } = await response.json()
+```
+
+---
+
+## Step 2: Assemble and test
+
+```bash
+npm run assemble:functions
+# Functions reload automatically in netlify dev
+
+# Test directly
+curl http://localhost:8888/api/custom_my-feature?action=list \
+  -H "Authorization: Bearer <your-jwt>"
+```
+
+---
+
+## POST requests
+
+```typescript
+export const handler = createHandler(async (event, ctx) => {
+  if (event.httpMethod === 'POST') {
+    const payload = ctx.body  // already parsed JSON
+
+    const { data, error } = await ctx.db
+      .from('items')
+      .insert({ ...payload, account_id: ctx.principal.account_id })
+      .select()
+      .single()
+
+    if (error) throw error
+    return { data }
+  }
+
+  throw new Error('Method not allowed')
+})
+```
+
+---
+
+## Next steps
+
+- [03-create-a-component.md](./03-create-a-component.md) — Build UI components for your app
+- [04-webhook-handlers.md](./04-webhook-handlers.md) — React to system events

package/docs/dev-guides/03-create-a-component.md

@@ -0,0 +1,178 @@
+# Guide 03: Create a Custom Component
+
+## What this guide covers
+
+How to build React components inside a custom app, using core hooks, UI primitives, and layout components.
+
+---
+
+## Where components live
+
+```
+custom/apps/my-app/
+  components/
+    MyAppSidebar.tsx     ← navigation sidebar
+    MyFeatureCard.tsx    ← any reusable UI piece
+    MyDataTable.tsx      ← data display
+```
+
+Components are local to your app. They are never imported by core.
+
+---
+
+## Import rules
+
+```tsx
+// ✅ Correct — use @core alias for anything from core
+import { useAuth } from '@core/contexts/AuthContext'
+import { Button } from '@core/components/ui/button'
+import { AppShell } from '@core/components/layout/AppShell'
+
+// ✅ Correct — relative imports within your own app
+import MyFeatureCard from './MyFeatureCard'
+import MyFeatureCard from '../components/MyFeatureCard'
+
+// ❌ Wrong — never use relative paths to .framework
+import { useAuth } from '../../../../.framework/src/contexts/AuthContext'
+```
+
+---
+
+## Building a sidebar
+
+Sidebars use the core `Sidebar` primitives from shadcn/ui.
+
+```tsx
+// custom/apps/my-app/components/MyAppSidebar.tsx
+import * as React from 'react'
+import { useNavigate, useLocation } from 'react-router-dom'
+import { useAuth } from '@core/contexts/AuthContext'
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+} from '@core/components/ui/sidebar'
+import { LayoutDashboard, Settings } from 'lucide-react'
+
+const navItems = [
+  { title: 'Dashboard', url: '/my-app/dashboard', icon: LayoutDashboard },
+  { title: 'Settings', url: '/my-app/settings', icon: Settings },
+]
+
+export function MyAppSidebar() {
+  const navigate = useNavigate()
+  const location = useLocation()
+
+  return (
+    <Sidebar>
+      <SidebarHeader>
+        <span className="font-semibold px-2">My App</span>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {navItems.map(item => (
+                <SidebarMenuItem key={item.url}>
+                  <SidebarMenuButton
+                    isActive={location.pathname.startsWith(item.url)}
+                    onClick={() => navigate(item.url)}
+                  >
+                    <item.icon className="w-4 h-4" />
+                    <span>{item.title}</span>
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarRail />
+    </Sidebar>
+  )
+}
+```
+
+---
+
+## Fetching data in a component
+
+```tsx
+import * as React from 'react'
+import { apiFetch } from '@core/lib/api'
+import { LoadingSpinner } from '@core/components/ui/LoadingSpinner'
+
+interface Item {
+  id: string
+  title: string
+}
+
+export function ItemList() {
+  const [items, setItems] = React.useState<Item[]>([])
+  const [loading, setLoading] = React.useState(true)
+
+  React.useEffect(() => {
+    apiFetch('/api/custom_my-feature?action=list')
+      .then(r => r.json())
+      .then(({ data }) => setItems(data || []))
+      .finally(() => setLoading(false))
+  }, [])
+
+  if (loading) return <LoadingSpinner />
+
+  return (
+    <ul className="space-y-2">
+      {items.map(item => (
+        <li key={item.id} className="p-3 border rounded">
+          {item.title}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+---
+
+## Available core UI components
+
+All from `@core/components/ui/...` (shadcn/ui):
+
+| Import | Component |
+|--------|-----------|
+| `@core/components/ui/button` | `Button` |
+| `@core/components/ui/badge` | `Badge` |
+| `@core/components/ui/card` | `Card`, `CardHeader`, `CardContent` |
+| `@core/components/ui/dialog` | `Dialog`, `DialogContent`, `DialogHeader` |
+| `@core/components/ui/input` | `Input` |
+| `@core/components/ui/label` | `Label` |
+| `@core/components/ui/select` | `Select`, `SelectContent`, `SelectItem` |
+| `@core/components/ui/sidebar` | `Sidebar`, `SidebarMenu`, `SidebarMenuItem`, etc. |
+| `@core/components/ui/tabs` | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
+| `@core/components/ui/tooltip` | `Tooltip`, `TooltipProvider` |
+| `@core/components/ui/LoadingSpinner` | `LoadingSpinner` |
+
+---
+
+## Available core hooks
+
+| Import | Hook | Purpose |
+|--------|------|---------|
+| `@core/contexts/AuthContext` | `useAuth()` | Current user, login/logout |
+| `@core/contexts/AppContext` | `useCurrentApp()` | Current app record |
+| `@core/lib/api` | `apiFetch()` | Auth-aware fetch wrapper |
+
+---
+
+## Next steps
+
+- [04-webhook-handlers.md](./04-webhook-handlers.md) — React to system events
+- [05-testing.md](./05-testing.md) — Test your components and functions

package/docs/dev-guides/04-webhook-handlers.md

@@ -0,0 +1,129 @@
+# Guide 04: Webhook Handlers
+
+## What this guide covers
+
+How to register a custom webhook handler that reacts to integration events without modifying core.
+
+---
+
+## How it works
+
+Core's `integration-routes.ts` resolves webhook handlers dynamically from the `webhook_handlers` database table at runtime. Custom handlers self-register into that table — core never imports them directly.
+
+```
+Integration event arrives
+  → core looks up handler name in webhook_handlers table
+  → calls the registered Netlify function
+  → your custom function runs
+```
+
+---
+
+## Step 1: Create the handler function
+
+```typescript
+// custom/functions/custom_my-handler.ts
+import { createHandler, registerWebhookHandler } from '@core/_shared'
+
+// Self-register on cold start
+registerWebhookHandler({
+  name: 'my-handler',
+  functionName: 'custom_my-handler',
+  description: 'Handles item.created events from my integration',
+  events: ['item.created', 'item.updated'],
+})
+
+export const handler = createHandler(async (event, ctx) => {
+  const payload = ctx.body
+
+  // payload.event   — event name e.g. 'item.created'
+  // payload.data    — the item/record that triggered the event
+  // ctx.principal   — the system or user that triggered it
+  // ctx.db          — RLS-scoped database client
+
+  console.log('Received event:', payload.event)
+
+  // Do your work
+  const { error } = await ctx.db
+    .from('items')
+    .insert({
+      type_slug: 'my_log',
+      data: { source_event: payload.event, source_id: payload.data?.id },
+      account_id: ctx.principal.account_id,
+    })
+
+  if (error) throw error
+
+  return { received: true }
+})
+```
+
+---
+
+## registerWebhookHandler options
+
+```typescript
+registerWebhookHandler({
+  name: string           // Unique handler name — used to look up this handler
+  functionName: string   // Netlify function name (must match the file prefix)
+  description?: string   // Human-readable description
+  events?: string[]      // Event names this handler responds to (informational)
+})
+```
+
+Registration is idempotent — calling it multiple times (e.g. on every cold start) is safe. It upserts by `name`.
+
+---
+
+## Step 2: Register the handler in the database
+
+The `registerWebhookHandler` call runs on cold start and writes to `webhook_handlers`. You can also seed it manually:
+
+```sql
+INSERT INTO webhook_handlers (name, function_name, description, events, is_active)
+VALUES (
+  'my-handler',
+  'custom_my-handler',
+  'Handles item.created events',
+  '["item.created", "item.updated"]',
+  true
+)
+ON CONFLICT (name) DO UPDATE
+  SET function_name = EXCLUDED.function_name,
+      is_active = EXCLUDED.is_active;
+```
+
+---
+
+## Step 3: Route events to your handler
+
+Integration routes look up the handler by name. To route an incoming webhook to your handler, the integration config should reference `"my-handler"` as the handler name. This is typically set in the `integrations` table or the integration's config payload.
+
+---
+
+## Step 4: Assemble and test
+
+```bash
+npm run assemble:functions
+
+# Trigger manually (replace with your webhook payload)
+curl -X POST http://localhost:8888/api/integration-routes \
+  -H "Content-Type: application/json" \
+  -d '{"handler": "my-handler", "event": "item.created", "data": {"id": "123"}}'
+```
+
+---
+
+## Verify registration
+
+```sql
+SELECT name, function_name, events, is_active
+FROM webhook_handlers
+WHERE name = 'my-handler';
+```
+
+---
+
+## Next steps
+
+- [05-testing.md](./05-testing.md) — Test your handler with the core test harness