aba-payway-journal

Files (1)

• SKILL.md

SKILL.md (first lines)

# Transaction Journal

CLI default-on / SDK opt-in, append-only JSONL record of every PayWay API exchange, command, poll,
observed status, artifact, and webhook capture. This is the AI/agent query
layer over that record — read-only, never a source of payment truth.

## Quick Start

For onboarding, start with [first payment](../aba-payway-first-payment/SKILL.md).
Use the shared lifecycle: `created`, `pending`, `approved`, `failed`, `unknown`.
Creation is not approval. Verify order ID, amount, and currency before fulfilling once.
A timeout means unknown; query the existing attempt before replacing it.
Expiry and closure remain local policy, even when the gateway reads PENDING.
See [webhook production](../aba-payway-webhook-production/SKILL.md) for callback trust and recovery.
Run the installed CLI as `npm exec -- payway-sdk`.


```sh
# API commands record by default (command lifecycle + every API exchange)
payway-sdk generate-qr -a 5.00 -c USD --no-polling -y

# Reconstruct what happened to one transaction
payway-sdk journal timeline -t qrmt8onznj46fdc1 --json

# Provider latency, retry rate, error codes, creation funnel
payway-sdk journal stats

# Which creations never received a callback?
payway-sdk journal reconcile --json
```

```ts
// Library access (all exported from aba-payway-ts) — read-only queries:
import {
  computeJournalStats,
  detectJournalAnomalies,
  explainTransaction,
  reconcileTransactions,
} from 'aba-payway-ts';

const rca = explainTransaction('qrmt8onznj46fdc1');   // verdict + steps + hints
const stats = computeJournalStats();                  // latency p50/p90/p99, funnel
const report = reconcileTransactions();               // without-callback bucket
```

## Retention (opt-in maintenance — destructive, separate from queries)

Pruning DELETES journal lines older than the given age. It is never part of an
investigation; run it only as a deliberate retention policy:

```ts
import { pruneJournal } from 'aba-payway-ts';
pruneJournal(new Date(Date.now() - 30 * 86_400_000)); // drop events older than 30 days
```
```sh
payway-sdk journal prune --before 30    # same, via CLI
```

## Recording defaults and location

- CLI API commands record by default. Use `--no-journal` or falsy
  `PAYWAY_JOURNAL=0|false|no|off` to disable. Pure-local docs/journal/doctor
  commands are exempt; `--journal` explicitly enables an invocation.
- Persistent: `PAYWAY_JOURNAL=1` (+ optional `PAYWAY_JOURNAL_DIR`,
  `PAYWAY_JOURNAL_MODE=digest|full`, `PAYWAY_JOURNAL_MAX_AGE_DAYS` retention), or SDK
  config `journal: true | {dir, mode, maxAgeDays}`.
- `--json` success envelopes carry `correlationId`/`traceId` — grep them in the
  journal to reconstruct the exact exchange. Create commands warn when the
  journal already holds the same tran_id (`--allow-duplicate-id` to suppress).
- SDK library default OFF: enable with the configuration above.
- File: `<data root>/journal.jsonl`. `PAYWAY_DATA_DIR` overrides the shared
  root; otherwise it is `<APPDATA|~/.config>/aba-payway-sdk/data`.
  An explicit journal directory or `PAYWAY_JOURNAL_DIR` overrides that root
  for the journal. Run `payway-sdk doctor --json` to find `.dataRoot`.
- JSON files are the default backend. Optional `better-sqlite3` selects a
  shared `<data root>/payway.db` through the storage facade;
  `PAYWAY_FORCE_JSON_STORAGE=1` forces JSON. See `payway-sdk docs storage-service`.
- `digest` mode (default) stores allow-listed non-secret fields only — no
  hash, no merchant_auth, no pwt, no QR base64, no PII. `full` mode adds
  sanitizeForLog-redacted bodies, size-capped.

## Agent Tool

The agent CLI exposes a read-only `query_journal` tool (planner-listed,
never gated): `query: timeline` (requires `transactionId`; returns the
reconstructed steps + verdict + hints), `stats`, `reconcile`, `anomalies`.
Ask the agent "what happened to transaction X" and it answers from the
journal when recording was on.

## Commands

| Command | Purpose |
| --- | --- |
| `journal show` | Recent events, filter by `--kind` / `--tran`, `--last N` |
| `journal timeline -t <id>` | Chronological history of one transaction |
| `journal stats` | Latency percentiles, retry rate, top errors, funnel |
| `journal reconcile` | Creations vs webhook captures (without-callback bucket) |
| `journal explain -t <id>` | Root-cause narrative + hints |
| `journal anomalies` | Error spikes, retry bursts, latency outliers (heuristics listed in output) |
| `journal prune --before 30` | Retention (days or ISO timestamp) |
| `journal timeline --with-webhooks` | Callback steps enriched with the persisted signature verdict / matched status / replay marker |
| `agent ledger prune --before 30` | Ledger retention — FINISHED records only; unfinished are never removed |

## Error Handling

- **A missing callback is NOT proof of non-payment.** PayWay never retries
  missed deliveries; re-check with `check-transaction` before acting.
- **PENDING is not alive.** Expired and closed transactions read PENDING
  forever (no EXPIRED/CLOSED status exists remotely) — keep a local flag.
- **Unpaid QR-only transactions never appear in `transaction-list`** —
  reconcile/poll with check-transaction per transaction instead.
- The journal only knows what was recorded while it was on; empty results
  mean "not journaled", not "never happened".
- Journal write failures never break SDK calls (fail-open); malformed lines
  are skipped by readers and counted in reports.
- `journal prune` never destroys lines it cannot parse.

From Ruzaid-aman/ABA-Payway-SDK-unofficial, MIT.

More from Ruzaid-aman/ABA-Payway-SDK-unofficial