# JSDaj Audience Review 0.2.0

Free browser-local review of audience CSV snapshots before import. Keep your email platform. No consent inference, automatic resolution, account access, remote uploads, tracking, savings estimate or import acceptance guarantee. Support: support@jsdaj.com (do not send customer files).

## Quickstart

Node 24+, npm; from an extracted kit directory:

```
npm ci --ignore-scripts
npm test
node src/cli.mjs check < examples/request.json
node src/cli.mjs report < examples/request.json > findings.csv
node src/http.mjs
# another terminal:
curl -s http://127.0.0.1:3211/v1/check -H 'Content-Type: application/json' --data-binary @examples/request.json
python3 examples/check.py
node examples/mcp.mjs
```

For this workstation substitute `ELECTRON_RUN_AS_NODE=1 /opt/t3code-bin/t3code` for node. npm is only needed at install; no sibling checkout needed. Dependencies are locked. Build kit with `NODE=/path/to/node python3 scripts/package.py`.

## Workflow and schemas

`examples/request.json` is a portable v1 job. Supply 1–8 sources: unique `id`, display `name` (names may repeat), CSV text, exact `emailColumn`, and exactly one of `statusColumn` or `declaredStatus`. Declare status only when the export omits it, based on your source evidence. Recognized status strings: subscribed, unsubscribed, non-subscribed, cleaned, pending, archived. Other strings, including blanks, become UNKNOWN_STATUS. No status aliases are inferred. Exact status strings are retained.

Matching defaults to `exact`; optionally choose `trim-lowercase` for the whole email. This may join case-sensitive local parts: choose deliberately. Plus suffixes and dots are preserved. The basic email shape check is not mailbox verification. Original mapped email/status strings remain in findings, including invalid rows. Only mapped columns are retained in reports; all CSV cells are parsed as strings. CSV header whitespace is trimmed for mapping; headers must be unique after trimming. Quoted commas/newlines, escaped quotes, BOM, CRLF, semicolon and tab delimiters supported. ZIP/XLSX are not supported; extract CSVs yourself.

Provenance is source ID/name and 1-based logical CSV record (header is record 1, quoted newlines do not add records; blank records count). Each extra occurrence points to its first within-source record or first cross-snapshot record. Different statuses produce STATUS_CONFLICT evidence, including unknown statuses; never a recommended status. Counts are findings, not billable contacts or people. Duplicate snapshots can represent time changes; a conflict does not establish which is current.

`offset` (default 0) and `limit` (default 100, max 1000) paginate findings with `page.total` and `nextOffset`; resend unchanged sources for subsequent pages. Counts cover the full input, exports only the selected page. JSON preserves strings; CSV quotes every value and prefixes spreadsheet formula-like cells with apostrophe. Reports contain personal data; store securely and delete when no longer needed. The browser renders text only and clears stale reports on input changes.

Limits: 5 MiB UTF-8 per CSV, 8 snapshots, 25,000 total data records, 100 columns, 1,000 characters per mapped email/status cell, 100 per source name/ID. Request envelope 24 MiB; output JSON max 4 MiB, lower page limit if exceeded. Synchronous parsing can pause the UI near limits. No durable storage or request-body logging. Runtime memory lasts until process/reload/GC; this is not secure memory erasure.

## Integration matrix and data modes

| Interface | Implemented workflow / boundary |
|---|---|
| Browser | Static `public/audience-review/`, local File/paste CSV and JSON/CSV report; no processing network calls |
| REST/OpenAPI 3.1 | POST `/v1/check`, `/v1/report.csv`; GET `/openapi.json`; optional operator-run local/self-hosted service |
| MCP stdio | `node src/stdio.mjs`; tools `review_audiences`, `export_review_csv`; resource `jsdaj-audience-review://openapi` |
| MCP Streamable HTTP | Same tools at `/mcp` on port 3211; official SDK v2 legacy and modern auto negotiation tested with real clients |
| CLI/batch | stdin JSON job, stdout JSON or CSV, errors stderr and nonzero exit; no paths/URLs in jobs |
| Portable formats | CSV snapshots, versioned JSON mappings/job, paginated JSON/CSV findings |
| Events/webhooks | Inapplicable: synchronous computation, no background jobs or stored state, no outbound callbacks |
| Ecosystem connectors | Existing REST/MCP clients can supply exports; no native Mailchimp/account connector or commercial host certification |
| Other protocols | GraphQL/gRPC not justified by current bounded file workflow evidence |

Stdio trusts the local process boundary and has no bearer token. HTTP defaults to loopback without auth for local scripts; no shared-user authorization/tenancy. Set JSDAJ_API_TOKEN (32+ characters) for bearer auth. Binding beyond loopback via JSDAJ_HOST requires token; configure explicit JSDAJ_ALLOWED_HOSTS and JSDAJ_ALLOWED_ORIGINS comma lists. Default allowed hosts localhost/127.0.0.1/[::1], no browser origins, no wildcard. All processing endpoints and schema require token when configured; health metadata is public. 60 requests/minute per instance, 4 concurrent requests, 16 connections, 30s request timeout, no compressed bodies. Remote operation is a separate mode transmitting input to your chosen operator: arrange TLS, privacy, network access and retention yourself. JSDaj does not host customer processing. Never expose this optional service as part of a static deployment.

Errors use `{error:{code,message}}`; stable codes INVALID_REQUEST/INVALID_CSV (422), INVALID_JSON (400), UNAUTHORIZED (401), INVALID_HOST/INVALID_ORIGIN (403), REQUEST_TOO_LARGE/RESULT_TOO_LARGE (413), RATE_LIMITED (429), UNSUPPORTED_ENCODING/UNSUPPORTED_MEDIA_TYPE (415), METHOD_NOT_ALLOWED (405), NOT_FOUND (404), INTERNAL_ERROR (500). MCP returns tool errors; malformed protocol/schema input follows SDK errors. CLI additionally UNKNOWN_COMMAND. v1 semantic changes require a new version; no automatic migration or deprecation currently scheduled. OpenAPI includes request and result schemas; security alternatives describe optional local auth, not unauthenticated remote permission.

## Release checklist

- Shared browser/domain core with REST/OpenAPI, real MCP stdio/HTTP, CLI, portable exports, bounds and security contracts tested.
- Integration matrix and data modes documented under owner product standard in business/product-standards.md.
- Lockfile and allowlisted kit/checksum generated; extracted kit installed and tested independently.
- Parent reviews static assets and deploys ONLY contents of public/audience-review/ to /audience-review/. No root files, backend, credentials, mail or shared config changes.
- No spending, new SaaS/account connection, hosted data exposure or paid offer without separate approval. No live payment collection.
