@khalido/home 0.0.0-stage → 0.1.1

package/src/connectors/up/index.ts

@@ -0,0 +1,370 @@
+import { z } from "zod";
+import { asOf, type Clock, realClock } from "../../clock.ts";
+import { errorText } from "../../connector.ts";
+import { envName, type Integration } from "../../home.ts";
+import type { Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import {
+  type Category,
+  type Transaction,
+  type TransactionQuery,
+  type UpClient,
+  upClient,
+  UpError,
+} from "./client.ts";
+import {
+  anomalies,
+  dollars,
+  type Household,
+  inHousehold,
+  isSpend,
+  type MerchantSpend,
+  type SpendSummary,
+  spendByCategory,
+  spendByMerchant,
+  uncategorised,
+  unknownCategories,
+} from "./spend.ts";
+
+export {
+  type Account,
+  type Category,
+  type Transaction,
+  type TransactionQuery,
+  type UpClient,
+  upClient,
+  UpError,
+  type Webhook,
+  type WebhookLog,
+} from "./client.ts";
+export {
+  type CategorySpend,
+  dollars,
+  type Household,
+  inHousehold,
+  isSpend,
+  merchantKey,
+  type MerchantSpend,
+  notSpend,
+  type Recurring,
+  recurring,
+  type SpendSummary,
+  spendByCategory,
+  spendByMerchant,
+  uncategorised,
+  type Unusual,
+  unusual,
+  type Window,
+} from "./spend.ts";
+export {
+  parseWebhookEvent,
+  SIGNATURE_HEADER,
+  verifyWebhook,
+  type WebhookEvent,
+} from "./webhook.ts";
+
+/** Poll every 15 minutes: spending moves slowly, and a webhook can nudge a read sooner. */
+export const POLL_MS = 15 * 60_000;
+
+const ACCOUNT_TYPES = ["TRANSACTIONAL", "SAVER", "HOME_LOAN"] as const;
+const OWNERSHIP_TYPES = ["INDIVIDUAL", "JOINT"] as const;
+
+/** Which accounts to read: by type and ownership, never by id (e.g. the joint everyday account). All of them when left out. */
+const AccountFilter = z.object({
+  accountType: z.enum(ACCOUNT_TYPES).optional(),
+  ownershipType: z.enum(OWNERSHIP_TYPES).optional(),
+});
+export type AccountFilter = z.infer<typeof AccountFilter>;
+
+/** Up in a home config: the token's env name, and which accounts count as the household's. */
+export const configSchema = z.looseObject({
+  connector: z.literal("up"),
+  key: envName.describe("env name holding the Up personal access token"),
+  account: AccountFilter.optional().describe(
+    "which accounts to read, by type and ownership; every account when left out",
+  ),
+  household: z
+    .object({
+      categories: z.array(z.string()).optional(),
+      tags: z.array(z.string()).optional(),
+    })
+    .optional()
+    .describe(
+      "what counts as the household's: Up category ids (a parent takes in its children, e.g. home) and tag labels; everything when left out",
+    ),
+});
+
+export type UpConfig = {
+  token: string;
+  account?: AccountFilter;
+  household?: Household;
+  fetch: typeof fetch;
+  clock?: Clock;
+  timeZone?: string;
+}; // timeZone: where a month starts (IANA), the runtime's by default
+
+/** One month's spend: Up's figures through `spendByCategory`, plus the top merchants. */
+export type MonthSpend = SpendSummary & {
+  month: string;
+  topMerchants: MerchantSpend[];
+}; // month: "2026-10" in the home's zone
+
+/** A transaction as the snapshot keeps it: no raw text, message, note, who spent, account or balance. */
+export type RecentTransaction = Pick<
+  Transaction,
+  | "id"
+  | "createdAt"
+  | "description"
+  | "amountCents"
+  | "categoryId"
+  | "parentCategoryId"
+  | "status"
+  | "tags"
+>;
+
+export type UpSnapshot = {
+  asOf: string;
+  thisMonth: MonthSpend; // month to date
+  lastMonth: MonthSpend;
+  uncategorised: string[]; // ids of spend, both months, with no category yet
+  recent: RecentTransaction[]; // the latest 20 purchases: movements between your own accounts would name them
+  accounts: number; // how many accounts the filter matched; 0 without a filter (every account)
+  household?: Household; // what the totals and recent rows count; everything when absent
+  truncated: boolean; // the read stopped at its page cap: totals are short
+};
+
+/** Transactions from the accounts a filter names (every account without one), newest first. The one read the integration and `home up` share. */
+export async function readTransactions(
+  client: UpClient,
+  account: AccountFilter | undefined,
+  query: TransactionQuery = {},
+  signal?: AbortSignal,
+) {
+  const accounts = account ? await client.accounts(account, signal) : undefined;
+  if (accounts && !accounts.length)
+    throw new UpError(
+      `no Up account is ${[account!.ownershipType, account!.accountType].filter(Boolean).join(" ").toLowerCase()}`,
+    );
+  const reads = await Promise.all(
+    (accounts ?? [undefined]).map((a) =>
+      client.transactions({ ...query, accountId: a?.id }, signal),
+    ),
+  );
+  const transactions = reads
+    .flatMap((r) => r.transactions)
+    .sort((a, b) => ((a.createdAt ?? "") < (b.createdAt ?? "") ? 1 : -1));
+  return {
+    transactions,
+    truncated: reads.some((r) => r.truncated),
+    accounts: accounts?.length ?? 0,
+  };
+}
+
+/** "2026-10" for each instant, in a time zone. */
+const monthIn = (timeZone?: string) => {
+  const f = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+  });
+  return (ms: number) => f.format(ms).slice(0, 7);
+};
+const monthBefore = (month: string) => {
+  const [y, m] = month.split("-").map(Number) as [number, number];
+  return m === 1 ? `${y - 1}-12` : `${y}-${String(m - 1).padStart(2, "0")}`;
+};
+
+/** The snapshot from two months of transactions: pure, so tests and a consumer's own reads build the same thing. */
+export function toSnapshot(
+  txs: Transaction[],
+  categories: Category[],
+  at: {
+    now: number;
+    asOf: string;
+    timeZone?: string;
+    accounts: number;
+    truncated: boolean;
+    household?: Household;
+  },
+): UpSnapshot {
+  const monthOf = monthIn(at.timeZone);
+  const thisMonth = monthOf(at.now);
+  const lastMonth = monthBefore(thisMonth);
+  const shared = txs.filter((t) => inHousehold(t, at.household));
+  const byMonth = Map.groupBy(shared, (t) =>
+    t.createdAt === undefined ? "" : monthOf(Date.parse(t.createdAt)),
+  );
+  const of = (month: string) => byMonth.get(month) ?? [];
+  const month = (m: string): MonthSpend => ({
+    month: m,
+    ...spendByCategory(of(m), categories),
+    topMerchants: spendByMerchant(of(m)).slice(0, 5),
+  });
+  // To categorise looks at every purchase in the accounts: a category is how one joins the household.
+  const both = txs.filter(
+    (t) =>
+      t.createdAt !== undefined &&
+      [thisMonth, lastMonth].includes(monthOf(Date.parse(t.createdAt))),
+  );
+  return {
+    asOf: at.asOf,
+    thisMonth: month(thisMonth),
+    lastMonth: month(lastMonth),
+    uncategorised: uncategorised(both).map((t) => t.id),
+    recent: shared
+      .filter(isSpend)
+      .slice(0, 20)
+      .map(
+        ({
+          id,
+          createdAt,
+          description,
+          amountCents,
+          categoryId,
+          parentCategoryId,
+          status,
+          tags,
+        }) => ({
+          id,
+          createdAt,
+          description,
+          amountCents,
+          categoryId,
+          parentCategoryId,
+          status,
+          tags,
+        }),
+      ),
+    accounts: at.accounts,
+    household: at.household,
+    truncated: at.truncated,
+  };
+}
+
+/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
+export function up(config: UpConfig): Integration<UpSnapshot, "up"> {
+  const client = upClient(config);
+  const clock = config.clock ?? realClock;
+  const poll = poller(clock);
+  return {
+    name: "up",
+    refresh: poll.nudge,
+    async run(signal, update) {
+      let last: UpSnapshot | undefined;
+      while (!signal.aborted) {
+        try {
+          const now = clock.now();
+          // 63 days back covers all of last month from any day of this one; months are cut in the home's zone below.
+          const since = new Date(now - 63 * 86_400_000).toISOString();
+          const categories = await client.categories(signal);
+          const read = await readTransactions(
+            client,
+            config.account,
+            { since },
+            signal,
+          );
+          last = toSnapshot(read.transactions, categories, {
+            now,
+            asOf: asOf(clock),
+            timeZone: config.timeZone,
+            accounts: read.accounts,
+            truncated: read.truncated,
+            household: config.household,
+          });
+          const odd = [
+            ...anomalies(read.transactions),
+            ...unknownCategories(config.household, categories),
+            last.truncated
+              ? "read stopped at its page cap; totals are short"
+              : "",
+          ].filter(Boolean);
+          update({
+            status: "connected",
+            anomaly: odd.length ? odd.join("; ") : undefined,
+            state: last,
+          });
+        } catch (error) {
+          if (signal.aborted) return; // stopped mid-read: not a failure
+          if (error instanceof UpError && error.status === 401)
+            return update({
+              status: "unavailable",
+              detail: "Up rejected the token",
+              state: last,
+            });
+          update({
+            status: "disconnected",
+            detail: errorText(error),
+            state: last,
+          });
+        }
+        await poll.wait(POLL_MS, signal);
+      }
+    },
+  };
+}
+
+const MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
+const monthName = (month: string) =>
+  MONTHS[Number(month.slice(5, 7)) - 1] ?? month;
+
+/** "Oct so far $2,140 · Sep $1,980 · 3 to categorise": this month's spend against last month's. */
+export function upText(s: UpSnapshot): string {
+  return [
+    `${monthName(s.thisMonth.month)} so far ${dollars(s.thisMonth.cents)}`,
+    `${monthName(s.lastMonth.month)} ${dollars(s.lastMonth.cents)}`,
+    s.uncategorised.length ? `${s.uncategorised.length} to categorise` : "",
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+/** One line per parent category this month, largest five: "home $1,030: groceries $620, utilities $410". */
+export const categoryLines = (m: MonthSpend) =>
+  m.byCategory
+    .slice(0, 5)
+    .map(
+      (p) =>
+        `${p.name ?? p.id} ${dollars(p.cents)}${p.children.length ? `: ${p.children.map((c) => `${(c.name ?? c.id).toLowerCase()} ${dollars(c.cents)}`).join(", ")}` : ""}`,
+    );
+
+export const manifest: Manifest<UpSnapshot> = {
+  name: "up",
+  title: "Up Bank",
+  iotClass: "cloud_polling",
+  pollSeconds: POLL_MS / 1000,
+  access: "cloud HTTPS, UP_TOKEN; reads only, writes are `home up` verbs",
+  env: [
+    {
+      name: "UP_TOKEN",
+      example: "up:yeah:xxxxxxxx",
+      what: "Up personal access token (api.up.com.au/getting_started)",
+    },
+    {
+      name: "UP_ACCOUNT",
+      example: "JOINT TRANSACTIONAL",
+      optional: true,
+      what: "which accounts count, by ownership and type; every account when unset",
+    },
+    {
+      name: "UP_HOUSEHOLD",
+      example: "home tag:home",
+      optional: true,
+      what: "what counts as the household's: Up category ids and tag:labels; everything when unset",
+    },
+  ],
+  lines: ({ state }) =>
+    state ? [upText(state), ...categoryLines(state.thisMonth)] : [],
+};

package/src/connectors/up/spend.ts

@@ -0,0 +1,280 @@
+import type { Category, Transaction } from "./client.ts";
+
+// Pure helpers over transactions, one owner per number. Amounts are cents; spend is reported as a positive number.
+
+/**
+ * Up's own movements between your accounts that carry no `transferAccount` (unconfirmed: matched by description, the
+ * way up-finance-skills does). Most movements do carry it and are caught by that field.
+ */
+const OWN_MOVEMENT = [
+  /^cover from /i,
+  /^forward to /i,
+  /^round up\b/i,
+  /^quick save transfer/i,
+]; // not "Transfer to …": paying someone else is spend
+
+/** Why a transaction is not spend, or undefined when it is. The one place the rule lives. */
+export function notSpend(t: Transaction): string | undefined {
+  if (t.status !== "SETTLED") return "held";
+  if (t.amountCents === undefined) return "no amount";
+  if (t.amountCents >= 0) return "money in";
+  if (t.transferAccountId) return "transfer between your accounts";
+  if (t.description && OWN_MOVEMENT.some((r) => r.test(t.description!)))
+    return "cover, forward or round-up";
+  return undefined;
+}
+
+/** Settled money out to someone else: not held, not a transfer, cover, forward or round-up between your own accounts. */
+export const isSpend = (t: Transaction) => notSpend(t) === undefined;
+
+/** Money spent, as a positive number of cents. */
+const spent = (t: Transaction) => -(t.amountCents ?? 0);
+
+/** A window of time by the transaction's creation, `[since, until)` as ISO strings; either end open. */
+export type Window = { since?: string; until?: string };
+const inWindow = (t: Transaction, w: Window = {}) => {
+  if (!w.since && !w.until) return true;
+  const at = Date.parse(t.createdAt ?? ""); // Up's times carry an offset (+11:00); compare instants, not text
+  return (
+    (!w.since || at >= Date.parse(w.since)) &&
+    (!w.until || at < Date.parse(w.until))
+  );
+};
+
+/** Money out that the rule leaves out (a transfer, cover, forward or round-up), counted so a total can be checked. */
+const MOVED = new Set([
+  "transfer between your accounts",
+  "cover, forward or round-up",
+]);
+
+export type CategorySpend = {
+  id: string;
+  name?: string;
+  cents: number;
+  count: number;
+  children: { id: string; name?: string; cents: number; count: number }[];
+};
+export type SpendSummary = {
+  cents: number; // spend in the window
+  count: number;
+  excluded: { count: number; cents: number }; // money out that is not spend (transfers, covers, round-ups), so the total can be checked
+  uncategorisedCents: number;
+  byCategory: CategorySpend[]; // parents, largest first, each with its children
+};
+
+/** Spend in a window grouped by Up's parent and child categories, with what was excluded counted and summed. */
+export function spendByCategory(
+  txs: Transaction[],
+  categories: Category[],
+  window?: Window,
+): SpendSummary {
+  const name = new Map(categories.map((c) => [c.id, c.name]));
+  const parentOf = new Map(categories.map((c) => [c.id, c.parentId]));
+  const parents = new Map<string, CategorySpend>();
+  const summary: SpendSummary = {
+    cents: 0,
+    count: 0,
+    excluded: { count: 0, cents: 0 },
+    uncategorisedCents: 0,
+    byCategory: [],
+  };
+  for (const t of txs) {
+    if (!inWindow(t, window)) continue;
+    const why = notSpend(t);
+    if (why) {
+      if (MOVED.has(why))
+        (summary.excluded.count++, (summary.excluded.cents += spent(t)));
+      continue;
+    }
+    summary.cents += spent(t);
+    summary.count++;
+    if (!t.categoryId) {
+      summary.uncategorisedCents += spent(t);
+      continue;
+    }
+    const parentId =
+      t.parentCategoryId ?? parentOf.get(t.categoryId) ?? t.categoryId;
+    const p = parents.get(parentId) ?? {
+      id: parentId,
+      name: name.get(parentId),
+      cents: 0,
+      count: 0,
+      children: [],
+    };
+    parents.set(parentId, p);
+    p.cents += spent(t);
+    p.count++;
+    if (t.categoryId !== parentId) {
+      let c = p.children.find((x) => x.id === t.categoryId);
+      if (!c)
+        p.children.push(
+          (c = {
+            id: t.categoryId,
+            name: name.get(t.categoryId),
+            cents: 0,
+            count: 0,
+          }),
+        );
+      c.cents += spent(t);
+      c.count++;
+    }
+  }
+  summary.byCategory = [...parents.values()].sort((a, b) => b.cents - a.cents);
+  for (const p of summary.byCategory)
+    p.children.sort((a, b) => b.cents - a.cents);
+  return summary;
+}
+
+/** A merchant's name as grouped: lower case, digits and punctuation dropped ("WOOLWORTHS 1234" and "Woolworths" are one); a name with no letters stays itself. */
+export const merchantKey = (description = "") =>
+  description
+    .toLowerCase()
+    .replace(/[^\p{L} ]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim() || description;
+
+export type MerchantSpend = { merchant: string; cents: number; count: number };
+
+/** Spend per merchant, largest first; the merchant shown as its latest description. */
+export function spendByMerchant(
+  txs: Transaction[],
+  window?: Window,
+): MerchantSpend[] {
+  const by = new Map<string, MerchantSpend>();
+  for (const t of txs) {
+    if (!inWindow(t, window) || !isSpend(t)) continue;
+    const key = merchantKey(t.description);
+    const m = by.get(key) ?? {
+      merchant: t.description ?? "?",
+      cents: 0,
+      count: 0,
+    };
+    by.set(key, m);
+    m.cents += spent(t);
+    m.count++;
+  }
+  return [...by.values()].sort((a, b) => b.cents - a.cents);
+}
+
+/** What the household shares: Up category ids (a parent takes in its children) and tag labels. */
+export type Household = { categories?: string[]; tags?: string[] };
+
+/** The one rule for what counts as the household's: a listed category or its parent, or a listed tag. Everything counts without a list. */
+export function inHousehold(t: Transaction, h: Household | undefined): boolean {
+  if (!h?.categories?.length && !h?.tags?.length) return true;
+  const byCategory =
+    h.categories?.some((c) => c === t.categoryId || c === t.parentCategoryId) ??
+    false;
+  return byCategory || (t.tags?.some((tag) => h.tags?.includes(tag)) ?? false);
+}
+
+/** Household categories Up does not have, said in words: a typo would otherwise count nothing, silently. */
+export const unknownCategories = (
+  h: Household | undefined,
+  categories: Category[],
+) =>
+  (h?.categories ?? [])
+    .filter((c) => !categories.some((k) => k.id === c))
+    .map((c) => `household category ${c} is not an Up category`);
+
+/** Spend Up lets you categorise that has no category yet. Money in (salary, a payment received) is categorisable too, but is not spend. */
+export const uncategorised = (txs: Transaction[]) =>
+  txs.filter((t) => t.isCategorizable && !t.categoryId && isSpend(t));
+
+const median = (xs: number[]) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+};
+
+export type Recurring = {
+  merchant: string;
+  months: number;
+  medianCents: number;
+  lastAt?: string;
+};
+
+/**
+ * A heuristic, since Up has no subscription endpoint: the same merchant in three or more distinct months, every amount
+ * within 20% of that merchant's median.
+ */
+export function recurring(txs: Transaction[], timeZone?: string): Recurring[] {
+  const month = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+  });
+  const by = new Map<string, Transaction[]>();
+  for (const t of txs) {
+    if (!isSpend(t) || !t.createdAt) continue;
+    const key = merchantKey(t.description);
+    by.set(key, [...(by.get(key) ?? []), t]);
+  }
+  const out: Recurring[] = [];
+  for (const list of by.values()) {
+    const months = new Set(
+      list.map((t) => month.format(new Date(t.createdAt!))),
+    );
+    if (months.size < 3) continue;
+    const mid = median(list.map(spent));
+    if (!list.every((t) => Math.abs(spent(t) - mid) <= mid * 0.2)) continue;
+    const latest = list.reduce((a, b) => (a.createdAt! > b.createdAt! ? a : b));
+    out.push({
+      merchant: latest.description ?? "?",
+      months: months.size,
+      medianCents: mid,
+      lastAt: latest.createdAt,
+    });
+  }
+  return out.sort((a, b) => b.medianCents - a.medianCents);
+}
+
+export type Unusual = {
+  id: string;
+  merchant: string;
+  cents: number;
+  medianCents: number;
+  at?: string;
+};
+
+/** Spend well above that merchant's usual: more than twice the median of at least three earlier purchases there. */
+export function unusual(txs: Transaction[]): Unusual[] {
+  const sorted = txs
+    .filter((t) => isSpend(t) && t.createdAt)
+    .sort((a, b) => (a.createdAt! < b.createdAt! ? -1 : 1));
+  const seen = new Map<string, number[]>();
+  const out: Unusual[] = [];
+  for (const t of sorted) {
+    const key = merchantKey(t.description);
+    const prior = seen.get(key) ?? [];
+    if (prior.length >= 3) {
+      const mid = median(prior);
+      if (spent(t) > 2 * mid)
+        out.push({
+          id: t.id,
+          merchant: t.description ?? "?",
+          cents: spent(t),
+          medianCents: mid,
+          at: t.createdAt,
+        });
+    }
+    seen.set(key, [...prior, spent(t)]);
+  }
+  return out;
+}
+
+/** Readings that look wrong, said in words: never fixed here. */
+export function anomalies(txs: Transaction[]): string[] {
+  const out: string[] = [];
+  const noAmount = txs.filter((t) => t.amountCents === undefined).length;
+  if (noAmount) out.push(`${noAmount} transaction(s) without an amount`);
+  const foreign = txs.filter(
+    (t) => t.currency !== undefined && t.currency !== "AUD",
+  ).length;
+  if (foreign) out.push(`${foreign} transaction(s) not in AUD`);
+  return out;
+}
+
+/** Cents as dollars for reading: "$1,234" (whole dollars) or "$12.50". Display only. */
+export const dollars = (cents: number, whole = true) =>
+  `${cents < 0 ? "-" : ""}$${(Math.abs(cents) / 100).toLocaleString("en-AU", { minimumFractionDigits: whole ? 0 : 2, maximumFractionDigits: whole ? 0 : 2 })}`;

package/src/connectors/up/webhook.ts

@@ -0,0 +1,62 @@
+// Receiving Up's webhooks is the consumer's job (it needs a public URL); these two pure functions are all it needs from
+// here. The handler: verify, parse, then `home.refresh("up")`. Web Crypto only, so it runs on Bun, Node and workers.
+
+/** The header Up signs each event with: the SHA-256 HMAC of the raw body under the webhook's `secretKey`, hex. */
+export const SIGNATURE_HEADER = "X-Up-Authenticity-Signature";
+
+const hex = (bytes: ArrayBuffer) =>
+  [...new Uint8Array(bytes)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+
+/** True when `signature` (the header's value) is the HMAC of `rawBody` under `secret`. Compares in constant time. */
+export async function verifyWebhook(
+  rawBody: string | Uint8Array,
+  signature: string | null | undefined,
+  secret: string,
+): Promise<boolean> {
+  if (!signature) return false;
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const body = typeof rawBody === "string" ? enc.encode(rawBody) : rawBody;
+  const want = hex(
+    await crypto.subtle.sign("HMAC", key, body as Uint8Array<ArrayBuffer>),
+  );
+  const got = signature.trim().toLowerCase();
+  let diff = want.length ^ got.length;
+  for (let i = 0; i < want.length; i++)
+    diff |= want.charCodeAt(i) ^ (got.charCodeAt(i) || 0);
+  return diff === 0;
+}
+
+/** One webhook event: its type ("TRANSACTION_CREATED", "TRANSACTION_SETTLED", "TRANSACTION_DELETED", "PING") and the transaction it names. */
+export type WebhookEvent = {
+  id?: string;
+  type?: string;
+  createdAt?: string;
+  transactionId?: string;
+};
+
+/** The event in a webhook body. Fields Up leaves out stay undefined; a body that is not JSON throws. */
+export function parseWebhookEvent(body: unknown): WebhookEvent {
+  const json = (typeof body === "string" ? JSON.parse(body) : body) as {
+    data?: {
+      id?: string;
+      attributes?: { eventType?: string; createdAt?: string };
+      relationships?: { transaction?: { data?: { id?: string } } };
+    };
+  };
+  const d = json?.data;
+  return {
+    id: d?.id,
+    type: d?.attributes?.eventType,
+    createdAt: d?.attributes?.createdAt,
+    transactionId: d?.relationships?.transaction?.data?.id,
+  };
+}