@pellux/goodvibes-daemon 1.28.19 → 1.28.21

package/src/daemon/handlers/payments/notifier.ts

@@ -0,0 +1,112 @@
+/**
+ * notifier.ts, sending a purchase notice over this daemon's channels.
+ *
+ * `createChannelPaymentNotifier` (platform/payments/notice-delivery.ts) wants
+ * a router, a target per configured channel, and a `PaymentReplySource`. The
+ * first two are real: `payments.notifyChannels` names which
+ * `CommandAuthorityChannel`s to notify, and delivery goes out over this
+ * daemon's own `ChannelDeliveryRouter`, the SAME router every other channel
+ * send in this daemon uses (see services.ts's comment on why there is exactly
+ * one).
+ *
+ * ── What is deliberately NOT wired in this pass ───────────────────────────
+ *
+ * `PaymentReplySource.waitForAnswer` always resolves `null`. That is not a
+ * stub standing in for something broken, it is the documented meaning of
+ * SILENCE (platform/payments/windows.ts): an approval window's silence DENIES
+ * and a veto window's silence PROCEEDS, both already correct, tested behaviors
+ * the decision layer exercises with no reply source at all. What is missing is
+ * the OTHER path, an inbound reply on a channel resolving the window before its
+ * deadline, "approve"/"yes"/"stop" arriving back from wherever the notice went.
+ * Building that needs an inbound-message correlation path this daemon does not
+ * have yet (there is no `payments.*` counterpart to
+ * `tryResolveApprovalReplyFromChannel`/`tryResolveWorkProposalReplyFromChannel`
+ * in `platform/daemon/surface-actions.ts`, which resolve DIFFERENT kinds of
+ * reply against a DIFFERENT store). Wiring it is a distinct, sizeable piece of
+ * work and is left for a later pass, exactly like `describeSubmission` above
+ * it; every purchase in the meantime is decided by budget and by the windows'
+ * own silence rules, with the notice actually reaching the owner's configured
+ * channels.
+ */
+import type { ChannelDeliveryRouter, ChannelDeliveryTarget } from '@pellux/goodvibes-sdk/platform/channels';
+import {
+  createChannelPaymentNotifier,
+  parseCommandAuthorityChannel,
+  readNotifyChannels,
+} from '@pellux/goodvibes-sdk/platform/payments';
+import type {
+  PaymentNotifier,
+  PaymentNoticeRouter,
+  PaymentNoticeTarget,
+  PaymentReplySource,
+  PaymentsConfigReader,
+} from '@pellux/goodvibes-sdk/platform/payments';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils';
+
+const PAYMENTS_NOTICE_JOB_ID = 'payments-notice';
+
+/**
+ * The channel name (`payments.notifyChannels` entry) turned into the router's
+ * own addressing shape. `parseChannelDeliveryTarget` (platform/channels'
+ * internal delivery/types.ts) is not on the published subpath, so this mirrors
+ * its `surface` construction for the plain channel names `readNotifyChannels`
+ * produces (no `kind:address` suffix, `CommandAuthorityChannel` carries none).
+ */
+function surfaceTarget(surfaceKind: string): ChannelDeliveryTarget {
+  return { kind: 'surface', surfaceKind: surfaceKind as ChannelDeliveryTarget['surfaceKind'] };
+}
+
+/** Adapts this daemon's router to the notifier's narrow, opaque-`request` shape. */
+function daemonNoticeRouter(router: Pick<ChannelDeliveryRouter, 'deliver'>): PaymentNoticeRouter {
+  return {
+    deliver: async (request) => {
+      const merged = request as unknown as Record<string, unknown> & { readonly content: string };
+      return router.deliver({
+        target: merged['target'] as ChannelDeliveryTarget,
+        body: merged.content,
+        title: 'Purchase',
+        jobId: PAYMENTS_NOTICE_JOB_ID,
+        runId: `${PAYMENTS_NOTICE_JOB_ID}-${String(Date.now())}`,
+        includeLinks: false,
+      });
+    },
+  };
+}
+
+/** No live reply integration yet; see this module's header for why silence is still correct. */
+const NO_REPLIES: PaymentReplySource = {
+  async waitForAnswer() {
+    return null;
+  },
+};
+
+export function channelBackedPaymentNotifier(
+  config: PaymentsConfigReader,
+  router: Pick<ChannelDeliveryRouter, 'deliver'>,
+): PaymentNotifier {
+  const targets: PaymentNoticeTarget[] = [];
+  for (const name of readNotifyChannels(config)) {
+    const channel = parseCommandAuthorityChannel(name);
+    if (channel === null) {
+      logger.warn('payments.notifyChannels names a channel this daemon does not recognise; it will not be notified', { channel: name });
+      continue;
+    }
+    targets.push({
+      channel,
+      request: { target: surfaceTarget(name) },
+      // No backfill path is wired (see this module's header): a notice missed
+      // while the daemon was down cannot be recovered by re-reading history it
+      // never asked this router to keep.
+      backfillable: false,
+    });
+  }
+
+  return createChannelPaymentNotifier({
+    router: daemonNoticeRouter(router),
+    targets,
+    replies: NO_REPLIES,
+    onDeliveryFailure: ({ channel, reason }) => {
+      logger.warn('A payments notice could not be delivered on a configured channel', { channel, reason });
+    },
+  });
+}

package/src/daemon/handlers/payments/purchase-ledger.ts

@@ -0,0 +1,108 @@
+/**
+ * purchase-ledger.ts, the durable audit ledger behind `payments.purchases.list`.
+ *
+ * The SDK declares `PurchaseLedger` as a one-method write port
+ * (platform/payments/checkout-flow.ts) and ships no implementation, for the same
+ * reason it ships no card store: the flow must be drivable in a test with an
+ * in-memory ledger, so the durable one belongs to whoever actually runs it. This
+ * is that one.
+ *
+ * Append-only by construction. There is no update and no delete: the row is the
+ * evidence a purchase happened, and a ledger a later call can edit is not
+ * evidence of anything. A refund is recorded on the row as `refundedAt` by the
+ * flow that observes it, and credits no pool, see the descriptor.
+ *
+ * ── `merchantDiscovered` ──────────────────────────────────────────────────
+ *
+ * The control-plane view requires it and `PurchaseRecord` does not carry it, so
+ * a row written by a flow that did not state it reads as `false`, "the owner
+ * named this storefront". That is the conservative direction: `true` is the
+ * flag that says a storefront was found while browsing, and inventing it would
+ * put a claim in the audit trail that nothing observed.
+ */
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { atomicWriteFileSync } from '@pellux/goodvibes-sdk/platform/config';
+import type { PurchaseLedger, PurchaseRecord } from '@pellux/goodvibes-sdk/platform/payments';
+
+/** A stored row: the SDK record plus the one view field it does not declare. */
+export interface StoredPurchase extends PurchaseRecord {
+  readonly merchantDiscovered: boolean;
+}
+
+const PURCHASES_FILE_VERSION = 1;
+
+/** Hard ceiling on rows the list verb will hand back in one call. */
+export const MAX_PURCHASE_LIST_LIMIT = 500;
+
+interface PurchasesFile {
+  readonly version: number;
+  readonly purchases: readonly StoredPurchase[];
+}
+
+function readPurchasesFile(filePath: string): StoredPurchase[] {
+  if (!existsSync(filePath)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf-8')) as Partial<PurchasesFile>;
+    return Array.isArray(parsed.purchases) ? [...parsed.purchases] : [];
+  } catch {
+    // A torn ledger file reads as an empty one rather than taking the daemon
+    // down. It is reported as empty, not as an error, because every other verb
+    // on this daemon is unrelated to it and refusing to boot would take them
+    // all with it.
+    return [];
+  }
+}
+
+export interface DaemonPurchaseLedgerOptions {
+  readonly filePath: string;
+}
+
+export interface PurchaseListQuery {
+  readonly limit: number;
+  readonly dayKey: string | undefined;
+}
+
+/**
+ * The daemon's purchase ledger.
+ *
+ * Implements the SDK's `PurchaseLedger` write port, so the checkout flow can be
+ * handed this object unchanged once `payments.checkout.begin` has a page driver
+ * to run against, and adds the read half the `payments.purchases.list` verb needs.
+ */
+export class DaemonPurchaseLedger implements PurchaseLedger {
+  private readonly filePath: string;
+
+  constructor(options: DaemonPurchaseLedgerOptions) {
+    this.filePath = options.filePath;
+  }
+
+  /** Append one purchase. The only write this class performs. */
+  async record(entry: PurchaseRecord): Promise<void> {
+    const discovered = (entry as { merchantDiscovered?: unknown }).merchantDiscovered;
+    const row: StoredPurchase = { ...entry, merchantDiscovered: discovered === true };
+    const rows = [...readPurchasesFile(this.filePath), row];
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    const contents: PurchasesFile = { version: PURCHASES_FILE_VERSION, purchases: rows };
+    atomicWriteFileSync(this.filePath, `${JSON.stringify(contents, null, 2)}\n`, { mode: 0o600 });
+  }
+
+  /**
+   * The most recent purchases first, optionally narrowed to one calendar day.
+   *
+   * `total` is the number of rows matching the FILTER, not the number returned,
+   * so a surface showing 100 of 340 can say so instead of implying there are
+   * only 100.
+   */
+  list(query: PurchaseListQuery): { purchases: readonly StoredPurchase[]; total: number } {
+    const rows = readPurchasesFile(this.filePath);
+    const matching = query.dayKey === undefined
+      ? rows
+      : rows.filter((row) => row.dayKey === query.dayKey);
+    const limit = Math.min(Math.max(1, Math.floor(query.limit)), MAX_PURCHASE_LIST_LIMIT);
+    return {
+      purchases: [...matching].reverse().slice(0, limit),
+      total: matching.length,
+    };
+  }
+}