spine-framework 0.3.17 → 0.3.18

package/.framework/config/signal-client.ts

@@ -1,147 +0,0 @@
-/**
- * @module config/signal-client
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * Universal funnel signal client — browser, Node.js, and Deno compatible.
- * Sends signals to the public `/api/signal` endpoint (no auth required).
- *
- * Usage (marketing site):
- * ```ts
- * import { SpineSignal } from 'spine-framework/config/signal-client'
- * SpineSignal.init({ endpoint: 'https://cortex.yourcompany.com' })
- * SpineSignal.send({ stage: 'anonymous', source: 'mar', action_type: 'page_view', action_value: 1, session_id: sid })
- * ```
- *
- * Usage (pixel — email tracking):
- * ```html
- * <img src="https://cortex.yourcompany.com/api/signal?format=pixel&stage=identified&source=mar&action_type=email_open&action_value=1&person_id=UUID" width="1" height="1" />
- * ```
- *
- * Usage (CLI / Node.js):
- * ```ts
- * import { SpineSignal } from 'spine-framework/config/signal-client'
- * await SpineSignal.send({ stage: 'installed', source: 'use', action_type: 'framework_init', action_value: 2, instance_id: serial })
- * ```
- */
-
-export interface SignalPayload {
-  stage: 'anonymous' | 'identified' | 'installed'
-  source: 'mar' | 'int' | 'use' | 'manual'
-  action_type: string
-  action_value: 1 | 2 | 5
-  pipeline_slug?: string
-  anonymous_id?: string
-  person_id?: string
-  account_id?: string
-  session_id?: string
-  action_description?: string
-  occurred_at?: string
-  url?: string
-  path?: string
-  referrer?: string
-  user_agent?: string
-  utm_source?: string
-  utm_medium?: string
-  utm_campaign?: string
-  instance_id?: string
-  environment?: 'dev' | 'staging' | 'production'
-}
-
-export interface SignalClientConfig {
-  endpoint: string
-  timeout?: number
-}
-
-export interface SignalResult {
-  ok: boolean
-  signal_id?: string
-  rating?: number
-  error?: string
-}
-
-let _config: SignalClientConfig = {
-  endpoint: 'https://cortex.spine-framework.com',
-  timeout: 5000,
-}
-
-/**
- * Initialize the signal client with a custom endpoint.
- * Call once at app startup before any `send()` calls.
- */
-function init(config: SignalClientConfig): void {
-  _config = { ..._config, ...config }
-}
-
-/**
- * Send a funnel signal. Fire-and-forget safe — never throws.
- * Returns a result object indicating success or failure.
- */
-async function send(payload: SignalPayload): Promise<SignalResult> {
-  try {
-    const controller = new AbortController()
-    const timeout = setTimeout(() => controller.abort(), _config.timeout ?? 5000)
-
-    const response = await fetch(`${_config.endpoint}/api/signal`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
-      signal: controller.signal,
-    }).finally(() => clearTimeout(timeout))
-
-    if (!response.ok) {
-      const body = await response.json().catch(() => ({}))
-      return { ok: false, error: body?.error || `HTTP ${response.status}` }
-    }
-
-    const data = await response.json()
-    return {
-      ok: true,
-      signal_id: data?.data?.signal_id,
-      rating: data?.data?.rating,
-    }
-  } catch {
-    return { ok: false, error: 'Signal send failed (network or timeout)' }
-  }
-}
-
-/**
- * Build a tracking pixel URL for email templates.
- * Embed as: `<img src={SpineSignal.pixelUrl({...})} width="1" height="1" />`
- */
-function pixelUrl(payload: Omit<SignalPayload, 'session_id'>): string {
-  const params = new URLSearchParams({ format: 'pixel' })
-  for (const [key, value] of Object.entries(payload)) {
-    if (value !== undefined && value !== null) {
-      params.set(key, String(value))
-    }
-  }
-  return `${_config.endpoint}/api/signal?${params.toString()}`
-}
-
-/**
- * Minimal browser session ID — stable for the tab session.
- * Suitable for `session_id` on marketing source signals.
- * Returns a consistent ID stored in sessionStorage (browser only).
- */
-function getSessionId(): string {
-  if (typeof sessionStorage !== 'undefined') {
-    const key = '_spine_sid'
-    let sid = sessionStorage.getItem(key)
-    if (!sid) {
-      sid = `sess_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`
-      sessionStorage.setItem(key, sid)
-    }
-    return sid
-  }
-  // Node.js / non-browser: generate ephemeral ID
-  return `sess_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`
-}
-
-export const SpineSignal = {
-  init,
-  send,
-  pixelUrl,
-  getSessionId,
-}

package/.framework/config/signals.ts

@@ -1,70 +0,0 @@
-/// <reference types="node" />
-/**
- * @module config/signals
- * @audience installer
- * @layer cli
- * @stability stable
- *
- * Signal endpoint configuration for framework install tracking and engagement.
- *
- * The public framework sends anonymous signals to a configurable endpoint.
- * Private Cortex instances receive and process these signals.
- */
-
-export interface SignalConfig {
-  endpoint: string
-  timeout: number
-  retryAttempts: number
-  batchSize: number
-}
-
-export const signalConfig: SignalConfig = {
-  endpoint: process.env.SPINE_SIGNAL_ENDPOINT || 'https://cortex.spine-framework.com',
-  timeout: 5000,
-  retryAttempts: 3,
-  batchSize: 10,
-}
-
-// Engagement signal types with scores
-export const engagementSignals = {
-  framework_installed: { score: 1, description: 'Framework npm install completion' },
-  framework_initialized: { score: 3, description: 'First successful startup' },
-  framework_connected_db: { score: 5, description: 'Database connection success' },
-  app_install: { score: 4, description: 'App installation' },
-  app_initialized: { score: 4, description: 'App first load' },
-  app_first_action: { score: 6, description: 'First feature usage' },
-  account_created: { score: 8, description: 'Anonymous → identified migration' },
-  first_deploy: { score: 10, description: 'Production deployment' },
-  team_collaboration: { score: 12, description: 'Multi-user usage' },
-} as const
-
-export type EngagementSignalType = keyof typeof engagementSignals
-
-// Claim trigger thresholds
-export const claimTriggers = {
-  immediate: 0,        // User explicitly runs `spine-framework claim`
-  gentle_nudge: 3,     // After first successful startup
-  value_realized: 5,   // After database connection
-  ecosystem_engaged: 8, // After app installation
-  power_user: 10,      // After regular usage patterns
-} as const
-
-export interface EngagementEntry {
-  type: EngagementSignalType
-  timestamp: string
-  score: number
-}
-
-export interface EngagementData {
-  framework_install_serial: string
-  engagement_score: number
-  signals: EngagementEntry[]
-  claim_status: 'anonymous' | 'claimed' | 'pending'
-  last_claim_prompt?: string
-  account_id?: string
-}
-
-export interface ClaimPrompt {
-  timing: keyof typeof claimTriggers
-  message: string
-}

package/.framework/docs/STABILITY.md

@@ -1,52 +0,0 @@
-# Stability Policy
-
-> Version target: **0.x** — breaking changes are allowed until 1.0.
-
-## Stability Levels
-
-Every exported symbol in `_shared/index.ts` is annotated with one of these levels:
-
-| Level | Meaning | Breaking change policy |
-|-------|---------|----------------------|
-| **stable** | Safe for custom code to depend on | Minimum 1 minor version deprecation notice before removal |
-| **evolving** | API may change between minor versions | No deprecation period required, but changelog entry mandatory |
-| **internal** | Not exported; core-contributor only | May change without notice |
-
-## Versioning
-
-Spine follows [semver](https://semver.org/) with these conventions:
-
-- **0.x.y** — Pre-stable. Breaking changes increment the minor version.
-- **1.0.0+** — Stable. Breaking changes increment the major version.
-
-## Deprecation Process
-
-1. Mark the symbol with `@deprecated` JSDoc tag and a migration hint
-2. Add a console warning on first use (once per process)
-3. Remove after the next minor version bump
-
-## What Counts as Breaking
-
-- Removing or renaming an exported function/type from `_shared/index.ts`
-- Changing function signatures (required params added, return type changed)
-- Removing a CLI command or changing its required arguments
-- Changing database table/column names in migration files
-- Removing seed data keys from `seed/*.json` schemas
-
-## What Does NOT Count as Breaking
-
-- Adding new optional parameters to existing functions
-- Adding new exports to `_shared/index.ts`
-- Adding new CLI commands
-- Adding new database tables or columns
-- Performance improvements to existing functions
-- Bug fixes (even if they change observable behavior that was clearly wrong)
-
-## Release Checklist
-
-1. `npm run test:boundary` — architectural boundaries intact
-2. `npm run test:unit` — unit tests pass
-3. Update `CHANGELOG.md` with breaking changes highlighted
-4. Bump version in `package.json`
-5. `npm run prepublishOnly` — build + test gate
-6. `npm publish`

package/.framework/docs/examples/custom-app/README.md

@@ -1,77 +0,0 @@
-# Example: Custom App
-
-A minimal React app with manifest and routing, installable via `spine-framework install-app`.
-
-## Directory Structure
-
-```
-custom/apps/my-app/
-├── manifest.json       # App metadata, routes, nav items
-├── index.tsx           # React entry point (default export)
-├── seed/
-│   ├── types.json      # Item types this app provides
-│   └── triggers.json   # Automation triggers
-├── components/
-│   └── Dashboard.tsx   # App-specific components
-└── package.json        # npm package metadata (optional)
-```
-
-## manifest.json
-
-```json
-{
-  "name": "My App",
-  "slug": "my-app",
-  "version": "0.1.0",
-  "description": "A custom app for demonstration",
-  "routes": [
-    { "path": "/", "redirect": "/dashboard" },
-    { "path": "/dashboard", "component": "Dashboard" }
-  ],
-  "nav_items": [
-    { "label": "Dashboard", "path": "/dashboard", "icon": "LayoutDashboard" }
-  ],
-  "required_roles": ["member"]
-}
-```
-
-## index.tsx
-
-```tsx
-import * as React from 'react'
-import { Routes, Route, Navigate } from 'react-router-dom'
-
-function Dashboard() {
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold">My App</h1>
-    </div>
-  )
-}
-
-export default function MyApp() {
-  return (
-    <Routes>
-      <Route path="/" element={<Navigate to="dashboard" replace />} />
-      <Route path="dashboard" element={<Dashboard />} />
-    </Routes>
-  )
-}
-```
-
-## Installation
-
-```bash
-# Create the app scaffold
-spine-framework create-app my-app
-
-# Or install an existing app package
-spine-framework install-app my-app
-```
-
-## How It Works
-
-1. `CustomAppLoader` discovers apps via `import.meta.glob('custom/apps/*/index.tsx')`
-2. The app's `manifest.json` provides routing and navigation metadata
-3. Seed data is applied via `spine-framework install-app` (idempotent upserts)
-4. The app is isolated — it cannot import from other apps or core internals

package/.framework/docs/examples/custom-function/README.md

@@ -1,27 +0,0 @@
-# Example: Custom Function
-
-A minimal Netlify Function using Spine's core context system.
-
-## Setup
-
-1. Create `custom/functions/custom_my-handler.ts`
-2. Import `createHandler` and `CoreContext` from `spine-framework/_shared`
-3. Your handler receives a fully-resolved `CoreContext` with:
-   - `ctx.principal` — authenticated user/machine identity
-   - `ctx.db` — Supabase client (scoped to principal's permissions)
-   - `ctx.accountId` — resolved account UUID
-   - `ctx.requestId` — unique request trace ID
-
-## Key Points
-
-- **Naming convention:** Custom functions MUST be prefixed with `custom_`
-- **No static imports from core:** Use the `spine-framework` package exports
-- **Authentication is automatic:** `createHandler` validates the JWT/API key before your code runs
-- **Database access:** Use `ctx.db` for RLS-scoped queries, or import `adminDb` for service-role operations
-
-## API
-
-```
-GET/POST /.netlify/functions/custom_my-handler?action=list
-Authorization: Bearer <jwt>
-```

package/.framework/docs/examples/custom-function/handler.ts

@@ -1,48 +0,0 @@
-/**
- * Example: Custom Netlify Function using Spine core context
- *
- * This demonstrates the minimal pattern for creating a custom function
- * that leverages Spine's authentication, database, and principal system.
- *
- * File: custom/functions/custom_my-handler.ts
- */
-
-import { createHandler, adminDb } from 'spine-framework/_shared'
-import type { CoreContext } from 'spine-framework/_shared'
-
-/**
- * A simple handler that lists items for the current account.
- */
-async function listAccountItems(ctx: CoreContext) {
-  const { data, error } = await ctx.db
-    .from('items')
-    .select('id, title, type_id, created_at')
-    .eq('account_id', ctx.accountId)
-    .eq('is_active', true)
-    .order('created_at', { ascending: false })
-    .limit(50)
-
-  if (error) {
-    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
-  }
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify({ items: data }),
-  }
-}
-
-/**
- * Netlify Function entry point.
- * `createHandler` resolves the principal, validates auth, and provides CoreContext.
- */
-export const handler = createHandler(async (ctx) => {
-  const { action } = ctx.params
-
-  switch (action) {
-    case 'list':
-      return listAccountItems(ctx)
-    default:
-      return { statusCode: 400, body: JSON.stringify({ error: 'Unknown action' }) }
-  }
-})

package/.framework/docs/examples/custom-webhook/README.md

@@ -1,68 +0,0 @@
-# Example: Custom Webhook Handler
-
-Demonstrates the self-registration pattern for webhook handlers.
-
-## How It Works
-
-1. Create a handler function in `custom/functions/custom_my-webhook.ts`
-2. Register it by calling `registerWebhookHandler()` in `custom/functions/custom_webhook-handlers.ts`
-3. Core resolves handlers at runtime via the `webhook_handlers` DB table — no static imports needed
-
-## Handler Function
-
-```ts
-// custom/functions/custom_my-webhook.ts
-
-import { createHandler } from 'spine-framework/_shared'
-import type { CoreContext } from 'spine-framework/_shared'
-
-export const handler = createHandler(async (ctx: CoreContext) => {
-  const payload = ctx.body
-
-  // Process the webhook payload
-  console.log('Received webhook:', payload.event_type)
-
-  // Do something with the data
-  const { error } = await ctx.db
-    .from('items')
-    .insert({
-      title: `Webhook: ${payload.event_type}`,
-      type_id: await resolveTypeId('webhook_event'),
-      account_id: ctx.accountId,
-      data: payload,
-    })
-
-  if (error) {
-    return { statusCode: 500, body: JSON.stringify({ error: error.message }) }
-  }
-
-  return { statusCode: 200, body: JSON.stringify({ ok: true }) }
-})
-```
-
-## Registration
-
-```ts
-// In custom/functions/custom_webhook-handlers.ts
-
-import { registerWebhookHandler } from 'spine-framework/_shared/webhook-registration'
-
-registerWebhookHandler({
-  name: 'my-webhook',
-  functionName: 'custom_my-webhook',
-  description: 'Handles incoming webhooks from MyService',
-  events: ['integration.webhook'],
-}).catch(console.error)
-```
-
-## Integration Config
-
-When configuring an integration in the admin panel, set:
-- `handler.path` = `my-webhook` (matches the `name` in registration)
-
-## Key Points
-
-- **Self-registration is idempotent** — safe to call on every module load
-- **No core changes needed** — just add your handler and register it
-- **Runtime resolution** — core looks up handlers from `webhook_handlers` table via `resolveHandler()`
-- **Events array** — currently `['integration.webhook']` is the standard event type

package/.framework/functions/handler-registry.ts

@@ -1,22 +0,0 @@
-/**
- * @module handler-registry
- * @audience core-contributor
- * @layer shared-service
- * @stability stable
- *
- * Static handler registry for esbuild-compatible dynamic dispatch.
- *
- * **THIS FILE IS OVERWRITTEN AT ASSEMBLY TIME.**
- * The stub here (empty registry) is replaced by `assemble-functions.sh`
- * with static imports of every `custom_*.ts` handler found in the assembled
- * functions directory. esbuild can then bundle all handlers into the
- * `integration-routes` function at build time — no runtime dynamic imports.
- *
- * Keys are the handler path (e.g. "funnel-signal") AND the full file name
- * (e.g. "custom_funnel-signal") so lookups work either way.
- *
- * @seeAlso scripts/assemble-functions.sh (generates this file)
- * @seeAlso integration-routes.ts (consumes HANDLER_REGISTRY)
- */
-
-export const HANDLER_REGISTRY: Record<string, any> = {}

package/.framework/functions/signal.ts

@@ -1,168 +0,0 @@
-/**
- * @module signal
- * @audience both
- * @layer api-handler
- * @stability stable
- *
- * Public funnel signal ingestion endpoint. Accepts signals from any source
- * (browser JS, CLI, email pixel) without authentication. Rate limiting is
- * enforced at the Netlify edge layer via netlify.toml.
- *
- * **Routed by:** `POST /.netlify/functions/signal`
- *                `GET  /.netlify/functions/signal?format=pixel`
- *
- * **Request formats:**
- *   - `POST` with JSON body — standard signal (returns JSON response)
- *   - `GET ?format=pixel` — tracking pixel (returns 1×1 transparent GIF)
- *
- * **Required fields (POST body / GET query params):**
- *   - `stage`        — 'anonymous' | 'identified' | 'installed'
- *   - `source`       — 'mar' | 'int' | 'use' | 'manual'
- *   - `action_type`  — string (e.g. 'page_view', 'form_submit')
- *   - `action_value` — 1 | 2 | 5
- *   - at least one of: `anonymous_id`, `person_id`, `account_id`
- *   - `session_id`   — required when source = 'mar'
- *
- * **Optional fields:**
- *   - `pipeline_slug` — routes signal to a specific funnel pipeline
- *   - `path`, `referrer`, `url`, `utm_*`, `instance_id`, `environment`
- *
- * **Authorization:** None — intentionally public. Signals are best-effort and
- *   validated by `processSignal` in `custom_funnel-signal.ts`.
- *
- * **CORS:** Allows all origins for cross-origin browser calls.
- *
- * @seeAlso custom/apps/cortex/functions/custom_funnel-signal.ts (processSignal)
- * @seeAlso config/signal-client.ts (browser/Node client for senders)
- */
-
-// 1×1 transparent GIF (base64)
-const PIXEL_GIF_BASE64 = 'R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
-const PIXEL_GIF = Buffer.from(PIXEL_GIF_BASE64, 'base64')
-
-const CORS_HEADERS = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, X-Session-Id',
-  'Access-Control-Max-Age': '86400',
-}
-
-export const handler = async (event: any) => {
-  // Handle CORS preflight
-  if (event.httpMethod === 'OPTIONS') {
-    return { statusCode: 204, headers: CORS_HEADERS, body: '' }
-  }
-
-  const requestId = crypto.randomUUID()
-  const isPixel = event.queryStringParameters?.format === 'pixel'
-
-  try {
-    // Build signal payload from body (POST) or query params (GET pixel)
-    let signalData: any
-
-    if (event.httpMethod === 'GET' && isPixel) {
-      signalData = { ...event.queryStringParameters }
-      // action_value comes as string in query params — coerce to number
-      if (signalData.action_value) {
-        signalData.action_value = parseInt(signalData.action_value, 10)
-      }
-    } else if (event.httpMethod === 'POST') {
-      if (!event.body) {
-        return {
-          statusCode: 400,
-          headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ error: 'Missing request body' }),
-        }
-      }
-      try {
-        signalData = JSON.parse(event.body)
-      } catch {
-        return {
-          statusCode: 400,
-          headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ error: 'Invalid JSON body' }),
-        }
-      }
-    } else {
-      return {
-        statusCode: 405,
-        headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ error: 'Method not allowed' }),
-      }
-    }
-
-    // Resolve processSignal dynamically — core must not statically import custom handlers.
-    // After assembly, custom_funnel-signal is a sibling in the same functions directory.
-    let processSignal: Function
-    try {
-      // @ts-ignore — custom_funnel-signal is injected at runtime by the assembly step
-      const mod = await import('./custom_funnel-signal')
-      processSignal = mod.processSignal
-      if (typeof processSignal !== 'function') throw new Error('processSignal not exported')
-    } catch {
-      return {
-        statusCode: 503,
-        headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ error: 'Signal handler not available' }),
-      }
-    }
-
-    // Minimal script context for processSignal
-    const scriptContext = {
-      requestId,
-      accountId: null,
-      slug: 'public-signal',
-      principal: { id: 'system', type: 'machine', accountId: null },
-      headers: event.headers || {},
-    }
-
-    const scriptEvent = {
-      httpMethod: event.httpMethod,
-      headers: event.headers || {},
-      body: signalData,
-      path: event.path || '/signal',
-      queryStringParameters: event.queryStringParameters || {},
-    }
-
-    // Fire-and-forget for pixel requests; await for JSON
-    if (isPixel) {
-      processSignal(signalData, scriptContext, scriptEvent).catch(() => {
-        // Silent fail for pixel — response is always the GIF
-      })
-      return {
-        statusCode: 200,
-        headers: {
-          ...CORS_HEADERS,
-          'Content-Type': 'image/gif',
-          'Cache-Control': 'no-store, no-cache, must-revalidate',
-          'Pragma': 'no-cache',
-        },
-        body: PIXEL_GIF.toString('base64'),
-        isBase64Encoded: true,
-      }
-    }
-
-    const result = await processSignal(signalData, scriptContext, scriptEvent)
-
-    if (result.status === 'error') {
-      return {
-        statusCode: 400,
-        headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ error: result.error }),
-      }
-    }
-
-    return {
-      statusCode: 200,
-      headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ data: result }),
-    }
-
-  } catch (err: any) {
-    return {
-      statusCode: 500,
-      headers: { ...CORS_HEADERS, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ error: 'Internal error' }),
-    }
-  }
-}