@arcforgelabs/flow 2026.11.1 → 2026.11.3

package/skills/flow/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: flow
+description: Run the lab's Flow app and read Seazona through it - invoice tabs, send ready invoices, void or delete drafts, invoice rules, jobs, reconcile Seazona jobs with Flow and Xero, compare prices across Flow, Xero and Seazona, link price codes, review items, the Seazona history import, and Seazona orders, invoices and clients.
+metadata: { "openclaw": { "requires": { "bins": ["curl", "openssl", "sha256sum"] } } }
+---
+
+# Flow
+
+Flow is the lab's invoicing app. It takes jobs from Seazona (the lab's case
+system) and sends invoices to Xero. Use `{baseDir}/flow.sh` for every call.
+It holds the Flow key; never print the key file or put the key in a message.
+
+Flow address: saved by `setup` next to the key (or `FLOW_URL`). There is no
+default: the key goes only to this lab's own Flow.
+Key file: `FLOW_AGENT_KEY_FILE` (default `~/.openclaw/credentials/flow-agent-key`).
+
+## First time only
+
+Run `{baseDir}/flow.sh setup https://<this lab's Flow>`. It saves the address,
+makes the key once and prints only `FLOW_AGENT_KEY_SHA256=<64 hex>`. That digest is safe to share: give it to the
+person who sets up Flow. Flow stores the digest, never the key. Run `setup`
+again any time to see the same digest. To change the key, delete the key file,
+run `setup`, and give the new digest to Flow.
+
+Then check: `{baseDir}/flow.sh get me` must answer `HTTP 200`.
+
+## Keep the skill current
+
+Run `{baseDir}/flow.sh update` after Flow gets a new release, and when a call
+answers 404 for a route this skill lists. It gets this skill from the Flow it
+talks to, so the skill always matches the release that Flow runs. It changes
+nothing if the answer is not a good skill. Install the skill from GitHub only
+the first time.
+
+## Calls
+
+Every answer ends with a line `HTTP <code>`. 401 or 403: the key is not set up
+in Flow, or the Flow person is turned off. Stop and tell the person.
+
+Read first. Before a change, read the record, say what you will change, and
+for sends, voids and deletes get the person's yes in the chat.
+
+| Do this | Command |
+| --- | --- |
+| Tabs and counts | `flow.sh get 'invoicing/invoices?status=ready&limit=50'` (status: pending, ready, draft, approved, sent, non_chargeable, void) |
+| Search invoices | `flow.sh get 'invoicing/invoices?q=<text>'` |
+| One invoice | `flow.sh get invoicing/invoices/<id>` |
+| Mark ready | `flow.sh post invoicing/invoices/mark-ready '{"invoiceIds":["<id>"]}'` |
+| Send all ready to Xero | `flow.sh post invoicing/invoices/send-ready '{}'` (or `'{"invoiceIds":["<id>"]}'`) |
+| Void an invoice | `flow.sh post invoicing/invoices/<id>/void` |
+| Delete a draft | `flow.sh delete invoicing/invoices/<id>` |
+| Jobs | `flow.sh get 'invoicing/jobs?limit=50'`, one job `invoicing/jobs/<id>/activity` |
+| Invoice rules | `flow.sh get invoicing/rules`; what a rule can use: `flow.sh get invoicing/rule-fields` |
+| Add a rule | `flow.sh post invoicing/rules '{"name":"...","conditions":[{"field":"job_total","test":"at_most","value":0}],"action":{"kind":"wait"}}'` |
+| Change or turn off a rule | `flow.sh put invoicing/rules/<id> '{"enabled":false}'` |
+| Delete a rule | `flow.sh delete invoicing/rules/<id>` |
+| Automations | `flow.sh get invoicing/automations` |
+| Flow settings | `flow.sh get invoicing/settings` |
+
+Rule actions: `wait` (hold the job) or `skip` (never invoice it). Take field,
+test and value only from `rule-fields`.
+
+Voids: the Void tab holds invoices voided in Flow **or voided or deleted in
+Xero**. Before a clean-up, list the tab, group the rows (Flow void, Xero void,
+deleted draft), show the person the groups, and act only on the group they
+confirm.
+
+Sending: Flow sends each invoice to Xero as a draft unless the "Approve and
+email" setting is on (`invoicing/settings`). Say which one applies before a send.
+
+## Prices and price codes
+
+Flow's price list is the lab's own list of codes and prices
+(`docs/PRICE_LIST.md`). Flow keeps a copy of the Xero items and the Seazona
+products and links each one to a Flow code. `price-list` reads only Flow's
+copies, so it costs no Xero or Seazona calls.
+
+| Do this | Command |
+| --- | --- |
+| Compare all prices | `flow.sh get invoicing/price-list` |
+| Flow codes only | `flow.sh get 'invoicing/price-items?q=<text>'` |
+| Change a Flow price | `flow.sh put invoicing/price-items/<id> '{"unitAmountCents":13500}'` (also `name`, `taxCode` GST or GST_FREE) |
+| Add a Flow code | `flow.sh post invoicing/price-items '{"code":"...","name":"...","unitAmountCents":13500,"taxCode":"GST"}'` |
+| Link records to codes | `flow.sh post invoicing/price-links '{"links":[{"priceItemId":"<id>","system":"xero","externalId":"<id>"}]}'` |
+| Remove a link | `flow.sh delete invoicing/price-links/<link id>` |
+| Accept a difference | `flow.sh post invoicing/price-items/<id>/resolve` |
+| Lines that wait for a code | `flow.sh get invoicing/line-labels` (rows with `unmapped` above 0) |
+| Give a line its code | `flow.sh post invoicing/line-mappings '{"kind":"saved","label":"<label>","unitAmountCents":<label price>,"itemCode":"<Flow code>"}'` |
+| Saved code choices | `flow.sh get invoicing/line-mappings`; change `put invoicing/line-mappings/<id>`, remove `delete invoicing/line-mappings/<id>` |
+
+How to read `price-list`:
+
+- `systems`: each connected list (`xero`, `seazona`), its record count and
+  `syncedAt`. An old `syncedAt` means Flow's copy can be behind.
+- `items`: each Flow code with its `links` (the linked Xero item or Seazona
+  product, as `record`) and `findings`. A finding `kind` is `price` (Flow and
+  the other system differ: `flow` and `other` in cents), `tax`, `missing` (the
+  linked record is gone) or `not_linked` (no Xero item for this code).
+- `unlinked`: Xero items and Seazona products that no Flow code has yet.
+
+Reconcile steps:
+
+1. Read `price-list` and `line-labels`. Show the person one table: each code
+   with the Flow, Xero and Seazona price, what differs, and each line label
+   that waits.
+2. For each difference, ask which price is right. Do not guess.
+3. When the person says yes, fix it in the right place:
+   - Flow price or code: the Flow commands above.
+   - Xero item: your own `xero` command (Flow never changes a Xero item).
+     Then refresh Flow's copy of Xero items and contacts:
+     `flow.sh post xero/sync '{"organisationId":"<org>"}'`.
+   - Seazona product: read only. Tell the person to change it in Seazona.
+   - A record that is the same thing as a code but has no link: link it.
+   - A difference that is correct (for example a Seazona product at $0):
+     accept it with `resolve`.
+4. Waiting lines: match each label to a code by name and price, show the
+   person the pairs, and save each pair they agree with as a line mapping.
+   The `label` and `unitAmountCents` come from that `line-labels` row. Jobs
+   with that line move on at the next Flow sync (a few minutes).
+5. Read `price-list` and `line-labels` again and show what is left.
+
+Every change on this list (price, code, link, resolve, line mapping) needs
+the person's yes in the chat first, like a send.
+
+## Seazona (read only)
+
+Flow reads Seazona for you with its own Seazona connection, so you need no
+Seazona password. Calls share Seazona's limit of 30 a minute with Flow's
+sync: make few calls, and never loop over many records.
+
+| Do this | Command |
+| --- | --- |
+| Orders on one day | `flow.sh get 'seazona/api/orders/?ordered=2026-11-11T00:00:00&page=1&pageSize=50'` |
+| One order | `flow.sh get seazona/api/orders/<order id>` |
+| Invoices changed since | `flow.sh get 'seazona/api/invoices/?lastModified=2026-11-01T00:00:00'` |
+| Clients changed since | `flow.sh get 'seazona/api/clients/?lastModified=2026-11-01T00:00:00'` |
+| Products, users | `flow.sh get seazona/api/products/`, `flow.sh get seazona/api/users/` |
+
+Answers are `{ "ok": true, "data": ... }`, as Seazona gives them. If the owner
+turned on "Hide patient details", patient, note, file and clinical fields are
+left out. Do not copy patient names outside this chat. 429: wait a
+minute and try once more.
+
+## Reconcile: Seazona jobs, Flow invoices, Xero
+
+When the person says "reconcile", "tidy up" or "why is this job not
+invoiced", work in this order. Read first, show the person what you found in
+short groups, then act on the group they confirm.
+
+1. **Jobs against Flow invoices.** `flow.sh get invoicing/reconcile` lists
+   jobs with no invoice and invoices with no job. For one row:
+   `flow.sh get invoicing/jobs/<job id>/reconcile` or
+   `flow.sh get invoicing/invoices/<id>/reconcile` (each lists the likely other
+   side; `best: true` is the top guess).
+   - Link a job to its invoice: `flow.sh post invoicing/jobs/<job id>/link '{"invoiceId":"<id>"}'`
+   - Job needs no invoice: `flow.sh post invoicing/jobs/<job id>/no-invoice`
+   - Make the invoice now: `flow.sh post invoicing/jobs/<job id>/draft`
+   - Read the job again from Seazona: `flow.sh post invoicing/jobs/<job id>/recheck`
+   - **Stuck on a void invoice** (the job shows "Invoice voided", or its Flow
+     invoice is void, and nothing drafts): `flow.sh post invoicing/jobs/<job id>/free '{"reason":"<why, in the person's words>"}'`.
+     The job lets go of the void invoice and goes on hold, so it does not
+     draft by itself. It refuses a live Flow invoice: void that first, only
+     after the person says yes to that invoice
+     (`flow.sh post invoicing/invoices/<id>/void`).
+   - **Held or in review:** `flow.sh get invoicing/jobs/<job id>/activity`
+     shows why. Release it: `flow.sh post invoicing/jobs/<job id>/hold '{"state":"none","reason":"<why>"}'`;
+     hold it: `'{"state":"held","reason":"<why>"}'` (or `"review"`).
+     A `history_import` hold is refused here: use the history import decisions.
+2. **Flow against Xero.** First get the lab id:
+   `flow.sh get invoicing/context` (`organisations[0].id`, below `<org>`).
+   - Refresh Flow's copy of Xero: `flow.sh post xero/mirror '{"organisationId":"<org>"}'`
+   - Xero invoices against Flow's: `flow.sh get 'xero/import?organisationId=<org>&show=check'`
+     (show: `check`, `linked`, `invoice_fits`, `job_fits`, `none`, `all`)
+   - Match them all again: `flow.sh post xero/import/match '{"organisationId":"<org>"}'`
+   - Link one Xero invoice to a Flow invoice: `flow.sh post xero/import/<xero invoice id>/link '{"organisationId":"<org>","invoiceId":"<id>"}'`
+   - Make the Flow invoice for one Xero invoice: `flow.sh post xero/import/<xero invoice id>/make '{"organisationId":"<org>","jobId":"<job id or null>"}'`
+   - Xero's state of some Flow invoices: `flow.sh post xero/invoices/status '{"organisationId":"<org>","invoiceIds":["<id>"]}'`
+   - Re-check one invoice after a fix in Xero: `flow.sh post xero/invoices/<id>/recheck '{"organisationId":"<org>"}'`
+   - Contacts: `flow.sh get 'xero/contacts/match?organisationId=<org>&contactId=<Flow contact id>'`; link to a Xero contact of another name: `flow.sh post xero/contacts/link '{"organisationId":"<org>","contactId":"<id>","xeroContactId":"<id>"}'`
+3. **Fix the cause with a rule.** If many jobs fail the same way, read
+   `invoicing/rule-fields`, propose one rule (`wait` or `skip`), and add it after
+   the person says yes. Line names that map to the wrong product:
+   `flow.sh get invoicing/line-mappings`, then change one with `put
+   invoicing/line-mappings/<id>`. Prices: `flow.sh get invoicing/price-list`.
+4. **Check Seazona itself** for one job with the Seazona read above (one order).
+
+Links, "no invoice", rules and mappings are Flow records only: say what you
+will change and do it after the person's yes. Mirror, match and recheck only
+read Xero. Sending to Xero still goes through `invoicing/invoices/send-ready`.
+
+## Review queue, health and history import
+
+Use these to find gaps in past billing: jobs Flow never saw, jobs held from
+the history import, and days where Seazona, Flow and Xero disagree.
+
+| Do this | Command |
+| --- | --- |
+| Flow health (build, Seazona sync, daily reconcile, history counts) | `flow.sh health` |
+| Open review items | `flow.sh get 'invoicing/review?limit=100'` (also `kind=`, `state=resolved`) |
+| History import state, backfill and batches | `flow.sh get seazona/history` |
+| One batch, or its rows that wait | `flow.sh get 'seazona/history/batches/<id>?outcome=needs_person'` |
+| Held history jobs that need a person | `flow.sh get 'seazona/history/ledger?state=needs_person'` (no state: all) |
+| Decide batch jobs | `flow.sh post seazona/history/batches/<id>/decisions '{"decisions":[{"jobKey":"<key>","decision":"import"}]}'` (`import`, `skip`, or `null` to undo) |
+| Apply a batch (once only) | `flow.sh post seazona/history/batches/<id>/apply` |
+| Read past Seazona days into Flow | `flow.sh post seazona/history/backfill '{"from":"2026-07-01"}'`; stop: `post seazona/history/backfill/stop` |
+| Let one held history job draft | `flow.sh post seazona/history/ledger/<job id>/release` |
+
+How to read them:
+
+- `health`: `integrations[].health.history` counts history jobs and open
+  batches; `reconcile` shows the last daily check, `daysDifferent` and
+  `openItems`; Seazona `missing` lists Seazona records Flow's copy lacks.
+- Review items: `kind` says what differs (for example `reconcile.day`,
+  `job.changed`, `job.source_totals`); `evidence` holds the numbers. An item
+  closes by itself when its cause is fixed, so fix the cause (link, mapping,
+  rule, recheck) and read the list again.
+- History jobs are held with reason `history_import`: they are past work,
+  most already billed. A matched one stays held. Release only a job that the
+  person agrees was never invoiced.
+
+Decisions, apply, backfill and release change Flow records or spend Seazona
+calls: say what you will do and act only after the person's yes. A backfill
+uses the shared Seazona limit a few calls at a time; one at a time only.
+
+## Xero
+
+Xero has its own `xero` command on this Gateway, for anything Flow does not
+cover. Flow's send and the reconcile steps above use Flow's own Xero
+connection, not yours.
+
+## Never
+
+- Never print, paste or send the key file, a Xero token or a callback URL.
+- Never send, void or delete without the person's yes in this chat.
+- Never send a turned-off person's work again without asking: a send stopped as
+  `requester_disabled` means a person turned the assistant off.
+- Never change Flow people, Integrations or owner settings: Flow refuses them.

package/skills/flow/flow.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Flow command for an AI assistant (docs/AGENT_ACCESS.md, "AI assistant key").
+#   flow.sh setup <https://flow url> save this lab's Flow address, make the key
+#                                    once, print only the key's SHA-256
+#   flow.sh get    <path>            GET    <FLOW_URL>/api/<path>
+#   flow.sh post   <path> [json]     POST   with an optional JSON body
+#   flow.sh put    <path> <json>     PUT    with a JSON body
+#   flow.sh delete <path>            DELETE
+#   flow.sh health                   GET <FLOW_URL>/health (public, no key sent)
+#   flow.sh update                   replace this skill with the copy the
+#                                    saved Flow serves (its own release)
+# The key stays in FLOW_AGENT_KEY_FILE (mode 600). It never goes on a command
+# line or into the output.
+set -euo pipefail
+
+KEY_FILE="${FLOW_AGENT_KEY_FILE:-$HOME/.openclaw/credentials/flow-agent-key}"
+URL_FILE="${KEY_FILE}.url"
+
+die() { echo "flow.sh: $*" >&2; exit 2; }
+
+# The key goes only to the Flow address saved at setup (or FLOW_URL). There is
+# no default address, so a key never goes to another lab's Flow.
+flow_url() {
+  local url="${FLOW_URL:-}"
+  [[ -n "$url" || ! -s "$URL_FILE" ]] || url="$(tr -d '\n' < "$URL_FILE")"
+  [[ "$url" =~ ^https://[A-Za-z0-9.-]+(:[0-9]+)?/?$ ]] || die "no Flow address: run flow.sh setup https://<your Flow>"
+  printf '%s' "${url%/}"
+}
+
+setup() {
+  local url="${1:-}"
+  if [[ -n "$url" ]]; then
+    [[ "$url" =~ ^https://[A-Za-z0-9.-]+(:[0-9]+)?/?$ ]] || die "the Flow address must be https://<host>"
+    mkdir -p "$(dirname "$URL_FILE")"
+    printf '%s\n' "${url%/}" > "$URL_FILE"
+  fi
+  echo "Flow address: $(flow_url)"
+  if [[ ! -s "$KEY_FILE" ]]; then
+    mkdir -p "$(dirname "$KEY_FILE")"
+    (umask 077 && openssl rand -hex 32 > "$KEY_FILE")
+  fi
+  chmod 600 "$KEY_FILE"
+  echo "FLOW_AGENT_KEY_SHA256=$(tr -d '\n' < "$KEY_FILE" | sha256sum | cut -d' ' -f1)"
+}
+
+call() {
+  local method="$1" path="${2:-}" body="${3:-}"
+  [[ -n "$path" ]] || die "give a path, for example: get invoicing/invoices?status=ready"
+  [[ -s "$KEY_FILE" ]] || die "no key yet: run flow.sh setup https://<your Flow> first"
+  local args=(-sS -X "$method" -K - -H 'Accept: application/json' -w '\nHTTP %{http_code}\n')
+  if [[ -n "$body" ]]; then args+=(-H 'Content-Type: application/json' --data-binary "$body"); fi
+  printf 'header = "Authorization: Bearer %s"\n' "$(tr -d '\n' < "$KEY_FILE")" \
+    | curl "${args[@]}" "$(flow_url)/api/${path#/}"
+}
+
+# Fetch SKILL.md and flow.sh from the saved Flow, so the skill always matches
+# the release that Flow runs. Both files arrive first, then both replace the
+# old ones; a bad answer changes nothing.
+update() {
+  [[ -s "$KEY_FILE" ]] || die "no key yet: run flow.sh setup https://<your Flow> first"
+  local dir tmp file code
+  dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  tmp="$(mktemp -d "$dir/.update.XXXXXX")"
+  trap "rm -rf '$tmp'" EXIT
+  for file in SKILL.md flow.sh; do
+    code="$(printf 'header = "Authorization: Bearer %s"\n' "$(tr -d '\n' < "$KEY_FILE")" \
+      | curl -sS -K - -o "$tmp/$file" -w '%{http_code}' "$(flow_url)/api/agent-skill/flow/$file")" \
+      || die "could not reach $(flow_url)"
+    [[ "$code" == 200 && -s "$tmp/$file" ]] || die "$file: HTTP $code from $(flow_url); nothing changed"
+  done
+  head -n 1 "$tmp/flow.sh" | grep -q '^#!/usr/bin/env bash' && bash -n "$tmp/flow.sh" \
+    || die "flow.sh from $(flow_url) is not a valid script; nothing changed"
+  grep -q '^name: flow$' "$tmp/SKILL.md" || die "SKILL.md from $(flow_url) is not the flow skill; nothing changed"
+  chmod 755 "$tmp/flow.sh"
+  chmod 644 "$tmp/SKILL.md"
+  mv -f "$tmp/SKILL.md" "$dir/SKILL.md"
+  mv -f "$tmp/flow.sh" "$dir/flow.sh"
+  echo "Skill updated from $(flow_url)"
+}
+
+case "${1:-}" in
+  setup) setup "${2:-}" ;;
+  get) call GET "${2:-}" ;;
+  post) call POST "${2:-}" "${3:-}" ;;
+  put) [[ -n "${3:-}" ]] || die "put needs a JSON body"; call PUT "${2:-}" "$3" ;;
+  delete) call DELETE "${2:-}" ;;
+  health) curl -sS -H 'Accept: application/json' -w '\nHTTP %{http_code}\n' "$(flow_url)/health" ;;
+  update) update ;;
+  *) sed -n '2,12p' "$0"; exit 2 ;;
+esac