stapel-forms 0.2.0__tar.gz

stapel_forms-0.2.0/CONFIG.MD

@@ -0,0 +1,81 @@
+# CONFIG.MD — stapel-forms
+
+Config registry for **stapel-forms** (`static-scaffold-and-config.md` §2).
+One row per configuration key the module reads, its **source** (`env` = the
+process environment / the `STAPEL_FORMS` settings dict), what it is for,
+whether it is required, and its default.
+
+All keys are read through `forms_settings`
+(`stapel_forms.conf.AppSettings`, namespace `STAPEL_FORMS`).
+Resolution order per key: `settings.STAPEL_FORMS` dict → a flat Django
+setting of the same name → environment variable → the default below.
+There are no `import_strings` keys in this module.
+
+## stapel-forms
+
+### Schema surface (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| FIELD_KINDS | env | allowlist of stapel-attributes kinds a form schema may use. A kind registered in the attributes registry but absent here cannot be asked on a public URL. Kinds implying binary payloads are absent by construction — there is no anonymous attachment path (check `stapel_forms.E001` refuses kinds nothing answers for; `E002` refuses an empty list). | no | the ten builtins: string, int, float, bool, select, date, header, hex_color, hierarchical_select, convertible_unit |
+| MAX_FIELDS_PER_FORM | env | ceiling on fields in a published version; also bounds the CSV column count. | no | 64 |
+
+### Abuse ladder (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_SUBMISSION_BYTES | env | `Content-Length` gate applied BEFORE the JSON parse; over it is 413 `error.413.forms_body_too_large`. 0 disables. | no | 65536 |
+| MAX_SUBMISSIONS_PER_FORM | env | per-form row cap bounding what one leaked public link can cost; past it the submit answers 409 `error.409.forms_submission_cap`. 0 disables. | no | 10000 |
+| MAX_OPEN_FORMS_PER_WORKSPACE | env | ceiling on simultaneously open forms in one workspace. 0 disables. | no | 100 |
+| SUBMIT_THROTTLE | env | DRF scoped rate for the anonymous submit, per client IP (netintel-resolved, never raw XFF). A library cannot own `DEFAULT_THROTTLE_RATES`, so the rate lives here. `None` disables — a conscious act. | no | 20/h |
+| PUBLIC_SCHEMA_THROTTLE | env | same, for the anonymous schema fetch — the enumeration backstop. `None` disables. | no | 120/h |
+| ALLOW_UNCAPTCHAED_PUBLIC | env | the confession switch. Off: a deployment with an open public form and no `STAPEL_CAPTCHA["SECRET"]` gets `stapel_forms.W001`. On: the warning is silenced because the host says the refusal is deliberate. | no | False |
+
+### Respondent privacy (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| STORE_CLIENT_META | env | persist the respondent's IP and user-agent on each submission. Off: nothing needs them on disk — throttling and netintel classification work off the live request and the cache. On: that data falls under the same retention clock as the answers. | no | False |
+| RETENTION_DAYS | env | how long a response lives before the purge destroys it. A per-form `settings.retention_days` may only SHORTEN this; lengthening past the ceiling requires raising it here, so one form cannot rewrite the deployment's promise. `None` keeps answers forever — an explicit host decision. | no | 365 |
+| PURGE_SCHEDULE | env | crontab kwargs for the retention beat entry (`get_forms_beat_schedule()`). Cadence is configuration, not a literal. | no | {"hour": 4, "minute": 40} |
+
+### Notifications (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| NOTIFY_COOLDOWN_SECONDS | env | minimum gap between auto-notify letters for one form; submissions inside the window fold into the next letter as a count. Keyed on the form, not the caller — the protected resource is the owner's inbox. Admin-initiated resend is deliberately NOT subject to it. 0 notifies every time. | no | 600 |
+
+### Versioning (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| ACCEPT_PREVIOUS_VERSION_SECONDS | env | grace window during which a submit naming the previous version is still accepted after a publish. 0 (strict) refuses it wholesale with 409 `error.409.forms_version_superseded`, so the renderer refetches and tells the respondent rather than half-validating against a schema they never saw. | no | 0 |
+
+### Response review (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MAX_PAGE_SIZE | env | service-side cap on `?limit=` for the keyset response listing. | no | 100 |
+| EXPORT_PAGE_SIZE | env | rows per CSV export request; the continuation cursor comes back in the `X-Forms-Next-Before` header rather than materializing the whole table. | no | 1000 |
+
+## Keys this module READS from other namespaces
+
+| Key | Owner | Why it matters here |
+|-----|-------|---------------------|
+| STAPEL_CAPTCHA["SECRET"] | stapel-core | with no backend configured the captcha verifier is a no-op and every bot that finds a public link is accepted; `stapel_forms.W001` says so. |
+| STAPEL_WORKSPACES["ROLES"] | stapel-workspaces | grants `forms.*` to roles. Without a grant every admin request denies; only `owner` has `*` by default. An entry REPLACES a whole role — there is no deep merge. |
+| STAPEL_GDPR["DATA_OWNERS"] | stapel-gdpr | must include `"forms"`, or the erasure closure never completes (`gdpr.E002`; `stapel_forms.W003` warns from this side). |
+| STAPEL_NOTIFICATIONS["TYPES"] | stapel-notifications | the host-side bridge for `forms.submission_received` / `forms.submission_resend` until the upstream `NOTIFICATION_ROUTING` entries land. See MODULE.md §9. |
+| CELERY_BEAT_SCHEDULE | the host | must contain an entry whose `task` is `stapel_forms.tasks.purge_expired_submissions`, or retention never runs (`stapel_forms.W002`). |
+| DATA_PLANE_APPS | the host | isolation-tier hosts list `forms`. No schema impact. |
+
+## Per-form settings (not deployment config)
+
+`Form.settings` is a JSON blob on the row, edited over the API, not a Django
+setting. Recognized keys:
+
+| Key | Purpose |
+|-----|---------|
+| notify_emails | `[str]` — email destinations for the auto-notify and resend. |
+| notify_telegram_chat_ids | `[str]` — telegram chat destinations (no account behind them; stapel-core 0.31 `telegram_chat_id`). |
+| retention_days | `int` — shortens this form's retention below `RETENTION_DAYS`. Lengthening past the module ceiling is refused with `error.400.forms_invalid_retention`. |

stapel_forms-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+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.

stapel_forms-0.2.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: stapel-forms
+Version: 0.2.0
+Summary: Admin-defined forms, anonymous submissions and response review for the Stapel framework
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-forms
+Project-URL: Repository, https://github.com/usestapel/stapel-forms
+Project-URL: Documentation, https://github.com/usestapel/stapel-forms#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-forms/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-forms/issues
+Keywords: django,stapel,forms,surveys
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<1.0,>=0.31.0
+Requires-Dist: stapel-attributes<1.0,>=0.4.6
+Provides-Extra: all
+Dynamic: license-file
+
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-forms
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-forms/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-forms/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-forms?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-forms)
+[![pypi](https://img.shields.io/pypi/v/stapel-forms?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-forms/)
+[![downloads](https://static.pepy.tech/badge/stapel-forms/month)](https://pepy.tech/project/stapel-forms)
+[![python](https://img.shields.io/pypi/pyversions/stapel-forms?logo=python&logoColor=white)](https://pypi.org/project/stapel-forms/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-forms)](https://github.com/usestapel/stapel-forms/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-forms/blob/main/docs/llms.txt)
+
+> Admin-defined forms with anonymous responses: a workspace-keyed form whose schema is a list of stapel-attributes FeatureDefs, immutable published versions (every response records which schema it answered), two anonymous endpoints (fetch schema by non-enumerable public handle, submit answers) hardened by module-namespaced throttles, netintel-tiered captcha, size and volume caps and a recipient-side notify cooldown, capability-gated response review with streamed injection-safe CSV export, admin-initiated resend, ids-only form.* events, a GDPR provider and a finite retention purge.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-forms
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.2.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 18 |
+| Config axes | 5 |
+| Usage surface | 31 |
+| Extension points | 4 |
+| Error codes | 75 |
+| Fleet dependencies | [`stapel-attributes`](https://github.com/usestapel/stapel-attributes) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-gdpr`](https://github.com/usestapel/stapel-gdpr) (optional) · [`stapel-notifications`](https://github.com/usestapel/stapel-notifications) (optional) · [`stapel-workspaces`](https://github.com/usestapel/stapel-workspaces) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-forms/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-forms/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-forms/blob/main/docs/llms.txt)
+
+## What this is
+
+Admin-defined **forms** with **anonymous responses**. A workspace admin
+defines a form's schema, the form gets a non-enumerable public handle, anyone
+holding that handle can fetch the schema and answer it without an account, and
+the admin reviews the answers.
+
+Two decisions carry the whole design.
+
+**The schema is a list of [stapel-attributes](https://github.com/usestapel/stapel-attributes)
+`FeatureDef`s.** There is no `FormField` class here, no field-type enum, no
+validation of its own: the fleet already has exactly one field-type vocabulary
+— the same one that types a marketplace listing — and forms is its third
+consumer. A host that registers a custom attribute kind gets it in forms for
+free.
+
+**A published version is immutable, and every response records which version
+it answered.** Editing a live form publishes the next version; it never
+rewrites a published one. A response is only interpretable against the schema
+it answered — delete a field or narrow a choice list under a mutable schema
+and `budget=3` becomes an orphan nobody can read. Snapshotting the schema into
+every response would preserve meaning but destroy identity: "the 240 responses
+to version 3" would become a JSON scan, and an export would have no stable
+column set. A version row buys both, at one row per publish instead of one
+snapshot per response.
+
+## Quick start
+
+```bash
+pip install stapel-forms
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_forms",
+]
+
+# urls.py
+path("forms/", include("stapel_forms.urls"))   # -> /forms/api/v1/...
+```
+
+The admin surface asks the `workspaces.check_capability` comm Function
+(fail-closed, deny-by-default) — install stapel-workspaces or provide that
+Function, and grant `forms.*` to the roles that should have it. The two
+respondent endpoints need none of that.
+
+## The public surface is exactly two routes
+
+```
+GET  /forms/api/v1/public/<public_id>/               -> the active schema
+POST /forms/api/v1/public/<public_id>/submissions/   -> 201 {accepted, confirmation}
+```
+
+`public_id` is a 22-character random token, not the row's UUID: rotating it
+after a leak must not re-key the row, and the primary key never travels to an
+anonymous caller. What the GET returns is a dedicated envelope — no workspace
+id, no internal id, no author, no counts, no sibling forms — built by its own
+presenter rather than the admin one with fields removed, because dropping
+fields is how leaks happen the day somebody adds one.
+
+Unknown handle, soft-deleted form and unpublished draft all answer **one
+byte-identical 404**. A closed form answers **410**, because its handle was
+public by definition and the renderer needs the difference between "this form
+is closed" and "broken link".
+
+## What a hostile submitter can and cannot do
+
+Stated, because a security posture nobody wrote down is a security posture
+nobody can check.
+
+**Can**: burn its own IP budget; fill a form with garbage that passes typed
+validation; consume rows up to the form's cap.
+
+**Cannot**: enumerate forms (uniform 404 behind a throttled GET); learn the
+workspace or any other tenant fact; store bytes outside typed answer values
+(no file fields, and nothing reaches disk except what the version's own
+configs produced through `normalize_to_dao`); make the module send mail at
+attack rate (the notify cooldown is keyed on the form, and folds the interim
+count into the next letter); read anything back (there is no public read of
+responses — the POST returns confirmation text, not even a submission id); or
+poison a reviewer's spreadsheet (CSV export escapes formula leads server-side,
+so every consumer inherits the guard).
+
+The ladder behind that: module-namespaced throttles, a `Content-Length` gate
+before the JSON parse, netintel-tiered captcha (`@captcha_protected`), a
+per-form submission cap, a per-workspace open-form cap, and the recipient-side
+cooldown. Every one ships on; the confession switch is
+`ALLOW_UNCAPTCHAED_PUBLIC`.
+
+## Privacy, said plainly
+
+Form answers are **respondent PII**. This module guarantees typed storage,
+finite retention, erasure for authenticated respondents, and admin deletion.
+
+It does **not** give anonymous respondents a self-service erasure channel.
+stapel-gdpr keys every subject on `user_id`, and an email a stranger typed
+into a field is opaque answer content, not a subject key — an email-keyed
+subject is upstream platform work, not something a form module should fake.
+What v1 answers with instead is a finite default retention (365 days, per-form
+overrides may only shorten it), a purge job that actually runs, and
+`DELETE /submissions/<id>` for the request that arrives by email.
+
+Hosts collecting sensitive categories should say so in the form's own
+description.
+
+## Reacting to a response
+
+```python
+# The module's own reaction: tell the form's destinations, cooldown-gated.
+# Each key maps to the request_notification keyword that addresses it, so a
+# telegram chat needs no account behind it.
+form.settings = {
+    "notify_emails": ["sales@example.com"],
+    "notify_telegram_chat_ids": ["-1001234567890"],
+}
+
+# Anything else subscribes to the fact:
+@on_action("form.submission.received")
+def route_it(event):
+    ...  # {form_id, form_version, submission_id, workspace_id}
+```
+
+Events carry **ids only**. The outbox has no retention and a durable bus fans
+out to every subscriber, so a respondent's answers never ride it; a consumer
+that needs content reads it under `forms.responses.view`.
+
+## Not in v1, deliberately
+
+File-upload fields (the platform CDN cannot take custody of an anonymous
+stranger's bytes and cannot gate reads — a résumé served world-readable by URL
+is the open switch, not the feature); conditional logic and branching (the
+schema reserves `meta.logic`); multi-language form content; a realtime
+response feed; honeypot fields; quotas or billing on submission volume; draft
+respondent saves, response editing and quiz scoring.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-forms/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_forms-0.2.0/README.md

@@ -0,0 +1,182 @@
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-forms
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-forms/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-forms/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-forms?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-forms)
+[![pypi](https://img.shields.io/pypi/v/stapel-forms?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-forms/)
+[![downloads](https://static.pepy.tech/badge/stapel-forms/month)](https://pepy.tech/project/stapel-forms)
+[![python](https://img.shields.io/pypi/pyversions/stapel-forms?logo=python&logoColor=white)](https://pypi.org/project/stapel-forms/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-forms)](https://github.com/usestapel/stapel-forms/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-forms/blob/main/docs/llms.txt)
+
+> Admin-defined forms with anonymous responses: a workspace-keyed form whose schema is a list of stapel-attributes FeatureDefs, immutable published versions (every response records which schema it answered), two anonymous endpoints (fetch schema by non-enumerable public handle, submit answers) hardened by module-namespaced throttles, netintel-tiered captcha, size and volume caps and a recipient-side notify cooldown, capability-gated response review with streamed injection-safe CSV export, admin-initiated resend, ids-only form.* events, a GDPR provider and a finite retention purge.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-forms
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.2.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 18 |
+| Config axes | 5 |
+| Usage surface | 31 |
+| Extension points | 4 |
+| Error codes | 75 |
+| Fleet dependencies | [`stapel-attributes`](https://github.com/usestapel/stapel-attributes) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-gdpr`](https://github.com/usestapel/stapel-gdpr) (optional) · [`stapel-notifications`](https://github.com/usestapel/stapel-notifications) (optional) · [`stapel-workspaces`](https://github.com/usestapel/stapel-workspaces) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-forms/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-forms/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-forms/blob/main/docs/llms.txt)
+
+## What this is
+
+Admin-defined **forms** with **anonymous responses**. A workspace admin
+defines a form's schema, the form gets a non-enumerable public handle, anyone
+holding that handle can fetch the schema and answer it without an account, and
+the admin reviews the answers.
+
+Two decisions carry the whole design.
+
+**The schema is a list of [stapel-attributes](https://github.com/usestapel/stapel-attributes)
+`FeatureDef`s.** There is no `FormField` class here, no field-type enum, no
+validation of its own: the fleet already has exactly one field-type vocabulary
+— the same one that types a marketplace listing — and forms is its third
+consumer. A host that registers a custom attribute kind gets it in forms for
+free.
+
+**A published version is immutable, and every response records which version
+it answered.** Editing a live form publishes the next version; it never
+rewrites a published one. A response is only interpretable against the schema
+it answered — delete a field or narrow a choice list under a mutable schema
+and `budget=3` becomes an orphan nobody can read. Snapshotting the schema into
+every response would preserve meaning but destroy identity: "the 240 responses
+to version 3" would become a JSON scan, and an export would have no stable
+column set. A version row buys both, at one row per publish instead of one
+snapshot per response.
+
+## Quick start
+
+```bash
+pip install stapel-forms
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_forms",
+]
+
+# urls.py
+path("forms/", include("stapel_forms.urls"))   # -> /forms/api/v1/...
+```
+
+The admin surface asks the `workspaces.check_capability` comm Function
+(fail-closed, deny-by-default) — install stapel-workspaces or provide that
+Function, and grant `forms.*` to the roles that should have it. The two
+respondent endpoints need none of that.
+
+## The public surface is exactly two routes
+
+```
+GET  /forms/api/v1/public/<public_id>/               -> the active schema
+POST /forms/api/v1/public/<public_id>/submissions/   -> 201 {accepted, confirmation}
+```
+
+`public_id` is a 22-character random token, not the row's UUID: rotating it
+after a leak must not re-key the row, and the primary key never travels to an
+anonymous caller. What the GET returns is a dedicated envelope — no workspace
+id, no internal id, no author, no counts, no sibling forms — built by its own
+presenter rather than the admin one with fields removed, because dropping
+fields is how leaks happen the day somebody adds one.
+
+Unknown handle, soft-deleted form and unpublished draft all answer **one
+byte-identical 404**. A closed form answers **410**, because its handle was
+public by definition and the renderer needs the difference between "this form
+is closed" and "broken link".
+
+## What a hostile submitter can and cannot do
+
+Stated, because a security posture nobody wrote down is a security posture
+nobody can check.
+
+**Can**: burn its own IP budget; fill a form with garbage that passes typed
+validation; consume rows up to the form's cap.
+
+**Cannot**: enumerate forms (uniform 404 behind a throttled GET); learn the
+workspace or any other tenant fact; store bytes outside typed answer values
+(no file fields, and nothing reaches disk except what the version's own
+configs produced through `normalize_to_dao`); make the module send mail at
+attack rate (the notify cooldown is keyed on the form, and folds the interim
+count into the next letter); read anything back (there is no public read of
+responses — the POST returns confirmation text, not even a submission id); or
+poison a reviewer's spreadsheet (CSV export escapes formula leads server-side,
+so every consumer inherits the guard).
+
+The ladder behind that: module-namespaced throttles, a `Content-Length` gate
+before the JSON parse, netintel-tiered captcha (`@captcha_protected`), a
+per-form submission cap, a per-workspace open-form cap, and the recipient-side
+cooldown. Every one ships on; the confession switch is
+`ALLOW_UNCAPTCHAED_PUBLIC`.
+
+## Privacy, said plainly
+
+Form answers are **respondent PII**. This module guarantees typed storage,
+finite retention, erasure for authenticated respondents, and admin deletion.
+
+It does **not** give anonymous respondents a self-service erasure channel.
+stapel-gdpr keys every subject on `user_id`, and an email a stranger typed
+into a field is opaque answer content, not a subject key — an email-keyed
+subject is upstream platform work, not something a form module should fake.
+What v1 answers with instead is a finite default retention (365 days, per-form
+overrides may only shorten it), a purge job that actually runs, and
+`DELETE /submissions/<id>` for the request that arrives by email.
+
+Hosts collecting sensitive categories should say so in the form's own
+description.
+
+## Reacting to a response
+
+```python
+# The module's own reaction: tell the form's destinations, cooldown-gated.
+# Each key maps to the request_notification keyword that addresses it, so a
+# telegram chat needs no account behind it.
+form.settings = {
+    "notify_emails": ["sales@example.com"],
+    "notify_telegram_chat_ids": ["-1001234567890"],
+}
+
+# Anything else subscribes to the fact:
+@on_action("form.submission.received")
+def route_it(event):
+    ...  # {form_id, form_version, submission_id, workspace_id}
+```
+
+Events carry **ids only**. The outbox has no retention and a durable bus fans
+out to every subscriber, so a respondent's answers never ride it; a consumer
+that needs content reads it under `forms.responses.view`.
+
+## Not in v1, deliberately
+
+File-upload fields (the platform CDN cannot take custody of an anonymous
+stranger's bytes and cannot gate reads — a résumé served world-readable by URL
+is the open switch, not the feature); conditional logic and branching (the
+schema reserves `meta.logic`); multi-language form content; a realtime
+response feed; honeypot fields; quotas or billing on submission volume; draft
+respondent saves, response editing and quiz scoring.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-forms/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_forms-0.2.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-forms — admin-defined forms, anonymous submissions, response review.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``forms_settings`` — resolved app settings (``stapel_forms.conf``).
+"""
+
+__all__ = [
+    "forms_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_forms` stays Django-free.
+_LAZY_EXPORTS = {
+    "forms_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_forms-0.2.0/_capabilities.py

@@ -0,0 +1,48 @@
+"""stapel-forms capabilities.json emitter — thin shim over stapel_tools.capabilities."""
+from pathlib import Path
+
+from stapel_tools.capabilities import axis_group_rules, run_capabilities_cli
+
+
+def main(argv=None):
+    from stapel_forms._codegen import _configure
+
+    _configure()
+    from stapel_forms.conf import DEFAULTS
+    from stapel_forms.urls_v1 import GATE_REGISTRY
+
+    # The CTO-facing axes are the ones that change what the PRODUCT is
+    # allowed to do, not how fast it runs: which field kinds a form may
+    # use, whether respondent IPs are stored, how long answers are kept,
+    # and whether public forms may run without a captcha. Throttle rates,
+    # page sizes, cooldown seconds and the caps are tuning — they bound
+    # abuse, they do not change the deal with the respondent.
+    axes = {
+        "FIELD_KINDS",
+        "STORE_CLIENT_META",
+        "RETENTION_DAYS",
+        "ALLOW_UNCAPTCHAED_PUBLIC",
+        "ACCEPT_PREVIOUS_VERSION_SECONDS",
+    }
+    return run_capabilities_cli(
+        argv,
+        repo=Path(__file__).resolve().parent,
+        canonical_prefix="/forms/api/v1",
+        defaults=DEFAULTS,
+        registry=GATE_REGISTRY,
+        is_axis=lambda k: k in axes,
+        axis_group=axis_group_rules(
+            exact={
+                "FIELD_KINDS": "forms.schema",
+                "STORE_CLIENT_META": "forms.privacy",
+                "RETENTION_DAYS": "forms.privacy",
+                "ALLOW_UNCAPTCHAED_PUBLIC": "forms.public",
+                "ACCEPT_PREVIOUS_VERSION_SECONDS": "forms.public",
+            }
+        ),
+        prog="stapel-forms-capabilities",
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())