- Judge membership on the envelope sender and require the From header to name the same address - Hold mismatches (and missing, unparsable or multiple From addresses) for the admin instead of delivering - Record why a message was held: new held.reason column, migrated, shown in the API, CLI and UI - Accept an empty message in the held queue - Document who may post
177 lines
5 KiB
TypeScript
177 lines
5 KiB
TypeScript
// Typed client for the Parsimony admin REST API (/api/v1).
|
|
|
|
export type PostPolicy = 'members' | 'moderated'
|
|
export type JoinPolicy = 'open' | 'closed'
|
|
export type ArchivePolicy = 'public' | 'private' | 'off'
|
|
|
|
export interface List {
|
|
id: number
|
|
name: string
|
|
domain: string
|
|
title: string
|
|
address: string
|
|
post_policy: PostPolicy
|
|
join_policy: JoinPolicy
|
|
archive_policy: ArchivePolicy
|
|
}
|
|
|
|
export interface Member {
|
|
address: string
|
|
display_name: string
|
|
disabled: boolean
|
|
bounce_count: number
|
|
}
|
|
|
|
export interface Held {
|
|
id: number
|
|
sender: string
|
|
subject: string
|
|
size: number
|
|
created_at: string
|
|
/** Why the message was held, for the admin. */
|
|
reason: string
|
|
}
|
|
|
|
export interface Message {
|
|
id: number
|
|
thread_id: number
|
|
message_id: string
|
|
in_reply_to?: string
|
|
subject: string
|
|
sender: string
|
|
date: string
|
|
size: number
|
|
body?: string
|
|
}
|
|
|
|
export interface ImportSummary {
|
|
imported: number
|
|
duplicates: number
|
|
failed: number
|
|
errors: string[]
|
|
}
|
|
|
|
export interface ArchivePage {
|
|
total: number
|
|
messages: Message[]
|
|
}
|
|
|
|
export interface QueueItem {
|
|
id: number
|
|
recipient: string
|
|
attempts: number
|
|
last_error: string
|
|
next_attempt: string
|
|
created_at: string
|
|
}
|
|
|
|
export interface Queue {
|
|
pending: number
|
|
retrying: number
|
|
oldest: string | null
|
|
items: QueueItem[]
|
|
}
|
|
|
|
export class ApiError extends Error {
|
|
readonly status: number
|
|
constructor(status: number, message: string) {
|
|
super(message)
|
|
this.name = 'ApiError'
|
|
this.status = status
|
|
}
|
|
}
|
|
|
|
const TOKEN_KEY = 'parsimony.token'
|
|
let unauthorizedHandler: (() => void) | null = null
|
|
|
|
/** The bearer token lives in sessionStorage: it dies with the tab. */
|
|
export const session = {
|
|
get: (): string | null => sessionStorage.getItem(TOKEN_KEY),
|
|
set: (token: string) => sessionStorage.setItem(TOKEN_KEY, token),
|
|
clear: () => sessionStorage.removeItem(TOKEN_KEY),
|
|
/** Called after any 401, once the token has been cleared. */
|
|
onUnauthorized: (fn: (() => void) | null) => {
|
|
unauthorizedHandler = fn
|
|
},
|
|
}
|
|
|
|
async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
|
|
const headers: Record<string, string> = {}
|
|
const token = session.get()
|
|
if (token) headers.Authorization = `Bearer ${token}`
|
|
// A file is streamed as is; everything else is JSON.
|
|
const raw = body instanceof Blob
|
|
if (body !== undefined) headers['Content-Type'] = raw ? 'application/mbox' : 'application/json'
|
|
|
|
let res: Response
|
|
try {
|
|
res = await fetch(`/api/v1${path}`, {
|
|
method,
|
|
headers,
|
|
body: body === undefined ? undefined : raw ? body : JSON.stringify(body),
|
|
})
|
|
} catch {
|
|
throw new ApiError(0, 'Cannot reach the server')
|
|
}
|
|
|
|
if (res.status === 401) {
|
|
session.clear()
|
|
unauthorizedHandler?.()
|
|
}
|
|
if (!res.ok) {
|
|
let message = `Request failed (${res.status})`
|
|
try {
|
|
const data = await res.json()
|
|
if (typeof data?.error === 'string') message = data.error
|
|
} catch {
|
|
// not JSON: keep the generic message
|
|
}
|
|
throw new ApiError(res.status, message)
|
|
}
|
|
if (res.status === 204) return undefined as T
|
|
return (await res.json()) as T
|
|
}
|
|
|
|
const enc = encodeURIComponent
|
|
|
|
export const api = {
|
|
lists: {
|
|
list: () => request<List[]>('GET', '/lists'),
|
|
get: (id: number) => request<List>('GET', `/lists/${id}`),
|
|
create: (b: { name: string; domain: string; title?: string }) => request<List>('POST', '/lists', b),
|
|
update: (
|
|
id: number,
|
|
b: Partial<Pick<List, 'title' | 'post_policy' | 'join_policy' | 'archive_policy'>>,
|
|
) => request<List>('PATCH', `/lists/${id}`, b),
|
|
remove: (id: number) => request<void>('DELETE', `/lists/${id}`),
|
|
},
|
|
members: {
|
|
list: (listId: number) => request<Member[]>('GET', `/lists/${listId}/members`),
|
|
add: (listId: number, b: { address: string; display_name?: string }) =>
|
|
request<Member>('POST', `/lists/${listId}/members`, b),
|
|
remove: (listId: number, address: string) =>
|
|
request<void>('DELETE', `/lists/${listId}/members/${enc(address)}`),
|
|
},
|
|
held: {
|
|
list: (listId: number) => request<Held[]>('GET', `/lists/${listId}/held`),
|
|
approve: (id: number) => request<void>('POST', `/held/${id}/approve`),
|
|
discard: (id: number) => request<void>('DELETE', `/held/${id}`),
|
|
},
|
|
queue: {
|
|
get: () => request<Queue>('GET', '/queue'),
|
|
discard: (id: number) => request<void>('DELETE', `/queue/${id}`),
|
|
},
|
|
archive: {
|
|
list: (listId: number, p: { q?: string; limit?: number; offset?: number } = {}) => {
|
|
const qs = new URLSearchParams()
|
|
if (p.q) qs.set('q', p.q)
|
|
if (p.limit !== undefined) qs.set('limit', String(p.limit))
|
|
if (p.offset !== undefined) qs.set('offset', String(p.offset))
|
|
const s = qs.toString()
|
|
return request<ArchivePage>('GET', `/lists/${listId}/archive${s ? `?${s}` : ''}`)
|
|
},
|
|
import: (listId: number, file: Blob) => request<ImportSummary>('POST', `/lists/${listId}/archive/import`, file),
|
|
get: (id: number) => request<Message>('GET', `/archive/${id}`),
|
|
remove: (id: number) => request<void>('DELETE', `/archive/${id}`),
|
|
},
|
|
}
|