Forms in Notes

Data Flow

Frontmatter         RawMeta              FormSpec               <script id=form-spec>
  form: ─────► RawMeta["form"] ─► formspec.ParseFromRawMeta ─► templateviews.Note.FormSpecJSON
                                                                       │
                                                                       ▼
                                                                  JSON in HTML
                                                                       │
                                                                       ▼
                                                          JS client → submitForm mutation
                                                                       │
                                                                       ▼
                                                          submitform.Resolve → form_submits + EAV
                                                                       │
                                                                       ▼
                                                          EnqueueSendFormSubmitEmail

Key Files

Frontmatter

Three shapes:

# 1. Single form
form:
  can_submit: admin              # guest | admin | paid_user
  success_url: /thanks           # redirect target after success
  fields:
    - { name: email, type: email, required: true }

# 2. Multiple named forms
forms:
  contact: { fields: [{ name: email, type: email }] }
  survey:  { can_submit: admin, fields: [{ name: rating, type: int, min: 1, max: 5 }] }

# 3. Reference to a shared spec
form_ref: "[[templates/comment_form]]"    # or: form_ref: templates/comment_form.md

Parsing: formspec.ParseFromRawMeta handles a single form: block and each entry of forms:. form_ref is resolved at render time through NVS (Ctx.FormSpecJSON in the default template). Submissions are always attached to the referencing note, not the spec source.

Field Types

EAV schema: one row per submission in form_submits, plus one row per value in a typed table. This avoids ballooning the schema for arbitrary field sets.

Authorisation — can_submit

Enforced in submitform.Resolve.checkCanSubmit (resolve.go):

switch spec.CanSubmit {
case "", formspec.CanSubmitGuest:
    return nil                                          // allow
case formspec.CanSubmitAdmin:
    if env.IsAdmin(ctx) { return nil }
    return &DeniedResult{Reason: DeniedAdminRequired}
case formspec.CanSubmitPaidUser:
    return &DeniedResult{Reason: DeniedNotSupported}    // not implemented yet
default:
    return nil                                          // forward-compatible
}

Env.IsAdmin lives on *app (cmd/server/main.go): pulls appreq.UserToken() and checks token.IsAdmin(). The token can arrive either as a cookie (trip2g_e2e=…) or as a Bearer (t2g_…); the admin role is set by personaltoken.Resolver when the token owner has a row in the admin table.

The GraphQL return is a union:

union SubmitFormOrErrorPayload =
    SubmitFormPayload          # { submitId: Int! }
  | FormSubmitDeniedPayload    # { reason: String! }
  | ErrorPayload               # { message, byFields[] }

Type mapping is in internal/graph/schema.resolvers.go (mutationResolver.SubmitForm).

Reading Submissions

API keys work: personaltoken.Resolver.Resolve assigns Role: "admin" when the token's owner has an admin row, so checkAdmin lets them through.

Default Template and Custom Layouts

The default template (views.html) does not actually render the form — it only emits the JSON. Rendering is the client JS's job. That JS does not currently exist in defaulttemplate.js, which means the form is not interactive out of the box — you either render it via a custom layout, or wait for the default renderer to land.

Sample custom layout: docs/_layouts/forms/example.html — builds fields from the spec, calls submitForm, handles SubmitFormPayload / FormSubmitDeniedPayload / ErrorPayload, and performs the success_url redirect.

templateviews.Note.FormSpecJSON() returns the same JSON shape as defaulttemplate.Ctx.FormSpecJSON(), minus form_ref resolution — without NVS access, custom layouts can't resolve refs yet.

Tests

• internal/formspec/spec_test.go — yaml → FormSpec parsing
• internal/case/submitform/resolve_test.go — validation, success, file_upload_not_supported, can_submit: admin allow/deny, paid_user → not_implemented
• internal/templateviews/note_test.go — FormSpecJSON for empty case, single form, named map
• e2e/forms.spec.js — embedded <script id=form-spec>, submission via mutation, anon → admin_required on an admin-only form, admin → success, success_url present in spec, admin read via admin.formSubmits

Current Spam Mitigation

• can_submit: admin removes anonymous spam entirely
• The existing user-ban system covers authenticated abusers
• Cloudflare Turnstile is on by default: submitform.Resolve calls Env.VerifyTurnstile whenever spec.Turnstile is true (the default if turnstile: is omitted). Forms that need to opt out set turnstile: false. The server returns TurnstileRequiredPayload{siteKey} when the token is missing or rejected — the client renders the widget keyed by siteKey and resubmits with turnstileToken filled in. Locally, turnstile-secret-key is unset so verification is a no-op; in production the key gates every submit.

Not Implemented (Roadmap)

Why This Matters — Agent-Driven Micro SaaS

When file + payment + webhook land, a closed loop emerges:

1. Frontend — a regular note with a form. SEO, sharing, any custom layout.
2. Auth + paywall — already there.
3. Submission storage — already there, typed EAV.
4. Payment — once the payment field exists, payment attaches to a submission.
5. Trigger — the webhook fires to an agent with a HAT token.
6. Agent logic — the agent replies to the user, writes a personal note via pushNotes, or grants access to a private folder via a subgraph.
7. Delivery — the user gets an email with a link to their personal note, or open access to the right subgraph.

The site owner can ship a landing page with payment intake, lead processing, and access delivery — with no separate backend. Note is the landing. Form is intake. Webhook is orchestration. Agent is business logic. trip2g is the runtime.

Roadmap

{{ forms.Get("/leads").Count() }}
{{ range i, s := forms.Get("/leads").Submits() }}
  {{ s.Field("email") }} — {{ s.CreatedAt() }}
{{ end }}

{{ range i, row := db.Query("SELECT field_value FROM form_string_values WHERE ...") }}
  {{ row.Get("field_value") }}
{{ end }}

Known Gaps

• form_ref is not resolved in custom layouts (templateviews.Note.FormSpecJSON) — only in the default template. Custom layouts that need a ref must inline the spec, or wait for a NVS.FormSpecJSON(note) helper.
• unprocessedFormSubmitsCount is a stub — it panics.
• No rate-limiting on guest forms. Not an issue with can_submit: admin, but mandatory once paid_user is enabled.
• The comment field on markFormSubmitProcessed is in the schema but not exposed in the admin UI.