@softure-ai/waitlist 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# @softure-ai/waitlist
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Collects sign-ups before a product opens: one row per email address with the consent scopes the
+person checked, evidence of each consent in privacy's ledger, a welcome mail sent once through
+mailing, and a standalone form. Built from FIRE_TRACKER's waitlist (`src/db/waitlist.ts`,
+`src/app/actions/{do-waitlist,waitlist,waitlist-contract}.ts`,
+`src/lib/{waitlist-consent,waitlist-placement,welcome-mail}.ts`, `src/components/consent-checkbox.tsx`
+and the form inside `calculator-lista.tsx`), with the scopes and placements moved from CHECK
+constraints into the app's configuration and the form out of the domain component.
+
+## 1. What it provides
+
+- The table `waitlist.signups`: the address (trimmed, lowercased, unique), the granted scopes in
+  the config's order, the placement of the first sign-up, the locale, its timestamps and, with
+  double opt-in, the request that waits for its confirmation link.
+- **Double opt-in as an option** (`doubleOptIn`, off by default). A sign-up then waits for the link
+  in a confirmation mail: until it is used, nothing is recorded, no opt-out is lifted, no list mail
+  goes out and `listSignups` leaves the address out. The link applies the request and sends the
+  welcome mail.
+- **Consent scopes from configuration.** The app declares them in `waitlist({ scopes })`, with
+  labels per locale, which ones are required and the legal document each refers to. The table
+  checks only their shape; nothing app-specific is hard-coded in a migration.
+- **Repeat sign-ups widen, never narrow.** Signing up again adds the newly checked scopes and keeps
+  the earlier ones. The answer is the same for a new and a known address.
+- **Consent evidence in privacy.** Each requested scope the ledger does not currently grant (never
+  given, withdrawn, or given to an older version of its document) is recorded with
+  `recordConsent` (source `waitlist`, the document's version), in the sign-up's transaction.
+- **A welcome mail after the response**, through mailing's delivery ledger: at most once per
+  sign-up (scope `waitlist.welcome:<id>`), as list mail of kind `waitlist`, so it carries mailing's
+  unsubscribe link and RFC 8058 headers and is never sent to an address that unsubscribed. Text
+  and HTML; the app can render the HTML of both mails with its own template (`mailTemplate`).
+- **The ledger follows unsubscribes.** `withdrawWaitlistConsents`, wired as mailing's
+  `onUnsubscribed`, records a withdrawal of every scope the address still grants, in the opt-out's
+  transaction. A new sign-up lifts the address's own opt-out (`liftSuppression`) in its
+  transaction and, after one, stores exactly the scopes checked this time.
+- **A rate-limited public action**: bucket `waitlist` per client, `waitlist-email` per address.
+- `<Waitlist placement="hero" />` (`/next`), the form wired in one line, and `WaitlistForm` (`/ui`)
+  with slots, `unstyled` and messages for an app that composes its own.
+- Export and deletion of the account's sign-up (`@softure-ai/privacy`), a health check for
+  `GET /api/health`, and `listSignups` for a launch mail.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/waitlist @softure-ai/mailing @softure-ai/privacy @softure-ai/auth @softure-ai/security @softure-ai/core @softure-ai/db @softure-ai/ui drizzle-orm zod
+```
+
+Peer dependencies: `next` 16, `react` 19, `drizzle-orm`. The module depends on `security`,
+`mailing` and `privacy` (which needs `auth`); a configuration without them fails at startup.
+
+## 3. Configuration
+
+```ts
+import { auth, AUTH_RATE_LIMIT_BUCKETS } from "@softure-ai/auth";
+import { mailing, resend } from "@softure-ai/mailing";
+import { privacy } from "@softure-ai/privacy";
+import { cloudflareIp, security } from "@softure-ai/security";
+import { waitlist, WAITLIST_RATE_LIMIT_BUCKETS } from "@softure-ai/waitlist";
+import { withdrawWaitlistConsents } from "@softure-ai/waitlist/server";
+import { en } from "./messages/en";
+import { pl } from "./messages/pl";
+
+// in defineSoftureConfig({ modules: [...] }):
+security({ clientIp: cloudflareIp(), buckets: { ...AUTH_RATE_LIMIT_BUCKETS, ...WAITLIST_RATE_LIMIT_BUCKETS } }),
+auth({ ... }),
+// An unsubscribe withdraws the waitlist's consents (section 10):
+mailing({ from: "Acme <hello@mail.acme.com>", provider: resend(), onUnsubscribed: withdrawWaitlistConsents }),
+privacy({ documents: [{ id: "privacy-policy", version: "2026-10-01" }] }),
+waitlist({
+  scopes: [
+    { id: "launch", required: true, document: "privacy-policy", label: { en: en.waitlist.launch, pl: pl.waitlist.launch } },
+    { id: "newsletter", label: { en: en.waitlist.newsletter, pl: pl.waitlist.newsletter } },
+  ],
+  placements: ["hero", "footer"],
+}),
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `scopes` | `{ id, required?, document?, label: { en, pl? } }[]`, 1 to 16 | required | The checkboxes, in order. `id` is kebab-case (at most 64 characters) and becomes the consent purpose in `privacy.consents`. `required` scopes must be checked; without any required scope, at least one must be. `document` names a document of `privacy({ documents })`, whose version is recorded with the consent. |
+| `placements` | kebab-case `string[]` | `["default"]` | Where the app embeds the form. Each sign-up stores the placement of its first form. |
+| `welcomeMail` | `boolean` | `true` | Sends the welcome mail (with double opt-in, after the confirmation). Off, the app sends its own (or none). |
+| `doubleOptIn` | `boolean` or `{ expiresInHours? }` | `false` | A sign-up counts only after the link in a confirmation mail is used. `true` keeps the link working for 168 hours (7 days); `expiresInHours` sets 1 to 720. Section 10. |
+| `mailTemplate` | `(mail) => string` | — | Renders the HTML body of the welcome and confirmation mails (below). Without it, a plain HTML body built from the same copy. |
+| `onJoined` | `(event, ctx) => void \| Promise<void>` | — | Called in the sign-up's transaction when a sign-up counts for the first time, e.g. to count it in the analytics funnel. Section 10. |
+| `rewriteConfirmationLink` | `(path, { config }) => string \| Promise<string>` | — | Rewrites the confirmation link's path, e.g. to keep the analytics channel tag through the mail. Section 10. |
+| `routes` | `{ confirm? }` | `{ confirm: "/waitlist/confirm" }` | The path of the confirmation page, when the app mounts it elsewhere. |
+| `messages` | partial `en` / `pl` | — | Copy overrides, the welcome mail's subject and text included. |
+
+`WAITLIST_RATE_LIMIT_BUCKETS` is `{ waitlist: { limit: 10, windowMinutes: 15 }, "waitlist-email": { limit: 3, windowMinutes: 60 } }`.
+Every attempt counts per client before anything is checked; the per-address bucket stops one
+address from being signed up over and over. The first sign-up checks once that both buckets are
+configured and that every scope's document is declared, and throws naming what is missing.
+
+The welcome mail is list mail, so mailing needs `MAILING_UNSUBSCRIBE_SECRET` (mailing README §6);
+without it the mail is refused and the sign-up still succeeds. The confirmation mail is
+transactional and needs no secret.
+
+Both mails carry a text body and an HTML body built from the same copy: each paragraph (blocks
+split by a blank line) escaped in `<p>`, and in the confirmation mail the link as an anchor
+labelled `confirmationMail.action`. Mailing adds its unsubscribe footer to both bodies of the
+welcome mail (inside `<body>` when the HTML is a whole document). To use the app's own layout, pass
+a template; it gets `kind` (`welcome` or `confirmation`), `locale`, `subject`, `paragraphs` (plain
+text: escape them with `escapeHtml`), `body` (the default HTML, safe to wrap) and, for the
+confirmation mail, `action: { href, label }`:
+
+```ts
+import { escapeHtml, waitlist, type WaitlistMailTemplate } from "@softure-ai/waitlist";
+
+const mailTemplate: WaitlistMailTemplate = (mail) =>
+  `<!doctype html><html lang="${mail.locale}"><body><h1>${escapeHtml(mail.subject)}</h1>${mail.body}</body></html>`;
+
+waitlist({ scopes: [...], mailTemplate });
+```
+
+The template runs when the mail is sent, after the response to the form or the link. One that
+throws, or returns blank HTML (the module then throws an error naming `mailTemplate`), sends no
+mail: the sign-up stands, and the error reaches the app's logs.
+
+## 4. Mounting
+
+The form posts to a server action that ships in the package. Embed it in any server component:
+
+```tsx
+import { Waitlist } from "@softure-ai/waitlist/next";
+
+<Waitlist placement="hero" />
+// a label with a link, in place of the config's text:
+<Waitlist placement="footer" consentLabels={{ launch: <>Tell me when it opens (<a href="/legal/privacy">privacy policy</a>).</> }} />
+```
+
+With double opt-in, mount the confirmation page (the link in the mail opens it):
+
+```tsx
+// app/waitlist/confirm/page.tsx
+export { ConfirmSignupPage as default } from "@softure-ai/waitlist/next";
+```
+
+Opening the page changes nothing (mail scanners open links): it shows a button that posts
+`confirmSignupAction`, which confirms and redirects back with `?status=done` (or `invalid`,
+`expired`, `limited`, `failed`; the last two keep the link for a retry).
+
+An app that composes its own form passes `joinWaitlistAction` (`/next`) to `WaitlistForm` (`/ui`)
+with the scopes it prepared (`{ id, label, required }`), the placement and the messages.
+
+Server functions, for scripts and other hosts (`@softure-ai/waitlist/server`):
+`joinWaitlist(ctx, { email, scopes, placement, clientKey })` returns
+`Ok<{ status: "joined", signup, isNew, recordedScopes }>` (applied at once),
+`Ok<{ status: "confirmation_required", signup, isNew, token, expiresAt }>` (double opt-in: pass
+`signup` and `token` to `deliverConfirmationMail(ctx, signup, token)`, never to the client) or
+`Err<waitlist.email_invalid | waitlist.consent_required | waitlist.form_invalid | security.rate_limited>`;
+`confirmSignup(ctx, { token, clientKey })` returns `Ok<{ signup, recordedScopes, isFirstConfirmation }>`
+or `Err<waitlist.confirmation_invalid | waitlist.confirmation_expired | security.rate_limited>`;
+`pruneUnconfirmedSignups(ctx)` deletes sign-ups whose link expired unused (for a scheduled job;
+returns the count); `getConfirmationLink(config, token)` builds the link;
+`withdrawWaitlistConsents(event, ctx)` is mailing's `onUnsubscribed` handler (section 10);
+`deliverWelcomeMail(ctx, signup)` returns mailing's `DeliveryOutcome` or `{ status: "skipped" }`;
+`getSignup(ctx, email)` (confirmed or not, see `confirmedAt`); `listSignups(ctx, { scope?, placement? })`,
+the confirmed sign-ups oldest first. A launch mail is
+a loop over `listSignups(ctx, { scope: "launch" })` with mailing's `deliverOnce` (or a mailing
+campaign): unsubscribed addresses are refused there.
+
+## 5. Migrations and tables
+
+`migrations/0001_create_signups.sql` creates `waitlist.signups` and the function
+`waitlist.is_scope_list(text[])` its check uses; `0002_add_confirmation.sql` adds the double opt-in
+columns, with checks that an unconfirmed row has a pending request and a pending request has a link:
+
+| Column | Meaning |
+| --- | --- |
+| `id` | `uuid`, the sign-up; the welcome mail's delivery scope names it. |
+| `email` | Trimmed and lowercased (a CHECK), unique (`signups_email_key`). |
+| `scopes` | `text[]`: 1 to 16 distinct kebab-case ids of at most 64 characters, in the config's order. GIN index for lists by scope. |
+| `placement` | Kebab-case, the first sign-up's form. |
+| `locale` | The app's locale at the first sign-up: the welcome mail's language. |
+| `created_at`, `updated_at` | The first sign-up and the last change. |
+| `confirmed_at` | When the sign-up first counted (at once without double opt-in); NULL while its first request waits for the link. Rows from before migration 2 are confirmed at `created_at`. |
+| `pending_scopes` | The scopes of a request that waits for its link (a first sign-up, or more scopes later), or NULL. |
+| `confirmation_token_hash`, `confirmation_expires_at` | sha256 (hex, unique) of the latest link's token and its expiry; set together. A used link keeps its hash until the next request replaces it, so a second click answers "confirmed". |
+
+Scope ids are validated text, not an enum or a CHECK list: they are the app's, and a list in the
+database would need a module migration for every app's change of copy.
+
+## 6. Environment variables
+
+None of its own. The welcome mail needs mailing's `MAILING_UNSUBSCRIBE_SECRET`; the confirmation
+link is a random token stored as a hash, so double opt-in needs no secret.
+
+## 7. Switches
+
+None. `welcomeMail: false` turns the mail off; `doubleOptIn` is an option, not a switch, because
+turning it off while requests wait would leave them unconfirmed (a later sign-up of the same
+address applies them).
+
+## 8. Appearance
+
+`WaitlistForm` uses the `@softure-ai/ui` primitives (TextField, Checkbox, FormError, Button) and
+takes `classNames` for its slots `root`, `form`, `scopes` and `notice`, or `unstyled`. `Waitlist`
+passes both through.
+
+## 9. Copy
+
+`waitlistMessages` (`en`, `pl`): `form` (field label, button, pending text, the confirmation and,
+with double opt-in, `confirmationSent`), `welcomeMail` (subject and text; mailing appends the
+unsubscribe footer), `confirmationMail` (subject, text and `action`, the link's label in the HTML
+body; in the text body the link follows the text), `confirm`
+(the confirmation page: its states and button) and `errors`. Override
+them with `waitlist({ messages: { pl: { welcomeMail: { subject: "…" } } } })`. Scope labels are
+the app's, in `scopes[].label` or `consentLabels`.
+
+## 10. Hooks
+
+`onJoined(event, ctx)` runs when a sign-up counts for the first time, inside its transaction (`ctx`
+is the module context with the transaction as `db`, like auth's `onRegistered`): a new sign-up
+without double opt-in (`via: "join"`), or the first use of its link with it (`via: "confirmation"`).
+`event.signup` is the sign-up as it stands. A repeat request that only widens the scopes, a second
+link, or a link used again does not call it: the consent ledger records those. An error the hook
+throws rolls the sign-up back (the form or the confirmation page answers the generic error, and the
+link stays usable), so a hook that must never refuse a sign-up catches its own errors, as
+analytics' `countFunnelStep` does:
+
+```ts
+import { countFunnelStep, tagRedirect } from "@softure-ai/analytics/next";
+
+waitlist({
+  scopes: [...],
+  doubleOptIn: true,
+  // Counts each sign-up as the funnel's `waitlist` step (a `server` step) under the visit's channel.
+  onJoined: countFunnelStep("waitlist"),
+  // With double opt-in the sign-up counts on the confirmation page, opened from a mail: the link
+  // carries the channel of the form's page so the count keeps it.
+  rewriteConfirmationLink: tagRedirect,
+}),
+```
+
+`rewriteConfirmationLink(path, { config })` gets the link's path (the confirm route with its
+token) where the confirmation mail is built: in the join action, after the response, where Next
+still exposes the request's headers. Its result is used only when it is the confirm route on this
+app with the same token; anything else, or an error, mails the module's own link with a log line.
+`resolveConfirmationLink(config, token)` from `/server` gives the link as it will be mailed.
+
+`joinWaitlist` also returns `isNew` and `recordedScopes` (and `confirmSignup` returns
+`isFirstConfirmation`) for an app that reacts to every request in its own server code.
+
+The waitlist plugs into mailing's `onUnsubscribed` with `withdrawWaitlistConsents`. Mailing's
+opt-out covers every list mail and its link names only the recipient key, so the handler withdraws
+each declared scope whose latest record grants it (`granted: false`, source `unsubscribe`, subject
+`{ emailKey }`); a repeated unsubscribe adds nothing. Without it, the ledger keeps showing granted
+consents for an address that unsubscribed, and a later sign-up's lift erases the only record of
+the opt-out. If the app has other mail consents, compose: `onUnsubscribed: async (event, ctx) => {
+await withdrawWaitlistConsents(event, ctx); await withdrawMine(event, ctx); }`.
+
+A sign-up is an explicit consent: applying it calls mailing's `liftSuppression` in its
+transaction, which removes an opt-out the person made themselves (never an operator's). When it
+removed one, the sign-up's scopes become the ones checked now instead of the union, because the
+opt-out withdrew all of them. Without double opt-in this happens in `joinWaitlist`; with it, only
+in `confirmSignup`, so typing someone's address cannot undo their opt-out.
+
+### Double opt-in
+
+With `doubleOptIn` on, `joinWaitlist` stores the request on the row (`pending_scopes`) with a new
+single-use link that replaces any earlier one, and the join action mails it as transactional mail
+(it must reach an address that opted out and signs up again). Nothing else happens until the link
+is used: no consent row, no lift, no welcome mail, and `listSignups` leaves a sign-up that never
+counted out. A repeat request on an unconfirmed sign-up replaces its scopes; on a confirmed one it
+waits beside the granted scopes, which stay until its link is used. `confirmSignup` applies the
+request as above, records the consents (with the document version in force at confirmation), sets
+`confirmed_at` the first time, and the confirm action sends the welcome mail. Consents are recorded
+only at confirmation: the ledger is insert-only, and a row written before would claim a consent
+nobody proved. Run `pruneUnconfirmedSignups(ctx)` from a scheduled job to delete sign-ups whose link
+expired unused; until then they count nowhere, and a new sign-up of the address reuses the row.
+
+## 11. GDPR
+
+- The waitlist contributes to `@softure-ai/privacy`: the export of an account holds the sign-up of
+  its email address (scopes, placement, dates, `confirmedAt`, a pending request's scopes), and
+  deleting the account deletes that sign-up.
+  Privacy's own part covers the consents the sign-up recorded.
+- Consents are recorded per scope with the document version in force, so the app can show what a
+  person agreed to and when (`listConsents` of `@softure-ai/privacy/server`, subject `{ email }`).
+  With double opt-in that is the version in force when the link is used; a document changed
+  between the form and the link (at most the link's lifetime) is recorded in its newer version.
+- With double opt-in, an address that never confirms is deleted by `pruneUnconfirmedSignups` once
+  its link expires.
+- A person without an account who asks for erasure: delete their row with
+  `DELETE FROM waitlist.signups WHERE email = lower(btrim($1))` and their consents in
+  `privacy.consents` by `email_key` (an operator task; there is no self-service page without an account).
+
+## 12. Limitations
+
+- Double opt-in is off by default: without it a sign-up counts at once, so a typo or a third
+  party's address joins the list, and anyone who types an address can lift that address's opt-out
+  by signing it up (bounded by the `waitlist-email` bucket).
+- With double opt-in, anyone can make the module send a confirmation mail to any address, also one
+  that opted out (it is transactional): bounded by the `waitlist-email` bucket, 3 per hour per
+  address. The mail carries only the link and says to ignore it.
+- Expired unconfirmed sign-ups stay until the app runs `pruneUnconfirmedSignups`; the module has
+  no scheduler of its own.
+- With double opt-in, a sign-up's channel reaches `onJoined` only through the confirmation link
+  (`rewriteConfirmationLink`, section 10); a link opened on another device still carries it, a
+  sign-up confirmed from an untagged link counts without one.
+- The placement is stored per sign-up; handing placement counts to `@softure-ai/analytics` belongs
+  to the analytics roadmap.

package/dist/contract.d.ts

@@ -0,0 +1,53 @@
+import type { CoreErrorCode } from "@softure-ai/core";
+export type WaitlistErrorCode = 
+/** Not an email address (or longer than 254 characters). */
+"waitlist.email_invalid"
+/** A required scope was not checked, or no scope at all. */
+ | "waitlist.consent_required"
+/** A scope or placement the config does not declare: a tampered or outdated form. */
+ | "waitlist.form_invalid";
+/** Why a confirmation link was refused. */
+export type WaitlistConfirmationErrorCode = 
+/** Missing, malformed, or replaced by a newer link. */
+"waitlist.confirmation_invalid"
+/** Past its expiry; signing up again sends a new one. */
+ | "waitlist.confirmation_expired";
+/** Every code the form can show: its own, the client and rate limit refusals, the generic ones. */
+export type WaitlistFormErrorCode = WaitlistErrorCode | "security.rate_limited" | "security.client_unidentified" | CoreErrorCode;
+export type WaitlistFormField = "email" | "consent";
+/** What the join action returns to its form (`useActionState`). */
+export interface WaitlistFormState {
+    /** `ok`: the sign-up counts; `confirmation_sent`: it waits for the link mailed to the address. */
+    readonly status: "idle" | "ok" | "confirmation_sent" | "error";
+    readonly error?: WaitlistFormErrorCode;
+    /** The field the error belongs to; none for a form-level error. */
+    readonly field?: WaitlistFormField;
+    /** The email as typed, to fill the field again after an error. */
+    readonly email?: string;
+    /** The scopes checked, to check them again after an error. */
+    readonly scopes?: readonly string[];
+}
+export declare const INITIAL_WAITLIST_FORM_STATE: WaitlistFormState;
+/** One sign-up as the module returns it. */
+export interface WaitlistSignup {
+    readonly id: string;
+    /** Trimmed and lowercased. */
+    readonly email: string;
+    /** Granted scopes, in the config's order. */
+    readonly scopes: readonly string[];
+    /** The placement of the first sign-up. */
+    readonly placement: string;
+    /** The app's locale at the first sign-up. */
+    readonly locale: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    /** When it first counted; null while its first request waits for the confirmation link. */
+    readonly confirmedAt: Date | null;
+}
+/** What `onJoined` receives: a sign-up that counts for the first time, and how it came to count. */
+export interface WaitlistJoinedEvent {
+    readonly signup: WaitlistSignup;
+    /** `join`: applied when it was made (no double opt-in); `confirmation`: its link was used. */
+    readonly via: "join" | "confirmation";
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,iBAAiB;AAC3B,4DAA4D;AAC1D,wBAAwB;AAC1B,4DAA4D;GAC1D,2BAA2B;AAC7B,qFAAqF;GACnF,uBAAuB,CAAC;AAE5B,2CAA2C;AAC3C,MAAM,MAAM,6BAA6B;AACvC,uDAAuD;AACrD,+BAA+B;AACjC,yDAAyD;GACvD,+BAA+B,CAAC;AAEpC,mGAAmG;AACnG,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,uBAAuB,GAAG,8BAA8B,GAAG,aAAa,CAAC;AAEjI,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEpD,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,mBAAmB,GAAG,OAAO,CAAC;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,2BAA2B,EAAE,iBAAsC,CAAC;AAEjF,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;CACnC;AAED,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC;CACvC"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export const INITIAL_WAITLIST_FORM_STATE = { status: "idle" };
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAqCA,MAAM,CAAC,MAAM,2BAA2B,GAAsB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC"}

package/dist/fields.d.ts

@@ -0,0 +1,7 @@
+/** The field with the address. */
+export declare const EMAIL_FIELD = "email";
+/** The hidden field with the form's placement. */
+export declare const PLACEMENT_FIELD = "placement";
+/** The field name of a scope's checkbox. */
+export declare function getScopeFieldName(scopeId: string): string;
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAGA,kCAAkC;AAClC,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,kDAAkD;AAClD,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C,4CAA4C;AAC5C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/fields.js

@@ -0,0 +1,11 @@
+// The field names the waitlist form sends and the join action reads, shared by both sides (the
+// form is a client module, so the action cannot import from it).
+/** The field with the address. */
+export const EMAIL_FIELD = "email";
+/** The hidden field with the form's placement. */
+export const PLACEMENT_FIELD = "placement";
+/** The field name of a scope's checkbox. */
+export function getScopeFieldName(scopeId) {
+    return `scope.${scopeId}`;
+}
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iEAAiE;AAEjE,kCAAkC;AAClC,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AACnC,kDAAkD;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,4CAA4C;AAC5C,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,SAAS,OAAO,EAAE,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+export declare const MODULE_ID = "waitlist";
+/**
+ * Rate limit buckets the waitlist consumes, with defaults to spread into `security({ buckets })`:
+ * `waitlist` per client address and `waitlist-email` per signed-up address (a form sent for
+ * someone else's address many times).
+ */
+export declare const WAITLIST_RATE_LIMIT_BUCKETS: {
+    readonly waitlist: {
+        readonly limit: 10;
+        readonly windowMinutes: 15;
+    };
+    readonly "waitlist-email": {
+        readonly limit: 3;
+        readonly windowMinutes: 60;
+    };
+};
+/**
+ * Enables the waitlist in `softure.config.ts` (after `security`, `mailing` and `privacy`):
+ * `waitlist({ scopes: [{ id: "launch", required: true, document: "privacy-policy", label: { en: "Tell me when it opens." } }], placements: ["hero", "footer"] })`.
+ */
+export declare const waitlist: import("@softure-ai/core").ModuleFactory<{
+    confirm: string;
+}, {
+    form: {
+        email: string;
+        submit: string;
+        pending: string;
+        success: string;
+        confirmationSent: string;
+    };
+    confirmationMail: {
+        subject: string;
+        text: string;
+        action: string;
+    };
+    confirm: {
+        title: string;
+        lead: string;
+        submit: string;
+        doneTitle: string;
+        doneBody: string;
+        invalidTitle: string;
+        invalidBody: string;
+        expiredTitle: string;
+        expiredBody: string;
+        failed: string;
+        limited: string;
+    };
+    welcomeMail: {
+        subject: string;
+        text: string;
+    };
+    errors: {
+        waitlist: {
+            email_invalid: string;
+            consent_required: string;
+            form_invalid: string;
+        };
+        security: {
+            rate_limited: string;
+            client_unidentified: string;
+        };
+        core: {
+            database_failed: string;
+            unexpected: string;
+        };
+    };
+}, import("zod").ZodObject<{
+    scopes: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        required: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        document: import("zod").ZodOptional<import("zod").ZodString>;
+        label: import("zod").ZodRecord<import("zod").ZodEnum<{
+            en: "en";
+            pl: "pl";
+        }> & import("zod/v4/core").$partial, import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+    placements: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
+    welcomeMail: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    doubleOptIn: import("zod").ZodPipe<import("zod").ZodDefault<import("zod").ZodUnion<readonly [import("zod").ZodBoolean, import("zod").ZodObject<{
+        expiresInHours: import("zod").ZodDefault<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>]>>, import("zod").ZodTransform<{
+        expiresInHours: number;
+    } | null, boolean | {
+        expiresInHours: number;
+    }>>;
+    mailTemplate: import("zod").ZodOptional<import("zod").ZodCustom<import("./mail-template.js").WaitlistMailTemplate, import("./mail-template.js").WaitlistMailTemplate>>;
+    onJoined: import("zod").ZodOptional<import("zod").ZodCustom<import("./options.js").OnJoinedHook, import("./options.js").OnJoinedHook>>;
+    rewriteConfirmationLink: import("zod").ZodOptional<import("zod").ZodCustom<import("./options.js").RewriteConfirmationLink, import("./options.js").RewriteConfirmationLink>>;
+}, import("zod/v4/core").$strict>>;
+export { INITIAL_WAITLIST_FORM_STATE, type WaitlistConfirmationErrorCode, type WaitlistErrorCode, type WaitlistFormErrorCode, type WaitlistFormField, type WaitlistFormState, type WaitlistJoinedEvent, type WaitlistSignup, } from "./contract.js";
+export { EMAIL_FIELD, getScopeFieldName, PLACEMENT_FIELD } from "./fields.js";
+export { escapeHtml, type ConfirmationMailTemplateInput, type WaitlistMailTemplate, type WaitlistMailTemplateInput, type WelcomeMailTemplateInput, } from "./mail-template.js";
+export { getWaitlistErrorMessage, waitlistMessages, type WaitlistMessages } from "./messages/index.js";
+export { DEFAULT_CONFIRMATION_HOURS, MAX_CONFIRMATION_HOURS, MAX_NAME_LENGTH, MAX_SCOPES, NAME_PATTERN, type OnJoinedHook, type RewriteConfirmationLink, type WaitlistOptions, type WaitlistOptionsInput, type WaitlistScope, type WaitlistScopeInput, } from "./options.js";
+export { signups, waitlistSchema } from "./schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,SAAS,aAAa,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;CAG9B,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAkBnB,CAAC;AAEH,OAAO,EACL,2BAA2B,EAC3B,KAAK,6BAA6B,EAClC,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EACL,UAAU,EACV,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvG,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,49 @@
+// Public API of @softure-ai/waitlist: the module factory for softure.config.ts, its rate limit
+// buckets, types, messages and the sign-ups table. Joining, confirming, the mails and reading
+// sign-ups are in `@softure-ai/waitlist/server`, the Next.js adapter (actions, `Waitlist` component,
+// confirmation page) in `/next`, the form in `/ui`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { waitlistMessages } from "./messages/index.js";
+import { waitlistOptionsSchema } from "./options.js";
+import { checkSignupsTable } from "./server/health.js";
+import { waitlistPrivacyContributor } from "./server/privacy.js";
+export const MODULE_ID = "waitlist";
+/**
+ * Rate limit buckets the waitlist consumes, with defaults to spread into `security({ buckets })`:
+ * `waitlist` per client address and `waitlist-email` per signed-up address (a form sent for
+ * someone else's address many times).
+ */
+export const WAITLIST_RATE_LIMIT_BUCKETS = {
+    waitlist: { limit: 10, windowMinutes: 15 },
+    "waitlist-email": { limit: 3, windowMinutes: 60 },
+};
+/**
+ * Enables the waitlist in `softure.config.ts` (after `security`, `mailing` and `privacy`):
+ * `waitlist({ scopes: [{ id: "launch", required: true, document: "privacy-policy", label: { en: "Tell me when it opens." } }], placements: ["hero", "footer"] })`.
+ */
+export const waitlist = defineModule({
+    manifest: {
+        id: MODULE_ID,
+        version: "0.1.5",
+        dependsOn: { security: "^0.1.0", mailing: "^0.1.0", privacy: "^0.1.0" },
+        dbSchema: "waitlist",
+        tables: ["signups"],
+        env: [],
+        switches: [],
+        routes: { confirm: "/waitlist/confirm" },
+        mount: [{ kind: "page", path: "app/waitlist/confirm/page.tsx", export: "ConfirmSignupPage" }],
+        privacy: { exports: true, deletes: true },
+    },
+    messages: waitlistMessages,
+    options: waitlistOptionsSchema,
+    migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+    privacy: waitlistPrivacyContributor,
+    health: checkSignupsTable,
+});
+export { INITIAL_WAITLIST_FORM_STATE, } from "./contract.js";
+export { EMAIL_FIELD, getScopeFieldName, PLACEMENT_FIELD } from "./fields.js";
+export { escapeHtml, } from "./mail-template.js";
+export { getWaitlistErrorMessage, waitlistMessages } from "./messages/index.js";
+export { DEFAULT_CONFIRMATION_HOURS, MAX_CONFIRMATION_HOURS, MAX_NAME_LENGTH, MAX_SCOPES, NAME_PATTERN, } from "./options.js";
+export { signups, waitlistSchema } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,8FAA8F;AAC9F,qGAAqG;AACrG,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE;IAC1C,gBAAgB,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE;CACzC,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;IACnC,QAAQ,EAAE;QACR,EAAE,EAAE,SAAS;QACb,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;QACvE,QAAQ,EAAE,UAAU;QACpB,MAAM,EAAE,CAAC,SAAS,CAAC;QACnB,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,EAAE;QACxC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;QAC7F,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;KAC1C;IACD,QAAQ,EAAE,gBAAgB;IAC1B,OAAO,EAAE,qBAAqB;IAC9B,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE;IAC5E,OAAO,EAAE,0BAA0B;IACnC,MAAM,EAAE,iBAAiB;CAC1B,CAAC,CAAC;AAEH,OAAO,EACL,2BAA2B,GAQ5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EACL,UAAU,GAKX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAyB,MAAM,qBAAqB,CAAC;AACvG,OAAO,EACL,0BAA0B,EAC1B,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,YAAY,GAOb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/mail-template.d.ts

@@ -0,0 +1,36 @@
+import type { Locale } from "@softure-ai/core";
+interface MailTemplateInputBase {
+    /** The language of the copy: the sign-up's locale. */
+    readonly locale: Locale;
+    readonly subject: string;
+    /** The copy's paragraphs as plain text (not escaped; use `escapeHtml` before putting them in HTML). */
+    readonly paragraphs: readonly string[];
+    /** The module's default HTML body: the paragraphs escaped and, with a link, its anchor. */
+    readonly body: string;
+}
+/** The welcome mail, list mail: mailing appends its unsubscribe footer to the HTML returned. */
+export interface WelcomeMailTemplateInput extends MailTemplateInputBase {
+    readonly kind: "welcome";
+}
+/** The confirmation mail of double opt-in: `action` is the single-use link and its label. */
+export interface ConfirmationMailTemplateInput extends MailTemplateInputBase {
+    readonly kind: "confirmation";
+    readonly action: {
+        readonly href: string;
+        readonly label: string;
+    };
+}
+export type WaitlistMailTemplateInput = WelcomeMailTemplateInput | ConfirmationMailTemplateInput;
+/**
+ * Renders the HTML body of a waitlist mail, e.g. `({ body }) => brandLayout(body)`. It must return
+ * non-blank HTML; a template that throws or returns nothing is a bug and the mail is not sent.
+ */
+export type WaitlistMailTemplate = (mail: WaitlistMailTemplateInput) => string;
+/** `text` safe inside HTML text and attribute values. */
+export declare function escapeHtml(text: string): string;
+/** The paragraphs of a copy text: blocks separated by a blank line, trimmed, empty ones dropped. */
+export declare function splitParagraphs(text: string): string[];
+/** The default body: each paragraph escaped in `<p>` (a line break as `<br>`), then the link's anchor. */
+export declare function renderDefaultMailBody(paragraphs: readonly string[], action: ConfirmationMailTemplateInput["action"] | null): string;
+export {};
+//# sourceMappingURL=mail-template.d.ts.map

package/dist/mail-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-template.d.ts","sourceRoot":"","sources":["../src/mail-template.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,UAAU,qBAAqB;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gGAAgG;AAChG,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,6FAA6F;AAC7F,MAAM,WAAW,6BAA8B,SAAQ,qBAAqB;IAC1E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,MAAM,yBAAyB,GAAG,wBAAwB,GAAG,6BAA6B,CAAC;AAEjG;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,yBAAyB,KAAK,MAAM,CAAC;AAI/E,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,6BAA6B,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,MAAM,CAInI"}