agency

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 45 Imported by: 0

Documentation

Overview

Package agency implements agency accounts (design expansion phase 8, M32; channels and agencies brief §3.10): an agency runs one instance for its clients, each in an ordinary workspace of its own.

  • Agency mode, turned on in Instance admin › Instance & updates (one agency per instance).
  • Staff at instance level: agency managers (every client) and account managers (the clients they're assigned to). Instance admins are agency managers.
  • Assignments are ordinary workspace memberships (source "agency"), behind the escalation guard: you can assign only roles whose permissions you hold in that workspace.
  • Clients, their account manager, rebill rates and usage per month.
  • Workspace templates and the shared library, copied into clients.
  • The agency overview and search across clients.

Nothing here moves data between clients: each keeps its own providers, domains, contacts, suppressions, consent, keys and audit log, and copies from the library or a template are new rows in the client's workspace.

Index

Constants

View Source
const (
	KindSection       = "section"
	KindTemplate      = "template"
	KindAutomation    = "automation"
	KindTransactional = "transactional"
	KindSMS           = "sms"
)

Library item kinds and where their copies go.

View Source
const CodeAgencyOff = "agency_off"

CodeAgencyOff is the problem code while agency mode is off.

Variables

This section is empty.

Functions

func Initials

func Initials(name string) string

Initials of a workspace or a person: "Contoso Coffee" → "CC", "Wide World Importers" → "WW".

func Register

func Register(h huma.API, s *Service)

Register adds the agency's operations.

func RegisterJobs

func RegisterJobs(reg *jobs.Registry, s *Service, log *slog.Logger)

RegisterJobs adds the hourly refresh of health and usage.

func SeedLibraryCopy

func SeedLibraryCopy(ctx context.Context, tx pgx.Tx, itemID uuid.UUID, version int32, workspaceID, by uuid.UUID, at time.Time) (uuid.UUID, error)

SeedLibraryCopy makes a copy of one version of a library item in a workspace, as "Copy to a client" does, and records it. Sections, campaign templates and automation templates only.

func SeedLibraryVersion

func SeedLibraryVersion(kind string, c LibraryContent) (summary []string, fields json.RawMessage)

SeedLibraryVersion returns what a library item's version stores besides its content: the lines its diff compares and the Liquid fields it needs.

Types

type AgencyAddToLibrary

type AgencyAddToLibrary struct {
	Kind string `json:"kind" enum:"section,template,automation,transactional"`
	ID   string `json:"id" format:"uuid" doc:"The saved section, campaign template, automation or transactional template"`
	// Name defaults to the item's own name.
	Name string `json:"name,omitempty" maxLength:"120"`
	// NewVersionOf saves it as a new version of this library item.
	NewVersionOf string `json:"newVersionOf,omitempty" format:"uuid"`
	Note         string `json:"note,omitempty" maxLength:"200"`
}

AgencyAddToLibrary adds a workspace's item to the library, or saves it as a new version of the library item it was copied from.

type AgencyApproval

type AgencyApproval struct {
	ID         string             `json:"id"`
	Workspace  AgencyWorkspaceRef `json:"workspace"`
	Campaign   string             `json:"campaign"`
	CampaignID string             `json:"campaignId"`
	// WaitingFor are the people whose approval it waits for: the client's
	// approvers under client sign-off.
	WaitingFor  []string   `json:"waitingFor"`
	RequestedBy string     `json:"requestedBy"`
	RequestedAt time.Time  `json:"requestedAt"`
	SendAt      *time.Time `json:"sendAt,omitempty"`
	Timezone    string     `json:"timezone,omitempty"`
	Recipients  int64      `json:"recipients"`
	// ClientSignoff: the request waits for the client's own approver.
	ClientSignoff bool `json:"clientSignoff"`
}

AgencyApproval is a send waiting for approval in a client.

type AgencyAssignInput

type AgencyAssignInput struct {
	StaffID     string `json:"staffId"`
	WorkspaceID string `json:"workspaceId" format:"uuid"`
	RoleID      string `json:"roleId" format:"uuid"`
}

AgencyAssignInput assigns a staff member to a workspace with a role.

type AgencyAssignableRole

type AgencyAssignableRole struct {
	AgencyRoleRef
	Description string `json:"description"`
	// Grantable is false for roles whose permissions you don't hold there
	// ("Not yours to give") and for Owner (only a transfer makes an Owner).
	Grantable bool   `json:"grantable"`
	Reason    string `json:"reason,omitempty"`
}

AgencyAssignableRole is a role in the assignment dropdown.

type AgencyAssignmentCell

type AgencyAssignmentCell struct {
	StaffID string `json:"staffId"`
	// Role is empty when they aren't assigned there.
	Role   *AgencyRoleRef `json:"role,omitempty"`
	Source string         `json:"source,omitempty"`
}

AgencyAssignmentCell is one staff member in one workspace.

type AgencyAssignmentKeys

type AgencyAssignmentKeys struct {
	Keys []AgencyKeyRef `json:"keys"`
}

AgencyAssignmentKeys are the keys a staff member created in a workspace, for the question removing the assignment asks.

type AgencyAssignmentRow

type AgencyAssignmentRow struct {
	Workspace AgencyWorkspaceRef     `json:"workspace"`
	Cells     []AgencyAssignmentCell `json:"cells"`
	// Roles are the workspace's roles, each with whether you can assign it.
	Roles []AgencyAssignableRole `json:"roles"`
	// CanAssign: you can change who works here and their roles: you hold
	// agency:manage, or a role here that manages its team (team:manage).
	CanAssign bool `json:"canAssign"`
	// AssignReason says why you can't, for the controls kept disabled.
	AssignReason string `json:"assignReason,omitempty"`
	// YourRole is your own role here, for "Your role here".
	YourRole string `json:"yourRole,omitempty"`
}

AgencyAssignmentRow is one workspace of the assignment matrix.

type AgencyAssignmentSpec

type AgencyAssignmentSpec struct {
	WorkspaceID string `json:"workspaceId" format:"uuid"`
	RoleID      string `json:"roleId" format:"uuid"`
}

AgencyAssignmentSpec is a client and a role.

type AgencyBilledMonth

type AgencyBilledMonth struct {
	Month    string      `json:"month"`
	Rate     *AgencyRate `json:"rate,omitempty"`
	ToRebill *float64    `json:"toRebill,omitempty"`
}

AgencyBilledMonth is a past month's rebill.

type AgencyClientCreated

type AgencyClientCreated struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	// Plan is what the template added, when one was used.
	Plan       *AgencyTemplatePlan         `json:"plan,omitempty"`
	Setup      *AgencySetup                `json:"setup,omitempty"`
	Invitation *team.TeamCreatedInvitation `json:"invitation,omitempty"`
	CreatedAt  time.Time                   `json:"createdAt"`
	CreatedBy  string                      `json:"createdBy"`
}

AgencyClientCreated says what creating the client did.

type AgencyClientDelete

type AgencyClientDelete struct {
	Confirm string `json:"confirm" doc:"The client's name, typed"`
}

AgencyClientDelete confirms deleting a client.

type AgencyClientDeleted

type AgencyClientDeleted struct {
	RestoreUntil time.Time `json:"restoreUntil"`
}

AgencyClientDeleted says until when it can be restored.

type AgencyClientDetails

type AgencyClientDetails struct {
	Workspace      AgencyWorkspaceRef   `json:"workspace"`
	AccountManager *AgencyPersonRef     `json:"accountManager,omitempty"`
	Rate           *AgencyRate          `json:"rate,omitempty"`
	RateSince      *time.Time           `json:"rateSince,omitempty"`
	ClientSince    time.Time            `json:"clientSince"`
	Template       string               `json:"template,omitempty"`
	Providers      []string             `json:"providers"`
	People         []AgencyClientPerson `json:"people"`
	Billed         []AgencyBilledMonth  `json:"billed"`
	CanSeeCosts    bool                 `json:"canSeeCosts"`
	// Staff are the agency's staff who can be the client's contact.
	Staff []AgencyPersonRef `json:"staff"`
	// CanManage: you can change the contact (agency:manage).
	CanManage bool `json:"canManage"`
}

AgencyClientDetails is what the agency keeps about a client: its contact, rate, origin, providers, people and the last months' rebill.

type AgencyClientInput

type AgencyClientInput struct {
	AccountManagerID string `json:"accountManagerId,omitempty" format:"uuid"`
}

AgencyClientInput changes a client's details.

type AgencyClientNew

type AgencyClientNew struct {
	Name     string `json:"name" minLength:"1" maxLength:"80"`
	Slug     string `json:"slug,omitempty" maxLength:"63" doc:"Defaults to the name in lowercase with hyphens"`
	Timezone string `json:"timezone" minLength:"1" maxLength:"64"`
	// TemplateID is the workspace template to start from (optional).
	TemplateID string `json:"templateId,omitempty" format:"uuid"`
	// OwnerID is the client workspace's Owner: an agency manager.
	OwnerID string `json:"ownerId" format:"uuid"`
	// AccountManagerIDs are assigned as Admin; the first is the client's contact.
	AccountManagerIDs []string `json:"accountManagerIds,omitempty" maxItems:"20"`
	// FirstPerson is the client's first person, invited as Client approver
	// or Client viewer.
	FirstPerson *AgencyFirstPerson `json:"firstPerson,omitempty"`
}

AgencyClientNew creates a client workspace.

type AgencyClientPerson

type AgencyClientPerson struct {
	Name    string        `json:"name"`
	Email   string        `json:"email"`
	Role    AgencyRoleRef `json:"role"`
	Invited bool          `json:"invited"`
}

AgencyClientPerson is one of the client's own people.

type AgencyClientPulse

type AgencyClientPulse struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Contacts  int64              `json:"contacts"`
	Health    *AgencyHealth      `json:"health,omitempty"`
	NextSend  *AgencySend        `json:"nextSend,omitempty"`
	// Draft names the latest draft when nothing is scheduled ("Holiday
	// catalog is a draft").
	Draft     string           `json:"draft,omitempty"`
	Approvals []AgencyApproval `json:"approvals"`
	Incidents []AgencyIncident `json:"incidents"`
	Setup     *AgencySetup     `json:"setup,omitempty"`
}

AgencyClientPulse is one row's details: health, the next send, the approvals and incidents, and a new client's setup.

type AgencyClientRow

type AgencyClientRow struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	// AccountManager is the client's contact at the agency.
	AccountManager *AgencyPersonRef `json:"accountManager,omitempty"`
	Contacts       int64            `json:"contacts"`
	Attention      bool             `json:"attention"`
	// AttentionReasons: health, incident, approval.
	AttentionReasons []string      `json:"attentionReasons"`
	Health           *AgencyHealth `json:"health,omitempty"`
	// Mine: you're assigned to this client.
	Mine bool `json:"mine"`
	// Role is your role there, when you're assigned.
	Role       *AgencyRoleRef `json:"role,omitempty"`
	NextSendAt *time.Time     `json:"nextSendAt,omitempty"`
	// SettingUp: a new client whose setup steps aren't done yet.
	SettingUp bool `json:"settingUp"`
	// CreatedAt is when it joined the agency.
	CreatedAt time.Time `json:"createdAt"`
	Template  string    `json:"template,omitempty"`
}

AgencyClientRow is a client in the overview's table and the switcher.

type AgencyCopyInput

type AgencyCopyInput struct {
	WorkspaceID string `json:"workspaceId" format:"uuid"`
}

AgencyCopyInput copies a library item into a client.

type AgencyCopyPath

type AgencyCopyPath struct {
	CopyID string `path:"copyId" format:"uuid"`
}

AgencyCopyPath names a copy of a library item.

type AgencyCopyResult

type AgencyCopyResult struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Kind      string             `json:"kind"`
	TargetID  string             `json:"targetId"`
	Name      string             `json:"name"`
}

AgencyCopyResult is the copy made.

type AgencyCopyTarget

type AgencyCopyTarget struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	// CanCopy: you can edit that kind of content there.
	CanCopy bool   `json:"canCopy"`
	Reason  string `json:"reason,omitempty"`
}

AgencyCopyTarget is a client an item can be copied to.

type AgencyCounts

type AgencyCounts struct {
	All       int `json:"all"`
	Attention int `json:"attention"`
	Mine      int `json:"mine"`
	Sends     int `json:"sends"`
}

AgencyCounts are the filter chips' numbers.

type AgencyEnteredPrice

type AgencyEnteredPrice struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Provider  string             `json:"provider"`
	Monthly   float64            `json:"monthly"`
}

AgencyEnteredPrice is a provider whose cost is a price set in the workspace (no per-message pricing from its API).

type AgencyFailover

type AgencyFailover struct {
	Stream string `json:"stream"`
	To     string `json:"to"`
}

AgencyFailover is a stream that moved to another provider.

type AgencyFirstPerson

type AgencyFirstPerson struct {
	Email string `json:"email" maxLength:"254"`
	Role  string `json:"role" enum:"client_approver,client_viewer"`
}

AgencyFirstPerson is the client's first person.

type AgencyGalleryCopy

type AgencyGalleryCopy struct {
	ID       string `json:"id"`
	ItemID   string `json:"itemId"`
	Kind     string `json:"kind"`
	TargetID string `json:"targetId"`
	Name     string `json:"name"`
	Version  int    `json:"version"`
	Latest   int    `json:"latest"`
}

AgencyGalleryCopy is a copy of a library item in this workspace.

type AgencyGalleryView

type AgencyGalleryView struct {
	Agency string              `json:"agency"`
	Items  []AgencyLibraryItem `json:"items"`
	// Copies are this workspace's copies, with the library's latest version.
	Copies []AgencyGalleryCopy `json:"copies"`
	// CanUse: you can edit that kind of content here.
	CanUse bool   `json:"canUse"`
	Reason string `json:"reason,omitempty"`
	// You is how you work here ("Mei Lin · Admin in Contoso Coffee, via Northwind Studio").
	Role string `json:"role,omitempty"`
}

AgencyGalleryView is the "Northwind library" tab of a client's composer gallery and automation starters: the items that can be used there.

type AgencyHealth

type AgencyHealth struct {
	// State is ready, or pending while the client has no sending domain.
	State string `json:"state" enum:"ready,pending,unknown"`
	Score int    `json:"score"`
	Tone  string `json:"tone"`
	// Trend is one score per day, oldest first (up to 30).
	Trend []int `json:"trend"`
	// HostRepute is clean, listed or stale; empty when it isn't connected.
	HostRepute string    `json:"hostRepute,omitempty"`
	Listings   int       `json:"listings,omitempty"`
	CheckedAt  time.Time `json:"checkedAt"`
}

AgencyHealth is a client's sender health: the Overview's score, its 30-day trend and HostRepute's view where it's connected.

type AgencyIncident

type AgencyIncident struct {
	ID        string             `json:"id"`
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Kind      string             `json:"kind" enum:"auto_pause,provider_down,webhooks_silent,sms_budget_reached,store_disconnected"`
	// State: ongoing, or how it ended (resumed, cancelled, recovered).
	State      string     `json:"state" enum:"ongoing,resumed,cancelled,recovered"`
	OccurredAt time.Time  `json:"occurredAt"`
	ResolvedAt *time.Time `json:"resolvedAt,omitempty"`
	Campaign   string     `json:"campaign,omitempty"`
	Provider   string     `json:"provider,omitempty"`
	// What tripped an auto-pause: "yahoo", "deferral", 4.1, 3.
	MailboxProvider string  `json:"mailboxProvider,omitempty"`
	Metric          string  `json:"metric,omitempty"`
	Value           float64 `json:"value,omitempty"`
	Threshold       float64 `json:"threshold,omitempty"`
	// How it ended: who resumed, and whether with changes.
	ResolvedBy  string `json:"resolvedBy,omitempty"`
	WithChanges bool   `json:"withChanges,omitempty"`
	// Failovers are the streams that moved to another provider meanwhile.
	Failovers []AgencyFailover `json:"failovers"`
	// BroadcastHeld: a Broadcast was held while the provider was down.
	BroadcastHeld bool   `json:"broadcastHeld"`
	Title         string `json:"title"`
	Detail        string `json:"detail"`
}

AgencyIncident is an incident in a client in the last 7 days.

type AgencyItemPath

type AgencyItemPath struct {
	ItemID string `path:"itemId" format:"uuid"`
}

AgencyItemPath names a library item.

type AgencyKeyRef

type AgencyKeyRef struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Kind   string `json:"kind" enum:"api_key,mcp_agent"`
	Prefix string `json:"prefix"`
}

AgencyKeyRef is an API key or agent.

type AgencyLibraryAdded

type AgencyLibraryAdded struct {
	ID      string `json:"id"`
	Version int    `json:"version"`
}

AgencyLibraryAdded says where it went.

type AgencyLibraryCopy

type AgencyLibraryCopy struct {
	ID        string             `json:"id"`
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Version   int                `json:"version"`
	Behind    bool               `json:"behind"`
	CopiedAt  time.Time          `json:"copiedAt"`
	// CanUpdate: you can edit it there and it can be updated in place.
	CanUpdate bool   `json:"canUpdate"`
	Reason    string `json:"reason,omitempty"`
}

AgencyLibraryCopy is a copy in a client.

type AgencyLibraryDetail

type AgencyLibraryDetail struct {
	Item AgencyLibraryItem `json:"item"`
	// Preview is the item's HTML (sections and templates) or text (SMS).
	Preview  string                 `json:"preview,omitempty"`
	Subject  string                 `json:"subject,omitempty"`
	Versions []AgencyLibraryVersion `json:"versions"`
	Copies   []AgencyLibraryCopy    `json:"copies"`
	// Diff compares the oldest version a copy is on with the latest.
	Diff *AgencyLibraryDiff `json:"diff,omitempty"`
	// Clients are where you can copy it.
	Clients []AgencyCopyTarget `json:"clients"`
	CanEdit bool               `json:"canEdit"`
}

AgencyLibraryDetail is one item: its preview, versions, the fields it needs, and the copies in clients with the diff of the ones behind.

type AgencyLibraryDiff

type AgencyLibraryDiff struct {
	From  int        `json:"from"`
	To    int        `json:"to"`
	Lines []DiffLine `json:"lines"`
}

AgencyLibraryDiff is what changed between two versions.

type AgencyLibraryEdit

type AgencyLibraryEdit struct {
	Name string `json:"name" minLength:"1" maxLength:"120"`
	// FromCopy publishes that copy's current content as a new version.
	FromCopy string `json:"fromCopy,omitempty" format:"uuid"`
	Note     string `json:"note,omitempty" maxLength:"200"`
}

AgencyLibraryEdit renames an item or publishes a client's copy as its next version.

type AgencyLibraryField

type AgencyLibraryField struct {
	Key      string `json:"key"`
	Fallback string `json:"fallback,omitempty"`
}

AgencyLibraryField is a Liquid field an item needs.

type AgencyLibraryItem

type AgencyLibraryItem struct {
	ID        string    `json:"id"`
	Kind      string    `json:"kind" enum:"section,template,automation,transactional,sms"`
	Name      string    `json:"name"`
	Version   int       `json:"version"`
	UpdatedAt time.Time `json:"updatedAt"`
	UpdatedBy string    `json:"updatedBy,omitempty"`
	// Clients counts the clients with a copy; Behind the copies on an older version.
	Clients int `json:"clients"`
	Copies  int `json:"copies"`
	Behind  int `json:"behind"`
	// Fields are the Liquid fields it needs, with their fallbacks.
	Fields []AgencyLibraryField `json:"fields"`
	// Thumb is the gallery wireframe (sections and templates); Body an SMS text.
	Thumb json.RawMessage `json:"thumb,omitempty"`
	Body  string          `json:"body,omitempty"`
	// Steps counts an automation template's steps.
	Steps int `json:"steps,omitempty"`
	// Background and Accent colour the wireframe: the first section's
	// background and the first button's colour.
	Background string `json:"background,omitempty"`
	Accent     string `json:"accent,omitempty"`
	// Columns is the most columns a section has (a row of products).
	Columns int `json:"columns,omitempty"`
}

AgencyLibraryItem is an item of the shared library.

type AgencyLibraryVersion

type AgencyLibraryVersion struct {
	Version int       `json:"version"`
	At      time.Time `json:"at"`
	By      string    `json:"by,omitempty"`
	Note    string    `json:"note,omitempty"`
}

AgencyLibraryVersion is one version of an item.

type AgencyLibraryView

type AgencyLibraryView struct {
	Items  []AgencyLibraryItem `json:"items"`
	Counts map[string]int      `json:"counts"`
	Total  int                 `json:"total"`
	// CanEdit: you hold agency:library (add, change and remove items).
	CanEdit bool     `json:"canEdit"`
	Reason  string   `json:"reason,omitempty"`
	Helpers []string `json:"helpers"`
}

AgencyLibraryView is the Library page's shared library.

type AgencyMe

type AgencyMe struct {
	Enabled  bool   `json:"enabled"`
	Name     string `json:"name"`
	Initials string `json:"initials"`
	Host     string `json:"host"`
	// Staff is set for the agency's staff; client people get only Enabled
	// and Name.
	Staff *AgencyMeStaff `json:"staff,omitempty"`
	// Clients are the clients the staff member works in (every one for
	// agency managers), with their health dots.
	Clients []AgencyClientRow `json:"clients"`
	// AgencyWorkspace is the agency's own workspace.
	AgencyWorkspace *AgencyClientRow `json:"agencyWorkspace,omitempty"`
	ClientCount     int              `json:"clientCount"`
	// Home is the workspace the Agency area opens in (its URLs live under
	// a workspace, like Instance admin's): the agency's own when you're a
	// member there, else your first client.
	Home string `json:"home,omitempty"`
}

AgencyMe is what the shell shows about the agency: the switcher's agency entry and clients, the More sheet and the agency area's sidebar.

type AgencyMeStaff

type AgencyMeStaff struct {
	Level       string   `json:"level" enum:"agency_manager,account_manager"`
	Title       string   `json:"title,omitempty"`
	Permissions []string `json:"permissions"`
}

AgencyMeStaff is the signed-in person's place on the staff.

type AgencyModeInput

type AgencyModeInput struct {
	Enabled           bool     `json:"enabled"`
	Name              string   `json:"name,omitempty" maxLength:"80"`
	AgencyWorkspaceID string   `json:"agencyWorkspaceId,omitempty"`
	DefaultTemplateID string   `json:"defaultTemplateId,omitempty"`
	ClientIDs         []string `json:"clientIds,omitempty" maxItems:"1000"`
}

AgencyModeInput saves the agency section.

type AgencyModeView

type AgencyModeView struct {
	Enabled bool `json:"enabled"`
	// Name is the agency's name; the instance name until one is set.
	Name          string     `json:"name"`
	InstanceName  string     `json:"instanceName"`
	EnabledByName string     `json:"enabledByName,omitempty"`
	EnabledAt     *time.Time `json:"enabledAt,omitempty"`
	// AgencyWorkspaceID is the agency's own workspace.
	AgencyWorkspaceID string `json:"agencyWorkspaceId,omitempty"`
	// DefaultTemplateID is the template new clients start from.
	DefaultTemplateID string `json:"defaultTemplateId,omitempty"`
	// Workspaces are every workspace of the instance, marked when it's a
	// client or the agency's own.
	Workspaces []AgencyModeWorkspace `json:"workspaces"`
	Templates  []AgencyTemplateRef   `json:"templates"`
	Clients    int                   `json:"clients"`
}

AgencyModeView is Instance admin › Instance & updates › Agency.

type AgencyModeWorkspace

type AgencyModeWorkspace struct {
	ID       string `json:"id"`
	Slug     string `json:"slug"`
	Name     string `json:"name"`
	Initials string `json:"initials"`
	Color    string `json:"color"`
	Client   bool   `json:"client"`
	Agency   bool   `json:"agency"`
}

AgencyModeWorkspace is a workspace in the agency section.

type AgencyNotification

type AgencyNotification struct {
	ID        string             `json:"id"`
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Kind      string             `json:"kind"`
	Severity  string             `json:"severity" enum:"info,ok,warn,bad"`
	Title     string             `json:"title"`
	Summary   string             `json:"summary"`
	Link      string             `json:"link"`
	CreatedAt time.Time          `json:"createdAt"`
	Read      bool               `json:"read"`
}

AgencyNotification is one of a staff member's notifications.

type AgencyNotificationList

type AgencyNotificationList struct {
	Items  []AgencyNotification `json:"items"`
	Unread int64                `json:"unread"`
}

AgencyNotificationList is the bell's latest notifications.

type AgencyOverviewView

type AgencyOverviewView struct {
	Clients         []AgencyClientRow `json:"clients"`
	AgencyWorkspace *AgencyClientRow  `json:"agencyWorkspace,omitempty"`
	Counts          AgencyCounts      `json:"counts"`
	// Approvals waiting, oldest first.
	Approvals []AgencyApproval `json:"approvals"`
	// Incidents in the last 7 days, newest first.
	Incidents []AgencyIncident `json:"incidents"`
	// Sends in the next 7 days across every workspace, soonest first, and
	// the first one after that.
	Sends     []AgencySend `json:"sends"`
	NextAfter *AgencySend  `json:"nextAfter,omitempty"`
	// CanCreate: you can create clients (agency:manage).
	CanCreate bool `json:"canCreate"`
	Manager   bool `json:"manager"`
	// Timezone is yours, for writing send times.
	Timezone string `json:"timezone"`
}

AgencyOverviewView is the agency overview: the summary, the three cards and the clients, cheap facts only (each row's details load on their own).

type AgencyPersonRef

type AgencyPersonRef struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Email       string `json:"email"`
	AvatarColor string `json:"avatarColor"`
}

AgencyPersonRef names a person.

type AgencyPlanPart

type AgencyPlanPart struct {
	Added   []string           `json:"added"`
	Renamed []AgencyPlanRename `json:"renamed"`
}

AgencyPlanPart is one kind of content.

type AgencyPlanRename

type AgencyPlanRename struct {
	From string `json:"from"`
	To   string `json:"to"`
}

AgencyPlanRename is a clash renamed on the way in.

type AgencyPlanSkip

type AgencyPlanSkip struct {
	Part       string `json:"part"`
	Permission string `json:"permission"`
}

AgencyPlanSkip is a part left out, and why.

type AgencyProviderCost

type AgencyProviderCost struct {
	Provider string  `json:"provider"`
	Adapter  string  `json:"adapter"`
	Channel  string  `json:"channel"`
	Units    int64   `json:"units"`
	Cost     float64 `json:"cost"`
	// Basis is metered (a price per unit) or plan (a monthly price).
	Basis string `json:"basis" enum:"metered,plan"`
	// Per1000 is the metered price per 1,000 emails.
	Per1000 *float64 `json:"per1000,omitempty"`
	// Entered: the price was set in the workspace, not read from the provider.
	Entered bool `json:"entered"`
}

AgencyProviderCost is one provider's cost in a month.

type AgencyRate

type AgencyRate struct {
	// CostPlusPct adds a percentage to each provider's cost.
	CostPlusPct *float64 `json:"costPlusPct,omitempty" minimum:"0" maximum:"1000"`
	// Per1000Emails is a price per 1,000 emails, counted across every stream.
	Per1000Emails *float64 `json:"per1000Emails,omitempty" minimum:"0" maximum:"100000"`
	// PerSegment is a price per SMS segment delivered or failed.
	PerSegment *float64 `json:"perSegment,omitempty" minimum:"0" maximum:"1000"`
	// MonthlyFee is added once a month.
	MonthlyFee *float64 `json:"monthlyFee,omitempty" minimum:"0" maximum:"10000000"`
	// Flat replaces everything above with one monthly amount.
	Flat *float64 `json:"flat,omitempty" minimum:"0" maximum:"10000000"`
}

AgencyRate is how the agency rebills a client for its usage. The parts can be combined; a flat amount replaces everything else. A rate with no part means the client isn't billed.

func (AgencyRate) Billed

func (r AgencyRate) Billed() bool

Billed reports whether the rate bills anything.

type AgencyRateInput

type AgencyRateInput struct {
	Rate AgencyRate `json:"rate"`
}

AgencyRateInput sets a client's rate.

type AgencyRateSaved

type AgencyRateSaved struct {
	EffectiveFrom time.Time `json:"effectiveFrom"`
}

AgencyRateSaved says from when the rate applies.

type AgencyRebill

type AgencyRebill struct {
	// Cost is the provider cost, rounded.
	Cost float64 `json:"cost"`
	// CostPlus is the percentage on the cost ("15% on cost $95.04").
	CostPlus float64 `json:"costPlus"`
	// Emails is the per-1,000-emails part; Segments the per-segment part.
	Emails   float64 `json:"emails"`
	Segments float64 `json:"segments"`
	Monthly  float64 `json:"monthly"`
	Flat     float64 `json:"flat"`
	// ToRebill is nil when the client isn't billed.
	ToRebill *float64 `json:"toRebill,omitempty"`
}

AgencyRebill is what a client's rate makes of a month's usage. Every part is rounded to the cent, and To rebill is their sum, so the lines of the breakdown always add up to the total.

type AgencyRoleRef

type AgencyRoleRef struct {
	ID      string `json:"id,omitempty"`
	Key     string `json:"key"`
	Name    string `json:"name"`
	Builtin bool   `json:"builtin"`
}

AgencyRoleRef names a role.

type AgencySearchGroup

type AgencySearchGroup struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Hits      []AgencySearchHit  `json:"hits"`
}

AgencySearchGroup is one client's results.

type AgencySearchHit

type AgencySearchHit struct {
	Kind string `json:"kind" enum:"campaign,automation,template,section,form,contact,library"`
	ID   string `json:"id"`
	Name string `json:"name"`
	// Status is the campaign's, automation's or form's; LibraryKind and
	// Version describe a library item.
	Status      string `json:"status,omitempty"`
	LibraryKind string `json:"libraryKind,omitempty"`
	Version     int    `json:"version,omitempty"`
	// Contact details: lists, and when they subscribed or left.
	Lists          []string   `json:"lists,omitempty"`
	LeftLists      []string   `json:"leftLists,omitempty"`
	SubscribedAt   *time.Time `json:"subscribedAt,omitempty"`
	UnsubscribedAt *time.Time `json:"unsubscribedAt,omitempty"`
}

AgencySearchHit is one result.

type AgencySearchResults

type AgencySearchResults struct {
	Query string `json:"query"`
	// Contact is true when the query was an email address: contacts were
	// searched by exact address, and the search was recorded.
	Contact bool                `json:"contact"`
	Groups  []AgencySearchGroup `json:"groups"`
	Library []AgencySearchHit   `json:"library"`
	Total   int                 `json:"total"`
	// Searched counts the clients searched for contacts (where you can see
	// contacts), and Skipped the ones you can't.
	Searched int `json:"searched"`
	Skipped  int `json:"skipped"`
}

AgencySearchResults are the results grouped by client, then the library.

type AgencySend

type AgencySend struct {
	Workspace  AgencyWorkspaceRef `json:"workspace"`
	CampaignID string             `json:"campaignId"`
	Name       string             `json:"name"`
	Status     string             `json:"status"`
	SendAt     time.Time          `json:"sendAt"`
	Timezone   string             `json:"timezone"`
	// Channel is the campaign's (email, sms, push, whatsapp). A campaign
	// sent by email and by text at the same time is one send: Recipients
	// counts its emails (or its push and WhatsApp messages) and Texts its
	// texts.
	Channel    string `json:"channel" enum:"email,sms,push,whatsapp"`
	Recipients int64  `json:"recipients"`
	Texts      int64  `json:"texts,omitempty"`
	// Health is the client's sender health, for the warning badge.
	Health *int `json:"health,omitempty"`
}

AgencySend is a send with a time.

type AgencySetup

type AgencySetup struct {
	Done  int               `json:"done"`
	Total int               `json:"total"`
	Steps []AgencySetupStep `json:"steps"`
}

AgencySetup is a new client's setup: the steps its template asked for.

type AgencySetupStep

type AgencySetupStep struct {
	Key  string `json:"key" enum:"provider,domain,invite,shopify"`
	Done bool   `json:"done"`
	// Detail is the domain to verify, when there is one.
	Detail string `json:"detail,omitempty"`
}

AgencySetupStep is one step: provider, domain, invite or shopify.

type AgencyStaffAdded

type AgencyStaffAdded struct {
	ID       string `json:"id"`
	Assigned int    `json:"assigned"`
	// Invitations are the links created when inviting by email.
	Invitations []team.TeamCreatedInvitation `json:"invitations"`
	Emailed     bool                         `json:"emailed"`
}

AgencyStaffAdded says what adding someone did.

type AgencyStaffCandidate

type AgencyStaffCandidate struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Email       string `json:"email"`
	AvatarColor string `json:"avatarColor"`
}

AgencyStaffCandidate is an account that can join the staff.

type AgencyStaffInput

type AgencyStaffInput struct {
	UserID string `json:"userId,omitempty" format:"uuid" doc:"An account of this instance"`
	Email  string `json:"email,omitempty" maxLength:"254" doc:"Invite by email instead"`
	Level  string `json:"level" enum:"agency_manager,account_manager"`
	Title  string `json:"title,omitempty" maxLength:"60"`
	// Assignments are an account manager's clients and their role in each.
	// Agency managers get Admin in every client.
	Assignments []AgencyAssignmentSpec `json:"assignments,omitempty" maxItems:"500"`
}

AgencyStaffInput adds someone to the staff: an account of the instance, or an email to invite.

type AgencyStaffMember

type AgencyStaffMember struct {
	ID          string `json:"id" doc:"Staff id: the staff row, or admin:<user id> for an instance admin"`
	UserID      string `json:"userId,omitempty" doc:"Empty while an invited person has no account yet"`
	Name        string `json:"name"`
	Email       string `json:"email"`
	AvatarColor string `json:"avatarColor"`
	Level       string `json:"level" enum:"agency_manager,account_manager"`
	// Title is what they do at the agency ("designer").
	Title         string `json:"title,omitempty"`
	InstanceAdmin bool   `json:"instanceAdmin"`
	// Invited: no account yet; they join through the invitations sent to them.
	Invited bool `json:"invited"`
	// EveryClient is true when they work in every client workspace.
	EveryClient bool `json:"everyClient"`
	// Clients names the clients they're assigned to, when not every one.
	Clients []string `json:"clients"`
	// Roles are the roles they hold in their clients, most common first.
	Roles        []AgencyRoleRef `json:"roles"`
	LastActiveAt *time.Time      `json:"lastActiveAt,omitempty"`
	You          bool            `json:"you"`
	// Permissions are the agency permissions they hold: their level's, or
	// fewer when narrowed.
	Permissions []string `json:"permissions"`
}

AgencyStaffMember is one row of Agency › Staff.

type AgencyStaffPath

type AgencyStaffPath struct {
	StaffID string `path:"staffId" maxLength:"80" doc:"A staff id, or admin:<user id> for an instance admin"`
}

AgencyStaffPath names a staff member.

type AgencyStaffRemoveInput

type AgencyStaffRemoveInput struct {
	// RemoveAssignments also removes their memberships in the agency's
	// workspaces; false keeps them as ordinary members.
	RemoveAssignments bool `json:"removeAssignments,omitempty"`
	// RevokeKeys revokes the API keys they created in those workspaces.
	RevokeKeys bool `json:"revokeKeys,omitempty"`
}

AgencyStaffRemoveInput removes someone from the staff.

type AgencyStaffUpdate

type AgencyStaffUpdate struct {
	Level string `json:"level" enum:"agency_manager,account_manager"`
	Title string `json:"title,omitempty" maxLength:"60"`
	// Permissions narrows the level's agency permissions (an account
	// manager without agency:usage); omitted, they hold all of the level's.
	// agency:view is always kept.
	Permissions []string `json:"permissions,omitempty" maxItems:"4" enum:"agency:view,agency:usage,agency:library,agency:manage"`
}

AgencyStaffUpdate changes someone's level or title.

type AgencyStaffView

type AgencyStaffView struct {
	Staff       []AgencyStaffMember   `json:"staff"`
	Assignments []AgencyAssignmentRow `json:"assignments"`
	Clients     int                   `json:"clients"`
	// HasAgencyWorkspace: the matrix ends with the agency's own workspace.
	HasAgencyWorkspace bool `json:"hasAgencyWorkspace"`
	// CanManage: you hold agency:manage (add and remove staff).
	CanManage bool     `json:"canManage"`
	Helpers   []string `json:"helpers"`
	Reason    string   `json:"reason,omitempty"`
}

AgencyStaffView is Agency › Staff.

type AgencyTemplate

type AgencyTemplate struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	Default     bool      `json:"default"`
	UpdatedAt   time.Time `json:"updatedAt"`
	UpdatedBy   string    `json:"updatedBy,omitempty"`
	// SetsUp counts what it sets up.
	SetsUp AgencyTemplateSummary `json:"setsUp"`
	// UsedBy are the clients it set up or was applied to.
	UsedBy    []AgencyWorkspaceRef `json:"usedBy"`
	NextSteps []string             `json:"nextSteps"`
}

AgencyTemplate is a workspace template on the Library page.

type AgencyTemplateFromWorkspace

type AgencyTemplateFromWorkspace struct {
	Name        string `json:"name" minLength:"1" maxLength:"80"`
	Description string `json:"description,omitempty" maxLength:"300"`
}

AgencyTemplateFromWorkspace saves a client's setup as a template.

type AgencyTemplateInput

type AgencyTemplateInput struct {
	Name        string `json:"name" minLength:"1" maxLength:"80"`
	Description string `json:"description,omitempty" maxLength:"300"`
	// Include switches the template's parts on or off (all on when empty):
	// lists, automations, sections, templates, smsTexts, forms,
	// clientSignoff, roles, branding, senderDefaults.
	Exclude []string `json:"exclude,omitempty" maxItems:"10"`
	// NextSteps are the setup steps new clients get.
	NextSteps []string `json:"nextSteps,omitempty" maxItems:"4"`
}

AgencyTemplateInput edits a template's name, description and what it includes.

type AgencyTemplatePath

type AgencyTemplatePath struct {
	TemplateID string `path:"templateId" format:"uuid"`
}

AgencyTemplatePath names a workspace template.

type AgencyTemplatePlan

type AgencyTemplatePlan struct {
	Template    AgencyTemplateRef  `json:"template"`
	Workspace   AgencyWorkspaceRef `json:"workspace"`
	Lists       AgencyPlanPart     `json:"lists"`
	Automations AgencyPlanPart     `json:"automations"`
	Sections    AgencyPlanPart     `json:"sections"`
	Templates   AgencyPlanPart     `json:"templates"`
	SMSTexts    AgencyPlanPart     `json:"smsTexts"`
	Forms       AgencyPlanPart     `json:"forms"`
	Roles       AgencyPlanPart     `json:"roles"`
	// ClientSignoff: on (turned on), already (already on), off (not in the
	// template) or skipped (you can't change the policy there).
	ClientSignoff string `json:"clientSignoff" enum:"on,already,off,skipped"`
	// ClientRoles: added or already there.
	ClientRoles string   `json:"clientRoles" enum:"added,already"`
	Branding    bool     `json:"branding"`
	Senders     bool     `json:"senders"`
	NextSteps   []string `json:"nextSteps"`
	// Skipped names the parts you can't add there, with the permission.
	Skipped []AgencyPlanSkip `json:"skipped"`
	// AppliedAt and AppliedBy are set once it's applied.
	AppliedAt *time.Time `json:"appliedAt,omitempty"`
	AppliedBy string     `json:"appliedBy,omitempty"`
}

AgencyTemplatePlan is what applying a template to a client adds, and what it renames because the client has something with that name.

func SeedTemplate

func SeedTemplate(ctx context.Context, tx pgx.Tx, templateID, workspaceID, by uuid.UUID, at time.Time) (AgencyTemplatePlan, error)

SeedTemplate applies a workspace template to a workspace in tx, with every permission, as creating a client does, and records the application. It writes no audit entry: the sample writes its own history.

type AgencyTemplateRef

type AgencyTemplateRef struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

AgencyTemplateRef names a workspace template.

type AgencyTemplateSummary

type AgencyTemplateSummary struct {
	Lists           int      `json:"lists"`
	ListNames       []string `json:"listNames"`
	Automations     int      `json:"automations"`
	AutomationNames []string `json:"automationNames"`
	AutomationsNote string   `json:"automationsNote,omitempty"`
	Sections        int      `json:"sections"`
	Templates       int      `json:"templates"`
	SMSTexts        int      `json:"smsTexts"`
	Forms           int      `json:"forms"`
	ClientSignoff   bool     `json:"clientSignoff"`
	Roles           int      `json:"roles"`
	ClientRoles     bool     `json:"clientRoles"`
	Branding        bool     `json:"branding"`
}

AgencyTemplateSummary counts a template's content.

type AgencyUnassignInput

type AgencyUnassignInput struct {
	StaffID     string `json:"staffId"`
	WorkspaceID string `json:"workspaceId" format:"uuid"`
	// RevokeKeys revokes the API keys and agents they created there; false
	// keeps them (they stop working until the person is assigned again).
	RevokeKeys bool `json:"revokeKeys,omitempty"`
}

AgencyUnassignInput removes a staff member from a workspace.

type AgencyUsageCount

type AgencyUsageCount struct {
	Key   string `json:"key"`
	Label string `json:"label"`
	Units int64  `json:"units"`
}

AgencyUsageCount is a count by key (stream or country).

type AgencyUsageMonth

type AgencyUsageMonth struct {
	Month   string `json:"month"`
	Partial bool   `json:"partial"`
}

AgencyUsageMonth is a choice of the month picker.

type AgencyUsageRow

type AgencyUsageRow struct {
	Workspace AgencyWorkspaceRef `json:"workspace"`
	Emails    int64              `json:"emails"`
	Segments  int64              `json:"segments"`
	Push      int64              `json:"push"`
	WhatsApp  int64              `json:"whatsApp"`
	// Costs is each provider's cost; empty without agency:usage.
	Costs []AgencyProviderCost `json:"costs"`
	// Rate is nil when the client isn't billed.
	Rate      *AgencyRate  `json:"rate,omitempty"`
	RateSince *time.Time   `json:"rateSince,omitempty"`
	Rebill    AgencyRebill `json:"rebill"`
	// Streams are the emails per stream; Countries the SMS segments per country.
	Streams   []AgencyUsageCount `json:"streams"`
	Countries []AgencyUsageCount `json:"countries"`
	// Providers says whether the client has a provider at all ("No provider yet").
	Providers int `json:"providers"`
}

AgencyUsageRow is one client's month.

type AgencyUsageTotals

type AgencyUsageTotals struct {
	Workspaces int     `json:"workspaces"`
	Clients    int     `json:"clients"`
	Billed     int     `json:"billed"`
	Emails     int64   `json:"emails"`
	Segments   int64   `json:"segments"`
	Push       int64   `json:"push"`
	WhatsApp   int64   `json:"whatsApp"`
	Cost       float64 `json:"cost"`
	ToRebill   float64 `json:"toRebill"`
}

AgencyUsageTotals sums the table.

type AgencyUsageView

type AgencyUsageView struct {
	// Month is "2026-09"; Partial marks the month in progress.
	Month   string `json:"month"`
	Partial bool   `json:"partial"`
	// From and To are the days covered (the 1st to today for the month
	// in progress).
	From      time.Time            `json:"from"`
	To        time.Time            `json:"to"`
	UpdatedAt *time.Time           `json:"updatedAt,omitempty"`
	Months    []AgencyUsageMonth   `json:"months"`
	Rows      []AgencyUsageRow     `json:"rows"`
	Totals    AgencyUsageTotals    `json:"totals"`
	Entered   []AgencyEnteredPrice `json:"entered"`
	// CanSeeCosts: you hold agency:usage; without it the table shows
	// volumes only.
	CanSeeCosts bool     `json:"canSeeCosts"`
	Reason      string   `json:"reason,omitempty"`
	Helpers     []string `json:"helpers"`
	// PricingDate is the day the providers' prices were read.
	PricingDate time.Time `json:"pricingDate"`
}

AgencyUsageView is Agency › Usage for one month.

type AgencyWorkspacePath

type AgencyWorkspacePath struct {
	WorkspaceID string `path:"workspaceId" format:"uuid"`
}

AgencyWorkspacePath names one of the agency's workspaces.

type AgencyWorkspaceRef

type AgencyWorkspaceRef struct {
	ID       string `json:"id"`
	Slug     string `json:"slug"`
	Name     string `json:"name"`
	Initials string `json:"initials"`
	Color    string `json:"color"`
	Kind     string `json:"kind" enum:"client,agency"`
}

AgencyWorkspaceRef names one of the agency's workspaces.

type ChannelUsage

type ChannelUsage interface {
	Channel() string
	Day(ctx context.Context, q store.DBTX, workspaceID uuid.UUID, day time.Time) ([]UsageRow, error)
}

ChannelUsage reads one channel's usage for a workspace and day: units (SMS segments, notifications, messages) and cost, per provider and, for SMS, per country.

func MessageChannels

func MessageChannels() []ChannelUsage

MessageChannels are the channels the message log carries.

type Deps

type Deps struct {
	// Health scores a workspace's sending: the Overview's sender health.
	Health func(ctx context.Context, ws *store.Workspace) (HealthScore, error)
	// Invite sends invitations in a workspace (Settings › Team's invite).
	Invite func(ctx context.Context, ws *store.Workspace, p *authz.Principal, in team.TeamInviteInput) (team.TeamInviteResult, error)
	// DeleteWorkspace is the existing workspace delete: typed name, sends
	// stop at once, restorable for 7 days. It returns the restore deadline.
	DeleteWorkspace func(ctx context.Context, ws *store.Workspace, confirm string) (time.Time, error)
	// Templates saves sections and campaign templates in a client.
	Templates *templates.Service
	// Transactional creates transactional templates in a client.
	Transactional *transactional.Service
	// Channels read the usage of SMS, push and WhatsApp (X21, X22): none
	// until those channels exist, and their columns read zero.
	Channels []ChannelUsage
}

Deps are the domain services the agency drives. Each is optional: a missing one turns its feature off with an explanation rather than failing the whole area (the OpenAPI command builds every service with nothing behind it).

type DiffLine

type DiffLine struct {
	Op   string `json:"op" enum:"del,add,ctx"`
	Text string `json:"text"`
}

DiffLine is a removed (-) or added (+) line.

type HealthScore

type HealthScore struct {
	// State is ready, or pending while the workspace has no sending domain.
	State string
	Score int
	Tone  string
}

HealthScore is a workspace's sender health as the Overview computes it.

type LibraryContent

type LibraryContent struct {
	// Sections and campaign templates.
	MJML  string          `json:"mjml,omitempty"`
	HTML  string          `json:"html,omitempty"`
	Thumb json.RawMessage `json:"thumb,omitempty"`
	// Automation templates.
	Automation *TplAutomation `json:"automation,omitempty"`
	// Transactional templates.
	Subject   string                                `json:"subject,omitempty"`
	Preheader string                                `json:"preheader,omitempty"`
	PlainText string                                `json:"plainText,omitempty"`
	Variables []transactional.TransactionalVariable `json:"variables,omitempty"`
	// SMS texts.
	Body string `json:"body,omitempty"`
}

LibraryContent is one version of an item.

type MessageChannel

type MessageChannel struct {
	// Name is sms, push or whatsapp.
	Name string
}

MessageChannel reads one channel's usage from the channel message log (channel_messages, X21): SMS segments today, and push notifications and WhatsApp messages once those channels write there. A message counts once it has reached its provider (sent, delivered, undelivered or failed), on the UTC day it was sent, with the cost the provider reported.

func (MessageChannel) Channel

func (c MessageChannel) Channel() string

Channel implements ChannelUsage.

func (MessageChannel) Day

func (c MessageChannel) Day(ctx context.Context, db store.DBTX, workspaceID uuid.UUID, day time.Time) ([]UsageRow, error)

Day implements ChannelUsage: units and cost per provider and, for SMS, segments per destination country.

type RefreshArgs

type RefreshArgs struct{}

RefreshArgs scores every workspace of the agency and rolls up their usage (hourly).

func (RefreshArgs) InsertOpts

func (RefreshArgs) InsertOpts() river.InsertOpts

InsertOpts keeps one refresh at a time.

func (RefreshArgs) Kind

func (RefreshArgs) Kind() string

Kind implements river.JobArgs.

type RefreshWorker

type RefreshWorker struct {
	river.WorkerDefaults[RefreshArgs]
	S   *Service
	Log *slog.Logger
}

RefreshWorker runs the hourly refresh.

func (*RefreshWorker) Timeout

Timeout gives the refresh time for a large agency.

func (*RefreshWorker) Work

Work implements river.Worker.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Now   func() time.Time
	// Cfg is the server configuration (the public URL it may pin).
	Cfg *config.Config
	// Deps are the domain services the agency drives (invitations, copies
	// into clients, sender health, deleting a client). Built lazily by the
	// wiring so the services that reference each other can be constructed.
	Deps func() Deps
}

Service is the agency's API and jobs.

func (*Service) AddStaff

AddStaff adds an account of the instance, or invites someone by email.

func (*Service) AddToLibrary

AddToLibrary is "Add to Northwind library" in a client workspace. It needs agency:library and the item's view permission in that workspace.

func (*Service) ApplyTemplate

func (s *Service) ApplyTemplate(ctx context.Context, templateID, wsID string) (AgencyTemplatePlan, error)

ApplyTemplate applies a template to an existing client: it adds what's missing, renames clashes, and never overwrites or deletes anything.

func (*Service) Assign

func (s *Service) Assign(ctx context.Context, in AgencyAssignInput) error

Assign gives a staff member a role in one of the agency's workspaces: a new membership, or another role for an existing one. It takes agency:manage, or a role there that manages its team, and you can assign only roles whose permissions you hold there.

func (*Service) AssignmentKeys

func (s *Service) AssignmentKeys(ctx context.Context, staffID, wsID string) (AgencyAssignmentKeys, error)

AssignmentKeys lists the active keys a staff member created in a workspace.

func (*Service) Candidates

func (s *Service) Candidates(ctx context.Context) ([]AgencyStaffCandidate, error)

Candidates are the instance's accounts that can join the staff.

func (*Service) ClientDetails

func (s *Service) ClientDetails(ctx context.Context, wsID string) (AgencyClientDetails, error)

ClientDetails returns a client's details for the agency.

func (*Service) CopyToClient

func (s *Service) CopyToClient(ctx context.Context, itemID string, in AgencyCopyInput) (AgencyCopyResult, error)

CopyToClient makes a copy of a library item in a client. It needs the edit permission of that kind of content there (templates:edit, automations:edit, transactional:edit).

func (*Service) CreateClient

func (s *Service) CreateClient(ctx context.Context, in AgencyClientNew) (AgencyClientCreated, error)

CreateClient creates a client workspace: its Owner (an agency manager), Admin for every agency manager and the account managers, the client roles, the template's setup, and an invitation for the client's first person.

func (*Service) DeleteClient

func (s *Service) DeleteClient(ctx context.Context, wsID string, in AgencyClientDelete) (AgencyClientDeleted, error)

DeleteClient deletes a client workspace through the existing workspace delete: the typed name, sends stop at once, restorable for 7 days.

func (*Service) DeleteTemplate

func (s *Service) DeleteTemplate(ctx context.Context, id string) error

DeleteTemplate removes a template. The clients it set up keep everything.

func (*Service) EditLibraryItem

func (s *Service) EditLibraryItem(ctx context.Context, itemID string, in AgencyLibraryEdit) error

EditLibraryItem renames an item, or makes a copy's content its next version.

func (*Service) ExportUsage

func (s *Service) ExportUsage(ctx context.Context, month string, w io.Writer) error

ExportUsage writes the month as CSV: one row per client and channel.

func (*Service) Gallery

func (s *Service) Gallery(ctx context.Context, ws *store.Workspace, kind string) (AgencyGalleryView, error)

Gallery returns the library items usable in a workspace, for its staff.

func (*Service) LatestApplication

func (s *Service) LatestApplication(ctx context.Context, wsID string) (AgencyTemplatePlan, error)

LatestApplication is the last template applied to a workspace (the "Template applied" result).

func (*Service) Library

func (s *Service) Library(ctx context.Context) (AgencyLibraryView, error)

Library lists the shared library, most used first.

func (*Service) LibraryItem

func (s *Service) LibraryItem(ctx context.Context, id string) (AgencyLibraryDetail, error)

LibraryItem returns one item with its versions and copies.

func (*Service) Me

func (s *Service) Me(ctx context.Context) (AgencyMe, error)

Me describes the agency for the shell.

func (*Service) Mode

func (s *Service) Mode(ctx context.Context) (AgencyModeView, error)

Mode returns the agency section of Instance admin.

func (*Service) Notifications

func (s *Service) Notifications(ctx context.Context, limit int) (AgencyNotificationList, error)

Notifications returns the caller's latest notifications in the agency's workspaces they're a member of, unread first.

func (*Service) Overview

func (s *Service) Overview(ctx context.Context) (AgencyOverviewView, error)

Overview returns the agency overview for the caller.

func (*Service) Pulse

func (s *Service) Pulse(ctx context.Context, wsID string) (AgencyClientPulse, error)

Pulse returns one client's row details.

func (*Service) RefreshAll

func (s *Service) RefreshAll(ctx context.Context) error

RefreshAll scores every workspace of the agency (the hourly job), and rolls up their usage for yesterday and today.

func (*Service) RemoveLibraryItem

func (s *Service) RemoveLibraryItem(ctx context.Context, itemID string) error

RemoveLibraryItem takes an item out of the library. Copies in clients stay: they were never linked.

func (*Service) RemoveStaff

func (s *Service) RemoveStaff(ctx context.Context, staffID string, in AgencyStaffRemoveInput) error

RemoveStaff takes someone off the staff.

func (*Service) SaveAsTemplate

SaveAsTemplate saves a workspace's setup as a new workspace template ("Save as workspace template" in a client's Settings › General).

func (*Service) SaveMode

func (s *Service) SaveMode(ctx context.Context, in AgencyModeInput) (AgencyModeView, error)

SaveMode turns agency mode on or off, names the agency, and marks which workspaces are clients and which is the agency's own. Turning it off keeps every workspace and membership; only the Agency area and the agency roles go, and they come back when it's turned on again.

func (*Service) Search

func (s *Service) Search(ctx context.Context, query string) (AgencySearchResults, error)

Search searches the caller's clients.

func (*Service) SetRate

func (s *Service) SetRate(ctx context.Context, wsID string, in AgencyRateInput) (AgencyRateSaved, error)

SetRate saves a client's rebill rate. It applies from the first day of the current month; earlier months keep the rate they had.

func (*Service) StaffView

func (s *Service) StaffView(ctx context.Context) (AgencyStaffView, error)

StaffView returns the staff and the assignment matrix.

func (*Service) TemplatePlan

func (s *Service) TemplatePlan(ctx context.Context, templateID, wsID string) (AgencyTemplatePlan, error)

TemplatePlan previews applying a template to one of your clients.

func (*Service) Templates

func (s *Service) Templates(ctx context.Context) ([]AgencyTemplate, error)

Templates lists the workspace templates.

func (*Service) Unassign

func (s *Service) Unassign(ctx context.Context, in AgencyUnassignInput) error

Unassign removes a staff member's membership in a workspace and keeps or revokes the keys they created there, as deactivating does. It takes what assigning there takes.

func (*Service) UpdateClient

func (s *Service) UpdateClient(ctx context.Context, wsID string, in AgencyClientInput) error

UpdateClient changes a client's contact at the agency.

func (*Service) UpdateCopy

func (s *Service) UpdateCopy(ctx context.Context, copyID string) error

UpdateCopy brings a client's copy to the library's latest version. It replaces the copy's content; a flow can't be replaced in place.

func (*Service) UpdateStaff

func (s *Service) UpdateStaff(ctx context.Context, staffID string, in AgencyStaffUpdate) error

UpdateStaff changes a staff member's level or title. A new agency manager gets Admin in every client.

func (*Service) UpdateTemplate

func (s *Service) UpdateTemplate(ctx context.Context, id string, in AgencyTemplateInput) error

UpdateTemplate renames a template, or leaves parts out of it.

func (*Service) Usage

func (s *Service) Usage(ctx context.Context, month string) (AgencyUsageView, error)

Usage returns each client's usage and what to rebill for a month.

func (*Service) UseItem

func (s *Service) UseItem(ctx context.Context, ws *store.Workspace, itemID string) (AgencyCopyResult, error)

UseItem copies a library item into this workspace (the gallery's "Use a copy"). It needs the edit permission of that kind of content here.

func (*Service) Workspace

func (s *Service) Workspace(ctx context.Context, ws *store.Workspace) (WorkspaceAgency, error)

Workspace describes the agency for one of its workspaces.

type Staff

type Staff struct {
	UserID        uuid.UUID
	Name          string
	Email         string
	Level         string
	Title         string
	InstanceAdmin bool
	Permissions   authz.Set
}

Staff is the signed-in member of the agency's staff.

func (*Staff) Can

func (st *Staff) Can(p authz.Permission) bool

Can reports whether the staff member holds an agency permission.

func (*Staff) Manager

func (st *Staff) Manager() bool

Manager reports whether they work across every client.

type TemplateContent

type TemplateContent struct {
	Lists       []TplList       `json:"lists"`
	Automations []TplAutomation `json:"automations"`
	// AutomationsNote names the automations in a few words on the card
	// ("welcome, booking reminder by SMS, win-back").
	AutomationsNote string    `json:"automationsNote,omitempty"`
	Sections        []TplItem `json:"sections"`
	Templates       []TplItem `json:"templates"`
	SMSTexts        []TplSMS  `json:"smsTexts"`
	Forms           []TplForm `json:"forms"`
	// ClientSignoff turns the approval policy's client sign-off on.
	ClientSignoff bool      `json:"clientSignoff"`
	Roles         []TplRole `json:"roles"`
	// Branding holds the public pages' branding without the logo and colours.
	Branding map[string]any `json:"branding,omitempty"`
	// SenderNames are the default senders' From names by stream, and Footer
	// the postal address under every email.
	SenderNames map[string]string `json:"senderNames,omitempty"`
	Footer      string            `json:"footer,omitempty"`
	// NextSteps are the setup steps a new client gets: provider, domain,
	// invite, and shopify when the template expects a store.
	NextSteps []string `json:"nextSteps"`
}

TemplateContent is what a workspace template sets up.

type TplAutomation

type TplAutomation struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Graph       json.RawMessage `json:"graph"`
	Emails      []TplEmail      `json:"emails"`
}

TplAutomation is a flow; list, form and email references in its graph are names ("list:Newsletter", "form:Signup", "email:welcome-1").

type TplEmail

type TplEmail struct {
	Ref       string `json:"ref"`
	Name      string `json:"name"`
	Subject   string `json:"subject"`
	Preheader string `json:"preheader,omitempty"`
	MJML      string `json:"mjml"`
	HTML      string `json:"html"`
	Text      string `json:"text,omitempty"`
}

TplEmail is one of a flow's emails.

type TplForm

type TplForm struct {
	Name           string          `json:"name"`
	Kind           string          `json:"kind"`
	Lists          []string        `json:"lists"`
	DoubleOptIn    bool            `json:"doubleOptIn"`
	Fields         json.RawMessage `json:"fields"`
	Content        json.RawMessage `json:"content"`
	SpamProtection json.RawMessage `json:"spamProtection"`
	ConsentText    string          `json:"consentText"`
}

TplForm is a signup form; its lists are names.

type TplItem

type TplItem struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	MJML        string          `json:"mjml"`
	HTML        string          `json:"html,omitempty"`
	Thumb       json.RawMessage `json:"thumb,omitempty"`
}

TplItem is a saved section or a campaign template.

type TplList

type TplList struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	DoubleOptIn bool   `json:"doubleOptIn"`
}

TplList is a list, copied empty.

type TplRole

type TplRole struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Permissions []string `json:"permissions"`
}

TplRole is a custom role.

type TplSMS

type TplSMS struct {
	Name string `json:"name"`
	Body string `json:"body"`
}

TplSMS is an SMS text.

type UsageRow

type UsageRow struct {
	Dimension  string // provider, country or stream
	Key        string
	Label      string
	Units      int64
	CostMicros int64
}

UsageRow is one rolled-up usage figure.

type WorkspaceAgency

type WorkspaceAgency struct {
	// Managed is true in the agency's workspaces (its clients and its own).
	Managed bool   `json:"managed"`
	Kind    string `json:"kind,omitempty" enum:"client,agency"`
	Agency  string `json:"agency,omitempty"`
	// AgencyInitials and Host draw the agency's tile and address.
	AgencyInitials string `json:"agencyInitials,omitempty"`
	Host           string `json:"host,omitempty"`
	// Contact is the client's account manager.
	Contact *AgencyPersonRef `json:"contact,omitempty"`
	// Staff are the members of this workspace who are agency staff.
	Staff []WorkspaceAgencyStaff `json:"staff"`
	// ViewerIsStaff: you're on the agency's staff.
	ViewerIsStaff bool `json:"viewerIsStaff"`
	// Client details, for staff only.
	ClientSince *time.Time  `json:"clientSince,omitempty"`
	Template    string      `json:"template,omitempty"`
	Rate        *AgencyRate `json:"rate,omitempty"`
	RateSince   *time.Time  `json:"rateSince,omitempty"`
	// Billed is false when the client isn't billed (staff with agency:usage).
	Billed bool `json:"billed"`
	// CanSaveTemplate and CanAddToLibrary: you hold agency:library.
	CanSaveTemplate bool `json:"canSaveTemplate"`
}

WorkspaceAgency is what a workspace shows about the agency that manages it: the "Managed by" banner with the client's contact, the agency's staff among its members ("via Northwind Studio"), and, for staff, the client details only the agency keeps.

type WorkspaceAgencyStaff

type WorkspaceAgencyStaff struct {
	UserID string `json:"userId"`
	Level  string `json:"level" enum:"agency_manager,account_manager"`
	Title  string `json:"title,omitempty"`
	// Contact: they're the client's contact.
	Contact     bool `json:"contact"`
	EveryClient bool `json:"everyClient"`
}

WorkspaceAgencyStaff is a staff member in this workspace.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL