@marlinjai/mail-sdk 0.6.0 → 0.7.0

package/README.md

@@ -197,6 +197,97 @@ Testing against a fake: implement the same replay rule (same key and body,
 same answer), `addRecipients` idempotent on the address, and at most one
 recipient on a letter, or the tests prove less than the real service does.
 
+## Declaring what a template receives
+
+A template's editor cannot see your code, so on its own it cannot say that
+`reason` is your contact form's "Reason" drop-down, which values it sends, or
+that `first_name` may be blank. Your app can say so: **declare each template's
+inputs** from the same constants your forms use, on every deploy. The editor
+then shows where every value comes from, names an insertion's rows by your
+labels ("I manage a venue", not `venue`), and starts its example values from
+your examples (`docs/public/mail-contract.md`, "Template inputs").
+
+```ts
+import { createMailClient, templateInputProblems, type TemplateInputsDeclaration } from '@marlinjai/mail-sdk';
+
+const mail = createMailClient({ baseUrl: process.env.MAIL_SERVICE_URL!, apiKey: process.env.MAIL_SERVICE_API_KEY! });
+
+// Built from the form's own constants, never typed twice.
+const contactReasons = ['general', 'venue', 'press'] as const;
+const reasonLabels: Record<(typeof contactReasons)[number], string> = {
+  general: 'General question',
+  venue: 'I manage a venue',
+  press: 'Press & Media',
+};
+
+export const contactInputs: TemplateInputsDeclaration['inputs'] = {
+  first_name: {
+    kind: 'text',
+    label: 'First name',
+    source: { kind: 'form_field', form: 'Contact form', field: 'Name' },
+    optional: true,
+    example: 'Anna',
+  },
+  reason: {
+    kind: 'one_of',
+    label: 'Contact reason',
+    source: {
+      kind: 'form_field',
+      form: 'Contact form',
+      field: 'Reason (dropdown)',
+      note: 'Also set by /contact?reason=; anything unknown is sent as general.',
+    },
+    values: contactReasons.map((value) => ({ value, label: reasonLabels[value] })),
+    example: 'venue',
+  },
+};
+
+/** Run after each deploy (or at server start), once per template the app sends from. */
+export async function declareInputs(commit: string) {
+  const result = await mail.templates.declareInputs(
+    process.env.MAIL_TEMPLATE_CONTACT_CONFIRMATION!,
+    { app: 'ŌPUNTIA website', app_version: commit, inputs: contactInputs },
+    { idempotencyKey: `inputs:contact:${commit}` },
+  );
+  return result.changed; // false when this commit declared exactly this already
+}
+```
+
+What each piece does, and why:
+
+- **The kinds** decide how the editor names an insertion's rows: `boolean`
+  (Yes and No; `false` and absent are both No), `text` and `url` (Has a value
+  and Is empty), `one_of` (a row per value with your label, then Anything else
+  and Not given). `values[].value` is exactly what your form sends, in an
+  insertion choice key's syntax (lowercase letters, digits, `-` and `_`).
+- **Where it comes from:** `form_field` names the form and the field as a
+  person sees them on your site; `derived` says in a `note` how your code works
+  it out ("the joined gathering's title in the visitor's language", "whether
+  the optional field was answered; the text is never sent").
+- **Only what you send.** `email` and `unsubscribe_url` are filled by the
+  service and refused (`input_reserved`); `first_name` and `last_name` are
+  yours to declare, since your merge values come first.
+- **Keep it true in your tests.** `templateInputProblems(inputs)` runs the
+  checks the service runs (a value listed twice, an example that is not a
+  value). Compare the declared names with the keys your merge builder returns,
+  so a renamed field fails your build, not a letter.
+- **On every deploy.** The same declaration again answers `changed: false` and
+  writes nothing; a new `app_version` alone moves `declared_at`, which is how
+  the editor tells a stale sync ("declared at commit 4d59e60, 3 days ago").
+  It creates no template version, so it never collides with someone editing
+  the template. Do not let a failed declaration fail the deploy: log it (to
+  Sentry, say) and carry on; the previous declaration stays in place.
+- **Who may declare.** An API key with `send` or `full` scope. The dashboard
+  cannot (`forbidden`, `details.reason: "api_key_only"`): the declaration
+  speaks for your code. A declaration replaces the one before whole, from
+  whichever app sends it; the audit log records each change and names the app
+  and key it replaced.
+- **What was really sent.** `templates.get` also returns `inputs_seen`: every
+  merge name your real sends of that template carried, with a count and when
+  first and last seen, names only, never values. `templateInputDrift(template.inputs,
+  template.inputs_seen)` lists what you declare but never send and what you
+  send but never declared.
+
 ## The dashboard variant: server-only, per signed-in person
 
 The mail service's own dashboard (`apps/dashboard`) signs people in through