outreach-engine: build plan + M0–M7 + M8 (Gmail, Outlook, Slack, health checker, D5 jurisdictions)

.github/workflows/outreach-engine.yml

@@ -0,0 +1,44 @@
+name: outreach-engine
+
+on:
+  push:
+    paths:
+      - "outreach-engine/**"
+      - ".github/workflows/outreach-engine.yml"
+  pull_request:
+    paths:
+      - "outreach-engine/**"
+      - ".github/workflows/outreach-engine.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: outreach-engine
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22, 24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+          cache-dependency-path: outreach-engine/package-lock.json
+      - run: npm ci
+      - run: npm run build
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run boundaries
+      - run: npm run secrets
+      - run: npm run loc
+      - run: npm run soak

outreach-engine/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+coverage/
+.DS_Store
+*.log
+*.db
+*.db-wal
+*.db-shm
+.env
+.env.*
+!.env.example
+*.tgz
+tmp/

outreach-engine/.npmrc

@@ -0,0 +1 @@
+provenance=true

outreach-engine/LICENSE

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

outreach-engine/README.md

@@ -0,0 +1,75 @@
+<p align="center">
+  <img src="../docs/brand/splitin-logo.png" alt="SplitIn logo" width="96" height="96">
+</p>
+
+# Outreach Engine
+
+MIT-licensed, provider-neutral outreach orchestration. It imports contacts, turns
+versioned playbooks into per-contact scheduled actions, executes each action at most
+once through capability-checked provider adapters, stops on reply, bounce, opt-out or
+pause, and records every transition in an append-only audit log.
+
+The engine is the product. The CLI, HTTP API, MCP server, Slack and the Papr Work app
+are thin clients of it.
+
+> **Status: M0–M7 complete, the D5 jurisdiction policy, the Gmail and Outlook adapters, Slack notifications and the health checker (M8).** Contracts, fakes, SQLite store, the durable execution core,
+> the campaign domain, the importer, inbound processing, the `outreach` CLI, the HTTP API
+> and the Papr Work console are built and tested on fake providers. Real provider adapters
+> and Slack are M8, MCP is M9.
+> Nothing is emailed until an admin opens the live-send gate. Specification:
+> [BUILD_PLAN.md](BUILD_PLAN.md), milestones in §14.
+
+## Guarantees it is being built to
+
+- **At most once without confirmation.** A send whose outcome is unknown is never
+  repeated until the provider confirms it did not happen ([ADR 0002](docs/adr/0002-at-most-once-without-confirmation.md)).
+- **Fail closed.** Unhealthy account, engaged kill switch, expired approval, suppressed
+  recipient or unrenderable template all mean no send, with a recorded reason.
+- **No social-network automation.** Social steps are manual tasks a human completes on
+  the native site ([ADR 0003](docs/adr/0003-no-social-automation.md)).
+- **No LLM in the send path.** Models may draft and suggest; deterministic code decides.
+
+## Packages
+
+| Package | Milestone | What it is |
+| --- | --- | --- |
+| `@splitin/outreach-contracts` | M0 seed, M1 | Types, schemas, action transition table, error taxonomy, provider ports |
+| `@splitin/outreach-fakes` | M1 | Fake providers with failure modes + provider conformance kit |
+| `@splitin/outreach-store-sqlite` | M2 | Migrations, repositories, audit hash chain |
+| `@splitin/outreach-core` | M3–M4, M6 | Execution core, campaign domain, policy, inbound processing |
+| `@splitin/outreach-import` | M5 | Inert HTML/CSV/XLSX/JSON importer |
+| `@splitin/outreach-e2e` (private) | M6 | Import-to-audit end-to-end suite on fake providers |
+| `@splitin/outreach-server` | M7 | HTTP API: bearer tokens, webhooks, one-click unsubscribe |
+| `@splitin/outreach-cli` | M7 | The `outreach` command (setup, imports, campaigns, approvals, worker, serve) |
+| `apps/papr` | M7 | Papr Work bundle: Outreach Console mini-app, worker job, agent skill |
+| `@splitin/outreach-mcp` | M9 | MCP server |
+| `@splitin/outreach-provider-email-gmail` | M8 | Gmail adapter: send as the mailbox user, Sent-folder reconciliation, History API inbound, loopback OAuth |
+| `@splitin/outreach-provider-email-outlook` | M8 | Outlook / Exchange Online adapter via Microsoft Graph: MIME draft-then-send, Sent Items reconciliation, rotating refresh tokens |
+| `@splitin/outreach-provider-kit` | M8 | Shared adapter building blocks: HTTP outcome classification, loopback OAuth (PKCE), DSN parsing |
+| `@splitin/outreach-notify-slack` | M8 | Slack notifications: incoming webhook or `chat.postMessage`, escaped Block Kit |
+| Zoho Mail adapter | M8 | Remaining |
+
+## Develop
+
+Requires Node ≥ 22.13.
+
+```zsh
+cd open-internal-tools/outreach-engine
+npm install
+npm run check   # lint, typecheck, test, package boundaries, secret scan, line limit
+npm run build
+```
+
+`npm run boundaries` enforces the dependency direction in BUILD_PLAN.md §3: the core,
+importer and adapters depend on `@splitin/outreach-contracts` only, and storage, HTTP,
+MCP, Slack and file-parsing libraries are confined to the packages that own them. A new
+package fails the check until it is given a rule.
+
+## Decisions
+
+Architecture decisions live in [docs/adr/](docs/adr/). Change a decision by adding a new
+ADR that supersedes the old one, not by editing it.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

outreach-engine/apps/papr/README.md

@@ -0,0 +1,46 @@
+# Outreach Console for Papr Work
+
+A Papr Work bundle that gives operators a console for the outreach engine: what goes out in the next 24 hours and what is holding it, approvals with the exact content being approved, the human review queue, manual social touches, campaign health, and one button that stops all sending.
+
+The engine is **not** inside Papr. It keeps its own SQLite database, because it needs multi-statement transactions that Papr's synced registry databases do not allow (see [ADR 0004](../../docs/adr/0004-papr-host-integration.md)). The console talks to the engine's HTTP API through a server-side backend handler, so the API token never reaches the browser.
+
+```text
+Papr mini-app (app.js) --POST /api/app/backend/:action--> backend/outreach.mjs --Bearer token--> outreach serve (loopback)
+Papr job (optional)   --node run.mjs--> outreach worker --once                                    \-> outreach.db
+```
+
+## Contents
+
+| Path | What it is |
+| --- | --- |
+| `bundle/manifest.json` | Papr portable bundle manifest (schema 1.0.0) |
+| `bundle/apps/outreach-console/` | The mini-app: `index.html`, `app.js`, `style.css` |
+| `bundle/apps/outreach-console/backend/` | `manifest.json` + `outreach.mjs`: a fixed allowlist of actions mapped to fixed API routes |
+| `bundle/jobs/outreach-worker/` | Optional Papr job running one worker pass per minute (pilot only) |
+| `bundle/skills/outreach.md` | Agent rules: draft, validate and report; never approve, activate or send |
+
+## Setup
+
+1. Initialise the engine (outside Papr):
+   ```zsh
+   export OUTREACH_DB=~/Papr/outreach/outreach.db
+   outreach init
+   outreach account add ...            # your provider account (decision D1)
+   outreach principal add papr:console --roles approver
+   outreach token create papr:console --name console --role approver
+   outreach serve                       # loopback only, port 8787
+   ```
+2. Import `bundle/` into Papr Work.
+3. In **Settings → Integration Keys**, add `OUTREACH_API_URL` (`http://127.0.0.1:8787`) and `OUTREACH_API_TOKEN` (the token from step 1). For a read-only wall display, issue a `--role viewer` token instead.
+4. The worker must run somewhere:
+   - **Production (recommended):** `outreach worker --loop` under launchd or systemd.
+   - **Pilot:** enable the bundled `outreach-worker` job, set it to **local-only**, and point its `package.json` at a local build of `@splitin/outreach-cli` until the package is published.
+
+## Acceptance on a live Papr install (not automated here)
+
+The bundle is validated against a copy of Papr's manifest schema, and the backend handler is tested against a real API server, both in-process and through the `PAPR_ACTION` subprocess contract. The first run on a real Papr install should still confirm:
+
+- [ ] bundle import succeeds and the app opens;
+- [ ] the app id Papr assigns matches `outreach-console`, or pass `?appId=<id>` (Papr apps usually hardcode their id);
+- [ ] `/api/app/backend/overview` returns data (keys injected);
+- [ ] the worker job installs its dependency and completes a pass.