Skip to main content
Version: 0.4.x(Latest)

Overview​

The notifications capability has three entry points:

Entry PointUserDescription
services.Notifications()Source plugin standard capabilityBatch reads visible notification message views
services.Admin().Notifications()Trusted source pluginsSends notifications, deletes notifications, deletes by business source
service: notificationsDynamic pluginsReads message views and sends managed notifications through the notifications service

The latest root capability catalog does not have a services.Notify() method. Source plugins that need to send notifications should use the management commands, because sending messages produces host write and delivery side effects.

Capability phase: Runtime

Type support: Source plugins, dynamic plugins

Capability Design​

Data Model​

TypeFieldDescription
SendInputRecipientsSet of target user identifiers
SendInputSourceType, SourceIDBusiness source type and source record identifier
SendInputTitle, ContentNotification title and body
SendInputCategoryInbox category; falls back to other when unspecified
SendInputSenderUserIDOptional sender; adapter may use the CapabilityContext operator when omitted
SendResultMessageID, DeliveryCountCreated message identifier and delivery count

Built-in source types include notice and plugin. The generic category fallback value is other.

Read/Write Separation Design​

The notifications capability follows a read/write separation pattern: the standard Notifications() provides a read-only view capability, while Admin().Notifications() provides managed write commands. Sending is a managed write command because it produces host write and delivery side effects.

Localization and Sending​

Notification content requires plugins to handle localization themselves. Before sending, you can use the internationalization capability to resolve copy; the notifications capability itself does not handle template rendering.

Interface Definitions​

Source Plugin Interface​

Entry PointMethodDescription
Notifications()BatchGetMessagesBatch reads visible notification message views
Admin().Notifications()SendSends a managed notification
Admin().Notifications()DeleteMessagesDeletes visible notification messages
Admin().Notifications()DeleteBySourceDeletes notifications by business source

Dynamic Plugin Interface​

Dynamic plugins declare authorized methods through hostServices.notifications:

Dynamic MethodDescription
messages.batch_getBatch reads visible notification message views
messages.sendSends a managed notification

Usage​

Source Plugin Usage​

Source plugins read notification views through services.Notifications(), passing the domain-required CapabilityContext explicitly:

// Batch read notification messages
result, err := services.Notifications().BatchGetMessages(ctx, capabilityCtx, messageIDs)

Trusted source plugins send and manage notifications:

// Send notification
result, err := services.Admin().Notifications().Send(ctx, capabilityCtx, notifycap.SendInput{
    Recipients: []string{userID},
    SourceType: notifycap.SourceTypePlugin,
    SourceID:   reportID,
    Title:      "Report Generation Complete",
    Content:    "Your report has been generated, please check it",
    Category:   notifycap.CategoryCode("report"),
})

// Delete notifications by business source
err := services.Admin().Notifications().DeleteBySource(ctx, capabilityCtx, notifycap.SourceTypePlugin, []string{reportID})

Dynamic Plugin Usage​

Dynamic plugins declare the notifications service and authorized methods in plugin.yaml:

hostServices:
  - service: notifications
    methods:
      - messages.batch_get
      - messages.send
    resources:
      - ref: inbox:business-alert

messages.send is a resource-type method and must declare resources[].ref. The host can use this to restrict the message scenarios or categories a plugin can send. Usage on the dynamic plugin side:

notifySvc := pluginbridge.Default().Notifications()

// Batch read notification messages
result, err := notifySvc.BatchGetMessages(ctx, capabilityCtx, messageIDs)

// Send notification
sendResult, err := notifySvc.Send(ctx, capabilityCtx, notifycap.SendInput{
    Recipients: []string{userID},
    SourceType: notifycap.SourceTypePlugin,
    SourceID:   taskID,
    Title:      "Task Complete",
    Content:    "Your export task has completed",
    Category:   notifycap.CategoryCode("report"),
})

Design Constraints​

  • Standard capability is read-only. Notifications() is for reading views and is not responsible for sending.
  • Sending is a managed write command. Source plugins send notifications via Admin().Notifications().Send; dynamic plugins use notifications.messages.send.
  • Deletion is governed by visibility and source. Both DeleteMessages and DeleteBySource should check target visibility in the host domain adapter.
  • Notification content should be localized by the plugin. You can use the internationalization capability to resolve copy before sending; the notifications capability does not handle template rendering.