notify

type Adoption ¶

type Adoption struct {
	Previous []Origin `json:"previous"`
	Current  Mutation `json:"current"`
}

Adoption maps exact legacy origins for Current's recipient to one current producer identity during an explicit, stopped-writer migration. The host authorizes the mapping; it never means a prefix, range or inbox search.

type AppView ¶

type AppView struct {
	AppID         string
	LegacyOrigins []OriginScope
}

AppView presents tenant-wide receipts and one exact application's receipts. LegacyOrigins is an explicit compatibility allowance for unclassified rows. A nil or empty allowance admits no legacy origins.

type Audience ¶

type Audience string

Audience selects an authorization boundary, not a delivery channel.

const (
	AudienceUser     Audience = "user"
	AudienceOperator Audience = "operator"
)

type Input ¶

type Input struct {
	Recipient  Recipient       `json:"recipient"`
	Origin     Origin          `json:"origin"`
	Kind       string          `json:"kind"`
	Data       json.RawMessage `json:"data"`
	CreatedAt  time.Time       `json:"created_at"`
	Visibility Visibility      `json:"visibility,omitempty"`
	AppID      string          `json:"app_id,omitempty"`
	Status     Status          `json:"status,omitempty"`
	// ActionRequested records the item's category at creation. With empty Status
	// it is historical information, not a claim that the issue is still open.
	ActionRequested bool   `json:"action_requested,omitempty"`
	Severity        string `json:"severity,omitempty"`
}

Input is trusted application-authored content. Kind is extensible. Data must contain only fields the recipient may see. CreatedAt is the source time. Publish accepts StatusNotice or StatusOpen; workflow transitions are separate.

func Validate(in Input) (Input, error)

type Item ¶

type Item struct {
	ID string `json:"id"`
	Input
	ReadAt *time.Time `json:"read_at"`
	// DismissedAt archives this recipient's receipt without resolving work.
	DismissedAt *time.Time `json:"dismissed_at"`
	ResolvedAt  *time.Time `json:"resolved_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	Revision    int64      `json:"revision"`
	// ProducerRevision orders source mutations independently of receipt changes.
	ProducerRevision int64 `json:"producer_revision,omitempty"`
	// Withdrawn items are retained only to reject delayed producer mutations.
	Withdrawn bool `json:"withdrawn,omitempty"`
}

Item is an inbox record or a projection of an existing domain record. ReadAt and ResolvedAt describe different operations; neither implies the other. Revision is positive in the durable store and zero for unversioned projections.

type ListOptions ¶

type ListOptions struct {
	Limit      int
	Cursor     string
	UnreadOnly bool
	Status     *Status
	// Dismissed selects archived receipts instead of the active inbox.
	Dismissed bool
}

ListOptions selects a bounded, newest-first page. Status nil includes notices and work items; a pointer to StatusNotice selects only general notices.

type Mutation ¶

type Mutation struct {
	Input
	Revision  int64 `json:"revision"`
	Withdrawn bool  `json:"withdrawn,omitempty"`
}

Mutation is the current state of one exact producer identity. The producer durably assigns Revision before delivery; transport retries reuse it. A newer publication replaces the payload, while Withdrawn hides the item even if it has not arrived yet. Neither IDs nor withdrawals interpret wildcards.

func ValidateMutation(in Mutation) (Mutation, error)

type Origin ¶

type Origin struct {
	System string `json:"system"`
	Scope  string `json:"scope"`
	ID     string `json:"id"`
	// Subject is the source recipient, when the destination maps it to a
	// different local identity. It grants no authority by itself.
	Subject string `json:"subject,omitempty"`
}

Origin preserves a producer's deployment, namespace and stable item ID. Scope can identify a merchant, project or account issuer. Each recipient receives at most one item for the same System, Scope and ID in one local store scope; Subject is optional provenance, not part of that identity.

type OriginScope ¶

type OriginScope struct {
	System string `json:"system" yaml:"system"`
	Scope  string `json:"scope" yaml:"scope"`
}

OriginScope selects all items from one exact producer namespace. It is separate from recipient authorization and never grants access to an account.

type Page ¶

type Page struct {
	Items      []Item `json:"items"`
	NextCursor string `json:"next_cursor,omitempty"`
}

Page is a bounded page; NextCursor is empty at the end of a current scan.

type Publication ¶

type Publication struct {
	RecipientID     string
	ID              string
	Revision        int64
	Kind            string
	Data            json.RawMessage
	CreatedAt       time.Time
	ActionRequested bool
	Severity        string
}

Publication describes one user's current notification. ID is the exact deterministic producer ID, not a receipt ID or a wildcard pattern.

func ValidatePublication(in Publication) (Publication, error)

type Publisher ¶

type Publisher interface {
	Publish(context.Context, []Publication, ...pgx.Tx) error
	Withdraw(context.Context, []Withdrawal, ...pgx.Tx) error
}

Publisher is the producer-facing account inbox channel. AuthKit binds its tenant, origin and application visibility when constructing the publisher. Each batch accepts at most MaxMutations exact identities. Retries reuse the producer's revision; older revisions never undo a newer publication or withdrawal. Producers do not read the inbox to decide what to publish.

Omit tx to durably accept the batch in a new transaction. Supplying one non-nil transaction joins the batch to the producer's database mutation. Remote publishers enqueue delivery in their source database in both cases; successful acceptance does not require the destination to be online.

type Reader ¶

type Reader interface {
	List(context.Context, Recipient, ListOptions) (Page, error)
}

Reader is a recipient-scoped inbox. Callers supply an authorized recipient.

type Recipient ¶

type Recipient struct {
	Audience Audience `json:"audience"`
	ID       string   `json:"id"`
}

Recipient names a user or an operator queue within the store's scope. Hosts authorize this pair; an email address is never an identity join.

type Status ¶

type Status string

Status is independent of read state. A general notice has no workflow; actionable items begin open and are explicitly resolved or dismissed.

const (
	StatusNotice    Status = ""
	StatusOpen      Status = "open"
	StatusResolved  Status = "resolved"
	StatusDismissed Status = "dismissed"
)

type Visibility ¶

type Visibility string

Visibility identifies where a receipt may be presented; Origin remains provenance and replay identity. Empty visibility means an unclassified legacy item, never an implicit tenant-wide grant in an AppView.

const (
	VisibilityTenant Visibility = "tenant"
	VisibilityApp    Visibility = "app"
)

type Withdrawal ¶

type Withdrawal struct {
	RecipientID string
	ID          string
	Revision    int64
}

Withdrawal hides one exact producer identity, including one not yet delivered. The retained revision prevents an older queued publication from reviving it.