eec-campaigns/internal/listmonk/listmonk.go

// Package listmonk is a small client for the listmonk REST calls
// eec-campaigns needs: managing campaigns (create/update/status/test),
// resolving list names to IDs, uploading media for attachments, and
// materializing a segment_query into list membership. Deliberately not
// shared with eec's or drip's own listmonk clients — same reasoning drip's
// client comment already gives: Go's internal/ visibility rules would block
// it anyway, and this client's needs (campaigns, media) diverge enough from
// eec's (transactional sends) and drip's (subscriber sweep) that duplicating
// the small HTTP-plumbing overlap beats a shared module.
package listmonk

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"net/url"
)

type Client struct {
	BaseURL  string // e.g. https://listmonk.reground.org
	APIUser  string
	APIToken string
	HTTP     *http.Client
}

func New(baseURL, apiUser, apiToken string) *Client {
	return &Client{
		BaseURL:  baseURL,
		APIUser:  apiUser,
		APIToken: apiToken,
		HTTP:     &http.Client{},
	}
}

func (c *Client) do(method, path string, body any) ([]byte, int, error) {
	var reader io.Reader
	if body != nil {
		b, err := json.Marshal(body)
		if err != nil {
			return nil, 0, err
		}
		reader = bytes.NewReader(b)
	}
	req, err := http.NewRequest(method, c.BaseURL+path, reader)
	if err != nil {
		return nil, 0, err
	}
	req.SetBasicAuth(c.APIUser, c.APIToken)
	req.Header.Set("Content-Type", "application/json")

	resp, err := c.HTTP.Do(req)
	if err != nil {
		return nil, 0, err
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, 0, err
	}
	return respBody, resp.StatusCode, nil
}

// ---- Lists ----

type List struct {
	ID   int
	Name string
}

func (c *Client) listAll() ([]List, error) {
	respBody, status, err := c.do(http.MethodGet, "/api/lists?per_page=all", nil)
	if err != nil {
		return nil, fmt.Errorf("listing lists: %w", err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("listing lists failed (%d): %s", status, string(respBody))
	}
	var parsed struct {
		Data struct {
			Results []struct {
				ID   int    `json:"id"`
				Name string `json:"name"`
			} `json:"results"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing list response: %w", err)
	}
	lists := make([]List, 0, len(parsed.Data.Results))
	for _, r := range parsed.Data.Results {
		lists = append(lists, List{ID: r.ID, Name: r.Name})
	}
	return lists, nil
}

// FindListByName resolves a list name to its numeric ID, matching exactly
// (never fuzzy) so a campaign's target audience is never guessed. Fetches
// all lists and filters client-side rather than depending on /api/lists'
// query-string search semantics, matching drip's existing style of not
// relying on unconfirmed server-side query behavior.
func (c *Client) FindListByName(name string) (id int, err error) {
	lists, err := c.listAll()
	if err != nil {
		return 0, err
	}
	var matches []List
	for _, l := range lists {
		if l.Name == name {
			matches = append(matches, l)
		}
	}
	switch len(matches) {
	case 0:
		return 0, fmt.Errorf("no list named %q", name)
	case 1:
		return matches[0].ID, nil
	default:
		return 0, fmt.Errorf("%d lists named %q — ambiguous, refusing to guess", len(matches), name)
	}
}

// FindOrCreateListByName is used for segment_query-backed lists
// (segment:<slug>), which this tool owns and manages itself rather than
// requiring the user to pre-create in the Listmonk admin UI.
func (c *Client) FindOrCreateListByName(name string) (int, error) {
	lists, err := c.listAll()
	if err != nil {
		return 0, err
	}
	for _, l := range lists {
		if l.Name == name {
			return l.ID, nil
		}
	}

	payload := map[string]any{
		"name": name,
		"type": "private",
	}
	respBody, status, err := c.do(http.MethodPost, "/api/lists", payload)
	if err != nil {
		return 0, fmt.Errorf("creating list %q: %w", name, err)
	}
	if status != http.StatusOK {
		return 0, fmt.Errorf("creating list %q failed (%d): %s", name, status, string(respBody))
	}
	var parsed struct {
		Data struct {
			ID int `json:"id"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return 0, fmt.Errorf("parsing list creation response: %w", err)
	}
	return parsed.Data.ID, nil
}

// ---- Subscribers / segmentation ----

// QuerySubscriberIDs runs a raw SQL boolean expression against the
// subscribers table (the same segmentation mechanism listmonk's own admin
// UI search box uses) and returns the IDs of every match. per_page=all
// deliberately skips pagination, matching drip's existing Query method.
func (c *Client) QuerySubscriberIDs(query string) ([]int, error) {
	path := "/api/subscribers?per_page=all&query=" + url.QueryEscape(query)
	respBody, status, err := c.do(http.MethodGet, path, nil)
	if err != nil {
		return nil, fmt.Errorf("querying subscribers: %w", err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("segment_query failed (%d): %s", status, string(respBody))
	}
	var parsed struct {
		Data struct {
			Results []struct {
				ID int `json:"id"`
			} `json:"results"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing subscriber query response: %w", err)
	}
	ids := make([]int, 0, len(parsed.Data.Results))
	for _, r := range parsed.Data.Results {
		ids = append(ids, r.ID)
	}
	return ids, nil
}

// BulkAddToList adds the given subscriber IDs to listID.
//
// TODO(verify): the bulk list-membership action's exact endpoint/body shape
// isn't confirmed against a live listmonk instance — this targets the
// documented bulk subscriber-action endpoint (PUT /api/subscribers/lists
// with explicit ids+action+target_list_ids), which is the same mechanism
// listmonk's admin UI uses for "add selected subscribers to list". Confirm
// against the real instance/version before relying on this in production.
func (c *Client) BulkAddToList(ids []int, listID int) error {
	if len(ids) == 0 {
		return nil
	}
	payload := map[string]any{
		"ids":             ids,
		"action":          "add",
		"target_list_ids": []int{listID},
		"status":          "unconfirmed",
	}
	respBody, status, err := c.do(http.MethodPut, "/api/subscribers/lists", payload)
	if err != nil {
		return fmt.Errorf("bulk-adding %d subscriber(s) to list %d: %w", len(ids), listID, err)
	}
	if status != http.StatusOK {
		return fmt.Errorf("bulk-adding subscribers to list %d failed (%d): %s", listID, status, string(respBody))
	}
	return nil
}

// ---- Media ----

type Media struct {
	ID       int
	Filename string
}

func (c *Client) mediaAll() ([]Media, error) {
	respBody, status, err := c.do(http.MethodGet, "/api/media", nil)
	if err != nil {
		return nil, fmt.Errorf("listing media: %w", err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("listing media failed (%d): %s", status, string(respBody))
	}
	var parsed struct {
		Data []struct {
			ID       int    `json:"id"`
			Filename string `json:"filename"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing media response: %w", err)
	}
	media := make([]Media, 0, len(parsed.Data))
	for _, r := range parsed.Data {
		media = append(media, Media{ID: r.ID, Filename: r.Filename})
	}
	return media, nil
}

// FindMediaByFilename looks for a previously uploaded file by its exact
// (content-hash-synthesized) filename — see internal/campaign/sync.go for
// why the filename itself is the dedup key. Returns (0, false, nil) if not
// found, never an error for a plain miss.
func (c *Client) FindMediaByFilename(filename string) (id int, found bool, err error) {
	media, err := c.mediaAll()
	if err != nil {
		return 0, false, err
	}
	for _, m := range media {
		if m.Filename == filename {
			return m.ID, true, nil
		}
	}
	return 0, false, nil
}

// UploadMedia uploads content under filename and returns its new media ID.
func (c *Client) UploadMedia(filename string, content io.Reader) (int, error) {
	var buf bytes.Buffer
	w := multipart.NewWriter(&buf)
	part, err := w.CreateFormFile("file", filename)
	if err != nil {
		return 0, err
	}
	if _, err := io.Copy(part, content); err != nil {
		return 0, err
	}
	if err := w.Close(); err != nil {
		return 0, err
	}

	req, err := http.NewRequest(http.MethodPost, c.BaseURL+"/api/media", &buf)
	if err != nil {
		return 0, err
	}
	req.SetBasicAuth(c.APIUser, c.APIToken)
	req.Header.Set("Content-Type", w.FormDataContentType())

	resp, err := c.HTTP.Do(req)
	if err != nil {
		return 0, fmt.Errorf("uploading media %q: %w", filename, err)
	}
	defer resp.Body.Close()
	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return 0, err
	}
	if resp.StatusCode != http.StatusOK {
		return 0, fmt.Errorf("uploading media %q failed (%d): %s", filename, resp.StatusCode, string(respBody))
	}

	var parsed struct {
		Data struct {
			ID int `json:"id"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return 0, fmt.Errorf("parsing media upload response: %w", err)
	}
	return parsed.Data.ID, nil
}

// ---- Campaigns ----

// Campaign is the subset of listmonk's campaign fields eec-campaigns cares
// about — enough to decide whether a re-sync's desired content differs from
// what's already there.
type Campaign struct {
	ID         int
	Name       string
	Status     string
	Subject    string
	Body       string
	FromEmail  string
	TemplateID int
	Type       string
	Tags       []string
	ListIDs    []int
	MediaIDs   []int
}

// CampaignInput is what sync.go builds from a campaign's frontmatter+body to
// create or update a listmonk campaign.
type CampaignInput struct {
	Name       string
	Subject    string
	FromEmail  string
	TemplateID int // 0 means "omit, use listmonk's default template"
	Type       string
	Tags       []string
	ListIDs    []int
	Body       string // raw Markdown; content_type "markdown" below
	MediaIDs   []int
}

func (in CampaignInput) payload() map[string]any {
	p := map[string]any{
		"name":         in.Name,
		"subject":      in.Subject,
		"lists":        in.ListIDs,
		"content_type": "markdown",
		"body":         in.Body,
		"type":         in.Type,
	}
	if in.FromEmail != "" {
		p["from_email"] = in.FromEmail
	}
	if in.TemplateID != 0 {
		p["template_id"] = in.TemplateID
	}
	if len(in.Tags) > 0 {
		p["tags"] = in.Tags
	}
	if len(in.MediaIDs) > 0 {
		// TODO(verify): field name for attaching media library items to a
		// campaign isn't documented publicly — confirm against a live
		// listmonk admin UI network trace (attach a file to any test
		// campaign and inspect the PUT /api/campaigns/{id} request it
		// sends) before relying on this in production.
		p["media_ids"] = in.MediaIDs
	}
	return p
}

func parseCampaign(data []byte) (*Campaign, error) {
	var parsed struct {
		ID         int      `json:"id"`
		Name       string   `json:"name"`
		Status     string   `json:"status"`
		Subject    string   `json:"subject"`
		Body       string   `json:"body"`
		FromEmail  string   `json:"from_email"`
		TemplateID int      `json:"template_id"`
		Type       string   `json:"type"`
		Tags       []string `json:"tags"`
		Lists      []struct {
			ID int `json:"id"`
		} `json:"lists"`
		MediaIDs []int `json:"media_ids"`
	}
	if err := json.Unmarshal(data, &parsed); err != nil {
		return nil, err
	}
	listIDs := make([]int, 0, len(parsed.Lists))
	for _, l := range parsed.Lists {
		listIDs = append(listIDs, l.ID)
	}
	return &Campaign{
		ID:         parsed.ID,
		Name:       parsed.Name,
		Status:     parsed.Status,
		Subject:    parsed.Subject,
		Body:       parsed.Body,
		FromEmail:  parsed.FromEmail,
		TemplateID: parsed.TemplateID,
		Type:       parsed.Type,
		Tags:       parsed.Tags,
		ListIDs:    listIDs,
		MediaIDs:   parsed.MediaIDs,
	}, nil
}

// FindCampaignByName resolves a campaign's identity (see
// internal/campaign/sync.go — the directory slug is sent as this name) by
// fetching every campaign and filtering client-side, same reasoning as
// FindListByName. Returns (nil, nil) on a plain miss, never an error.
func (c *Client) FindCampaignByName(name string) (*Campaign, error) {
	respBody, status, err := c.do(http.MethodGet, "/api/campaigns?per_page=all", nil)
	if err != nil {
		return nil, fmt.Errorf("listing campaigns: %w", err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("listing campaigns failed (%d): %s", status, string(respBody))
	}
	var parsed struct {
		Data struct {
			Results []json.RawMessage `json:"results"`
		} `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing campaign list response: %w", err)
	}
	var matches []*Campaign
	for _, raw := range parsed.Data.Results {
		camp, err := parseCampaign(raw)
		if err != nil {
			return nil, fmt.Errorf("parsing campaign in list response: %w", err)
		}
		if camp.Name == name {
			matches = append(matches, camp)
		}
	}
	switch len(matches) {
	case 0:
		return nil, nil
	case 1:
		return matches[0], nil
	default:
		return nil, fmt.Errorf("%d campaigns named %q — ambiguous, refusing to guess", len(matches), name)
	}
}

// CreateCampaign creates a new campaign. listmonk's create-time default
// status is draft, which is this tool's core safety invariant — see the
// TODO below.
//
// TODO(verify): confirm that POST /api/campaigns' create-time default
// status really is "draft" against a live instance (and whether an explicit
// status field is even accepted on create) before depending on it.
func (c *Client) CreateCampaign(in CampaignInput) (*Campaign, error) {
	respBody, status, err := c.do(http.MethodPost, "/api/campaigns", in.payload())
	if err != nil {
		return nil, fmt.Errorf("creating campaign %q: %w", in.Name, err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("creating campaign %q failed (%d): %s", in.Name, status, string(respBody))
	}
	var parsed struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing campaign creation response: %w", err)
	}
	return parseCampaign(parsed.Data)
}

// UpdateCampaign overwrites a draft campaign's content. Callers (sync.go)
// must have already confirmed the campaign is still in draft status —
// this client does not re-check, since the point of a fresh
// FindCampaignByName just beforehand is exactly that check.
func (c *Client) UpdateCampaign(id int, in CampaignInput) (*Campaign, error) {
	respBody, status, err := c.do(http.MethodPut, fmt.Sprintf("/api/campaigns/%d", id), in.payload())
	if err != nil {
		return nil, fmt.Errorf("updating campaign %d: %w", id, err)
	}
	if status != http.StatusOK {
		return nil, fmt.Errorf("updating campaign %d failed (%d): %s", id, status, string(respBody))
	}
	var parsed struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.Unmarshal(respBody, &parsed); err != nil {
		return nil, fmt.Errorf("parsing campaign update response: %w", err)
	}
	return parseCampaign(parsed.Data)
}

// SetCampaignStatus transitions a campaign's status — "running" is the one
// real send trigger in this whole tool (see cmd/send).
func (c *Client) SetCampaignStatus(id int, status string) error {
	payload := map[string]any{"status": status}
	respBody, code, err := c.do(http.MethodPut, fmt.Sprintf("/api/campaigns/%d/status", id), payload)
	if err != nil {
		return fmt.Errorf("setting campaign %d status to %q: %w", id, status, err)
	}
	if code != http.StatusOK {
		return fmt.Errorf("setting campaign %d status to %q failed (%d): %s", id, status, code, string(respBody))
	}
	return nil
}

// TestCampaign sends a preview of the campaign's current content to the
// given addresses without touching its status.
//
// TODO(verify): the request body key for the recipient address list isn't
// confirmed against a live instance — using "subscribers" per listmonk's
// documented shape for this endpoint; confirm before relying on it.
func (c *Client) TestCampaign(id int, emails []string) error {
	if len(emails) == 0 {
		return nil
	}
	payload := map[string]any{"subscribers": emails}
	respBody, status, err := c.do(http.MethodPost, fmt.Sprintf("/api/campaigns/%d/test", id), payload)
	if err != nil {
		return fmt.Errorf("sending test for campaign %d: %w", id, err)
	}
	if status != http.StatusOK {
		return fmt.Errorf("sending test for campaign %d failed (%d): %s", id, status, string(respBody))
	}
	return nil
}