mesh-contracts/operator-and-conversation/go/seats/operatorchannel/contract.go

// Code generated by seatgen from the seat definitions; DO NOT EDIT.

// Package operatorchannel is the contract of the seat "operator-channel", defined whole (seats/operator-channel/seat.json): Asking a person and answering on a channel (ADR 0259): held by the router, the messenger module, whose manifest declares the seat; written from that seat entry (design 26).
package operatorchannel

import (
	"bytes"
	"encoding/json"
	"errors"
	"strings"
	"time"
)

// Seat is the seat's name.
const Seat = "operator-channel"

const (
	VerbOpen    = "open"
	VerbHistory = "history"
	VerbNotify  = "notify"
	VerbTell    = "tell"
	VerbAsks    = "asks"
)

const (
	AcceptAsk       = "ask"
	AcceptCancel    = "cancel"
	AcceptCondition = "condition"
)

const (
	EventDecided = "decided"
)

// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
	return []string{VerbOpen, VerbHistory, VerbNotify, VerbTell, VerbAsks}
}

// Events is every event published on the seat's subject: a new copy each call.
func Events() []string {
	return []string{EventDecided}
}

// Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects.
const (
	Family           = "operator-channel.decided"
	FamilyMaxAgeDays = 7
)

// SubjectDecided is where decided is published for one caller.
func SubjectDecided(caller string) string {
	return "mesh.seat.operator-channel.event.decided." + caller
}

// AcceptSubjectAsk is where one caller sends ask.
func AcceptSubjectAsk(caller string) string { return "mesh.seat.operator-channel.accept.ask." + caller }

// AcceptSubjectCancel is where one caller sends cancel.
func AcceptSubjectCancel(caller string) string {
	return "mesh.seat.operator-channel.accept.cancel." + caller
}

// AcceptSubjectCondition is where one caller sends condition.
func AcceptSubjectCondition(caller string) string {
	return "mesh.seat.operator-channel.accept.condition." + caller
}

// The holder's own events, listed beside the seat and published under the holder's subjects (ADR 0620 §2).
const (
	HolderEventRefused = "refused"
	HolderEventOffered = "offered"
	HolderEventClosed  = "closed"
)

// HolderSubjectRefused is where the holder publishes refused.
func HolderSubjectRefused(holder string) string { return "mesh.mod." + holder + ".event.refused" }

// HolderSubjectOffered is where the holder publishes offered, kept in router.asks.
func HolderSubjectOffered(holder string) string { return "mesh.stream." + holder + ".event.offered" }

// HolderSubjectClosed is where the holder publishes closed, kept in router.asks.
func HolderSubjectClosed(holder string) string { return "mesh.stream." + holder + ".event.closed" }

const (
	StateAsks = "asks"
)

// AsksByAskerIDKey is the key of one value of the state asks under the form "<asker>.<id>".
func AsksByAskerIDKey(asker, id string) string { return asker + "." + id }

// ParseAsksByAskerIDKey reads the parts of a key of the form "<asker>.<id>", in the order of the form; the last result is false for a key of another form.
func ParseAsksByAskerIDKey(key string) (string, string, bool) {
	rest := key
	v0, after0, found0 := strings.Cut(rest, ".")
	if !found0 || v0 == "" {
		return "", "", false
	}
	rest = after0
	if rest == "" {
		return "", "", false
	}
	v2 := rest
	rest = ""
	if rest != "" {
		return "", "", false
	}
	return v0, v2, true
}

// DecodeAsksByAskerIDValue reads one value of the state asks under the form "<asker>.<id>", refusing a field AsksByAskerIDValue does not know and any text after the value.
func DecodeAsksByAskerIDValue(raw []byte) (AsksByAskerIDValue, error) {
	var v AsksByAskerIDValue
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	if err := dec.Decode(&v); err != nil {
		return v, err
	}
	if dec.More() {
		return v, errors.New("text after the value")
	}
	return v, nil
}

// Ask is a type of the contract.
type Ask struct {
	// what it is about: a newer ask about it replaces the older
	About string `json:"about,omitempty"`
	// its secondary words
	Details string `json:"details,omitempty"`
	// when it ends unanswered, RFC 3339
	Expires string `json:"expires"`
	// what happened and what it means
	Explanation string `json:"explanation"`
	// a few plain words
	Headline string `json:"headline"`
	// the asker's own id
	ID string `json:"id"`
	// what the asker then does
	OnExpiry string `json:"on-expiry"`
	// the answers it offers
	Options []Option `json:"options"`
	// urgent
	Urgent bool `json:"urgent,omitempty"`
	// who may answer: operator
	Who string `json:"who"`
	// the explanation with its values whole
	Whole string `json:"whole,omitempty"`
	// the details whole
	WholeDetails string `json:"whole-details,omitempty"`
}

// Button is one answer a channel offers: its label and the router's one-time ticket for it.
type Button struct {
	// the button's label
	Label string `json:"label"`
	// the router's one-time ticket for it
	Ticket string `json:"ticket"`
}

// Choice is a button chosen on a channel, said on the bench intake as the event `choice`.
type Choice struct {
	// when, RFC 3339
	At time.Time `json:"at"`
	// the message's handle
	Handle string `json:"handle,omitempty"`
	// the channel's own for this arrival, unique, so the router acts on it once
	ID     string `json:"id"`
	Sender Sender `json:"sender"`
	// the ticket of the button
	Ticket string `json:"ticket"`
}

// Code is a code a person typed on a channel, asked as the proof `code` on the bench intake by request and reply: never in an event, never kept.
type Code struct {
	// the code
	Code string `json:"code"`
	// what it is for
	Purpose string `json:"purpose"`
	Sender  Sender `json:"sender"`
}

// ConditionActionsItem is a type of the contract.
type ConditionActionsItem struct {
	Arguments map[string]string `json:"arguments,omitempty"`
	// label
	Label string `json:"label"`
	// level
	Level string `json:"level,omitempty"`
	// machine
	Machine string `json:"machine,omitempty"`
	// verb
	Verb string `json:"verb"`
}

// ConditionSubject is a type of the contract.
type ConditionSubject struct {
	// id
	ID string `json:"id"`
	// machine
	Machine string `json:"machine,omitempty"`
	// scope
	Scope string `json:"scope"`
}

// Condition is a type of the contract.
type Condition struct {
	// the answers it offers
	Actions []ConditionActionsItem `json:"actions,omitempty"`
	// plain words
	Explanation string `json:"explanation,omitempty"`
	// plain words
	Headline string `json:"headline,omitempty"`
	// the condition's key
	Key string `json:"key"`
	// what it needs
	Needs string `json:"needs,omitempty"`
	// the line said when it is over
	Resolved string `json:"resolved,omitempty"`
	// urgent or warning
	Severity string `json:"severity,omitempty"`
	// raised or cleared
	State   string           `json:"state"`
	Subject ConditionSubject `json:"subject"`
	// one line
	Summary string `json:"summary,omitempty"`
	// the form's version, 1
	V int64 `json:"v"`
}

// Failed is a message a channel could not deliver, said on the bench intake as the event `failed`.
type Failed struct {
	// when, RFC 3339
	At time.Time `json:"at"`
	// the message's handle
	Handle string `json:"handle"`
	// trying again cannot help
	Permanent bool `json:"permanent,omitempty"`
	// why
	Why string `json:"why"`
}

// LinkAsked is somebody on a channel asking to be linked as the operator, said on the bench intake as the event `link`.
type LinkAsked struct {
	// when, RFC 3339
	At time.Time `json:"at"`
	// the channel's own for this arrival
	ID     string `json:"id"`
	Sender Sender `json:"sender"`
}

// Message is the work a channel takes on the bench channel: shown with buttons (show), shown again in place (edit) or said (send); the words are the router's, shown as given.
type Message struct {
	// its body
	Body string `json:"body"`
	// the answers it offers (none for a send)
	Buttons []Button `json:"buttons,omitempty"`
	// the router's name for it, the same across a show and its edits
	Handle string `json:"handle"`
	// its secondary words after the body and the buttons: who asked and when, what each answer does, when it expires, the ask's details
	Note string `json:"note,omitempty"`
	// the choice or link request this answers, by its id: the channel shows it where that was made
	Reply string `json:"reply,omitempty"`
	// the words carry something shown once (a link's code): the channel keeps no copy
	Secret bool `json:"secret,omitempty"`
	// shown without notifying
	Silent bool `json:"silent,omitempty"`
	// its title
	Title string `json:"title"`
	// the account linked as the operator on this kind, where the channel sends what is not a reply; empty when none is linked
	To string `json:"to,omitempty"`
	// urgent
	Urgent bool `json:"urgent,omitempty"`
}

// Option is a type of the contract.
type Option struct {
	// the digest of exactly what the asker performs when it is chosen
	Binds string `json:"binds,omitempty"`
	// what it does, in plain words
	Does string `json:"does"`
	// the option's id
	ID string `json:"id"`
	// the button's label
	Label string `json:"label"`
	// the proof its answer needs
	Level string `json:"level"`
}

// Person is a type of the contract.
type Person struct {
	// the name shown
	Display string `json:"display,omitempty"`
	// the account
	Identity string `json:"identity"`
	// the channel kind
	Kind string `json:"kind"`
	// how the router knew
	Verified string `json:"verified"`
	// the role
	Who string `json:"who"`
}

// ProofAnswer is the router's answer to a proof.
type ProofAnswer struct {
	// whether it was taken
	Accepted bool `json:"accepted"`
	// words to say to the person
	Words string `json:"words"`
}

// Sender is who a channel's service says sent something; the router alone judges whether that is the operator.
type Sender struct {
	// whether the service authenticated it
	Authenticated bool `json:"authenticated"`
	// the name it shows
	Display string `json:"display,omitempty"`
	// the account
	Identity string `json:"identity"`
}

// Standing is what a channel says of itself at least every five minutes and whenever it changes, on the bench intake as the event `standing`.
type Standing struct {
	// when, RFC 3339
	At time.Time `json:"at"`
	// its edits notify nobody
	EditsSilently bool `json:"edits-silently,omitempty"`
	// it can send now
	Ready bool `json:"ready"`
	// why not
	Why string `json:"why,omitempty"`
}

// Warrant is a type of the contract.
type Warrant struct {
	// what it was about
	About string `json:"about,omitempty"`
	// the ask
	Ask string `json:"ask"`
	// the digest of the ask as the router took it
	AskDigest string `json:"ask-digest,omitempty"`
	// its asker
	Asker string `json:"asker"`
	// when, RFC 3339
	At string  `json:"at"`
	By *Person `json:"by,omitempty"`
	// the module it came through
	Channel string `json:"channel,omitempty"`
	// its label
	Label string `json:"label,omitempty"`
	// its level
	Level string `json:"level,omitempty"`
	// the option chosen
	Option  string `json:"option,omitempty"`
	Outcome string `json:"outcome"`
	// the proofs present
	Proofs []string `json:"proofs,omitempty"`
	// why it ended without a choice, or what refused it
	Words string `json:"words,omitempty"`
}

// The values of Warrant's outcome.
const (
	WarrantOutcomeChosen    = "chosen"
	WarrantOutcomeExpired   = "expired"
	WarrantOutcomeCancelled = "cancelled"
	WarrantOutcomeReplaced  = "replaced"
	WarrantOutcomeRefused   = "refused"
)

// OpenInput is what open takes.
type OpenInput struct {
}

// OpenAnswer is what open answers.
type OpenAnswer = map[string]any

// HistoryInput is what history takes.
type HistoryInput struct {
	// at most this many of each (default 50)
	Limit int64 `json:"limit,omitempty"`
}

// HistoryAnswer is what history answers.
type HistoryAnswer = map[string]any

// NotifyInput is what notify takes.
type NotifyInput struct {
	// it is over
	Clear bool `json:"clear,omitempty"`
	// one or two plain sentences
	Explanation string `json:"explanation,omitempty"`
	// plain words
	Headline string `json:"headline,omitempty"`
	// the message's key
	Key string `json:"key,omitempty"`
	// the line said when it is over
	Resolved string `json:"resolved,omitempty"`
	Severity string `json:"severity,omitempty"`
	// what it is about
	Subject string `json:"subject,omitempty"`
	// one line
	Summary string `json:"summary,omitempty"`
}

// The values of NotifyInput's severity.
const (
	NotifyInputSeverityUrgent  = "urgent"
	NotifyInputSeverityWarning = "warning"
)

// NotifyAnswer is what notify answers.
type NotifyAnswer = map[string]any

// TellInput is what tell takes.
type TellInput struct {
	// plain words
	Headline string `json:"headline,omitempty"`
	// one or two plain lines
	Lines []string `json:"lines,omitempty"`
	// what it is about
	Subject string `json:"subject,omitempty"`
}

// TellAnswer is what tell answers.
type TellAnswer = map[string]any

// AsksInput is what asks takes.
type AsksInput struct {
}

// AsksAnswer is what asks answers.
type AsksAnswer = map[string]any

// AskAccept is the body of ask.
type AskAccept = Ask

// CancelAccept is the body of cancel.
type CancelAccept struct {
	// the ask's id
	ID string `json:"id"`
}

// ConditionAccept is the body of condition.
type ConditionAccept = Condition

// DecidedEvent is the body of the event decided.
type DecidedEvent = Warrant

// OfferedHolderEvent is the body of the holder's event offered.
type OfferedHolderEvent struct {
	// its asker
	Asker string `json:"asker"`
	// the channels it was offered on
	Channels []string `json:"channels,omitempty"`
	// its headline
	Headline string `json:"headline,omitempty"`
	// the ask's id
	ID string `json:"id"`
}

// ClosedHolderEvent is the body of the holder's event closed.
type ClosedHolderEvent struct {
	// its asker
	Asker string `json:"asker"`
	How   string `json:"how"`
	// the ask's id
	ID string `json:"id"`
}

// The values of ClosedHolderEvent's how.
const (
	ClosedHolderEventHowAnswered  = "answered"
	ClosedHolderEventHowExpired   = "expired"
	ClosedHolderEventHowCancelled = "cancelled"
	ClosedHolderEventHowReplaced  = "replaced"
	ClosedHolderEventHowUnlinked  = "unlinked"
)

// AsksByAskerIDValue is one value of the state asks under the key <asker>.<id>.
type AsksByAskerIDValue struct {
	// how it ended, in words
	Answer string `json:"answer,omitempty"`
	// its asker
	Asker string `json:"asker"`
	// its asker has been told how it ended
	AskerTold bool `json:"asker_told,omitempty"`
	// when it ends unanswered, RFC 3339
	Expires string `json:"expires"`
	// its headline
	Headline string `json:"headline"`
	// <asker>.<id>
	Key string `json:"key"`
	// the channels it was offered on
	OfferedOn []string `json:"offered_on,omitempty"`
	// when it was opened, RFC 3339
	Opened string `json:"opened"`
	// how it stands: open, chosen, expired, cancelled, replaced or refused
	State string `json:"state"`
}