Live updates and notifications
Two different jobs, two core services. Neither runs inside your plugin.
| Live events | Notifications | |
|---|---|---|
| For | Screens that are open now | A person, even when no app is open |
| Reaches | Subscribed sockets of the listed people | Inbox, push (phone, browser), desktop, email — as the person allows |
| Carries | Ids or a small payload | A rendered message and the route a tap opens |
| Declared in | events.publishes |
notifications.types |
| Sent with | PluginEvents.publish |
PluginNotifications.send |
Live events
Section titled “Live events”Declare:
events: publishes: - name: af.sales.lead.changed.v1 description: A lead you work on changed permission: 'sales:read' schema: ./events/lead-changed.schema.json # { leadId, change }Publish in your transaction, to the people who should see it:
await this.events.publish( 'af.sales.lead.changed.v1', { leadId, change: 'stage' }, { users: peopleOnTheLead, transaction: tx, // goes out only if the change commits },);Subscribe in screens and reload through the API:
useEffect(() => { const stop = events.subscribe<LeadChangedEvent>( 'af.sales.lead.changed.v1', () => void reload(), ); const resync = events.onResyncRequired(() => void reload()); // after a reconnect return () => { stop(); resync(); };}, [reload]);Rules:
- Address events with
users. Without it, everyone holding the permission receives them. Sales sends to the people on the lead, and a second event withsales:manageto managers. - Send ids, reload through REST. The API applies the access rules again; the event cannot leak what the person may not see.
- Batch bursts on the client (Sales waits 250 ms and reloads once).
ephemeral: truefor things that may be lost (typing); not withtransaction.
Reacting to other plugins (server-side events)
Section titled “Reacting to other plugins (server-side events)”The same events reach other plugins’ server code, durably. Declare the subscription, then register a handler at start-up:
events: subscribes: [af.files.file.stored.v1]onModuleInit(): void { this.events.on<FileStored>('af.files.file.stored.v1', async (event) => { await this.index.add(event.payload.fileId, { dedupeKey: event.id }); });}- Handlers run in the workers, at least once and in no particular order: dedupe on
event.id. - A handler that throws or runs over 60 s is retried with backoff (10 attempts). Your failures never delay another subscriber.
- The handler acts for the person whose action published the event, so contract calls inside it act for them too.
userson publish only narrows sockets: subscribers get every event of the type.
To narrow who receives your own events on sockets by your own rule (a private folder, say), use
this.events.filterRecipients(name, async (event, userIds) => allowed). If it throws or is slow,
nobody gets that event on a socket.
Notifications
Section titled “Notifications”Declare each type with its templates, a resolver and where a tap goes:
notifications: types: - id: af.sales.follow-up-due description: One of your follow-ups is due category: activityUpdates channels: [inApp, push, email] templates: inApp: ./notifications/follow-up-due.txt push: ./notifications/follow-up-due-push.txt email: { subject: ./notifications/follow-up-due-subject.txt, body: ./notifications/follow-up-due.html, } variables: { schema: ./notifications/follow-up-variables.schema.json, sampleValues: { … }, } resolver: ./server/notifications#resolveFollowUp contextSchema: ./notifications/follow-up-context.schema.json destination: { routeId: lead }Send with ids in the context and a stable key:
await this.notifications.send({ type: 'af.sales.follow-up-due', recipients: [ownerId], context: { followUpId }, idempotencyKey: `follow-up-${followUpId}-${dueAtSeconds}`, // the same key never sends twice});Resolve the variables at delivery time, so the message is current:
export const resolveFollowUp = defineNotificationResolver< { followUpId: string }, Vars>(async ({ context, sdk }) => { /* read with sdk.db, sdk.people → { leadName, note, leadId } */});Rules:
- Never notify the person who did the thing.
- Keys name the business event (
assigned-<activity id>,follow-up-<id>-<due time>), so a retry or a crash never sends twice. - Templates escape every value in email; keep variables short and plain.
- Hundreds at once is a smell. Sales imports do not notify per lead.