@live-change/frontend-template 0.9.198 → 0.9.200

package/.claude/rules/live-change-backend-actions-views-triggers.md

@@ -0,0 +1,246 @@
+---
+description: Rules for implementing actions, views, and triggers in LiveChange services
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – actions, views, triggers (Claude Code)
+
+Use these rules when implementing actions, views, and triggers in LiveChange services.
+
+## Actions
+
+- Place actions in domain files, near the models they operate on.
+- Each action should:
+  - declare clear input `properties`,
+  - perform minimal but necessary validation,
+  - use indexes instead of full scans,
+  - return a meaningful result (ids, data, etc.).
+
+Example:
+
+```js
+definition.action({
+  name: 'registerDeviceConnection',
+  properties: {
+    pairingKey: { type: String },
+    connectionType: { type: String },
+    capabilities: { type: Array }
+  },
+  async execute({ pairingKey, connectionType, capabilities }, { client, service }) {
+    const device = await Device.indexObjectGet('byPairingKey', { pairingKey })
+    if(!device) throw new Error('notFound')
+
+    const id = app.generateUid()
+    const sessionKey = app.generateUid() + app.generateUid()
+
+    await DeviceConnection.create({
+      id,
+      device: device.id,
+      connectionType,
+      capabilities,
+      sessionKey,
+      status: 'offline'
+    })
+
+    return { connectionId: id, sessionKey }
+  }
+})
+```
+
+## Views
+
+- Views should be simple query endpoints over models.
+- Prefer `indexObjectGet` / `indexRangeGet` instead of scanning whole tables.
+
+Example of a range view:
+
+```js
+definition.view({
+  name: 'pendingCommands',
+  properties: {
+    connectionId: { type: String }
+  },
+  async get({ connectionId }, { client, service }) {
+    return BotCommand.indexRangeGet('byConnectionAndStatus', {
+      connection: connectionId,
+      status: 'pending'
+    })
+  }
+})
+```
+
+## Triggers – online/offline and batch updates
+
+- Use triggers for reacting to events (e.g. connection online/offline, server startup).
+- There are two typical patterns:
+  - single-object triggers (update one record),
+  - batch triggers (update many records safely).
+
+Online/offline example:
+
+```js
+definition.trigger({
+  name: 'sessionDeviceConnectionOnline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+
+definition.trigger({
+  name: 'sessionDeviceConnectionOffline',
+  properties: {
+    connection: { type: String }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
+```
+
+### Batch processing – always paginate
+
+- Never load “all rows” in one go.
+- Use a fixed `limit` (e.g. 32 or 128) and a cursor (`gt: lastId`) in a loop.
+
+```js
+definition.trigger({
+  name: 'allOffline',
+  async execute({}, { service }) {
+    let last = ''
+    while(true) {
+      const connections = await DeviceConnection.rangeGet({
+        gt: last,
+        limit: 32
+      })
+      if(connections.length === 0) break
+
+      for(const conn of connections) {
+        await DeviceConnection.update(conn.id, { status: 'offline' })
+      }
+
+      last = connections[connections.length - 1].id
+    }
+  }
+})
+```
+
+## Change triggers – reacting to model changes
+
+Models with relations (`propertyOf`, `itemOf`, `userItem`, etc.) automatically fire change triggers on every create/update/delete. The naming convention is `{changeType}{ServiceName}_{ModelName}`:
+
+- `changeSvc_Model` — fires on any change (recommended, covers all cases)
+- `createSvc_Model` / `updateSvc_Model` / `deleteSvc_Model` — specific lifecycle
+
+Parameters: `{ objectType, object, identifiers, data, oldData, changeType }`.
+
+```js
+// React to any change in Schedule model from cron service
+definition.trigger({
+  name: 'changeCron_Schedule',
+  properties: {
+    object: { type: Schedule, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { triggerService }) {
+    if(oldData) { /* cleanup old state */ }
+    if(data) { /* setup new state */ }
+  }
+})
+```
+
+Check `data`/`oldData`: both present = update, only `data` = create, only `oldData` = delete.
+
+## Granting access on object creation
+
+When a model uses `entity` with `writeAccessControl` / `readAccessControl`, the auto-generated CRUD checks roles but does **not** grant them automatically. The creator must be explicitly granted roles — typically `'owner'` — otherwise they cannot access their own object.
+
+Use a change trigger that fires on creation (`data` exists, `oldData` does not):
+
+```js
+definition.trigger({
+  name: 'changeMyService_MyModel',
+  properties: {
+    object: { type: MyModel, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { client, triggerService }) {
+    if (!data || oldData) return   // only on create
+    if (!client?.user) return
+
+    await triggerService({ service: 'accessControl', type: 'accessControl_setAccess' }, {
+      objectType: 'myService_MyModel',
+      object,
+      roles: ['owner'],
+      sessionOrUserType: 'user_User',
+      sessionOrUser: client.user,
+      lastUpdate: new Date()
+    })
+  }
+})
+```
+
+Key details:
+- `objectType` format: `serviceName_ModelName` (e.g. `company_Company`)
+- For public access (readable by everyone), use `accessControl_setPublicAccess` with `userRoles` / `sessionRoles`
+- For anonymous users, use `sessionOrUserType: 'session_Session'` and `sessionOrUser: client.session`
+
+## Pending + resolve pattern (async result)
+
+Use this pattern when an action must wait for a result from an external process (device, worker, etc.).
+
+1. The main action creates a “pending” record and calls `waitForCommand(id, timeoutMs)`.
+2. Another action or trigger updates the record and calls `resolveCommand(id, result)`.
+
+In-memory helper:
+
+```js
+const pendingCommands = new Map()
+
+export function waitForCommand(commandId, timeoutMs = 115000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(commandId)
+      reject(new Error('timeout'))
+    }, timeoutMs)
+    pendingCommands.set(commandId, { resolve, reject, timer })
+  })
+}
+
+export function resolveCommand(commandId, result) {
+  const pending = pendingCommands.get(commandId)
+  if(pending) {
+    clearTimeout(pending.timer)
+    pendingCommands.delete(commandId)
+    pending.resolve(result)
+  }
+}
+```
+
+Usage in an action:
+
+```js
+await SomeCommand.create({ id, status: 'pending', ... })
+const result = await waitForCommand(id)
+return result
+```
+
+And in a reporting action:
+
+```js
+await SomeCommand.update(id, {
+  status: 'completed',
+  result
+})
+resolveCommand(id, result)
+```
+

package/.claude/rules/live-change-backend-architecture.md

@@ -0,0 +1,126 @@
+---
+description: Rules for LiveChange backend service architecture and directory structure
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – service architecture (Claude Code)
+
+Use these rules whenever you work on backend services in this repo or other live-change-stack projects.
+
+## Service must be a directory
+
+- Each LiveChange service **must be a directory**, not a single file.
+- Use a consistent structure:
+
+```
+server/services/<serviceName>/
+  definition.js  # createServiceDefinition + use – no models/actions here
+  index.js       # imports definition + all domain files, exports definition
+  config.js      # optional – reads definition.config and exports plain object
+  <domain>.js    # domain files: models, views, actions, triggers
+```
+
+## `definition.js`
+
+- Import `app` from `@live-change/framework`.
+- Create the service definition **without** registering models/actions/views there.
+- If the service uses relations or access control, **always** add the plugins in `use`.
+
+```js
+import { app } from '@live-change/framework'
+import relationsPlugin from '@live-change/relations-plugin'
+import accessControlService from '@live-change/access-control-service'
+
+const definition = app.createServiceDefinition({
+  name: 'myService',
+  use: [relationsPlugin, accessControlService]
+})
+
+export default definition
+```
+
+## `index.js`
+
+- Import `definition`.
+- Import all domain files (models/views/actions/triggers) as side-effect imports.
+- Re-export `definition` as default.
+
+```js
+import definition from './definition.js'
+
+import './modelA.js'
+import './modelB.js'
+import './authenticator.js'
+
+export default definition
+```
+
+## `config.js` (optional)
+
+- Read `definition.config` (set in `app.config.js`).
+- Apply defaults and export a plain object.
+
+```js
+import definition from './definition.js'
+
+const {
+  someOption = 'default'
+} = definition.config
+
+export default { someOption }
+```
+
+## Registering the service in the app
+
+### `services.list.js`
+
+- Always import the service from its `index.js`:
+
+```js
+import myService from './services/myService/index.js'
+
+export default {
+  // ...
+  myService
+}
+```
+
+### `app.config.js`
+
+- Make sure `services: [{ name }]` matches the name in `createServiceDefinition`.
+- Keep a **sensible order** of services:
+  - core/common services and plugins first,
+  - application-specific services last (they can depend on earlier ones).
+
+```js
+services: [
+  { name: 'user' },
+  { name: 'session' },
+  { name: 'accessControl' },
+  // ...
+  { name: 'myService' }
+]
+```
+
+## Inspecting services with `describe`
+
+Use the `describe` CLI command to see what the framework generated from your definitions (models, views, actions, triggers, indexes, events):
+
+```bash
+# All services overview
+node server/start.js describe
+
+# One service in YAML (shows all generated code)
+node server/start.js describe --service myService --output yaml
+
+# Specific entity
+node server/start.js describe --service myService --model MyModel --output yaml
+```
+
+This is especially useful after using relations (`userItem`, `itemOf`, `propertyOf`) — `describe` shows all the auto-generated views, actions, triggers, and indexes.
+
+## When to create a new service
+
+- When you have a clearly separate domain (payments, notifications, devices, etc.).
+- When a group of models/actions/views has its own configuration and dependencies.
+- When adding it to an existing service would mix unrelated responsibilities.

package/.claude/rules/live-change-backend-event-sourcing.md

@@ -0,0 +1,186 @@
+---
+description: Event-sourcing data flow rules — emit events for DB writes, use triggerService for cross-service writes
+globs: **/services/**/*.js
+---
+
+# LiveChange backend – event-sourcing data flow (Claude Code)
+
+Use these rules when implementing actions, triggers, and events in LiveChange services.
+
+## How data flows in LiveChange
+
+LiveChange uses an event-sourcing pattern:
+
+1. **Actions and triggers** validate input and publish events via `emit()`.
+2. **Events** (`definition.event()`) execute and perform actual database writes (`Model.create`, `Model.update`, `Model.delete`).
+3. For models with **relations** (`userItem`, `itemOf`, `propertyOf`, etc.), the relations plugin auto-generates CRUD events and triggers — use those via `triggerService()`.
+4. For **cross-service writes**, always use `triggerService()` — `foreignModel` is read-only.
+
+```
+Action/Trigger  ──emit()──▶  Event handler  ──▶  Model.create/update/delete
+       │
+       └──triggerService()──▶  Other service's trigger  ──emit()──▶  ...
+```
+
+## Rule 1: No direct Model.create/update/delete in actions or triggers
+
+Actions and triggers must **not** call `Model.create()`, `Model.update()`, or `Model.delete()` directly. Instead:
+
+- **If the model has relations** (auto-generated CRUD) → use `triggerService()` to call the relation-declared trigger (e.g. `serviceName_createModelName`, `serviceName_updateModelName`, `serviceName_setModelName`).
+- **If no relation trigger exists** → use `emit()` to publish an event, then define a `definition.event()` handler that performs the DB write.
+
+### Correct: emit an event from an action
+
+```js
+definition.action({
+  name: 'createImage',
+  properties: { /* ... */ },
+  waitForEvents: true,
+  async execute({ image, name, width, height }, { client, service }, emit) {
+    const id = image || app.generateUid()
+    // validation, business logic...
+    emit({
+      type: 'ImageCreated',
+      image: id,
+      data: { name, width, height }
+    })
+    return id
+  }
+})
+
+definition.event({
+  name: 'ImageCreated',
+  async execute({ image, data }) {
+    await Image.create({ ...data, id: image })
+  }
+})
+```
+
+### Correct: use triggerService for relation-declared triggers
+
+```js
+definition.action({
+  name: 'giveCard',
+  properties: { /* ... */ },
+  async execute({ receiverType, receiver }, { client, triggerService }, emit) {
+    // Use the auto-generated trigger from the relations plugin
+    await triggerService({
+      service: definition.name,
+      type: 'businessCard_setReceivedCard',
+    }, {
+      sessionOrUserType: receiverType,
+      sessionOrUser: receiver,
+      // ...
+    })
+  }
+})
+```
+
+### Wrong: direct DB write in an action
+
+```js
+// ❌ DON'T DO THIS
+definition.action({
+  name: 'createSomething',
+  async execute({ name }, { client }, emit) {
+    const id = app.generateUid()
+    await Something.create({ id, name })  // ❌ direct write in action
+    return id
+  }
+})
+```
+
+## Rule 2: Events can only modify same-service models
+
+Event handlers (`definition.event()`) must only write to models defined in the **same service**. Never attempt to write to a `foreignModel` — it is read-only (supports `.get()`, `.indexObjectGet()`, `.indexRangeGet()` but not `.create()`, `.update()`, `.delete()`).
+
+For cross-service writes, use `triggerService()` from the action or trigger (before emitting):
+
+```js
+// ✅ Correct: cross-service write via triggerService
+definition.trigger({
+  name: 'chargeCollected_billing_TopUp',
+  async execute(props, { triggerService }, emit) {
+    // Write to another service via its declared trigger
+    await triggerService({
+      service: 'balance',
+      type: 'balance_setOrUpdateBalance',
+    }, { ownerType: 'billing_Billing', owner: props.cause })
+
+    // Write to own service via triggerService (relation-declared trigger)
+    await triggerService({
+      service: definition.name,
+      type: 'billing_updateTopUp'
+    }, { topUp: props.cause, state: 'paid' })
+  }
+})
+```
+
+```js
+// ❌ DON'T DO THIS — foreignModel is read-only
+const ExternalModel = definition.foreignModel('otherService', 'SomeModel')
+
+definition.event({
+  name: 'SomethingHappened',
+  async execute({ id }) {
+    await ExternalModel.update(id, { status: 'done' })  // ❌ will fail
+  }
+})
+```
+
+## `waitForEvents: true`
+
+When an action or trigger emits events and needs them processed before returning a result, set `waitForEvents: true`:
+
+```js
+definition.action({
+  name: 'createNotification',
+  waitForEvents: true,
+  async execute({ message }, { client }, emit) {
+    const id = app.generateUid()
+    emit({
+      type: 'created',
+      notification: id,
+      data: { message, sessionOrUserType: 'user_User', sessionOrUser: client.user }
+    })
+    return id  // event is processed before this returns
+  }
+})
+```
+
+Without `waitForEvents: true`, the action returns immediately and events are processed asynchronously.
+
+## Relation-declared triggers
+
+When a model uses relations (`userItem`, `itemOf`, `propertyOf`, etc.), the relations plugin auto-generates CRUD triggers. Use `describe` to discover them:
+
+```bash
+node server/start.js describe --service myService --output yaml
+```
+
+Common auto-generated trigger patterns:
+- `serviceName_createModelName` — create a new record
+- `serviceName_updateModelName` — update an existing record
+- `serviceName_deleteModelName` — delete a record
+- `serviceName_setModelName` — create or update (upsert)
+- `serviceName_setOrUpdateModelName` — set if not exists, update if exists
+
+Invoke them via `triggerService()`:
+
+```js
+await triggerService({
+  service: 'myService',
+  type: 'myService_createMyModel'
+}, {
+  // properties matching the model's writeable fields
+})
+```
+
+## Summary
+
+| Where | Can call Model.create/update/delete? | How to change data |
+|---|---|---|
+| `definition.event()` | ✅ Yes (same-service models only) | Direct DB writes |
+| `definition.action()` | ❌ No | `emit()` or `triggerService()` |
+| `definition.trigger()` | ❌ No | `emit()` or `triggerService()` |
+| Cross-service | ❌ Never via foreignModel | `triggerService()` to target service |