# Connect a scheduled script to Report Watch

Download [report-watch-client.mjs](https://reportwatch.mayd-it.com/examples/report-watch-client.mjs). Readable setup page: [script guide](https://reportwatch.mayd-it.com/guides/script-csv-monitoring). This is a Node.js 22+ command-line client with no package dependencies, not an account creator, report generator or scheduler. Keep the downloaded version in your controlled workflow rather than downloading and executing a changing URL on every run.

## Before sending

A person must create an eligible, unpaused report monitor, choose its rules and daily/weekly schedule, and authorize this workflow. Public monitoring needs a confirmed paid plan. The client does not purchase access, change a report or use ChatGPT browser credentials. Start with synthetic data. `prepare` and `inspect` stay local; **`send` writes check evidence and can open/recover incidents and queue email alerts**.

Use protected local storage. The saved JSON envelope contains the entire CSV, even though Report Watch does not retain raw CSV rows. Do not place envelopes in a public web directory, shared download folder, source repository, logs or an AI prompt. Preparation requests file mode 0600 on systems that support it; on Windows, use a folder with appropriate user/service ACLs. Keep the files until their outcome has been reviewed, then apply your own retention policy. The client never automatically deletes them.

## 1. Prepare once per artifact

Run this single-line command after generating a finished UTF-8 CSV. Replace every uppercase placeholder with an approved value. The output's parent folder must already exist.

```sh
node report-watch-client.mjs prepare --csv report.csv --monitor REPORT_ID --deadline INTENDED_DEADLINE_MS --id STABLE_SUBMISSION_ID --out submission.json
```

The report ID comes from your report's submission URL. The deadline must be exactly 13 digits of Unix milliseconds for the **intended scheduled occurrence**, without its grace period. It must fit the report's current schedule, not precede creation, and not be later than the next upcoming occurrence. The client checks its format; it cannot verify your server-side schedule offline. Do not substitute the current time, recalculate a deadline on retry or add 24 hours in UTC to implement daylight-saving schedules.

Choose one stable printable-ASCII submission ID, 1–128 characters without spaces, for this artifact and deadline. The command copies the CSV, ID, report ID and deadline into a new JSON file. It preserves UTF-8 text, BOM and line endings; it rejects invalid UTF-8 and CSVs over 1 MiB. It refuses to overwrite an existing envelope. No request or token is needed at this stage. A failed disk write can leave an incomplete file: inspect and review it; never send merely because a file exists.

Every new period gets a separate envelope and ID. A corrected file gets a new envelope and ID **with the original deadline being corrected**. Do not create new IDs just to get around an access error, timeout or conflict.

## 2. Inspect without sending

```sh
node report-watch-client.mjs inspect --envelope submission.json
```

This checks the local envelope's encoding, allowed fields and size. It prints a small summary with `sent: false` and `scheduleVerified: false`. It does not validate CSV quality, access, payment, schedule eligibility or email delivery. Use the [free CSV checker](https://reportwatch.mayd-it.com/tools/csv-checker) to explore rules locally.

## 3. Inject the report token, then send

Configure the executing process's **REPORT_WATCH_TOKEN** environment variable using your platform's protected runtime secret facility. Use the 64-character report token issued for this monitor. Do not paste it into a command, ordinary workflow field, envelope, source file, prompt or log. The client deliberately has no `--token`, URL or origin option.

```sh
node report-watch-client.mjs send --envelope submission.json
```

The destination is fixed to `https://reportwatch.mayd-it.com/api/ingest/<reportId>`. The client does not follow redirects, use browser cookies or send an Origin header. It prints a compact JSON outcome without CSV rows, rule/header names, provider responses or the token. Store that summary as protected workflow evidence. It is not a full diagnostic export; inspect Check history in Report Watch for details.

## 4. Branch on the result

| Exit | Outcome | What your job should do |
| --- | --- | --- |
| 0 | `prepared` / `locally_valid` | Local command completed; **nothing sent**. |
| 0 | `passed` from `send` | Save the receipt; inspect `late` and `duplicate`. A pass only describes this submitted CSV. |
| 2 | `quality_failed` | A failed check was saved. Review evidence and correct the file. Repeating the same ID returns the original failure. |
| 3 | `review` | No acceptable receipt, or access/quota/routing needs attention. Retain the original envelope; do not treat the report as passed. |
| 1 | `input_error` | Inspect the command, file access, envelope and protected token. Existing files are never overwritten. |

An HTTP 200 is not enough: the receipt must have the expected deadline and consistent pass/fail checks. `late: true` can accompany a pass; it does not move that evidence into a new period. `duplicate: true` returns the original saved result and check time. Neither a successful check nor a provider-accepted message proves client inbox delivery or business accuracy.

## Retry policy and unattended operation

Each `send` invocation permits at most **four attempts**: immediately, then after 5, 30 and 120 seconds. Only a timeout or HTTP 5xx triggers an automatic retry. Each attempt has a 30-second timeout covering headers and body; receipt bodies are limited to 256 KiB. Normal worst-case retries take about 4 minutes 35 seconds. Give your process enough time to finish and prevent overlapping job executions.

All retries use the same captured bytes, ID, report ID and deadline. Reload the same protected envelope after a restart. Never regenerate the CSV or replace its ID inside a retry. The server may have saved a request whose response was lost. After the retry budget, stop for review. External schedulers must not restart exit-3 jobs forever. Other network failures, redirects, unexpected content, invalid receipts and all 4xx responses stop immediately; 429 can mean a total-storage cap that waiting cannot clear.

A scheduler must supply the correct occurrence, create separate envelope paths, inject the protected token, prevent overlap and route nonzero exits to its own review mechanism. This download does not install a task, calculate timezone occurrences, lock jobs, run a durable queue or contact an operator itself. After human review, an authorized retry uses the unchanged original envelope. Token replacement, pauses, holds, schedule edits or lost entitlement can make it ineligible; the client cannot override them.

## Verification and your first connection

The downloadable CLI was exercised locally on Node 24 with synthetic files. Tests cover exact-byte preparation, overwrite refusal, local-only inspection, protected-token handling, bounded retries, body timeouts, permanent errors and malformed receipts. The same client was run against the real application handler with in-memory SQLite and intercepted transport: a committed response loss returned the original check on retry; a failed CSV and correction preserved the period and incident state. No production account, real CSV, provider request or email was used. This does not verify your installed scheduler, real customer alerts or a paid customer journey.

Before enabling your authorized job, inspect the code, run a passing synthetic submission, repeat its envelope to confirm the same check ID, test a deliberate quality failure and a correction, and review saved evidence. Verify any intended alert recipient with appropriate sending authorization. Report Watch allows 1 MiB, 100 columns, 10,000 rows, 1,000 new checks per rolling 24 hours and 5,000 saved checks total per workspace. Identical retries do not use an additional saved-check slot.

References: [submission contract](https://reportwatch.mayd-it.com/guides/agent-integration.md), [schedule rules](https://reportwatch.mayd-it.com/guides/integration-guide.md), [OpenAPI](https://reportwatch.mayd-it.com/openapi.json), [Node file operations](https://nodejs.org/api/fs.html), [Node fetch](https://nodejs.org/api/globals.html#fetch).
