ugly-app 0.1.106 → 0.1.107

package/README.md

@@ -84,6 +84,7 @@ The returned `App` object has:
 - `registerRoutes(fn)` — mount additional Express routes after creation
 - `httpServer` — the underlying Node.js HTTP server
 - `db` — the `TypedDB` instance for direct database access
+- `wss` — the main `WebSocketServer` instance (path configured via `setWsPath`, default `'/rpc'`)
 - `dispatch(name, input, userId)` — invoke an RPC handler programmatically
 
 ### `AppConfigurator`
@@ -99,6 +100,12 @@ The optional fourth argument to `createApp` receives a configurator object:
 | `setOnSocketMessage(handler)` | Handle raw WebSocket messages. Return `true` to consume, `false` to let the framework handle it |
 | `registerRoutes(fn)` | Mount custom Express routes — `(router: express.Router) => void` |
 | `setWorkerQueue(queue)` | Register a background worker queue with `start()` and `stop()` |
+| `setWsPath(path)` | Override the WebSocket path (default: `'/rpc'`) |
+| `setOnWsAuth(handler)` | Called after a WebSocket session is authenticated. `(ws, userId, req) => void` |
+| `setOnAfterStart(handler)` | Called once after MongoDB, Redis, and NATS are ready. `(db) => Promise<void>` |
+| `setOnMinuteTick(handler)` | Fires every minute (only when `CLOCK_ENABLED=true`). `() => Promise<void>` |
+| `setOnHourlyTick(handler)` | Fires when the hour changes (only when `CLOCK_ENABLED=true`). `(now, currentHour) => Promise<void>` |
+| `setHealthHandler(handler)` | Override the default `GET /health` endpoint handler. `(req, res) => void` |
 
 ### Handler signatures
 
@@ -163,11 +170,11 @@ import type { Note } from './types';
 export const collections = defineCollections({
   note: {
     type: {} as Note,
-    meta: { cache: true, trackable: true, public: false, parent: null },
+    meta: { cache: true, trackable: true, public: false, cascadeFrom: null },
   },
   user: {
     type: {} as User,
-    meta: { cache: true, trackable: false, public: false, parent: null },
+    meta: { cache: true, trackable: false, public: false, cascadeFrom: null },
   },
 });
 ```
@@ -175,13 +182,14 @@ export const collections = defineCollections({
 Each collection definition has:
 - `type` — phantom field for TypeScript type inference (never read at runtime)
 - `meta` — runtime metadata:
-  - `cache` — enable in-memory caching
-  - `trackable` — allow real-time `trackDoc`/`trackDocs` subscriptions
-  - `public` — accessible without auth
-  - `parent` — parent collection name for cascade deletes (or `null`)
-- `onDelete?` — optional callback invoked on document deletion
+  - `cache` — enable in-memory LRU caching for `getDoc`; `setDoc`/`deleteDoc` invalidate it
+  - `trackable` — allow real-time `trackDoc`/`trackDocs` subscriptions via Change Streams
+  - `public` — allows client reads via `getDoc`/`trackDoc`/`trackDocs` without auth
+  - `cascadeFrom` — parent collection name for cascade deletes (or `null`)
+  - `trackKeys?` — fields usable as NATS routing keys for `trackDocs`
+- `onDelete?` — optional async callback invoked on document deletion
 
-All documents extend `DBObject`: `{ id: string, version: number, created: Date, updated: Date }`.
+All documents extend `DBObject`: `{ _id: string, version: number, created: Date, updated: Date }`.
 
 ### Pages (`shared/pages.ts`)
 
@@ -254,13 +262,30 @@ await socket.connect(token); // returns UserBase
 | Method | Description |
 |--------|-------------|
 | `connect(token)` | Authenticate and connect. Returns the user object |
-| `request(name, input)` | Invoke a request (query or mutation) |
+| `request(name, input)` | Invoke a typed request (query or mutation) |
 | `getDoc(collection, id)` | Fetch a single document |
+| `getDocs(collection, filter?, opts?)` | Query documents (filter, sort, limit, skip) |
+| `getQuery(collection, pipeline, opts?)` | Run an aggregation pipeline |
 | `trackDoc(collection, id, cb)` | Subscribe to real-time doc changes. Returns unsubscribe fn |
-| `trackDocs(collection, filter, cb, opts?)` | Subscribe to query results. Returns unsubscribe fn |
+| `trackDocs(collection, params, cb)` | Subscribe to query results (`keys`, `filter`, `sort`, `limit`, `skip`). Returns unsubscribe fn |
 | `uploadFile(file, key)` | Upload a file via presigned URL |
+| `emit(type, data)` | Send a fire-and-forget message over WebSocket |
+| `send(type, data, timeout?)` | Send a message and wait for a response |
+| `waitForConnection(timeout?)` | Wait until the socket is connected |
+| `connectionState` | Current state: `'connecting'` \| `'connected'` \| `'reconnecting'` \| `'disconnected'` \| `'idle-disconnected'` |
 | `disconnect()` | Close the connection |
 
+**`createSocket()` options:**
+
+| Option | Description |
+|--------|-------------|
+| `requests` | The requests registry from `shared/api.ts` |
+| `url?` | WebSocket path (default: `'/rpc'`) |
+| `buildId?` | Build identifier sent on connect |
+| `onCustomMessage?` | Handle custom server-pushed messages |
+| `getUrlParams?` | Extra query params appended to the WebSocket URL |
+| `messageReviver?` | JSON reviver for incoming messages (e.g. Date parsing) |
+
 ### `createHttpClient()`
 
 Creates a typed HTTP client for RPC communication (no WebSocket needed).
@@ -524,7 +549,7 @@ The `AuthProvider` interface:
 
 ```typescript
 interface AuthProvider {
-  verify(code: string): Promise<{ userId: string; email?: string; phone?: string }>;
+  verify(code: string): Promise<{ userId: string; email?: string; phone?: string; token?: string }>;
   authUrl(origin: string): string;
   registerRoutes?(router: express.Router): void;
 }
@@ -578,8 +603,8 @@ const docs = await db.rawGetDocs(collectionName, filter);
 ### Deleting
 
 ```typescript
-await db.deleteDoc(collections.note, id);        // single doc (cascades via parent)
-await db.deleteQuery(collections.note, { userId }); // bulk delete by filter
+await db.deleteDoc(collections.note, id);           // single doc (cascades via cascadeFrom)
+await db.deleteQuery(collections.note, { userId }); // bulk delete by filter (cascades + calls onDelete)
 ```
 
 ### Caching
@@ -948,6 +973,7 @@ Run with `npm run db:migrate`. Use `npm run db:migrate -- --status` to preview p
 | `KIE_API_KEY` | Kie.ai key |
 | `KIE_BASE_URL` | Kie.ai base URL override (optional) |
 | `MAILGUN_FROM` | Default from address |
+| `CLOCK_ENABLED` | Set to `true` to enable `setOnMinuteTick`/`setOnHourlyTick` handlers |
 
 Client-side variables must be prefixed with `VITE_`.
 

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.106";
+export declare const CLI_VERSION = "0.1.107";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.106";
+export const CLI_VERSION = "0.1.107";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.106",
+  "version": "0.1.107",
   "type": "module",
   "main": "./dist/server/index.js",
   "exports": {

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.106";
+export const CLI_VERSION = "0.1.107";