Files
zeekayandGitHub 38494b3909 form: forms, responses, themes and webhooks as typed ops (#1)
A form is defined once and answered at a public address, "<org>.<slug or id>",
by anyone or a signed-in person. Every record lives in the org's own store; the
host supplies who is calling, the store, the rate window, the settings and the
sinks (event stream, CRM, mail, KMS for webhook secrets).

A response is keyed by its token, so a double click is one response; a
subscribe form's by its address. A completed response goes to the CRM keyed by
the person id, never the address, and to signed webhooks that dial public
addresses only.

Claude-Session: https://claude.ai/code/session_016DKtyuzxU43Gsc6Pm9vKTF
2026-11-02 05:24:06 -08:00

351 lines
10 KiB
Go

package form
// forms.go — an org's forms: made, listed, read, replaced, changed and deleted
// by the org's admins.
import (
"context"
"errors"
"net/http"
"strings"
"github.com/zap-proto/zip"
)
// FormRef names one form of the caller's org.
type FormRef struct {
// ID is the form's id or its slug, from the path.
ID string `json:"id"`
}
// FormList is one page of an org's forms.
type FormList struct {
// Items are the forms, newest first.
Items []Form `json:"items"`
// Page is this page, from 1.
Page int `json:"page"`
// PageSize is how many a page holds.
PageSize int `json:"page_size"`
// Total is how many forms answer the query.
Total int `json:"total"`
}
// FormsIn asks for a page of the org's forms.
type FormsIn struct {
// Page is the page, from 1. Default 1.
Page int `json:"page"`
// PageSize is how many a page holds: at most 200, default 50.
PageSize int `json:"page_size"`
// Search keeps the forms whose title holds it.
Search string `json:"search"`
// Tag keeps the forms tagged with it.
Tag string `json:"tag"`
}
// FormPatch is a change to a form: every field present replaces the form's, every
// field absent keeps it.
type FormPatch struct {
// ID is the form's id or its slug, from the path.
ID string `json:"id"`
Kind *string `json:"kind,omitempty"`
Title *string `json:"title,omitempty"`
Fields []Field `json:"fields,omitempty"`
Welcome *Screen `json:"welcome,omitempty"`
Thanks *Screen `json:"thanks,omitempty"`
Hidden []string `json:"hidden,omitempty"`
Settings *Options `json:"settings,omitempty"`
Theme *string `json:"theme,omitempty"`
Tags []string `json:"tags,omitempty"`
Sinks *Sinks `json:"sinks,omitempty"`
}
// formKey is the record id a form's id or slug names.
func formKey(key string) string {
key = strings.TrimSpace(key)
if recordID(key) {
return key
}
return derived("form", key)
}
// lookup reads the form key names, by id and then by slug.
func (s *service) lookup(ctx context.Context, org, key string) (*Form, error) {
key = strings.TrimSpace(key)
ids := []string{formKey(key)}
if recordID(key) && slugShape.MatchString(key) {
ids = append(ids, derived("form", key))
}
for _, id := range ids {
r, err := s.d.Store.Get(ctx, org, Forms, id)
if errors.Is(err, ErrNotFound) {
continue
}
if err != nil {
return nil, s.failed("the form could not be read", org, err)
}
f := formOf(org, r)
return &f, nil
}
return nil, zip.ErrNotFound("form: no such form")
}
// formOf is a stored form as the wire carries it.
func formOf(org string, r Record) Form {
var f Form
decode(r, "doc", &f)
f.ID = field(r, "id")
f.Slug = field(r, "slug")
f.PublicID = org + "." + publicName(f)
f.Created, f.Updated = wire(r, "created"), wire(r, "updated")
if f.Fields == nil {
f.Fields = []Field{}
}
return f
}
// publicName is the part of a public id that names the form in its org.
func publicName(f Form) string {
if f.Slug != "" {
return f.Slug
}
return f.ID
}
// recordOf is a form as the store keeps it.
func recordOf(f Form) Record {
doc := f
doc.ID, doc.PublicID, doc.Created, doc.Updated = "", "", "", ""
tags := f.Tags
if tags == nil {
tags = []string{}
}
return Record{"id": f.ID, "slug": f.Slug, "title": f.Title, "kind": f.Kind, "theme": f.Theme, "tags": tags, "doc": doc}
}
// save checks f against the platform and its theme and writes it.
func (s *service) save(ctx context.Context, org string, f Form, held *Form) (*Form, error) {
f, problems := checkForm(f, s.settings(ctx), held)
if len(problems) > 0 {
return nil, zip.ErrBadRequest("form: " + strings.Join(problems, "; "))
}
if f.Theme != "" {
if _, err := s.d.Store.Get(ctx, org, Themes, f.Theme); errors.Is(err, ErrNotFound) {
return nil, zip.ErrBadRequest("form: theme names no theme of this org")
} else if err != nil {
return nil, s.failed("the theme could not be read", org, err)
}
}
if err := s.d.Store.Put(ctx, org, Forms, recordOf(f)); err != nil {
return nil, s.failed("the form could not be saved", org, err)
}
if err := s.publish(ctx, org, f, f.Settings.Visibility == "public"); err != nil {
return nil, err
}
return s.lookup(ctx, org, f.ID)
}
// publish puts a form's public id in the index, or takes it out.
func (s *service) publish(ctx context.Context, org string, f Form, public bool) error {
if err := s.indexReady(ctx); err != nil {
return err
}
pid := org + "." + publicName(f)
id := derived("public", pid)
var err error
if public {
err = s.d.Store.Put(ctx, s.d.Platform, Index, Record{"id": id, "public": pid, "org": org, "form": f.ID})
} else {
err = s.d.Store.Delete(ctx, s.d.Platform, Index, id)
}
if err != nil {
return s.failed("the form's public address could not be written", org, err)
}
return nil
}
// Makes a form in the caller's org and answers it as stored, its fields' ids
// assigned and its defaults filled: kind form, visibility public, language en,
// one question at a time, and the platform's default sinks when it names none.
//
// A slug, when given, is the form's id for good: a second form with the same
// slug is refused (409). Every problem with the form is named at once (400). An
// org admin only.
//
// Example: {"slug":"video-feedback","title":"How was the video?","fields":[{"ref":"rating","type":"rating","title":"Rate the video","required":true},{"ref":"comment","type":"long_text","title":"Anything to tell us?"}],"hidden":["video"]}
func (s *service) createForm(ctx context.Context, in *Form) (*Form, error) {
org, err := s.change(ctx)
if err != nil {
return nil, err
}
f := *in
f.Slug = strings.TrimSpace(f.Slug)
if f.Slug != "" {
f.ID = derived("form", f.Slug)
if _, err := s.d.Store.Get(ctx, org, Forms, f.ID); err == nil {
return nil, zip.Errorf(http.StatusConflict, "form: a form with slug %q exists", f.Slug)
} else if !errors.Is(err, ErrNotFound) {
return nil, s.failed("the form could not be read", org, err)
}
} else {
f.ID = fresh()
}
return s.save(ctx, org, f, nil)
}
// Lists the caller org's forms, newest first, a page at a time; search keeps
// the forms whose title holds it and tag the ones carrying it. An org admin only.
func (s *service) listForms(ctx context.Context, in *FormsIn) (*FormList, error) {
org, err := s.admin(ctx)
if err != nil {
return nil, err
}
if err := s.ready(ctx, org); err != nil {
return nil, err
}
page, size := paged(in.Page, in.PageSize, 50, 200)
var where []Record
if q := strings.TrimSpace(in.Search); q != "" {
where = append(where, leaf("title", "contains", q))
}
if t := strings.TrimSpace(in.Tag); t != "" {
where = append(where, leaf("tags", "contains", t))
}
got, err := s.d.Store.List(ctx, org, Forms, Query{Where: and(where...), Sort: "-created", Page: page, PerPage: size, Count: true})
if err != nil {
return nil, s.failed("the forms could not be read", org, err)
}
out := &FormList{Items: []Form{}, Page: page, PageSize: size, Total: got.Total}
for _, r := range got.Items {
out.Items = append(out.Items, formOf(org, r))
}
return out, nil
}
// Reads one form of the caller's org, by its id or its slug. An org admin only.
func (s *service) getForm(ctx context.Context, in *FormRef) (*Form, error) {
org, err := s.admin(ctx)
if err != nil {
return nil, err
}
if err := s.ready(ctx, org); err != nil {
return nil, err
}
return s.lookup(ctx, org, in.ID)
}
// Replaces a form whole and answers it as stored. Named by a slug no form has
// yet, it makes the form under that slug, so a definition written twice is one
// form: the way a seed states a form. A field sent with its id keeps it; a type
// the platform no longer offers stays answerable where the form already asks
// it, and is refused where it is new. An org admin only.
func (s *service) replaceForm(ctx context.Context, in *Form) (*Form, error) {
org, err := s.change(ctx)
if err != nil {
return nil, err
}
key := strings.TrimSpace(in.ID)
held, err := s.lookup(ctx, org, key)
var he *zip.HTTPError
switch {
case err == nil:
case errors.As(err, &he) && he.Status == http.StatusNotFound && !recordID(key) && slugShape.MatchString(key):
f := *in
f.Slug, f.ID = key, derived("form", key)
return s.save(ctx, org, f, nil)
default:
return nil, err
}
f := *in
f.ID = held.ID
if f.Slug == "" {
f.Slug = held.Slug
}
return s.save(ctx, org, f, held)
}
// Changes the parts of a form the body names and keeps the rest, then answers it
// as stored. The whole form is checked as it will be, exactly as a replace is.
// An org admin only.
func (s *service) updateForm(ctx context.Context, in *FormPatch) (*Form, error) {
org, err := s.change(ctx)
if err != nil {
return nil, err
}
held, err := s.lookup(ctx, org, in.ID)
if err != nil {
return nil, err
}
f := *held
if in.Kind != nil {
f.Kind = *in.Kind
}
if in.Title != nil {
f.Title = *in.Title
}
if in.Fields != nil {
f.Fields = in.Fields
}
if in.Welcome != nil {
f.Welcome = in.Welcome
}
if in.Thanks != nil {
f.Thanks = in.Thanks
}
if in.Hidden != nil {
f.Hidden = in.Hidden
}
if in.Settings != nil {
f.Settings = *in.Settings
}
if in.Theme != nil {
f.Theme = *in.Theme
}
if in.Tags != nil {
f.Tags = in.Tags
}
if in.Sinks != nil {
f.Sinks = in.Sinks
}
return s.save(ctx, org, f, held)
}
// Deletes a form with every response, webhook and delivery it has, and the
// webhooks' signing secrets. An org admin only.
func (s *service) deleteForm(ctx context.Context, in *FormRef) (*struct{}, error) {
org, err := s.change(ctx)
if err != nil {
return nil, err
}
f, err := s.lookup(ctx, org, in.ID)
if err != nil {
return nil, err
}
hooks, err := s.d.Store.List(ctx, org, Webhooks, Query{Where: leaf("form", "is", f.ID), PerPage: 100})
if err != nil {
return nil, s.failed("the form's webhooks could not be read", org, err)
}
for _, h := range hooks.Items {
if err := s.forget(ctx, org, field(h, "id")); err != nil {
return nil, err
}
}
if err := s.publish(ctx, org, *f, false); err != nil {
return nil, err
}
if err := s.d.Store.Delete(ctx, org, Forms, f.ID); err != nil {
return nil, s.failed("the form could not be deleted", org, err)
}
return &struct{}{}, nil
}
// paged is a page and its size, each defaulted and bounded.
func paged(page, size, def, most int) (int, int) {
if page < 1 {
page = 1
}
if size < 1 {
size = def
}
return page, min(size, most)
}