@spooky-sync/query-builder 0.0.1-canary.19 → 0.0.1-canary.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/query-builder",
-  "version": "0.0.1-canary.19",
+  "version": "0.0.1-canary.20",
   "description": "Type-safe query builder for SurrealDB with relationship support",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/skills/spooky-query-builder/SKILL.md

@@ -120,6 +120,66 @@ new QueryBuilder(schema, 'user')
 
 Cardinality is inferred from the schema. For `'one'` relationships, the result is an object. For `'many'`, it is an array.
 
+## Backend Schema
+
+The `backends` field in `SchemaStructure` defines available HTTP backends, their outbox tables, and typed routes. This is generated by `spooky generate` from your `spooky.yml` config and OpenAPI spec.
+
+### Schema Structure
+
+```typescript
+export interface SchemaStructure {
+  // ...tables, relationships...
+  readonly backends: Record<string, HTTPOutboxBackendDefinition>;
+}
+
+export interface HTTPOutboxBackendDefinition {
+  readonly outboxTable: string;  // The SurrealDB table used as the outbox (e.g., 'job')
+  readonly routes: Record<string, HTTPBackendRouteDefinition>;
+}
+
+export interface HTTPBackendRouteDefinition {
+  readonly args: Record<string, HTTPBackendRouteArgsDefinition>;
+}
+
+export interface HTTPBackendRouteArgsDefinition {
+  readonly type: ValueType;      // 'string' | 'number' | 'boolean' | 'null' | 'json'
+  readonly optional: boolean;
+}
+```
+
+### Generated Example
+
+Given a `spooky.yml` with an `api` backend and an OpenAPI spec defining a `/spookify` route with an `id` parameter, `spooky generate` produces:
+
+```typescript
+export const schema = {
+  // ...tables, relationships...
+  backends: {
+    "api": {
+      outboxTable: 'job' as const,
+      routes: {
+        "/spookify": {
+          args: {
+            "id": {
+              type: 'string' as const,
+              optional: false as const
+            },
+          }
+        },
+      }
+    },
+  },
+} as const satisfies SchemaStructure;
+```
+
+### Backend Type Helpers
+
+- `BackendNames<S>` — Union of all backend name strings (e.g., `'api'`)
+- `BackendRoutes<S, B>` — Union of all route paths for backend `B` (e.g., `'/spookify'`)
+- `RoutePayload<S, B, R>` — Typed payload object for route `R` on backend `B`. Required args become required fields, optional args become optional fields. Types are mapped from `ValueType` to TypeScript types.
+
+These types are used by `db.run()` to provide full type safety — backend name, route path, and payload are all checked at compile time.
+
 ## Type Helpers
 
 See [references/type-helpers.md](references/type-helpers.md) for a full reference of all type utilities.