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
- func Initials(name string) string
- func Register(h huma.API, s *Service)
- func RegisterJobs(reg *jobs.Registry, s *Service, log *slog.Logger)
- func SeedLibraryCopy(ctx context.Context, tx pgx.Tx, itemID uuid.UUID, version int32, ...) (uuid.UUID, error)
- func SeedLibraryVersion(kind string, c LibraryContent) (summary []string, fields json.RawMessage)
- type AgencyAddToLibrary
- type AgencyApproval
- type AgencyAssignInput
- type AgencyAssignableRole
- type AgencyAssignmentCell
- type AgencyAssignmentKeys
- type AgencyAssignmentRow
- type AgencyAssignmentSpec
- type AgencyBilledMonth
- type AgencyClientCreated
- type AgencyClientDelete
- type AgencyClientDeleted
- type AgencyClientDetails
- type AgencyClientInput
- type AgencyClientNew
- type AgencyClientPerson
- type AgencyClientPulse
- type AgencyClientRow
- type AgencyCopyInput
- type AgencyCopyPath
- type AgencyCopyResult
- type AgencyCopyTarget
- type AgencyCounts
- type AgencyEnteredPrice
- type AgencyFailover
- type AgencyFirstPerson
- type AgencyGalleryCopy
- type AgencyGalleryView
- type AgencyHealth
- type AgencyIncident
- type AgencyItemPath
- type AgencyKeyRef
- type AgencyLibraryAdded
- type AgencyLibraryCopy
- type AgencyLibraryDetail
- type AgencyLibraryDiff
- type AgencyLibraryEdit
- type AgencyLibraryField
- type AgencyLibraryItem
- type AgencyLibraryVersion
- type AgencyLibraryView
- type AgencyMe
- type AgencyMeStaff
- type AgencyModeInput
- type AgencyModeView
- type AgencyModeWorkspace
- type AgencyNotification
- type AgencyNotificationList
- type AgencyOverviewView
- type AgencyPersonRef
- type AgencyPlanPart
- type AgencyPlanRename
- type AgencyPlanSkip
- type AgencyProviderCost
- type AgencyRate
- type AgencyRateInput
- type AgencyRateSaved
- type AgencyRebill
- type AgencyRoleRef
- type AgencySearchGroup
- type AgencySearchHit
- type AgencySearchResults
- type AgencySend
- type AgencySetup
- type AgencySetupStep
- type AgencyStaffAdded
- type AgencyStaffCandidate
- type AgencyStaffInput
- type AgencyStaffMember
- type AgencyStaffPath
- type AgencyStaffRemoveInput
- type AgencyStaffUpdate
- type AgencyStaffView
- type AgencyTemplate
- type AgencyTemplateFromWorkspace
- type AgencyTemplateInput
- type AgencyTemplatePath
- type AgencyTemplatePlan
- type AgencyTemplateRef
- type AgencyTemplateSummary
- type AgencyUnassignInput
- type AgencyUsageCount
- type AgencyUsageMonth
- type AgencyUsageRow
- type AgencyUsageTotals
- type AgencyUsageView
- type AgencyWorkspacePath
- type AgencyWorkspaceRef
- type ChannelUsage
- type Deps
- type DiffLine
- type HealthScore
- type LibraryContent
- type MessageChannel
- type RefreshArgs
- type RefreshWorker
- type Service
- func (s *Service) AddStaff(ctx context.Context, in AgencyStaffInput) (AgencyStaffAdded, error)
- func (s *Service) AddToLibrary(ctx context.Context, ws *store.Workspace, in AgencyAddToLibrary) (AgencyLibraryAdded, error)
- func (s *Service) ApplyTemplate(ctx context.Context, templateID, wsID string) (AgencyTemplatePlan, error)
- func (s *Service) Assign(ctx context.Context, in AgencyAssignInput) error
- func (s *Service) AssignmentKeys(ctx context.Context, staffID, wsID string) (AgencyAssignmentKeys, error)
- func (s *Service) Candidates(ctx context.Context) ([]AgencyStaffCandidate, error)
- func (s *Service) ClientDetails(ctx context.Context, wsID string) (AgencyClientDetails, error)
- func (s *Service) CopyToClient(ctx context.Context, itemID string, in AgencyCopyInput) (AgencyCopyResult, error)
- func (s *Service) CreateClient(ctx context.Context, in AgencyClientNew) (AgencyClientCreated, error)
- func (s *Service) DeleteClient(ctx context.Context, wsID string, in AgencyClientDelete) (AgencyClientDeleted, error)
- func (s *Service) DeleteTemplate(ctx context.Context, id string) error
- func (s *Service) EditLibraryItem(ctx context.Context, itemID string, in AgencyLibraryEdit) error
- func (s *Service) ExportUsage(ctx context.Context, month string, w io.Writer) error
- func (s *Service) Gallery(ctx context.Context, ws *store.Workspace, kind string) (AgencyGalleryView, error)
- func (s *Service) LatestApplication(ctx context.Context, wsID string) (AgencyTemplatePlan, error)
- func (s *Service) Library(ctx context.Context) (AgencyLibraryView, error)
- func (s *Service) LibraryItem(ctx context.Context, id string) (AgencyLibraryDetail, error)
- func (s *Service) Me(ctx context.Context) (AgencyMe, error)
- func (s *Service) Mode(ctx context.Context) (AgencyModeView, error)
- func (s *Service) Notifications(ctx context.Context, limit int) (AgencyNotificationList, error)
- func (s *Service) Overview(ctx context.Context) (AgencyOverviewView, error)
- func (s *Service) Pulse(ctx context.Context, wsID string) (AgencyClientPulse, error)
- func (s *Service) RefreshAll(ctx context.Context) error
- func (s *Service) RemoveLibraryItem(ctx context.Context, itemID string) error
- func (s *Service) RemoveStaff(ctx context.Context, staffID string, in AgencyStaffRemoveInput) error
- func (s *Service) SaveAsTemplate(ctx context.Context, ws *store.Workspace, in AgencyTemplateFromWorkspace) (AgencyTemplateRef, error)
- func (s *Service) SaveMode(ctx context.Context, in AgencyModeInput) (AgencyModeView, error)
- func (s *Service) Search(ctx context.Context, query string) (AgencySearchResults, error)
- func (s *Service) SetRate(ctx context.Context, wsID string, in AgencyRateInput) (AgencyRateSaved, error)
- func (s *Service) StaffView(ctx context.Context) (AgencyStaffView, error)
- func (s *Service) TemplatePlan(ctx context.Context, templateID, wsID string) (AgencyTemplatePlan, error)
- func (s *Service) Templates(ctx context.Context) ([]AgencyTemplate, error)
- func (s *Service) Unassign(ctx context.Context, in AgencyUnassignInput) error
- func (s *Service) UpdateClient(ctx context.Context, wsID string, in AgencyClientInput) error
- func (s *Service) UpdateCopy(ctx context.Context, copyID string) error
- func (s *Service) UpdateStaff(ctx context.Context, staffID string, in AgencyStaffUpdate) error
- func (s *Service) UpdateTemplate(ctx context.Context, id string, in AgencyTemplateInput) error
- func (s *Service) Usage(ctx context.Context, month string) (AgencyUsageView, error)
- func (s *Service) UseItem(ctx context.Context, ws *store.Workspace, itemID string) (AgencyCopyResult, error)
- func (s *Service) Workspace(ctx context.Context, ws *store.Workspace) (WorkspaceAgency, error)
- type Staff
- type TemplateContent
- type TplAutomation
- type TplEmail
- type TplForm
- type TplItem
- type TplList
- type TplRole
- type TplSMS
- type UsageRow
- type WorkspaceAgency
- type WorkspaceAgencyStaff
Constants ¶
const ( KindSection = "section" KindTemplate = "template" KindAutomation = "automation" KindTransactional = "transactional" KindSMS = "sms" )
Library item kinds and where their copies go.
const CodeAgencyOff = "agency_off"
CodeAgencyOff is the problem code while agency mode is off.
Variables ¶
This section is empty.
Functions ¶
func Initials ¶
Initials of a workspace or a person: "Contoso Coffee" → "CC", "Wide World Importers" → "WW".
func RegisterJobs ¶
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 ¶
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 ¶
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 ¶
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 ¶
AgencyPlanRename is a clash renamed on the way in.
type AgencyPlanSkip ¶
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 ¶
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 ¶
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 ¶
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 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.
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.
type RefreshWorker ¶
type RefreshWorker struct {
river.WorkerDefaults[RefreshArgs]
S *Service
Log *slog.Logger
}
RefreshWorker runs the hourly refresh.
func (*RefreshWorker) Timeout ¶
func (w *RefreshWorker) Timeout(*river.Job[RefreshArgs]) time.Duration
Timeout gives the refresh time for a large agency.
func (*RefreshWorker) Work ¶
func (w *RefreshWorker) Work(ctx context.Context, _ *river.Job[RefreshArgs]) error
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 ¶
func (s *Service) AddStaff(ctx context.Context, in AgencyStaffInput) (AgencyStaffAdded, error)
AddStaff adds an account of the instance, or invites someone by email.
func (*Service) AddToLibrary ¶
func (s *Service) AddToLibrary(ctx context.Context, ws *store.Workspace, in AgencyAddToLibrary) (AgencyLibraryAdded, error)
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 ¶
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 ¶
DeleteTemplate removes a template. The clients it set up keep everything.
func (*Service) EditLibraryItem ¶
EditLibraryItem renames an item, or makes a copy's content its next version.
func (*Service) ExportUsage ¶
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 ¶
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 ¶
LibraryItem returns one item with its versions and copies.
func (*Service) Mode ¶
func (s *Service) Mode(ctx context.Context) (AgencyModeView, error)
Mode returns the agency section of Instance admin.
func (*Service) Notifications ¶
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) RefreshAll ¶
RefreshAll scores every workspace of the agency (the hourly job), and rolls up their usage for yesterday and today.
func (*Service) RemoveLibraryItem ¶
RemoveLibraryItem takes an item out of the library. Copies in clients stay: they were never linked.
func (*Service) RemoveStaff ¶
RemoveStaff takes someone off the staff.
func (*Service) SaveAsTemplate ¶
func (s *Service) SaveAsTemplate(ctx context.Context, ws *store.Workspace, in AgencyTemplateFromWorkspace) (AgencyTemplateRef, error)
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) 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 ¶
UpdateClient changes a client's contact at the agency.
func (*Service) UpdateCopy ¶
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 ¶
UpdateStaff changes a staff member's level or title. A new agency manager gets Admin in every client.
func (*Service) UpdateTemplate ¶
UpdateTemplate renames a template, or leaves parts out of it.
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.
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"`
// 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 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.