ofw-mcp 2.4.3 → 2.5.0

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/ofw-mcp",
     "source": "github"
   },
-  "version": "2.4.3",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "ofw-mcp",
-      "version": "2.4.3",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -34,6 +34,12 @@
           "description": "Write-tool gate: \"none\" registers no write tools; \"drafts\" registers draft-level writes only (save/delete drafts, upload attachments); \"all\" registers everything (default). Unrecognized values fail closed to \"none\".",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "OFW_CALENDAR_WRITES",
+          "description": "Set to \"true\" to register calendar write tools (create/update/delete event) in \"drafts\" write mode. Events have no draft stage but are reversible. Never overrides \"none\".",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/ofw-fpx/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: ofw-fpx
+description: >-
+  Access OurFamilyWizard (OFW) — messages, calendar, expenses, journal —
+  from a shell with the fpx CLI (@fetchproxy/cli) instead of running the
+  ofw-mcp server: capture the signed-in web app's Bearer token once via the
+  browser bridge, then curl the REST API directly. Use when you want OFW
+  data without the MCP, in a script, or on a machine where the MCP isn't
+  installed.
+---
+
+# OurFamilyWizard via fpx + curl (no MCP)
+
+OFW's app (`ofw.ourfamilywizard.com`) has no API key a script can request —
+the only credential is the Bearer token the web app itself mints on login
+and stores in `localStorage["auth"]` (with `localStorage["tokenExpiry"]`
+alongside). Once you have that token the API itself has **no bot wall** —
+`ofw-mcp`'s own `src/client.ts` calls it with plain Node `fetch` for every
+request. So this skill is **hybrid**: `fpx` captures the token from a
+signed-in browser tab ONCE, then plain `curl` does every read/write from
+then on. fetchproxy never touches the actual API calls.
+
+**This is a shared family-court record.** Every write here (`send`,
+`create_event`, `create_expense`, `create_journal_entry`,
+`upload_attachment`, the `delete_*`/bulk-delete calls) lands on the same
+record the MCP's `OFW_WRITE_MODE` gate exists to protect. There is no
+dry-run/confirm here — curl just does it. Treat every write like the MCP's
+`all` mode: real, permanent, and visible to your co-parent.
+
+## One-time setup
+
+```sh
+npm install -g @fetchproxy/cli                                       # provides `fpx`
+fpx profile add ofw --domain ourfamilywizard.com
+fpx profile declare ofw --local-storage auth --local-storage tokenExpiry
+fpx pair -p ofw                                                       # prints a pair code → approve in Transporter
+```
+
+Requirements: the **Transporter** browser extension installed, with an
+open, signed-in `ofw.ourfamilywizard.com` (or `www.ourfamilywizard.com`)
+tab, and its Chrome **Site access** allowing `ourfamilywizard.com`. Pairing
+persists across invocations.
+
+## Capture the token (once per shell / whenever it goes stale)
+
+```sh
+LS=$(fpx local-storage auth tokenExpiry -p ofw)
+TOKEN=$(jq -r '.auth' <<<"$LS")
+EXPIRES=$(jq -r '.tokenExpiry' <<<"$LS")
+```
+
+If `auth` comes back empty, sign into OFW in the browser tab first — the
+same precondition `ofw-mcp`'s own fetchproxy fallback documents in
+`src/auth.ts`.
+
+## Core call
+
+Every request needs the bearer token plus OFW's two protocol headers
+(sent on every call, not just login):
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/profiles' \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'ofw-client: WebApplication' \
+  -H 'ofw-version: 1.0.0' \
+  | jq .
+```
+
+`ofw-version` is OFW's wire-protocol version (see `src/protocol.ts`),
+unrelated to any package version — send it as-is. Writes add
+`-H 'Content-Type: application/json' --data '...'` for JSON bodies, or
+`-F` multipart fields for uploads/deletes — both shown per-endpoint in
+`references/requests.md`.
+
+## The one rule: re-GET after every message POST to confirm it landed
+
+OFW's `POST /pub/v3/messages` response is minimal (`{"entityId": <id>}` or
+legacy `{"id": <id>}`) and — worse — its draft-*replace* path silently
+no-ops while still echoing success. Never trust the POST status alone for
+a send or draft save: immediately `GET /pub/v3/messages/{id}` with the
+returned id and check the body/subject actually match what you sent. See
+§2/§3 in `references/requests.md`.
+
+## Auth-error handling
+
+- **401** — the token expired or was invalidated. OFW has no refresh-token
+  flow; re-mint by reloading/re-signing-in on the `ourfamilywizard.com`
+  tab, then re-run the capture step above.
+- **429** — OFW's own client waits 2s and retries exactly once
+  (`src/client.ts`); do the same: `sleep 2` and resend the identical
+  request. A second 429 is a real rate-limit — back off further.
+- Any other non-2xx is a real upstream error — surface the response body.
+
+All 20 endpoint operations, request bodies, and `jq` projections are in
+`references/requests.md`, transcribed from `src/tools/*.ts`, `src/sync.ts`,
+and `src/tools/_shared.ts` — nothing here is guessed.
+
+## Notes
+
+- Base URL is `https://ofw.ourfamilywizard.com` for every endpoint (the
+  `www.` host serves the web app UI, not the API).
+- `ofw-mcp` maintains a local SQLite message cache for fast list/search;
+  this skill has no cache — every list call here goes straight to OFW, and
+  `GET /pub/v3/messages/{id}` on an **unread inbox message marks it read**
+  on OFW, exactly as it does for the MCP.
+- This project is developed and maintained by AI (Claude).

package/skills/ofw-fpx/references/requests.md

@@ -0,0 +1,252 @@
+# OurFamilyWizard requests for fpx + curl
+
+Base URL for every call: `https://ofw.ourfamilywizard.com`. Every request
+carries these three headers (from `src/protocol.ts` / `src/client.ts`):
+
+```sh
+AUTH_HEADERS=(-H "Authorization: Bearer $TOKEN" -H 'ofw-client: WebApplication' -H 'ofw-version: 1.0.0')
+```
+
+`$TOKEN` comes from the one-time capture in `SKILL.md`. All paths, params,
+and bodies below are transcribed from `src/tools/*.ts`, `src/sync.ts`, and
+`src/tools/_shared.ts` — the exact shapes `ofw-mcp` sends.
+
+---
+
+## 1. Profile & dashboard
+
+**Current user + co-parent profile:**
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/profiles' "${AUTH_HEADERS[@]}" | jq .
+```
+
+**Dashboard summary (unread count, upcoming events, outstanding expenses).
+Note: this call updates your last-seen status on OFW, same as opening the
+web app's dashboard:**
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v1/users/useraccountstatus' "${AUTH_HEADERS[@]}" | jq .
+```
+
+## 2. Messages — folders, list, detail
+
+**Folder IDs + unread counts** (needed before listing by folder):
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v1/messageFolders?includeFolderCounts=true' "${AUTH_HEADERS[@]}" \
+  | jq '.systemFolders[] | {id, folderType}'
+# folderType is one of INBOX / SENT_MESSAGES / DRAFTS
+```
+
+**List messages in a folder** (date-desc, 50/page is what the MCP's sync
+uses; unread inbox items carry `showNeverViewed: true` — the reliable
+unread signal, per CLAUDE.md):
+
+```sh
+FOLDER_ID=<id from above>
+curl -s "https://ofw.ourfamilywizard.com/pub/v3/messages?folders=${FOLDER_ID}&page=1&size=50&sort=date&sortDirection=desc" \
+  "${AUTH_HEADERS[@]}" \
+  | jq '.data[] | {id, subject, sentAt: .date.dateTime, from: .from.name, showNeverViewed}'
+```
+
+**Message/draft detail by id** (GETting an unread inbox message marks it
+read on OFW):
+
+```sh
+curl -s "https://ofw.ourfamilywizard.com/pub/v3/messages/${ID}" "${AUTH_HEADERS[@]}" \
+  | jq '{id, subject, body, sentAt: .date.dateTime, from: .from.name, files, recipients: [.recipients[] | {id: .user.id, name: .user.name, viewedAt: .viewed.dateTime}]}'
+```
+
+## 3. Send a message / save a draft (write — confirm-by-re-GET)
+
+Both send and save-draft POST the same shape to `/pub/v3/messages`; only
+`draft` (bool) differs. **Never pass `messageId`/an existing id in this
+POST** — OFW's update-in-place endpoint silently no-ops on repeat edits
+while echoing success. To "replace" a draft: POST a fresh one, confirm it
+landed, then bulk-delete the old id (§4).
+
+```sh
+BODY=$(jq -n \
+  --arg subject 'Pickup time change' \
+  --arg body 'Can we move Friday pickup to 5pm instead of 4?' \
+  --argjson recipientIds '[12345]' \
+  --argjson myFileIDs '[]' \
+  --arg draft false \
+  --arg includeOriginal false \
+  --argjson replyToId null \
+  '{subject:$subject, body:$body, recipientIds:$recipientIds,
+    attachments:{myFileIDs:$myFileIDs}, draft:($draft=="true"),
+    includeOriginal:($includeOriginal=="true"), replyToId:$replyToId}')
+
+RESP=$(curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v3/messages' \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' --data "$BODY")
+
+NEW_ID=$(jq -r '.id // .entityId // empty' <<<"$RESP")
+[ -n "$NEW_ID" ] || { echo "SEND UNCONFIRMED: no id in response: $RESP" >&2; exit 1; }
+
+# Re-GET immediately — the only honest way to confirm the write landed.
+DETAIL=$(curl -s "https://ofw.ourfamilywizard.com/pub/v3/messages/${NEW_ID}" "${AUTH_HEADERS[@]}")
+jq -e --arg s 'Pickup time change' --arg b 'Can we move Friday pickup' \
+  '(.subject // "" | contains($s)) and (.body // "" | contains($b))' <<<"$DETAIL" >/dev/null \
+  && echo "confirmed id=$NEW_ID" || echo "WARNING: re-fetched body/subject does not contain what was sent — verify on ourfamilywizard.com" >&2
+```
+
+For a **draft**, set `draft:true`; `subject`/`body` are the only required
+fields (`recipientIds` may be `[]`).
+
+To **reply**, set `replyToId` to the parent message id and
+`includeOriginal:true` (OFW appends the original message to the body
+server-side — that's why containment, not equality, is the right check
+above).
+
+## 4. Delete messages/drafts (bulk, multipart)
+
+Same endpoint deletes both sent-message ids and draft ids — pass whichever
+you mean:
+
+```sh
+curl -s -X DELETE 'https://ofw.ourfamilywizard.com/pub/v1/messages' \
+  "${AUTH_HEADERS[@]}" \
+  -F 'messageIds=111' -F 'messageIds=222'   # repeat -F per id
+```
+
+## 5. Attachments
+
+**Upload a file to "My Files"** (multipart; `shareClass` is `PRIVATE` or
+`SHARED`; matches the web UI's upload request in `src/tools/messages.ts`):
+
+```sh
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v3/myfiles/multipart' \
+  "${AUTH_HEADERS[@]}" \
+  -F "file=@/path/to/file.pdf;type=application/pdf" \
+  -F 'source=message' \
+  -F 'description=file.pdf' \
+  -F 'label=file.pdf' \
+  -F 'fileName=file.pdf' \
+  -F 'shareClass=PRIVATE' \
+  | jq '{fileId, fileName, fileType, sizeInBytes}'
+```
+
+The response's `fileId` is what you pass as `myFileIDs` in §3's POST body
+(`attachments.myFileIDs`) to attach it to a message/draft.
+
+**Attachment metadata:**
+
+```sh
+curl -s "https://ofw.ourfamilywizard.com/pub/v1/myfiles/${FILE_ID}" "${AUTH_HEADERS[@]}" \
+  | jq '{fileId, fileName, fileType, fileSize, label}'
+```
+
+**Download attachment bytes** (binary — write straight to a file, don't
+pipe through `jq`):
+
+```sh
+curl -s "https://ofw.ourfamilywizard.com/pub/v1/myfiles/${FILE_ID}/data" \
+  "${AUTH_HEADERS[@]}" -o "./${FILE_ID}-download"
+```
+
+## 6. Calendar
+
+**List events** (`basic` or `detailed`; dates are `YYYY-MM-DD`):
+
+```sh
+curl -s "https://ofw.ourfamilywizard.com/pub/v1/calendar/basic?startDate=2026-07-01&endDate=2026-07-31" \
+  "${AUTH_HEADERS[@]}" | jq .
+# swap "basic" for "detailed" for full event details
+```
+
+**Create an event** (write — court-visible; `eventFor` is
+`neither|parent1|parent2`):
+
+```sh
+BODY=$(jq -n '{
+  title: "Soccer practice",
+  startDate: "2026-07-20T16:00:00",
+  endDate: "2026-07-20T17:30:00",
+  allDay: false,
+  location: "Community field",
+  reminder: "1 hour before",
+  privateEvent: false,
+  eventFor: "neither",
+  children: [67890]
+}')
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v1/calendar/events' \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' --data "$BODY" | jq .
+```
+
+**Update an event** (send only the fields you're changing):
+
+```sh
+curl -s -X PUT "https://ofw.ourfamilywizard.com/pub/v1/calendar/events/${EVENT_ID}" \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' \
+  --data '{"title":"Soccer practice (moved)","startDate":"2026-07-20T17:00:00"}' | jq .
+```
+
+**Delete an event:**
+
+```sh
+curl -s -X DELETE "https://ofw.ourfamilywizard.com/pub/v1/calendar/events/${EVENT_ID}" "${AUTH_HEADERS[@]}"
+```
+
+## 7. Expenses
+
+**Totals (owed/paid):**
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses/totals' "${AUTH_HEADERS[@]}" | jq .
+```
+
+**List expenses** (offset-based, 0-indexed `start`):
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses?start=0&max=20' "${AUTH_HEADERS[@]}" | jq .
+```
+
+**Create an expense** (write):
+
+```sh
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v2/expense/expenses' \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' \
+  --data '{"amount": 45.00, "description": "Cleats for soccer"}' | jq .
+```
+
+## 8. Journal
+
+**List entries** (offset-based, but **1-indexed** `start` — unlike
+expenses):
+
+```sh
+curl -s 'https://ofw.ourfamilywizard.com/pub/v1/journals?start=1&max=10' "${AUTH_HEADERS[@]}" | jq .
+```
+
+**Create an entry** (write — journal entries are a permanent court record):
+
+```sh
+curl -s -X POST 'https://ofw.ourfamilywizard.com/pub/v1/journals' \
+  "${AUTH_HEADERS[@]}" -H 'Content-Type: application/json' \
+  --data '{"title": "Missed pickup", "body": "Co-parent arrived 45 min late without notice."}' | jq .
+```
+
+---
+
+## Auth-error / retry recipe (wrap any of the above)
+
+```sh
+RESP_FILE=$(mktemp /tmp/ofw-resp.XXXXXX.json)
+trap 'rm -f "$RESP_FILE"' EXIT
+
+call() { curl -s -o "$RESP_FILE" -w '%{http_code}' "$@" "${AUTH_HEADERS[@]}"; }
+
+STATUS=$(call 'https://ofw.ourfamilywizard.com/pub/v2/profiles')
+if [ "$STATUS" = "429" ]; then
+  sleep 2
+  STATUS=$(call 'https://ofw.ourfamilywizard.com/pub/v2/profiles')
+fi
+if [ "$STATUS" = "401" ]; then
+  echo "token expired — reload/sign in on the ourfamilywizard.com tab, then re-run the fpx local-storage capture" >&2
+  exit 1
+fi
+[ "$STATUS" -lt 300 ] || { echo "OFW API error: $STATUS $(cat "$RESP_FILE")" >&2; exit 1; }
+jq . "$RESP_FILE"
+```

package/dist/validate.js

@@ -1,35 +0,0 @@
-/**
- * Validate an OFW API response against a zod schema at the call site.
- *
- * Every OFW endpoint is reverse-engineered and undocumented, so a backend
- * change on their side would otherwise flow `undefined` silently into the
- * SQLite cache and persist (issue #83). Schemas are `.looseObject(...)`
- * covering ONLY the fields the code actually reads — cosmetic API additions
- * pass through untouched (and stay present in the parsed output, which
- * matters for `listData`/`metadata` blobs cached verbatim).
- *
- * Two modes, chosen per call site:
- *  - `'lenient'` (default) — read/sync paths. On mismatch, log a structured
- *    warning to stderr naming the endpoint and fields, then return the RAW
- *    response unchanged so the existing `??` fallbacks keep the tool useful.
- *  - `'strict'` — write paths (send/save_draft verification, upload). On
- *    mismatch, throw: proceeding on an unverifiable response risks deleting
- *    a draft, mis-reporting a send, or caching an unusable fileId.
- *
- * The error/warning text is deliberately precise ("date.dateTime: expected
- * string…") — it's the failure signal a maintainer (human or Claude) fixes
- * in one session, vs. "some messages show the wrong date sometimes".
- */
-export function parseOFW(schema, raw, ctx, mode = 'lenient') {
-    const result = schema.safeParse(raw);
-    if (result.success)
-        return result.data;
-    const issues = result.error.issues
-        .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
-        .join('; ');
-    const message = `OFW response for ${ctx} failed validation: ${issues}`;
-    if (mode === 'strict')
-        throw new Error(message);
-    console.error(`[ofw-mcp] WARNING: ${message} — continuing with the raw response; fields derived from it may be missing or wrong.`);
-    return raw;
-}