openrails

type Backend ¶ added in v0.90.0

type Backend interface {
	Register(context.Context) error
	Pending(context.Context, int) ([]Event, error)
	Acknowledge(context.Context, []string) error
	Retire(context.Context) error
}

Options binds one trusted OpenRails deployment, merchant and independent consumer. Token supplies a merchant-authorized application access token; Client may instead authenticate through its transport. URL precedes /v1.

type ConsumeOptions ¶

type ConsumeOptions struct {
	Limit           int
	IncludeOptional bool
	// Filter is evaluated before recipient mapping; false intentionally skips+ACKs.
	Filter func(Event) bool
}

ConsumeOptions bounds one worker call. Optional events default to skip+ACK; opt in to map them, applying any per-user preferences inside RecipientMapper.

type ConsumeResult ¶

type ConsumeResult struct{ Fetched, Delivered, Skipped, Acknowledged int }

ConsumeResult counts this attempt, including idempotent destination replays. Failed events remain pending. Acknowledged counts only a successful source ACK.

type Event ¶

type Event struct {
	ID              string          `json:"id"`
	MerchantID      string          `json:"merchant_id"`
	CustomerID      string          `json:"customer_id"`
	EventType       string          `json:"event_type"`
	Data            json.RawMessage `json:"data"`
	CreatedAt       time.Time       `json:"created_at"`
	ActionRequested bool            `json:"action_requested,omitempty"`
	Optional        bool            `json:"optional,omitempty"`
}

Event is an immutable source fact, not an OpenRails-owned inbox item. Kind strings and JSON fields remain extensible. ActionRequested is historical, independent of a destination's tracked workflow state.

type Jobs ¶ added in v0.90.0

type Jobs struct {
	// contains filtered or unexported fields
}

Jobs routes one shared worker to any number of explicitly configured sources. Each source has a distinct queue and durable consumer, and contributes to the same host fleet. A worker never acknowledges an unconfigured source's job.

func (j *Jobs) Add(s *Source, destination notify.Publisher, mapper RecipientMapper, namespace string) (riverhelpers.Contribution, error)

type Options ¶

type Options struct {
	// Backend connects an embedded OpenRails client; nil uses HTTP.
	Backend Backend
	// Name is the complete stable origin system; defaults to openrails:URL.
	Name       string
	URL        string
	MerchantID string
	// Consumer is stable across restarts and unique per destination within the
	// authenticated application/merchant. Tokens can rotate without losing ACKs.
	Consumer string
	Client   *http.Client
	Token    func(context.Context) (string, error)
}

type RecipientMapper ¶

type RecipientMapper func(context.Context, Event) (recipientID string, deliver bool, err error)

RecipientMapper resolves the event's verified merchant/customer coordinates through host-owned account records. deliver=false deliberately skips the event and allows its ACK. An error keeps it pending for retry. Email equality alone must never establish the association. Future event kinds pass through.

type Source ¶

type Source struct {
	// contains filtered or unexported fields
}

Source consumes the notification events of one configured merchant.

func New(opts Options) (*Source, error)

func (s *Source) Consume(ctx context.Context, destination notify.Publisher, mapper RecipientMapper, opts ConsumeOptions) (ConsumeResult, error)

func (s *Source) Origin() notify.OriginScope

func (s *Source) Register(ctx context.Context) error

func (s *Source) Retire(ctx context.Context) error