feat(api): publisher flag on members and the publishers post policy

- the member DTO carries publisher
- POST /lists/{id}/members takes an optional publisher: absent leaves the flag
  of an existing member alone, true or false sets it
- PATCH /lists/{id}/members/{address} with {"publisher": bool}: 404 for a
  non-member, 400 when the field is missing
- the list PATCH accepts post_policy publishers; the validation message says so
- openapi updated
This commit is contained in:
tgiachi 2026-11-10 12:38:35 +01:00
commit 0bbfd43e30
3 changed files with 176 additions and 7 deletions

View file

@ -20,7 +20,7 @@ components:
domain: {type: string}
title: {type: string}
address: {type: string}
post_policy: {type: string, enum: [members, moderated]}
post_policy: {type: string, enum: [members, moderated, publishers], description: "publishers: a newsletter, only members flagged publisher may post"}
join_policy: {type: string, enum: [open, closed]}
archive_policy: {type: string, enum: [public, private, off], description: "public: browsable on the web; private: API only (default); off: not stored"}
Message:
@ -52,6 +52,7 @@ components:
display_name: {type: string}
disabled: {type: boolean, description: Disabled after 3 hard bounces within 30 days; re-adding the member re-enables it}
bounce_count: {type: integer, description: Recent hard bounces (restarts at 1 when the last one is older than 30 days)}
publisher: {type: boolean, description: May post when the list's post_policy is publishers}
Held:
type: object
properties:
@ -142,7 +143,7 @@ paths:
type: object
properties:
title: {type: string, minLength: 1, maxLength: 200, description: A single line without control characters.}
post_policy: {type: string, enum: [members, moderated]}
post_policy: {type: string, enum: [members, moderated, publishers], description: "publishers: a newsletter, only members flagged publisher may post"}
join_policy: {type: string, enum: [open, closed]}
archive_policy: {type: string, enum: [public, private, off]}
responses:
@ -182,6 +183,7 @@ paths:
properties:
address: {type: string}
display_name: {type: string}
publisher: {type: boolean, description: "Absent: an existing member keeps its flag (a new one is not a publisher); true or false: set it"}
responses:
'201':
description: Created
@ -199,6 +201,21 @@ paths:
responses:
'204': {description: Removed}
'404': {$ref: '#/components/responses/Error'}
patch:
summary: Make a member a publisher or a plain subscriber
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [publisher]
properties:
publisher: {type: boolean}
responses:
'204': {description: Updated}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/held:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}

View file

@ -68,6 +68,7 @@ func (s *server) routes() []route {
{"GET /api/v1/lists/{id}/members", s.auth(s.listMembers)},
{"POST /api/v1/lists/{id}/members", s.auth(s.addMember)},
{"DELETE /api/v1/lists/{id}/members/{address}", s.auth(s.removeMember)},
{"PATCH /api/v1/lists/{id}/members/{address}", s.auth(s.updateMember)},
{"GET /api/v1/lists/{id}/archive", s.auth(s.listArchive)},
{"POST /api/v1/lists/{id}/archive/import", s.auth(s.importArchive)},
{"GET /api/v1/archive/{id}", s.auth(s.getArchived)},
@ -124,6 +125,7 @@ type memberDTO struct {
DisplayName string `json:"display_name"`
Disabled bool `json:"disabled"`
BounceCount int `json:"bounce_count"`
Publisher bool `json:"publisher"`
}
// Helpers.
@ -322,10 +324,10 @@ func (s *server) updateList(w http.ResponseWriter, r *http.Request) {
l.ArchivePolicy = *in.ArchivePolicy
}
// Validate before writing anything.
if (l.PostPolicy != store.PostMembers && l.PostPolicy != store.PostModerated) ||
if (l.PostPolicy != store.PostMembers && l.PostPolicy != store.PostModerated && l.PostPolicy != store.PostPublishers) ||
(l.JoinPolicy != store.JoinOpen && l.JoinPolicy != store.JoinClosed) ||
(l.ArchivePolicy != store.ArchivePublic && l.ArchivePolicy != store.ArchivePrivate && l.ArchivePolicy != store.ArchiveOff) {
writeError(w, http.StatusBadRequest, "post_policy must be members or moderated; join_policy open or closed; archive_policy public, private or off")
writeError(w, http.StatusBadRequest, "post_policy must be members, moderated or publishers; join_policy open or closed; archive_policy public, private or off")
return
}
if err := s.store.UpdateList(id, l.Title); err != nil {
@ -369,7 +371,7 @@ func (s *server) listMembers(w http.ResponseWriter, r *http.Request) {
}
out := make([]memberDTO, 0, len(ms))
for _, m := range ms {
out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount})
out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount, Publisher: m.Publisher})
}
writeJSON(w, http.StatusOK, out)
}
@ -379,7 +381,11 @@ func (s *server) addMember(w http.ResponseWriter, r *http.Request) {
if !ok {
return
}
var in memberDTO
// publisher is optional: absent leaves an existing member's flag as it is.
var in struct {
memberDTO
Publisher *bool `json:"publisher"`
}
if !decodeBody(w, r, &in) {
return
}
@ -400,7 +406,41 @@ func (s *server) addMember(w http.ResponseWriter, r *http.Request) {
storeError(w, err)
return
}
writeJSON(w, http.StatusCreated, memberDTO{Address: strings.ToLower(a.Address), DisplayName: in.DisplayName})
if in.Publisher != nil {
if err := s.store.SetPublisher(id, a.Address, *in.Publisher); err != nil {
storeError(w, err)
return
}
}
pub, err := s.store.IsPublisher(id, a.Address)
if err != nil {
storeError(w, err)
return
}
writeJSON(w, http.StatusCreated, memberDTO{Address: strings.ToLower(a.Address), DisplayName: in.DisplayName, Publisher: pub})
}
// updateMember changes the publisher flag of a member.
func (s *server) updateMember(w http.ResponseWriter, r *http.Request) {
id, ok := listID(w, r)
if !ok {
return
}
var in struct {
Publisher *bool `json:"publisher"`
}
if !decodeBody(w, r, &in) {
return
}
if in.Publisher == nil {
writeError(w, http.StatusBadRequest, "publisher (true or false) is required")
return
}
if err := s.store.SetPublisher(id, r.PathValue("address"), *in.Publisher); err != nil {
storeError(w, err)
return
}
w.WriteHeader(http.StatusNoContent)
}
func (s *server) removeMember(w http.ResponseWriter, r *http.Request) {

View file

@ -0,0 +1,112 @@
package api
import (
"net/http"
"strings"
"testing"
)
type publisherJSON struct {
Address string `json:"address"`
Publisher bool `json:"publisher"`
}
// publishers returns the publisher flag of every member of list 1, by address.
func publishers(t *testing.T, h http.Handler) map[string]bool {
t.Helper()
rec := do(t, h, "GET", "/api/v1/lists/1/members", "", true)
expect(t, rec, 200)
var ms []publisherJSON
decode(t, rec, &ms)
out := map[string]bool{}
for _, m := range ms {
out[m.Address] = m.Publisher
}
return out
}
func TestAddMemberWithThePublisherFlag(t *testing.T) {
h := newServer(t)
createList(t, h)
rec := do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com","publisher":true}`, true)
expect(t, rec, 201)
var m publisherJSON
decode(t, rec, &m)
if !m.Publisher {
t.Fatalf("created: %+v", m)
}
expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"b@x.com"}`, true), 201)
if got := publishers(t, h); !got["a@x.com"] || got["b@x.com"] {
t.Fatalf("publishers: %v", got)
}
}
func TestAddMemberLeavesThePublisherFlagAloneWhenAbsent(t *testing.T) {
h := newServer(t)
createList(t, h)
expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com","publisher":true}`, true), 201)
rec := do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com","display_name":"A"}`, true)
expect(t, rec, 201)
var m publisherJSON
decode(t, rec, &m)
if !m.Publisher || !publishers(t, h)["a@x.com"] {
t.Fatalf("re-adding keeps the flag: %+v %v", m, publishers(t, h))
}
// An explicit false demotes an existing member.
rec = do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com","publisher":false}`, true)
expect(t, rec, 201)
decode(t, rec, &m)
if m.Publisher || publishers(t, h)["a@x.com"] {
t.Fatalf("demoted: %+v %v", m, publishers(t, h))
}
}
func TestPatchMemberSetsThePublisherFlag(t *testing.T) {
h := newServer(t)
createList(t, h)
expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com"}`, true), 201)
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/A%40X.com", `{"publisher":true}`, true), 204)
if !publishers(t, h)["a@x.com"] {
t.Fatal("promoted")
}
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/a%40x.com", `{"publisher":false}`, true), 204)
if publishers(t, h)["a@x.com"] {
t.Fatal("demoted")
}
}
func TestPatchMemberErrors(t *testing.T) {
h := newServer(t)
createList(t, h)
expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com"}`, true), 201)
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/b%40x.com", `{"publisher":true}`, true), 404)
expect(t, do(t, h, "PATCH", "/api/v1/lists/99/members/a%40x.com", `{"publisher":true}`, true), 404)
rec := do(t, h, "PATCH", "/api/v1/lists/1/members/a%40x.com", `{}`, true)
expect(t, rec, 400)
if !strings.Contains(rec.Body.String(), "publisher") {
t.Fatalf("the error names the field: %s", rec.Body.String())
}
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/a%40x.com", `{"publisher":"yes"}`, true), 400)
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/a%40x.com", `{"publisher":true,"x":1}`, true), 400)
expect(t, do(t, h, "PATCH", "/api/v1/lists/1/members/a%40x.com", `{"publisher":true}`, false), 401)
if publishers(t, h)["a@x.com"] {
t.Fatal("nothing changed")
}
}
func TestThePublishersPostPolicyViaAPI(t *testing.T) {
h := newServer(t)
createList(t, h)
rec := do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"publishers"}`, true)
expect(t, rec, 200)
var l listJSON
decode(t, rec, &l)
if l.PostPolicy != "publishers" {
t.Fatalf("patched: %+v", l)
}
rec = do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"bogus"}`, true)
expect(t, rec, 400)
if !strings.Contains(rec.Body.String(), "members, moderated or publishers") {
t.Fatalf("the message lists the policies: %s", rec.Body.String())
}
}