Documentation
¶
Overview ¶
Package renders sends a campaign to the workspace's own rendering service, Litmus or Mailgun Inspect, for screenshots from real email clients (review 2026-10, CO-13). The composer's built-in previews are drawn in the browser from the compiled HTML and say so; this is the optional real thing.
The API key is the workspace's own, sealed at rest (secrets.Box) and never returned. Calls go through the address guard (netguard) like every call to a service outside the instance. Content leaves the instance only on purpose: a person asks for each render, it is audited, and the email is personalized for the synthetic sample contact, never a real one.
Index ¶
- Constants
- func Register(h huma.API, s *Service)
- type CampaignPath
- type CampaignRenderInput
- type Content
- type Email
- type Render
- type RenderClient
- type RenderList
- type RenderResult
- type RenderingConnectInput
- type RenderingService
- type Service
- func (s *Service) Connect(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (RenderingService, error)
- func (s *Service) Disconnect(ctx context.Context, ws *store.Workspace) error
- func (s *Service) Get(ctx context.Context, ws *store.Workspace) (RenderingService, error)
- func (s *Service) List(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (RenderList, error)
- func (s *Service) Start(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (Render, error)
- func (s *Service) Test(ctx context.Context, ws *store.Workspace) (RenderingService, error)
Constants ¶
const ( Litmus = "litmus" MailgunInspect = "mailgun_inspect" )
Services a workspace can connect.
const ( StatusPending = "pending" StatusDone = "done" StatusFailed = "failed" )
Render and per-client states.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CampaignPath ¶
type CampaignPath struct {
api.WorkspaceInput
CampaignID string `path:"campaignId" format:"uuid"`
}
CampaignPath is the {workspace}/{campaignId} part of render operations (exported: huma reads path parameters of embedded structs only when they're exported).
type CampaignRenderInput ¶
type CampaignRenderInput struct {
Clients []string `` /* 131-byte string literal not displayed */
Variant string `json:"variant,omitempty" enum:"A,B,C" doc:"The A/B variant to render (A by default)"`
}
CampaignRenderInput asks for a render of the saved campaign.
type Content ¶
type Content interface {
// SampleRender is the campaign's saved content (one A/B variant)
// personalized for the synthetic sample contact, so no contact's data
// leaves the instance.
SampleRender(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID, variant string) (Email, error)
// CampaignName is the campaign's name, or a 404 problem when the
// workspace has no such campaign.
CampaignName(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (string, error)
}
Content gives the email to render (internal/campaigns, wired in internal/app).
type Email ¶
type Email struct {
Subject string
HTML string
Version int
// Name is the campaign's, for the audit log.
Name string
}
Email is what a service renders: a saved version of the campaign as the sample contact gets it.
type Render ¶
type Render struct {
ID string `json:"id"`
Version int `json:"version" doc:"The saved version rendered"`
Variant string `json:"variant" enum:"A,B,C"`
Service string `json:"service" enum:"litmus,mailgun_inspect"`
Status string `json:"status" enum:"pending,done,failed"`
Results []RenderResult `json:"results"`
Error string `json:"error,omitempty"`
RequestedBy string `json:"requestedBy"`
RequestedAt time.Time `json:"requestedAt"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
}
Render is one request to the service and what it returned.
type RenderClient ¶
type RenderClient struct {
ID string `json:"id"`
Name string `json:"name"`
// Default marks the clients picked when nobody chooses: Gmail, Outlook,
// Apple Mail, iPhone, Android, Yahoo, when the account has them.
Default bool `json:"default"`
}
RenderClient is an email client a service renders in.
type RenderList ¶
type RenderList struct {
Items []Render `json:"items"`
}
RenderList is a campaign's latest renders, newest first.
type RenderResult ¶
type RenderResult struct {
Client string `json:"client"`
Name string `json:"name"`
Status string `json:"status" enum:"pending,done,failed"`
ImageURL string `json:"imageUrl,omitempty" doc:"The full screenshot, hosted by the service"`
ThumbURL string `json:"thumbUrl,omitempty"`
}
RenderResult is one client's screenshot.
type RenderingConnectInput ¶
type RenderingConnectInput struct {
Service string `json:"service" enum:"litmus,mailgun_inspect"`
APIKey string `json:"apiKey" minLength:"8" maxLength:"256" doc:"Write-only: sealed at rest and never returned"`
Region string `json:"region,omitempty" enum:"us,eu" doc:"Mailgun Inspect: the account's region (us by default)"`
}
RenderingConnectInput connects (or replaces) the workspace's service.
type RenderingService ¶
type RenderingService struct {
Connected bool `json:"connected"`
Service string `json:"service,omitempty" enum:"litmus,mailgun_inspect"`
Region string `json:"region,omitempty" enum:"us,eu" doc:"Mailgun Inspect: the account's region"`
// KeyHint is the key's last four characters; the key itself is never returned.
KeyHint string `json:"keyHint,omitempty"`
Status string `json:"status,omitempty" enum:"connected,failing" doc:"failing: the last call was refused or failed (lastError says why)"`
LastError string `json:"lastError,omitempty"`
ConnectedBy string `json:"connectedBy,omitempty"`
ConnectedAt *time.Time `json:"connectedAt,omitempty"`
CheckedAt *time.Time `json:"checkedAt,omitempty"`
Clients []RenderClient `json:"clients" doc:"The email clients the account can render, as the service last listed them"`
}
RenderingService is the workspace's connection, without its key.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Box *secrets.Box
Content Content
// HTTP calls the services (a netguard client in the app).
HTTP *http.Client
Now func() time.Time
}
Service is the rendering service domain.
func (*Service) Connect ¶
func (s *Service) Connect(ctx context.Context, ws *store.Workspace, p *authz.Principal, in RenderingConnectInput) (RenderingService, error)
Connect tests a key with the service, then keeps it (sealed).
func (*Service) Disconnect ¶
Disconnect forgets the service and its key. Renders already made stay.
func (*Service) List ¶
func (s *Service) List(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (RenderList, error)
List returns the campaign's latest renders, asking the service about running ones (at most every few seconds, whoever is watching).