waitlists

type List struct {

	// CreatedAt is when the list was opened. It is the database's clock rather
	// than the application's, read back by the write — see waitlists/migrations.
	CreatedAt time.Time `json:"createdAt"`

	// ClosesAt is when the list stops taking signups. Required.
	//
	// It is a value rather than a pointer, and the column behind it is NOT NULL,
	// which is the one shape in this package worth arguing about — see the
	// package documentation. A list whose end is not yet decided names a far
	// horizon and is brought in by an update; a list that should stop this
	// instant is archived.
	ClosesAt time.Time `json:"closesAt"`

	// LastUpdatedAt is when the list last changed, or nil for one that has not
	// been edited.
	LastUpdatedAt *time.Time `json:"lastUpdatedAt"`

	// ArchivedAt is when the list was retired. An archived list is excluded from
	// every read that does not ask for archived rows, and takes no further
	// signups; the signups already against it are left alone, because archiving
	// is not erasure.
	ArchivedAt *time.Time `json:"archivedAt"`

	// ID identifies the list. Minted on write when empty.
	ID string `json:"id"`

	// Name is what the list is called, for whoever administers it and for
	// whatever renders the signup form. Required.
	//
	// It is not unique and is not a handle: a list is addressed by its id
	// everywhere in this package, so two lists may share a name and neither is
	// reachable by it.
	Name string `json:"name"`

	// Description is prose about what people are queueing for.
	Description string `json:"description"`

	// Scope is whose list this is. See the tenancy package.
	Scope tenancy.Scope `json:"scope"`
	// contains filtered or unexported fields
}

type ListStore interface {
	// CreateList opens a waitlist and returns it as stored, with the id it was
	// minted under and the creation time the database assigned.
	//
	// It refuses a list with no name and one with no closing time. There is no
	// default for the latter — see ErrEmptyClosesAt.
	CreateList(ctx context.Context, scope tenancy.Scope, list *List) (*List, error)

	// GetList reads one live list by id.
	GetList(ctx context.Context, scope tenancy.Scope, listID string) (*List, error)

	// ListLists pages the scope's catalog, open and closed alike. It is the
	// administrative read.
	ListLists(ctx context.Context, scope tenancy.Scope, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[List], error)

	// ListOpenLists pages the lists still taking signups: live, and not yet
	// past their closing time as of the store's clock.
	//
	// It is the public read — what a "join the waitlist" page offers — and it
	// is a separate statement rather than a filter applied to ListLists'
	// results, because a page filtered after the fact is a page whose size the
	// caller cannot rely on.
	ListOpenLists(ctx context.Context, scope tenancy.Scope, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[List], error)

	// UpdateList rewrites a list's name, description and closing time.
	//
	// Moving the closing time is how a list is extended or brought in, and it
	// is not guarded against the signups already on it: a list closed early
	// keeps everybody who joined while it was open, and reopening one lets the
	// next person through. What it will not do is revive an archived list.
	UpdateList(ctx context.Context, scope tenancy.Scope, list *List) error

	// ArchiveList retires a list.
	//
	// The signups against it are left alone and stay readable, because archiving
	// is not erasure. What it does do is close the list to new signups
	// immediately, whatever its closing time says — see List.OpenAt.
	ArchiveList(ctx context.Context, scope tenancy.Scope, listID string) error
}

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

type SQLStoreOption func(*SQLStore)

type Signup struct {

	// CreatedAt is when they joined, which is also the order they joined in —
	// the id sorts by creation time, and every page here walks it.
	CreatedAt time.Time `json:"createdAt"`

	// LastUpdatedAt is when the row last changed, or nil for one nobody has
	// touched since it was written.
	LastUpdatedAt *time.Time `json:"lastUpdatedAt"`

	// StatusChangedAt is when the signup last moved through the lifecycle, or
	// nil for one that is still where it started.
	//
	// It is not LastUpdatedAt, and the difference is the point: an administrator
	// fixing a typo in Notes changes the row without moving anybody, and the
	// reminder that goes out three days after an invitation is scheduled off
	// this column.
	StatusChangedAt *time.Time `json:"statusChangedAt"`

	// ArchivedAt is when the signup was retired administratively. It is not a
	// withdrawal — see [StatusWithdrawn], which is what somebody asking to come
	// off the list gets.
	ArchivedAt *time.Time `json:"archivedAt"`

	// Subject is who the signup belongs to, where anybody does. The zero value
	// is a signup that names nobody, which is the ordinary case.
	Subject Subject `json:"subject"`

	// ID identifies the signup. Minted on write when empty.
	ID string `json:"id"`

	// ListID is the list this signup is for.
	ListID string `json:"listID"`

	// Contact is the address the list exists to write to, as it was given —
	// [Normalize] is what the digest is taken of, not what this holds, so a
	// mail client renders the capitalization somebody typed.
	//
	// It is empty for a withdrawn signup, which is the whole of what a
	// withdrawal erases from this column.
	Contact string `json:"contact"`

	// ContactDigest is what the row is found by and what survives a withdrawal.
	//
	// It is [SQLStore.Digest] of [Normalize] of the contact, and it is
	// exported because a deployment migrating off a hand-written table has to
	// write the column from the addresses it is holding. It is not reversible,
	// so a caller holding one holds nothing.
	ContactDigest string `json:"contactDigest"`

	// Notes is whatever whoever administers the list wrote about this signup.
	// It is empty for a withdrawn signup.
	Notes string `json:"notes"`

	// Status is where the signup stands.
	Status Status `json:"status"`

	// Scope is whose list this signup is on.
	Scope tenancy.Scope `json:"scope"`
	// contains filtered or unexported fields
}

type SignupStore interface {
	// Join adds somebody to a list.
	//
	// It refuses a list that is closed or missing (ErrListClosed,
	// ErrListNotFound), a contact already on the list (ErrAlreadySignedUp), and
	// a contact that has withdrawn from it (ErrContactWithdrawn) — the last of
	// which is the obligation this package is shaped around and outlives the
	// address it is about.
	//
	// The signup's Contact is stored as it was given and digested as
	// [Normalize] renders it, so two capitalizations of one address are one
	// person. Status and the timestamps are the store's; whatever the caller
	// set on them is ignored.
	Join(ctx context.Context, scope tenancy.Scope, listID string, signup *Signup) (*Signup, error)

	// GetSignup reads one live signup by id, on the list it belongs to.
	GetSignup(ctx context.Context, scope tenancy.Scope, listID, signupID string) (*Signup, error)

	// GetSignupByContact reads one live signup by the address it was made with,
	// which is the read behind "am I already on this list" and the read an
	// unsubscribe link resolves.
	//
	// The contact is normalized and digested, so it is found by whichever
	// capitalization the caller has. A withdrawn signup is still a live row and
	// comes back as one, with its contact blank and its status saying why —
	// which is what lets an unsubscribe page tell somebody they are already off
	// the list rather than that they were never on it.
	GetSignupByContact(ctx context.Context, scope tenancy.Scope, listID, contact string) (*Signup, error)

	// ListSignups pages one list's live signups, oldest first by default, which
	// is the order they joined in.
	ListSignups(ctx context.Context, scope tenancy.Scope, listID string, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[Signup], error)

	// ListSignupsForSubject pages the signups belonging to one principal across
	// every list in the scope. It is the read a profile page makes and the one a
	// data privacy export walks.
	//
	// A withdrawn signup is not among them: a withdrawal blanks the subject
	// reference along with the contact, so the row that remembers a suppression
	// no longer says whose it was.
	ListSignupsForSubject(ctx context.Context, scope tenancy.Scope, subject Subject, filter *filtering.QueryFilter) (*filtering.QueryFilteredResult[Signup], error)

	// UpdateSignupNotes rewrites the operator's note against a signup.
	//
	// It is the one write that touches a signup without moving it, and it
	// deliberately leaves StatusChangedAt alone — a typo fixed in a note must
	// not reschedule the reminder somebody's invitation started.
	UpdateSignupNotes(ctx context.Context, scope tenancy.Scope, listID, signupID, notes string) error

	// Invite moves a waiting signup to invited and stamps the moment.
	//
	// It refuses anything that is not waiting with ErrWrongStatus, and the
	// refusal is the affected-row count of a guarded update rather than a
	// decision made on a read — so two requests inviting the same person send
	// one email between them.
	Invite(ctx context.Context, scope tenancy.Scope, listID, signupID string) error

	// Convert moves an invited signup to converted and stamps the moment. It
	// refuses anything that is not invited with ErrWrongStatus, guarded the same
	// way Invite is.
	Convert(ctx context.Context, scope tenancy.Scope, listID, signupID string) error

	// Withdraw takes somebody off the list at their own request, and erases what
	// the row said about them.
	//
	// It blanks the contact, the notes and the subject reference and keeps the
	// contact digest, which is what lets a later signup from the same address be
	// refused with ErrContactWithdrawn instead of quietly re-subscribing
	// somebody who asked to be left alone. It moves a signup in any status; a
	// second call reports ErrAlreadyWithdrawn rather than restamping the moment
	// they left.
	Withdraw(ctx context.Context, scope tenancy.Scope, listID, signupID string) error

	// ArchiveSignup retires a signup administratively.
	//
	// It is not a withdrawal and must not be used as one: it hides the row from
	// every read that does not ask for archived rows and changes nothing about
	// what the row holds, so the contact is still stored and nothing suppresses
	// a re-signup — the uniqueness covers archived rows, so what the next
	// attempt gets is ErrAlreadySignedUp. Somebody asking to come off a list
	// wants Withdraw.
	ArchiveSignup(ctx context.Context, scope tenancy.Scope, listID, signupID string) error
}

type Status string

type Store interface {
	ListStore
	SignupStore
}

type Subject struct {
	// Type says what kind of principal this is.
	Type SubjectType `json:"type"`
	// ID identifies the principal within that type.
	ID string `json:"id"`
}

type SubjectType string