feat: Typed Frontend SDK (@numen/sdk) — React, Vue 3, Svelte, TypeScript

app/Models/Performance/ContentPerformanceEvent.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Models\Performance;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class ContentPerformanceEvent extends Model
+{
+    use HasFactory;
+    use HasUlids;
+
+    protected $fillable = [
+        'space_id',
+        'content_id',
+        'event_type',
+        'source',
+        'value',
+        'metadata',
+        'session_id',
+        'visitor_id',
+        'occurred_at',
+    ];
+
+    protected function casts(): array
+    {
+        return [
+            'value' => 'float',
+            'metadata' => 'array',
+            'occurred_at' => 'datetime',
+        ];
+    }
+}

app/Services/Migration/Connectors/CmsConnectorInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Migration\Connectors;
+
+interface CmsConnectorInterface
+{
+    /**
+     * Retrieve content types from the external CMS.
+     *
+     * @return array<array-key, mixed>
+     */
+    public function getContentTypes(): array;
+}

app/Services/Migration/SchemaInspectorService.php

@@ -1,7 +1,11 @@
 <?php
+
 declare(strict_types=1);
+
 namespace App\Services\Migration;
+
 use App\Services\Migration\Connectors\CmsConnectorInterface;
+
 /** Normalises CMS schema into a standard format. */
 class SchemaInspectorService
 {
@@ -39,11 +43,12 @@ public function inspectSchema(CmsConnectorInterface $connector): array
         if (empty($raw)) {
             return [];
         }
+
         return $this->normalise($raw);
     }
 
     /**
-     * @param  array<string, mixed>  $raw
+     * @param  array<array-key, mixed>  $raw
      * @return array<int, array{key: string, label: string, fields: array<int, array{name: string, type: string, required: bool}>}>
      */
     public function normalise(array $raw): array
@@ -66,6 +71,7 @@ public function normalise(array $raw): array
         if ($this->looksLikeWordPressTypes($raw)) {
             return $this->normaliseWordPress($raw);
         }
+
         return [];
     }
 
@@ -74,7 +80,7 @@ private function normaliseStrapi(array $items): array
     {
         $result = [];
         foreach ($items as $item) {
-            if (!is_array($item)) {
+            if (! is_array($item)) {
                 continue;
             }
             $key = $item['apiID'] ?? (isset($item['uid']) ? (string) $item['uid'] : null);
@@ -89,6 +95,7 @@ private function normaliseStrapi(array $items): array
                 'fields' => $this->normaliseFields($schema['attributes'] ?? [], 'strapi'),
             ];
         }
+
         return $result;
     }
 
@@ -97,7 +104,7 @@ private function normaliseWordPress(array $raw): array
     {
         $result = [];
         foreach ($raw as $slug => $type) {
-            if (!is_array($type)) {
+            if (! is_array($type)) {
                 continue;
             }
             $result[] = [
@@ -106,6 +113,7 @@ private function normaliseWordPress(array $raw): array
                 'fields' => $this->wordPressDefaultFields((string) $slug),
             ];
         }
+
         return $result;
     }
 
@@ -114,7 +122,7 @@ private function normaliseContentful(array $items): array
     {
         $result = [];
         foreach ($items as $ct) {
-            if (!is_array($ct)) {
+            if (! is_array($ct)) {
                 continue;
             }
             $key = $ct['sys']['id'] ?? null;
@@ -127,6 +135,7 @@ private function normaliseContentful(array $items): array
                 'fields' => $this->normaliseFields($ct['fields'] ?? [], 'contentful'),
             ];
         }
+
         return $result;
     }
 
@@ -135,7 +144,7 @@ private function normaliseDirectus(array $collections): array
     {
         $result = [];
         foreach ($collections as $col) {
-            if (!is_array($col)) {
+            if (! is_array($col)) {
                 continue;
             }
             $key = $col['collection'] ?? null;
@@ -148,6 +157,7 @@ private function normaliseDirectus(array $collections): array
                 'fields' => $this->normaliseFields($col['fields'] ?? [], 'directus'),
             ];
         }
+
         return $result;
     }
 
@@ -156,7 +166,7 @@ private function normalisePayload(array $collections): array
     {
         $result = [];
         foreach ($collections as $col) {
-            if (!is_array($col)) {
+            if (! is_array($col)) {
                 continue;
             }
             $key = $col['slug'] ?? null;
@@ -169,6 +179,7 @@ private function normalisePayload(array $collections): array
                 'fields' => $this->normaliseFields($col['fields'] ?? [], 'payload'),
             ];
         }
+
         return $result;
     }
 
@@ -186,6 +197,7 @@ private function normaliseGhost(array $raw): array
                 ];
             }
         }
+
         return $result;
     }
 
@@ -197,13 +209,13 @@ public function normaliseFields(array $rawFields, string $cms = 'generic'): arra
     {
         $fields = [];
         foreach ($rawFields as $nameOrIndex => $fieldDef) {
-            if (!is_array($fieldDef)) {
+            if (! is_array($fieldDef)) {
                 continue;
             }
             $name = match ($cms) {
                 'contentful' => $fieldDef['apiName'] ?? $fieldDef['id'] ?? (is_string($nameOrIndex) ? $nameOrIndex : null),
-                'directus'   => $fieldDef['field'] ?? (is_string($nameOrIndex) ? $nameOrIndex : null),
-                default      => $fieldDef['name'] ?? (is_string($nameOrIndex) ? $nameOrIndex : null),
+                'directus' => $fieldDef['field'] ?? (is_string($nameOrIndex) ? $nameOrIndex : null),
+                default => $fieldDef['name'] ?? (is_string($nameOrIndex) ? $nameOrIndex : null),
             };
             if ($name === null) {
                 continue;
@@ -216,6 +228,7 @@ public function normaliseFields(array $rawFields, string $cms = 'generic'): arra
                 'required' => $required,
             ];
         }
+
         return $fields;
     }
 
@@ -243,6 +256,7 @@ private function wordPressDefaultFields(string $typeSlug): array
             $base[] = ['name' => 'categories', 'type' => 'relation', 'required' => false];
             $base[] = ['name' => 'tags', 'type' => 'relation', 'required' => false];
         }
+
         return $base;
     }
 
@@ -268,6 +282,7 @@ private function ghostDefaultFields(string $typeSlug): array
     private function looksLikeWordPressTypes(array $raw): bool
     {
         $first = reset($raw);
+
         return is_array($first) && (isset($first['slug']) || isset($first['name']));
     }
 

database/migrations/2026_03_17_000001_create_content_performance_events_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        if (! Schema::hasTable('content_performance_events')) {
+            Schema::create('content_performance_events', function (Blueprint $table) {
+                $table->ulid('id')->primary();
+                $table->string('space_id', 26)->index();
+                $table->string('content_id', 26)->index();
+                $table->string('event_type', 50)->index();
+                $table->string('source', 50);
+                $table->decimal('value', 16, 4)->nullable();
+                $table->json('metadata')->nullable();
+                $table->string('session_id')->index();
+                $table->string('visitor_id')->nullable()->index();
+                $table->timestamp('occurred_at')->index();
+                $table->timestamps();
+
+                $table->index(['session_id', 'content_id', 'event_type', 'occurred_at'], 'cpe_dedup_idx');
+            });
+        }
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('content_performance_events');
+    }
+};

phpunit.xml

@@ -21,7 +21,6 @@
     <php>
         <ini name="memory_limit" value="512M"/>
         <env name="APP_ENV" value="testing"/>
-        <env name="APP_BASE_PATH" value="/tmp/quality-worktree"/>
         <env name="DB_CONNECTION" value="sqlite"/>
         <env name="DB_DATABASE" value=":memory:"/>
         <env name="QUEUE_CONNECTION" value="array"/>

routes/api.php

@@ -3,23 +3,33 @@
 use App\Http\Controllers\Api\AuditLogController;
 use App\Http\Controllers\Api\BriefController;
 use App\Http\Controllers\Api\ChatController;
+use App\Http\Controllers\Api\CompetitorController;
+use App\Http\Controllers\Api\CompetitorSourceController;
 use App\Http\Controllers\Api\ComponentDefinitionController;
 use App\Http\Controllers\Api\ContentController;
+use App\Http\Controllers\Api\ContentQualityController;
 use App\Http\Controllers\Api\ContentTaxonomyController;
+use App\Http\Controllers\Api\DifferentiationController;
 use App\Http\Controllers\Api\FormatTemplateController;
+use App\Http\Controllers\Api\GraphController;
 use App\Http\Controllers\Api\LocaleController;
 use App\Http\Controllers\Api\MediaCollectionController;
 use App\Http\Controllers\Api\MediaController;
 use App\Http\Controllers\Api\MediaEditController;
 use App\Http\Controllers\Api\MediaFolderController;
 use App\Http\Controllers\Api\PageController;
+use App\Http\Controllers\Api\PerformanceTrackingController;
 use App\Http\Controllers\Api\PermissionController;
 use App\Http\Controllers\Api\PluginAdminController;
 use App\Http\Controllers\Api\PublicMediaController;
 use App\Http\Controllers\Api\RepurposingController;
 use App\Http\Controllers\Api\RoleController;
 use App\Http\Controllers\Api\TaxonomyController;
 use App\Http\Controllers\Api\TaxonomyTermController;
+use App\Http\Controllers\Api\Templates\PipelineTemplateController;
+use App\Http\Controllers\Api\Templates\PipelineTemplateInstallController;
+use App\Http\Controllers\Api\Templates\PipelineTemplateRatingController;
+use App\Http\Controllers\Api\Templates\PipelineTemplateVersionController;
 use App\Http\Controllers\Api\TranslationController;
 use App\Http\Controllers\Api\UserRoleController;
 use App\Http\Controllers\Api\V1\Admin\SearchAdminController;
@@ -322,7 +332,6 @@
 });
 
 // Knowledge Graph API
-use App\Http\Controllers\Api\GraphController;
 
 Route::prefix('v1/graph')->middleware(['auth:sanctum'])->group(function () {
     Route::get('/related/{contentId}', [GraphController::class, 'related']);
@@ -360,15 +369,6 @@
 });
 
 // --- #36 Pipeline Templates API ---
-use App\Http\Controllers\Api\CompetitorController;
-use App\Http\Controllers\Api\CompetitorSourceController;
-use App\Http\Controllers\Api\ContentQualityController;
-use App\Http\Controllers\Api\DifferentiationController;
-use App\Http\Controllers\Api\Templates\PipelineTemplateController;
-use App\Http\Controllers\Api\Templates\PipelineTemplateInstallController;
-use App\Http\Controllers\Api\Templates\PipelineTemplateRatingController;
-use App\Http\Controllers\Api\Templates\PipelineTemplateVersionController;
-
 
 Route::prefix('v1/spaces/{space}/pipeline-templates')->middleware(['auth:sanctum'])->group(function () {
     Route::get('/', [PipelineTemplateController::class, 'index'])->name('api.pipeline-templates.index');
@@ -419,3 +419,6 @@
     Route::get('/differentiation/summary', [DifferentiationController::class, 'summary']);
     Route::get('/differentiation/{id}', [DifferentiationController::class, 'show']);
 });
+
+// --- Performance Tracking (public, rate limited) ---
+Route::post('v1/track', [PerformanceTrackingController::class, 'track'])->middleware('throttle:120,1');

sdk/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.vite/

sdk/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@numen/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-03-17
+
+### Added
+
+- **Core Client** (`NumenClient`) — typed HTTP client with auth middleware and SWR caching
+- **16 Resource Modules**
+  - `ContentResource` — CRUD for content items with status filtering
+  - `PagesResource` — page management with reordering and tree queries
+  - `MediaResource` — asset management with upload support
+  - `SearchResource` — full-text search, suggestions, and AI-powered ask
+  - `VersionsResource` — content version history and diff
+  - `TaxonomiesResource` — taxonomy and term management
+  - `BriefsResource` — content brief generation and management
+  - `PipelineResource` — AI pipeline run management
+  - `WebhooksResource` — webhook endpoint CRUD and delivery logs
+  - `GraphResource` — knowledge graph queries
+  - `ChatResource` — conversational AI interface
+  - `AdminResource` — admin operations (settings, users, roles)
+  - `CompetitorResource` — competitor analysis
+  - `QualityResource` — content quality scoring
+  - `RepurposeResource` — content repurposing workflows
+  - `TranslationsResource` — translation management
+- **React Bindings** (`@numen/sdk/react`)
+  - `NumenProvider` context provider
+  - Hooks: `useContent`, `useContentList`, `useSearch`, `useMedia`, `usePipeline`, `useRealtime`, `usePage`, `usePageList`
+  - Built on `useNumenQuery` with SWR caching
+- **Vue 3 Bindings** (`@numen/sdk/vue`)
+  - `NumenPlugin` for `app.use()` installation
+  - Composables: `useContent`, `useContentList`, `useSearch`, `useMedia`, `usePipeline`, `useRealtime`, `usePage`, `usePageList`
+  - Reactive refs with automatic cleanup
+- **Svelte Bindings** (`@numen/sdk/svelte`)
+  - `setNumenClient` / `getNumenClient` context
+  - Store factories: `createContentStore`, `createContentListStore`, `createSearchStore`, `createMediaStore`, `createPipelineStore`, `createPageStore`, `createPageListStore`, `createRealtimeStore`
+- **Realtime**
+  - `RealtimeClient` — SSE connection with auto-reconnect and exponential backoff
+  - `PollingClient` — HTTP polling fallback
+  - `RealtimeManager` — unified interface with pattern-based channel subscriptions
+- **Error Handling** — typed error classes: `NumenError`, `NumenRateLimitError`, `NumenValidationError`, `NumenAuthError`, `NumenNotFoundError`, `NumenNetworkError`
+- **SWR Cache** — stale-while-revalidate caching with TTL and listeners
+- **Auth Middleware** — pluggable authentication (API key, Bearer token)
+- **TypeScript** — full type coverage with exported types for all resources
+- **355 Tests** — comprehensive test suite covering core, resources, framework bindings, and realtime
+
+[0.1.0]: https://github.com/byte5digital/numen/releases/tag/sdk-v0.1.0