@spooky-sync/core 0.0.1-canary.8 → 0.0.1-canary.81

package/skills/sp00ky-core/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: sp00ky-core
+description: >-
+  Core client for the Sp00ky reactive local-first SurrealDB framework. Use when
+  initializing Sp00kyClient, registering queries and subscriptions, performing
+  mutations (create/update/delete), handling auth (signUp/signIn/signOut),
+  working with file buckets, or using backend runs (HTTP outbox pattern).
+metadata:
+  author: sp00ky-sync
+  version: "0.0.1"
+---
+
+# Sp00ky Core
+
+`@spooky-sync/core` provides `Sp00kyClient`, the main entry point for the Sp00ky framework. It handles local-first data sync with SurrealDB, reactive queries, optimistic mutations, authentication, file storage, and backend runs.
+
+## Initialization
+
+```typescript
+import { Sp00kyClient } from '@spooky-sync/core';
+import { schema } from './generated/schema'; // Generated by `spooky generate`
+import schemaSurql from './generated/schema.surql?raw';
+
+const client = new Sp00kyClient({
+  database: {
+    endpoint: 'ws://localhost:8000',
+    namespace: 'my_ns',
+    database: 'my_db',
+    store: 'indexeddb', // or 'memory'
+  },
+  schema,
+  schemaSurql,
+  logLevel: 'info',
+});
+
+// IMPORTANT: You must call init() before using the client
+await client.init();
+
+// When done (e.g., app teardown):
+await client.close();
+```
+
+### Sp00kyConfig Options
+
+See [references/config.md](references/config.md) for all configuration options.
+
+Key fields:
+- `database.endpoint` — SurrealDB WebSocket URL
+- `database.namespace` / `database.database` — SurrealDB namespace and database
+- `database.store` — `'indexeddb'` (persistent) or `'memory'` (transient)
+- `schema` — The `SchemaStructure` object (use `as const satisfies SchemaStructure`)
+- `schemaSurql` — The compiled SURQL schema string for local DB provisioning
+- `logLevel` — `'debug' | 'info' | 'warn' | 'error'`
+- `persistenceClient` — `'surrealdb'` (default), `'localstorage'`, or a custom `PersistenceClient`
+- `streamDebounceTime` — Debounce ms for stream updates (default: 100)
+
+## Querying
+
+Queries are registered with the client and return a hash. You subscribe to the hash to receive reactive updates.
+
+```typescript
+// Register a query — returns a QueryBuilder
+const finalQuery = client.query('post', {})
+  .where({ author: 'user:alice' })
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .build();
+
+// Run it to get the hash
+const { hash } = await finalQuery.run();
+
+// Subscribe to reactive updates
+const unsubscribe = await client.subscribe(hash, (records) => {
+  console.log('Posts:', records);
+}, { immediate: true });
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+### Query TTL
+
+Queries have a time-to-live. Supported values: `'1m'`, `'5m'`, `'10m'` (default), `'15m'`, `'20m'`, `'25m'`, `'30m'`, `'1h'`–`'12h'`, `'1d'`.
+
+## Mutations
+
+Mutations are optimistic and automatically synced to the remote SurrealDB instance.
+
+```typescript
+// Create — pass a full "table:id" string and the record data
+await client.create('post:abc123', {
+  title: 'Hello World',
+  body: 'My first post',
+  author: 'user:alice',
+});
+
+// Update — pass table name, record ID, and partial data
+await client.update('post', 'post:abc123', { title: 'Updated Title' });
+
+// Update with debounce (useful for text fields)
+await client.update('post', 'post:abc123', { body: 'typing...' }, {
+  debounced: { key: 'recordId_x_fields', delay: 300 },
+});
+
+// Delete
+await client.delete('post', 'post:abc123');
+```
+
+### Debounced Updates
+
+Use `debounced` option for frequent updates (e.g., live typing):
+- `key: 'recordId'` — Debounce by record ID only (latest write wins, no merge)
+- `key: 'recordId_x_fields'` — Debounce by record ID + changed fields (recommended)
+
+## Authentication
+
+See [references/auth.md](references/auth.md) for the full auth API.
+
+```typescript
+// Sign up
+await client.auth.signUp('user_access', {
+  email: 'alice@example.com',
+  password: 'secret',
+  name: 'Alice',
+});
+
+// Sign in
+await client.auth.signIn('user_access', {
+  email: 'alice@example.com',
+  password: 'secret',
+});
+
+// Subscribe to auth state changes
+const unsub = client.auth.subscribe((userId) => {
+  console.log('Auth state:', userId); // string ID or null
+});
+
+// Sign out
+await client.auth.signOut();
+```
+
+Auth state properties: `client.auth.token`, `client.auth.currentUser`, `client.auth.isAuthenticated`, `client.auth.isLoading`.
+
+## Buckets (File Storage)
+
+```typescript
+const avatars = client.bucket('avatars');
+
+await avatars.put('alice/profile.png', fileBytes);
+const content = await avatars.get('alice/profile.png');
+const exists = await avatars.exists('alice/profile.png');
+await avatars.delete('alice/profile.png');
+await avatars.copy('alice/profile.png', 'alice/backup.png');
+await avatars.rename('old.png', 'new.png');
+const files = await avatars.list('alice/');
+```
+
+Buckets must be defined in the schema under the `buckets` array.
+
+## Backend Runs (HTTP Outbox)
+
+Backend runs let you trigger server-side HTTP operations via an **outbox pattern**. When you call `db.run()`, it creates a job record in a local outbox table. That record syncs to remote SurrealDB, where the Sp00ky Sync Platform (SSP) picks it up and calls your backend HTTP API. The result status is written back to the job record and syncs to the client reactively.
+
+### `db.run()` Signature
+
+```typescript
+db.run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+  backend: B,        // Backend name from sp00ky.yml (e.g., 'api')
+  route: R,          // Route path from OpenAPI spec (e.g., '/spookify')
+  payload: RoutePayload<S, B, R>,  // Typed args for the route
+  options?: RunOptions
+): Promise<void>
+```
+
+All parameters are type-safe — `backend`, `route`, and `payload` are inferred from the generated schema.
+
+### RunOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `assignedTo` | `string` | `undefined` | Record ID to link the job to an entity (e.g., `'thread:abc'`) |
+| `max_retries` | `number` | `3` | Maximum retry attempts on failure |
+| `retry_strategy` | `'linear' \| 'exponential'` | `'linear'` | Backoff strategy between retries |
+
+### Entity Linking via `assignedTo`
+
+The `assignedTo` option is how you link a job to an entity. Passing a record ID:
+
+- Sets the `assigned_to` field on the job record (typed as `record<thread>` etc. in the outbox schema)
+- Enables **permission scoping** — e.g., `WHERE assigned_to.author.id = $auth.id` restricts job visibility to the entity's owner
+- Allows **querying jobs via relationships** — use `.related('jobs')` on the parent entity to reactively track job status
+
+### Full Example
+
+**1. Configure the backend in `sp00ky.yml`:**
+
+```yaml
+backends:
+  api:
+    type: http
+    spec: ../api/openapi.yml
+    baseUrl: http://host.docker.internal:3660
+    auth:
+      type: token
+      token: MY_SECRET
+    method:
+      type: outbox
+      table: job
+      schema: ./src/outbox/api.surql
+```
+
+**2. Define the outbox table in SurrealQL** (`src/outbox/api.surql`):
+
+```sql
+DEFINE TABLE job SCHEMAFULL
+PERMISSIONS
+  FOR select, create, update, delete
+  WHERE $access = "account" AND assigned_to.author.id = $auth.id;
+
+DEFINE FIELD assigned_to ON TABLE job TYPE record<thread>;
+DEFINE FIELD path ON TABLE job TYPE string;
+DEFINE FIELD payload ON TABLE job TYPE any;
+DEFINE FIELD retries ON TABLE job TYPE int DEFAULT ALWAYS 0;
+DEFINE FIELD max_retries ON TABLE job TYPE int DEFAULT ALWAYS 3;
+DEFINE FIELD retry_strategy ON TABLE job TYPE string DEFAULT ALWAYS "linear"
+  ASSERT $value IN ["linear", "exponential"];
+DEFINE FIELD status ON TABLE job TYPE string DEFAULT ALWAYS "pending"
+  ASSERT $value IN ["pending", "processing", "success", "failed"];
+DEFINE FIELD errors ON TABLE job TYPE array<object> DEFAULT ALWAYS [];
+DEFINE FIELD created_at ON TABLE job TYPE datetime VALUE time::now();
+```
+
+**3. Run `spooky generate`** — this produces the typed `backends` block in `schema.gen.ts`.
+
+**4. Call `db.run()` with entity linking:**
+
+```typescript
+// Trigger the /spookify backend route, linked to a thread
+await client.run('api', '/spookify', { id: threadId }, {
+  assignedTo: threadId,  // Links job to the thread entity
+});
+```
+
+### How It Works Under the Hood
+
+When you call `db.run('api', '/spookify', payload, options)`:
+
+1. Validates the route exists in the schema and all required args are present
+2. Creates a record in the outbox table (`job`) with fields: `path`, `payload` (JSON-stringified), `max_retries`, `retry_strategy`, and optionally `assigned_to`
+3. The record is created via the standard `client.create()` path — optimistic, synced to remote
+4. SSP detects the new job, calls your backend HTTP API, and updates the job's `status` field (`pending` → `processing` → `success`/`failed`)
+
+## Common Pitfalls
+
+1. **Must call `init()` before using the client** — All operations will fail if you skip initialization.
+2. **Schema is generated** — Use `spooky generate` to produce the schema TypeScript file and SURQL file from your `.surql` definitions.
+3. **RecordId format** — SurrealDB uses `table:id` format. When creating records, pass the full ID (e.g., `'post:abc123'`). The framework auto-converts string IDs to `RecordId` objects internally.
+4. **Queries are hash-based** — The same query always produces the same hash, enabling deduplication and caching.

package/skills/sp00ky-core/references/auth.md

@@ -0,0 +1,98 @@
+# Authentication Reference
+
+## AuthService API
+
+The `AuthService` is available on `Sp00kyClient` as `client.auth`.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `string \| null` | Current auth token |
+| `currentUser` | `any \| null` | Current authenticated user record |
+| `isAuthenticated` | `boolean` | Whether a user is authenticated |
+| `isLoading` | `boolean` | Whether auth state is being validated |
+
+### Methods
+
+#### `signUp(accessName, params)`
+
+Create a new account using the named access definition from the schema.
+
+```typescript
+await client.auth.signUp('user_access', {
+  email: 'alice@example.com',
+  password: 'secret123',
+  name: 'Alice',
+});
+```
+
+The access definition in the schema determines what parameters are required:
+
+```typescript
+access: {
+  user_access: {
+    signup: {
+      params: {
+        email: { type: 'string', optional: false },
+        password: { type: 'string', optional: false },
+        name: { type: 'string', optional: true },
+      },
+    },
+    signIn: {
+      params: {
+        email: { type: 'string', optional: false },
+        password: { type: 'string', optional: false },
+      },
+    },
+  },
+}
+```
+
+Parameters are fully type-safe — TypeScript will infer the correct types from the schema.
+
+#### `signIn(accessName, params)`
+
+Authenticate with existing credentials.
+
+```typescript
+await client.auth.signIn('user_access', {
+  email: 'alice@example.com',
+  password: 'secret123',
+});
+```
+
+#### `signOut()`
+
+Sign out, clear the session token, and notify subscribers.
+
+```typescript
+await client.auth.signOut();
+```
+
+#### `subscribe(callback)`
+
+Subscribe to auth state changes. The callback fires immediately with the current state, then on every change.
+
+```typescript
+const unsub = client.auth.subscribe((userId: string | null) => {
+  if (userId) {
+    console.log('Logged in as', userId);
+  } else {
+    console.log('Not authenticated');
+  }
+});
+
+// Cleanup
+unsub();
+```
+
+#### `check(accessToken?)`
+
+Manually re-validate the current session. Called automatically during `init()`.
+
+```typescript
+await client.auth.check();
+// Or with a specific token:
+await client.auth.check('eyJhbGciOiJIUzI1NiJ9...');
+```

package/skills/sp00ky-core/references/config.md

@@ -0,0 +1,76 @@
+# Sp00kyConfig Reference
+
+```typescript
+interface Sp00kyConfig<S extends SchemaStructure> {
+  database: {
+    /** SurrealDB WebSocket endpoint URL */
+    endpoint?: string;
+    /** SurrealDB namespace */
+    namespace: string;
+    /** SurrealDB database name */
+    database: string;
+    /** Local store type: 'memory' (transient) or 'indexeddb' (persistent) */
+    store?: 'memory' | 'indexeddb';
+    /** Authentication token */
+    token?: string;
+  };
+  /** Unique client identifier. Auto-generated if not provided. */
+  clientId?: string;
+  /** The schema object (must use `as const satisfies SchemaStructure`) */
+  schema: S;
+  /** Compiled SURQL schema string for local DB provisioning */
+  schemaSurql: string;
+  /** Logging level */
+  logLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent' | 'trace';
+  /**
+   * Persistence client for local storage.
+   * - 'surrealdb': Uses the local SurrealDB instance (default)
+   * - 'localstorage': Uses browser localStorage
+   * - Custom: Provide an object implementing PersistenceClient
+   */
+  persistenceClient?: PersistenceClient | 'surrealdb' | 'localstorage';
+  /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel) */
+  otelTransmit?: PinoTransmit;
+  /** Debounce time in ms for stream updates (default: 100) */
+  streamDebounceTime?: number;
+}
+```
+
+## PersistenceClient Interface
+
+```typescript
+interface PersistenceClient {
+  set<T>(key: string, value: T): Promise<void>;
+  get<T>(key: string): Promise<T | null>;
+  remove(key: string): Promise<void>;
+}
+```
+
+## QueryTimeToLive Values
+
+Supported TTL values for `client.query()`:
+
+`'1m'`, `'5m'`, `'10m'`, `'15m'`, `'20m'`, `'25m'`, `'30m'`, `'1h'`, `'2h'`, `'3h'`, `'4h'`, `'5h'`, `'6h'`, `'7h'`, `'8h'`, `'9h'`, `'10h'`, `'11h'`, `'12h'`, `'1d'`
+
+## RunOptions
+
+```typescript
+interface RunOptions {
+  assignedTo?: string;
+  max_retries?: number;
+  retry_strategy?: 'linear' | 'exponential';
+}
+```
+
+## UpdateOptions
+
+```typescript
+interface UpdateOptions {
+  debounced?: boolean | {
+    /** 'recordId': latest write wins. 'recordId_x_fields': merge by field (recommended). */
+    key?: 'recordId' | 'recordId_x_fields';
+    /** Debounce delay in ms */
+    delay?: number;
+  };
+}
+```

package/src/build-globals.d.ts

@@ -0,0 +1,12 @@
+// Build-time string constants injected by tsdown's `define` (see
+// tsdown.config.ts). They carry the real bundled frontend package versions so
+// the DevTools can surface frontend/backend version drift.
+//
+// Typed as `string | undefined` on purpose: the substitution only happens when
+// `@spooky-sync/core` is built with our tsdown plugin. A downstream app that
+// bundles core from source never runs that plugin, so these identifiers must be
+// guarded with `typeof` (see modules/devtools/index.ts) to avoid a runtime
+// ReferenceError that would break DB initialization.
+declare const __SP00KY_CORE_VERSION__: string | undefined;
+declare const __SP00KY_WASM_VERSION__: string | undefined;
+declare const __SP00KY_SURREAL_VERSION__: string | undefined;

package/src/events/events.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { EventSystem, EventDefinition } from './index';
+import type { EventDefinition } from './index';
+import { EventSystem } from './index';
 
 // Define test event types
 type TestEvents = {

package/src/events/index.ts

@@ -172,6 +172,9 @@ export class EventSystem<E extends EventTypeMap> {
    * @param payload The data associated with the event.
    */
   emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void {
+    // `{ type, payload }` structurally matches `Event<E, T>` (= the indexed
+    // access `E[T]`), but TS can't verify assignability to an indexed-access
+    // type over the generic `E`/`T`, so the constructed event is asserted.
     const event = {
       type,
       payload,

package/src/index.ts

@@ -1,4 +1,11 @@
 export * from './types';
-export * from './spooky';
+export * from './sp00ky';
 export * from './modules/auth/index';
-export { fileToUint8Array } from './utils/index';
+export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export {
+  FeatureFlagModule,
+  FeatureFlagHandle,
+  type FeatureFlagOptions,
+  type FeatureFlagSnapshot,
+} from './modules/feature-flag/index';
+export { fileToUint8Array, textToHtml } from './utils/index';

package/src/modules/auth/events/index.ts

@@ -1,4 +1,5 @@
-import { createEventSystem, EventDefinition, EventSystem } from '../../../events/index';
+import type { EventDefinition, EventSystem } from '../../../events/index';
+import { createEventSystem } from '../../../events/index';
 
 export const AuthEventTypes = {
   AuthStateChanged: 'AUTH_STATE_CHANGED',

package/src/modules/auth/index.ts

@@ -1,17 +1,14 @@
-import { RemoteDatabaseService } from '../../services/database/remote';
-import { LocalDatabaseService } from '../../services/database/local';
-import { DataModule } from '../data/index';
-import {
+import type { RemoteDatabaseService } from '../../services/database/remote';
+import type {
   SchemaStructure,
   AccessDefinition,
   ColumnSchema,
   TypeNameToTypeMap,
 } from '@spooky-sync/query-builder';
-import { Logger } from '../../services/logger/index';
-import { encodeRecordId } from '../../utils/index';
+import type { Logger } from '../../services/logger/index';
 export * from './events/index';
 import { AuthEventTypes, createAuthEventSystem } from './events/index';
-import { PersistenceClient } from '../../types';
+import type { PersistenceClient } from '../../types';
 
 // Helper to pretty print types
 type Prettify<T> = {
@@ -38,11 +35,41 @@ type ExtractAccessParams<
       }>
     : never;
 
+/**
+ * Read the `AC` (access-method name) claim from a SurrealDB record-access
+ * JWT without verifying it — we only need the claim, the server enforces the
+ * token. Returns null on any malformed input. The in-browser SSP needs this
+ * to resolve `$access` in table permission predicates (mirrors the session's
+ * `$access` that the server's `fn::query::register` reads).
+ */
+function decodeAccessFromToken(token: string): string | null {
+  try {
+    const payload = token.split('.')[1];
+    if (!payload) return null;
+    let b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    b64 += '='.repeat((4 - (b64.length % 4)) % 4);
+    const json =
+      typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('binary');
+    const claims = JSON.parse(json) as Record<string, unknown>;
+    const ac = claims.AC ?? claims.ac;
+    return typeof ac === 'string' ? ac : null;
+  } catch {
+    return null;
+  }
+}
+
 export class AuthService<S extends SchemaStructure> {
   // State
   public token: string | null = null;
   public currentUser: any | null = null;
   public isAuthenticated: boolean = false;
+  /**
+   * The record-access method name for the current session (e.g. `"account"`),
+   * derived from the token's `AC` claim. Consumed by the in-browser SSP's
+   * permission injection so `$access`-gated table predicates resolve locally,
+   * mirroring the server's `$access`. Null when logged out.
+   */
+  public access: string | null = null;
   public isLoading: boolean = true;
 
   private events = createAuthEventSystem();
@@ -95,11 +122,11 @@ export class AuthService<S extends SchemaStructure> {
     this.isLoading = true;
 
     try {
-      const token = accessToken || (await this.persistenceClient.get<string>('spooky_auth_token'));
+      const token = accessToken || (await this.persistenceClient.get<string>('sp00ky_auth_token'));
 
       if (!token) {
         this.logger.debug(
-          { Category: 'spooky-client::AuthService::check' },
+          { Category: 'sp00ky-client::AuthService::check' },
           'No token found in storage or arguments'
         );
         this.isLoading = false;
@@ -119,13 +146,13 @@ export class AuthService<S extends SchemaStructure> {
 
       if (user && user.id) {
         this.logger.info(
-          { user, Category: 'spooky-client::AuthService::check' },
+          { user, Category: 'sp00ky-client::AuthService::check' },
           'Auth check complete (via $auth.id)'
         );
         await this.setSession(token, user);
       } else {
         this.logger.warn(
-          { Category: 'spooky-client::AuthService::check' },
+          { Category: 'sp00ky-client::AuthService::check' },
           '$auth.id empty, attempting manual user fetch'
         );
 
@@ -140,13 +167,13 @@ export class AuthService<S extends SchemaStructure> {
 
         if (manualUser && manualUser.id) {
           this.logger.info(
-            { user: manualUser, Category: 'spooky-client::AuthService::check' },
+            { user: manualUser, Category: 'sp00ky-client::AuthService::check' },
             'Auth check complete (via manual fetch)'
           );
           await this.setSession(token, manualUser);
         } else {
           this.logger.warn(
-            { Category: 'spooky-client::AuthService::check' },
+            { Category: 'sp00ky-client::AuthService::check' },
             'Token valid but user not found via fallback'
           );
           await this.signOut();
@@ -154,7 +181,7 @@ export class AuthService<S extends SchemaStructure> {
       }
     } catch (error) {
       this.logger.error(
-        { error, stack: (error as Error).stack, Category: 'spooky-client::AuthService::check' },
+        { error, stack: (error as Error).stack, Category: 'sp00ky-client::AuthService::check' },
         'Auth check failed'
       );
       await this.signOut();
@@ -170,12 +197,13 @@ export class AuthService<S extends SchemaStructure> {
     this.token = null;
     this.currentUser = null;
     this.isAuthenticated = false;
+    this.access = null;
 
-    await this.persistenceClient.remove('spooky_auth_token');
+    await this.persistenceClient.remove('sp00ky_auth_token');
 
     try {
       await this.remote.getClient().invalidate();
-    } catch (e) {
+    } catch (_e) {
       // Ignore invalidation errors
     }
 
@@ -186,10 +214,21 @@ export class AuthService<S extends SchemaStructure> {
     this.token = token;
     this.currentUser = user;
     this.isAuthenticated = true;
-    await this.persistenceClient.set('spooky_auth_token', token);
+    // Resolve the access-method name (e.g. "account") for in-browser SSP
+    // permission injection. Prefer the token's `AC` claim; fall back to the
+    // schema's sole record-access method if the claim is absent.
+    this.access = decodeAccessFromToken(token) ?? this.defaultAccessName();
+    await this.persistenceClient.set('sp00ky_auth_token', token);
     this.notifyListeners();
   }
 
+  /** Fallback when the token carries no `AC` claim: if the schema defines
+   *  exactly one record-access method, assume the session used it. */
+  private defaultAccessName(): string | null {
+    const names = Object.keys(this.schema.access ?? {});
+    return names.length === 1 ? names[0] : null;
+  }
+
   async signUp<Name extends keyof S['access'] & string>(
     accessName: Name,
     params: ExtractAccessParams<S, Name, 'signup'>
@@ -212,7 +251,7 @@ export class AuthService<S extends SchemaStructure> {
     }
 
     this.logger.info(
-      { accessName, runtimeParams, Category: 'spooky-client::AuthService::signUp' },
+      { accessName, runtimeParams, Category: 'sp00ky-client::AuthService::signUp' },
       'Attempting signup'
     );
 
@@ -222,7 +261,7 @@ export class AuthService<S extends SchemaStructure> {
     });
 
     this.logger.info(
-      { Category: 'spooky-client::AuthService::signUp' },
+      { Category: 'sp00ky-client::AuthService::signUp' },
       'Signup successful, token received'
     );
 
@@ -253,7 +292,7 @@ export class AuthService<S extends SchemaStructure> {
     }
 
     this.logger.info(
-      { accessName, Category: 'spooky-client::AuthService::signIn' },
+      { accessName, Category: 'sp00ky-client::AuthService::signIn' },
       'Attempting signin'
     );