Skip to content
AntFabric Corev1.0.0local

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

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 with sales:manage to 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: true for things that may be lost (typing); not with transaction.

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:

plugin.yaml
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.
  • users on 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.

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.