notificationep

type ListNotificationsEndpoint ¶

type ListNotificationsEndpoint struct{}

Lists the notifications addressed to the current user, newest first.

The feed is personal and scoped to the account being acted in, so it never includes another user's notifications. Callers with no user membership in that account, such as an API key, get an empty list rather than an error.

func (e *ListNotificationsEndpoint) Materialize() *apiendpoint.APIEndpoint[*ListNotificationsRequest, *apiresource.List[apiresource.Notification]]

type ListNotificationsRequest ¶

type ListNotificationsRequest struct {
	apiresource.PaginationRequest
	// Return only notifications of this category, such as `chat.mention` or `order.updated`.
	Category *constants.NotificationCategory `query:"category"`
	// Return only notifications in this lifecycle state.
	//
	// When omitted, the response is the active feed: every notification that has not been dismissed, whatever its seen or read state. Pass `dismissed` to review notifications that were cleared out of the feed.
	Status *constants.NotificationStatus `query:"status"`
	// Return only notifications sent by these actors.
	//
	// A notification sent by a person is attributed to their account user id, not their user id.
	SenderIDs []string `query:"sender_ids"`
	// Return only notifications sent by these kinds of actor.
	//
	// Notifications raised by the platform itself are attributed to the `system` sender type but are returned without a sender.
	SenderTypes []constants.NotificationSenderType `query:"sender_types"`
}

Request to list the caller's notifications.

type MarkAllSeenEndpoint ¶

type MarkAllSeenEndpoint struct{}

Marks every one of the caller's unseen notifications as seen in a single call.

The notifications stay in the feed and are not marked read. Account announcements are unaffected and are cleared individually, so the unread total can remain above zero afterwards.

func (e *MarkAllSeenEndpoint) Materialize() *apiendpoint.APIEndpoint[*MarkAllSeenRequest, *apiresource.EmptyResource]

type MarkAllSeenRequest ¶

type MarkAllSeenRequest struct{}

Request to mark all of the caller's notifications as seen.

type MarkDismissedEndpoint ¶

type MarkDismissedEndpoint struct{}

Dismisses a notification, removing it from the active feed.

The notification is not deleted: it can still be retrieved by ID and listed with the `dismissed` status filter. Dismissing an already-dismissed notification keeps the original dismissal time.

func (e *MarkDismissedEndpoint) Materialize() *apiendpoint.APIEndpoint[*MarkNotificationRequest, *apiresource.Notification]

type MarkNotificationRequest ¶

type MarkNotificationRequest struct {
	// Notification ID.
	NotificationID string `path:"id" validate:"required"`
}

Request to advance the state of a single notification addressed to the caller.

type MarkReadEndpoint ¶

type MarkReadEndpoint struct{}

Marks a notification as read, as when the user opens it.

Reading also marks the notification seen if it was not already, and leaves it in the feed until it is dismissed. Repeating the call keeps the original read time.

func (e *MarkReadEndpoint) Materialize() *apiendpoint.APIEndpoint[*MarkNotificationRequest, *apiresource.Notification]

type MarkSeenEndpoint ¶

type MarkSeenEndpoint struct{}

Marks a notification as seen, as when it is surfaced to the user without being opened.

Seeing a notification removes it from the unread count but leaves it in the feed. Repeating the call keeps the original seen time.

func (e *MarkSeenEndpoint) Materialize() *apiendpoint.APIEndpoint[*MarkNotificationRequest, *apiresource.Notification]

type NotificationSvc ¶

type NotificationSvc interface {
	SendNotification(ctx context.Context, req *SendNotificationRequest) (*apiresource.NotificationSendResult, *apierror.APIError)
	ListNotifications(ctx context.Context, req *ListNotificationsRequest) (*apiresource.List[apiresource.Notification], *apierror.APIError)
	GetNotification(ctx context.Context, req *RetrieveNotificationRequest) (*apiresource.Notification, *apierror.APIError)
	GetUnreadCount(ctx context.Context, req *UnreadCountRequest) (*apiresource.NotificationUnreadCount, *apierror.APIError)
	GetUnreadSummary(ctx context.Context, req *UnreadSummaryRequest) (*apiresource.NotificationUnreadSummary, *apierror.APIError)
	MarkSeen(ctx context.Context, req *MarkNotificationRequest) (*apiresource.Notification, *apierror.APIError)
	MarkRead(ctx context.Context, req *MarkNotificationRequest) (*apiresource.Notification, *apierror.APIError)
	MarkDismissed(ctx context.Context, req *MarkNotificationRequest) (*apiresource.Notification, *apierror.APIError)
	MarkAllSeen(ctx context.Context, req *MarkAllSeenRequest) (*apiresource.EmptyResource, *apierror.APIError)
}

NotificationSvc backs the in-app notification (bell) endpoints via the notification-service MessagingService gRPC client.

func NewNotificationSvc(config *NotificationSvcConfig) NotificationSvc

type NotificationSvcConfig ¶

type NotificationSvcConfig struct {
	// MessagingClient (required) is the notification-service MessagingService gRPC client.
	MessagingClient pb.MessagingServiceClient
}

type RetrieveNotificationEndpoint ¶

type RetrieveNotificationEndpoint struct{}

Retrieves a single notification by ID.

Only notifications addressed to the current user are visible; another user's notification is reported as not found. Dismissed notifications remain retrievable.

func (e *RetrieveNotificationEndpoint) Materialize() *apiendpoint.APIEndpoint[*RetrieveNotificationRequest, *apiresource.Notification]

type RetrieveNotificationRequest ¶

type RetrieveNotificationRequest struct {
	// Notification ID.
	NotificationID string `path:"id" validate:"required"`
}

Request to retrieve a single notification addressed to the caller.

type SendNotificationEndpoint ¶

type SendNotificationEndpoint struct{}

Sends an in-app notification to a single member of an account, or announces it to everyone in the account.

A send to one member is attributed to the authenticated caller, so the recipient sees who sent it. It is accepted and then fanned out, so it reaches the recipient's feed and their connected clients shortly after the response.

An announcement to the whole account is stored as the request is accepted, carries no sender, and may only target the account you are currently acting in.

func (e *SendNotificationEndpoint) Materialize() *apiendpoint.APIEndpoint[*SendNotificationRequest, *apiresource.NotificationSendResult]

type SendNotificationRequest ¶

type SendNotificationRequest struct {
	// The kind of event the notification represents, such as `order.updated`.
	//
	// Categories are how clients group and filter the feed, so reuse an existing one where it fits.
	Category constants.NotificationCategory `json:"category" validate:"required"`
	// Who to send to: an `account_user` for a personal notification, or an `account` to announce to everyone in it.
	Target apiresource.NotificationTargetInput `json:"target" validate:"required"`
	// Short headline shown in the recipient's feed.
	Title string `json:"title" validate:"required"`
	// Supporting detail shown beneath the title.
	Body field.Optional[string] `json:"body,omitzero"`
	// How prominently the notification should be surfaced, from `low` through `urgent`.
	Priority field.Optional[constants.NotificationPriority] `json:"priority,omitzero" default:"normal"`
	// Type of the resource the notification should link to, such as `sales_order`.
	//
	// Set it together with `link_resource_id` to point the notification at something the recipient can open; supplying only one of the two produces a notification with no link.
	LinkResourceType field.Optional[constants.ObjectType] `json:"link_resource_type,omitzero"`
	// ID of the resource the notification should link to.
	LinkResourceID field.Optional[string] `json:"link_resource_id,omitzero"`
}

Request to send an in-app notification.

The target decides whether the notification goes to one member of the account or to everyone in it.

func (*SendNotificationRequest) SchemaExample() any

type UnreadCountEndpoint ¶

type UnreadCountEndpoint struct{}

Returns the current user's unread tallies for the account they are acting in, for driving a notification badge.

The total also counts account announcements the user has not seen, so it can be higher than the notification count alone.

func (e *UnreadCountEndpoint) Materialize() *apiendpoint.APIEndpoint[*UnreadCountRequest, *apiresource.NotificationUnreadCount]

type UnreadCountRequest ¶

type UnreadCountRequest struct{}

Request for the caller's unread notification tallies.

type UnreadSummaryEndpoint ¶

type UnreadSummaryEndpoint struct{}

Returns the caller's unread totals broken down by account, covering every account they belong to and not just the one they are acting in.

Use it to show a user that activity is waiting for them elsewhere before they switch accounts. Each tally counts unseen notifications and unseen account announcements together.

func (e *UnreadSummaryEndpoint) Materialize() *apiendpoint.APIEndpoint[*UnreadSummaryRequest, *apiresource.NotificationUnreadSummary]

type UnreadSummaryRequest ¶

type UnreadSummaryRequest struct{}

Request for the caller's cross-account unread summary.