# Wix enquiries → Notion: reference connector 0.2.1

**Runnable source release, not a managed service or a live customer installation.**
Built by Dylan Powell with AI assistance, 13 November 2026. Python 3.11+ on Linux/macOS; standard library only. No account, paid dependency or real credential is needed for the demonstration. Windows is not supported (`fcntl` is required).

This package supplies a durable local outbox, strict field mapping, an authenticated intake, a Notion HTTP adapter, recovery commands, automated tests and a reproducible fictional-data demonstration. It is the technical reference behind Dylan's separately priced £350 scoped implementation service. Downloading/running this code neither places an order nor includes hosting/support.

## Fixed in 0.2.1 — durable retry ceiling

A reproduced 0.2.0 defect let an API caller increase an existing queue's original retry ceiling by restarting `Engine` with a larger `max_attempts`. The regression produced six create calls after an original limit of two. Version 0.2.1 saves a queue-wide ceiling in SQLite, allows it only to decrease, and makes already-created workers refresh it under the worker lock. Ten dedicated regression tests cover restart, older workers, recovery, concurrency, corrupt metadata and legacy initialization. No new connector features were added.

For an upgrade, keep the same queue and deploy the fixed code to **all** workers together. Earlier releases did not save the original ceiling: the first 0.2.1 initialization adopts the explicitly supplied current `max_attempts` (CLI default six). If you used a lower custom limit, supply that limit on first initialization; the past value cannot be reconstructed. Existing counters, cooldowns and uncertain-write states are preserved. A lower ceiling waits for current in-flight work; it cannot undo attempts already authorised. Never delete metadata or replace the queue to reset the limit. See RUNBOOK.md.

## Run it now — no network credentials

Extract the ZIP, open its top-level folder, then:

```sh
python3 -m wix_notion demo
python3 -W error -m unittest discover -v
# Optional: Node 20+ tests for the Wix event normalizer
node --test tests/wix-normalize.test.mjs
```

`demo` runs the real intake, mapper, SQLite engine and Notion adapter against an **in-process local HTTP Notion simulator**. It emits JSON with scenario results, synthetic inputs, actual recorded requests and assertions. It never contacts live Wix or Notion. The simulator is explicitly synthetic; its responses are not fabricated evidence of provider testing.

The demonstration covers normal delivery, identical replay, different IDs for the same person, missing fields, a 503 after commit, lost response after commit, and repaired authentication failure. Additional tests exercise separate processes, crash/restart, duplicate/concurrent delivery, uncertainty with an empty lookup, 429/529 delays/budgets, partial pagination, redirects, invalid input and source-ID conflicts.

**Not tested:** a real Wix form/event subscription; a real Notion workspace or integration; production reverse proxy/TLS; customer workload/permissions/schema; a complete client installation. These require an authorised isolated test destination before deployment. No Dragon Academy or other business records were used.

## Inspect a durable local queue

```sh
python3 -m wix_notion --config examples/config.json --db ./private-demo/queue.sqlite3 ingest examples/event.json
python3 -m wix_notion --config examples/config.json --db ./private-demo/queue.sqlite3 status
python3 -m wix_notion --config examples/config.json --db ./private-demo/queue.sqlite3 exceptions
```

The sample data source is fictional. **Do not run a live worker against it.** `ingest`, `status`, `exceptions` and `recover` cannot call the provider. A 202 acknowledgement means durable local acceptance, not delivery.

## Check the destination before starting a queue

New in **0.2.0**: an explicit read-only check of the previously manual destination-schema/read-access prerequisite. After replacing the fictional example with an authorised isolated destination and supplying `NOTION_TOKEN` through a protected environment:

```sh
python3 -m wix_notion --config examples/config.json check
```

No `--db` is required. Even if supplied, its path is ignored: the checker never opens SQLite, creates a directory or touches a worker lock. Do not point the unchanged fictional example at live Notion.

The checker reads the exact data-source schema, validates property names/types/IDs and the single mapped title, requires the reserved key to be rich text, and checks that any mapped `$status` initial select option already exists. It then makes one read-only POST query with a fresh synthetic key. No page/schema create, update or delete is performed; no retry or pagination loop runs. Token, schema names, returned rows and provider error prose are never printed.

Exit 0 means **schema and read access only** at that moment. Output explicitly says `write_permission=not_tested`, `wix_source=not_tested`, `hosting=not_tested`, and `live_integration=not_tested`. **Reading does not establish insert permission or production readiness.** Exit 2 means setup/input/read verification failed; see the runbook's fixed reason codes. This release's checker was exercised against real loopback HTTP fakes, not a live account.

## What gets mapped

- A stable **original Wix submission ID**, an explicitly allowed form ID, original timezone-aware submission timestamp, and selected adult business-enquiry fields.
- Up to **10 total Notion properties**, including the generated source key (therefore up to nine configured mappings).
- Exactly one title. Supported types: title, rich text, email, select and date. Unsupported values are rejected, not truncated or silently coerced.
- `$submitted_at`, `$follow_up_due` and `$status` supply configured values. Follow-up is elapsed UTC hours from original submission time, not from a retry.
- The key is SHA-256 of `form_id + NUL + submission_id`. Same person with a different original submission ID is a separate enquiry. A different mapped payload under the same key is a conflict, not an update.

## Deployment and recovery

Read **RUNBOOK.md** before connecting any accounts. You need an agreed Wix server-side delivery route, a limited Notion integration shared with the exact data source, an existing or separately approved POSIX host, private storage and an HTTPS reverse proxy. No hosting subscription or scheduler is installed by this package.

The receiver is deliberately loopback-only. Do not expose Python's HTTP server directly. Keep its bearer token in server-side secrets, never a Wix page, public form, URL or source repository. The `work` and read-only `check` commands use `NOTION_TOKEN`.

A single database/worker lock coordinates all local processes for that destination. This is **not distributed exactly-once delivery**: separate databases, external/manual writers, lost state or network filesystems are outside the guarantee. Preserve the database and lock; do not create a fresh ID to force a retry.

After an uncertain create, the engine only reconciles. An empty query is not proof that no page was committed. It will leave the job visibly uncertain rather than risk creating a duplicate. Known committed IDs and successful writes are read back and every mapped field/destination verified before `delivered`.

Definite rejections can be repaired and recovered explicitly. Retry limits, global provider cooldowns and operation history survive restarts. No automatic customer emails/messages, payments, sensitive data processing, AI decisions, historical migrations or two-way sync are included.

## Verified for 0.2.1

On Linux, **121 Python unittest tests passed** with warnings treated as errors on both Python **3.14.9** and **3.12.3**. This includes **19 setup-check test methods** with multiple failure/transport subcases. **2 Node normalizer tests passed** on Node **22.23.3**. Python 3.11 and macOS were not exercised in this verification run.

The unchanged delivery demo passed all **13 assertions** from a temporary copy containing only `wix_notion/`, without repository tests/examples or provider credentials. The checker was also run from that runtime-only copy against a synthetic HTTP destination: one schema GET, one read-only query POST, zero writes and no DB directory. See `verification/` for actual captured test output, the synthetic demo and RED/GREEN history. The setup checker is unchanged; its retained loopback evidence is identified as the 0.2.0 check.

## Package contents

- `wix_notion/`: runnable connector, CLI and isolated simulator.
- `examples/config.json`, `event.json`: fictional configuration and event.
- `examples/wix-normalize.mjs`: tested pure adapter for Wix's documented submission-created envelope; no live event binding or transport installed.
- `tests/`: executable Python and optional Node tests.
- `RUNBOOK.md`: setup, intake, source wiring, recovery, safeguards and limitations.
- `verification/`: captured RED/GREEN reproduction, full test output, actual synthetic demo, and retained 0.2.0 setup-check wire evidence.
- `SOURCES.md`: official API documentation and version assumptions.
- `LICENSE`: MIT. Software is supplied as-is; this does not promise fitness, uptime or support.

This release demonstrates tested mechanisms. It is not a claim of client adoption, earned income, a paid deployment or end-to-end live-provider certification.
