- StreamPay
-
+
+ StreamPay
+
Payment streaming on Stellar
-
+
Connect your wallet to create and manage payment streams.
diff --git a/package-lock.json b/package-lock.json
index 517eb7d1..7ab9f998 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -4518,6 +4518,7 @@
"integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
"dev": true,
"license": "MIT",
+ "peer": true,
"dependencies": {
"@rtsao/scc": "^1.1.0",
"array-includes": "^3.1.9",
From 9847dea83a108a5d62c3fb6fc5d58d8ae4852bb5 Mon Sep 17 00:00:00 2001
From: Abdul-dev-creator
Date: Mon, 30 Mar 2026 11:26:49 +0100
Subject: [PATCH 009/409] feat: add Card component with padding variants and
clickable states (#18)
---
app/components/Card.test.tsx | 40 ++++++++++++++++++++++++
app/components/Card.tsx | 37 ++++++++++++++++++++++
app/globals.css | 24 +++++++++++++++
app/page.tsx | 59 +++++++++++++++++++++++++++++++-----
package-lock.json | 23 ++++++--------
5 files changed, 162 insertions(+), 21 deletions(-)
create mode 100644 app/components/Card.test.tsx
create mode 100644 app/components/Card.tsx
diff --git a/app/components/Card.test.tsx b/app/components/Card.test.tsx
new file mode 100644
index 00000000..92807e23
--- /dev/null
+++ b/app/components/Card.test.tsx
@@ -0,0 +1,40 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import "@testing-library/jest-dom";
+import { Card } from "./Card";
+
+describe("Card", () => {
+ it("renders children correctly", () => {
+ render(Test Content);
+ expect(screen.getByText("Test Content")).toBeInTheDocument();
+ });
+
+ it("applies padding variant styles correctly", () => {
+ const { container: smContainer } = render(SM);
+ expect(smContainer.firstChild).toHaveStyle({ padding: "0.75rem" });
+
+ const { container: lgContainer } = render(LG);
+ expect(lgContainer.firstChild).toHaveStyle({ padding: "1.5rem" });
+ });
+
+ it("becomes clickable and calls onClick when provided", () => {
+ const handleClick = jest.fn();
+ render(Clickable Card);
+
+ const card = screen.getByText("Clickable Card");
+ expect(card).toHaveClass("card--clickable");
+
+ fireEvent.click(card);
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
+
+ it("has default padding when none provided", () => {
+ const { container } = render(Default);
+ expect(container.firstChild).toHaveStyle({ padding: "1rem" });
+ });
+
+ it("is not clickable when onClick is not provided", () => {
+ render(Static Card);
+ const card = screen.getByText("Static Card");
+ expect(card).not.toHaveClass("card--clickable");
+ });
+});
diff --git a/app/components/Card.tsx b/app/components/Card.tsx
new file mode 100644
index 00000000..74b76cee
--- /dev/null
+++ b/app/components/Card.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+import React, { PropsWithChildren } from "react";
+
+interface CardProps {
+ padding?: "none" | "sm" | "md" | "lg";
+ onClick?: (e: React.MouseEvent) => void;
+ className?: string;
+}
+
+const paddingStyles = {
+ none: "0",
+ sm: "0.75rem",
+ md: "1rem",
+ lg: "1.5rem",
+};
+
+export const Card: React.FC> = ({
+ children,
+ padding = "md",
+ onClick,
+ className = "",
+}) => {
+ const isClickable = !!onClick;
+
+ return (
+
+ {children}
+
+ );
+};
diff --git a/app/globals.css b/app/globals.css
index 80a8edfd..3b132b48 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -3,6 +3,8 @@
--foreground: #e4e4e7;
--accent: #22c55e;
--muted: #71717a;
+ --card-surface: #12121e;
+ --card-border: #27272a;
}
* {
@@ -28,3 +30,25 @@ a {
a:hover {
text-decoration: underline;
}
+
+.card {
+ background-color: var(--card-surface);
+ border: 1px solid var(--card-border);
+ border-radius: 0.75rem;
+ transition: all 0.2s ease-in-out;
+}
+
+.card--clickable {
+ cursor: pointer;
+}
+
+.card--clickable:hover {
+ border-color: var(--accent);
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+
+.card--clickable:active {
+ transform: translateY(0);
+}
+
diff --git a/app/page.tsx b/app/page.tsx
index df5e12ee..9369956c 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,3 +1,7 @@
+"use client";
+
+import { Card } from "./components/Card";
+
export default function Home() {
return (
- StreamPay
-
- Payment streaming on Stellar
-
-
- Connect your wallet to create and manage payment streams.
-
+
+
+
+
+ Stream details summary
+
+
+
+
+ Status
+ Active
+
+
+ Flow rate
+ 10 XLM/day
+
+
+ Total Streamed
+ 45.2 XLM
+
+
+
alert("Card clicked!")}>
+
+ View performance charts →
+
+
+
StreamPay
-
- Payment streaming on Stellar
-
-
- Connect your wallet to create and manage payment streams.
-
-
+ <>
+
+ Skip to main content
+
+
+
+
+
+
+
+
+
Payment streaming on Stellar
+
Move money with the same confidence as the rest of your app.
+
+ Review active payouts, jump between sections with the keyboard,
+ and create a new stream without leaving the page.
+
+
+
+
- Active streams
+ - 12
+
+
+
- Next payout
+ - Today, 18:00 UTC
+
+
+
- Wallet status
+ - Ready to sign
+
+
+
+
+
+
+
+
+
+
Create flow
+
Create a stream
+
+
+ The fields follow the same order as the final review so the tab
+ sequence stays predictable from start to submit.
+
+
+
+
+ setIsOpen(false)}
+ title="Confirm action"
+ description="This action cannot be undone."
+ footer={
+
+ }
+ >
+
+
+
+ );
+}
+
+describe("Modal", () => {
+ it("opens and closes from user actions", () => {
+ render();
+
+ fireEvent.click(screen.getByRole("button", { name: /open modal/i }));
+ expect(screen.getByRole("dialog", { name: /confirm action/i })).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole("button", { name: /close dialog/i }));
+ expect(screen.queryByRole("dialog", { name: /confirm action/i })).not.toBeInTheDocument();
+ });
+
+ it("closes on escape and restores focus to the trigger", async () => {
+ render();
+
+ const trigger = screen.getByRole("button", { name: /open modal/i });
+ trigger.focus();
+
+ fireEvent.click(trigger);
+ expect(screen.getByRole("dialog", { name: /confirm action/i })).toBeInTheDocument();
+
+ fireEvent.keyDown(document, { key: "Escape" });
+
+ await waitFor(() => {
+ expect(screen.queryByRole("dialog", { name: /confirm action/i })).not.toBeInTheDocument();
+ expect(trigger).toHaveFocus();
+ });
+ });
+
+ it("locks background scroll while open", () => {
+ render();
+
+ fireEvent.click(screen.getByRole("button", { name: /open modal/i }));
+ expect(document.body.style.overflow).toBe("hidden");
+
+ fireEvent.click(screen.getByRole("button", { name: /close dialog/i }));
+ expect(document.body.style.overflow).toBe("");
+ });
+});
diff --git a/app/components/Modal.tsx b/app/components/Modal.tsx
new file mode 100644
index 00000000..4f716d74
--- /dev/null
+++ b/app/components/Modal.tsx
@@ -0,0 +1,161 @@
+"use client";
+
+import {
+ type KeyboardEvent as ReactKeyboardEvent,
+ type ReactNode,
+ useEffect,
+ useId,
+ useRef,
+} from "react";
+
+type ModalProps = {
+ isOpen: boolean;
+ onClose: () => void;
+ title?: string;
+ description?: string;
+ ariaLabel?: string;
+ children: ReactNode;
+ footer?: ReactNode;
+};
+
+const FOCUSABLE_SELECTOR = [
+ "a[href]",
+ "button:not([disabled])",
+ "textarea:not([disabled])",
+ "input:not([disabled])",
+ "select:not([disabled])",
+ '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+function getFocusableElements(container: HTMLElement) {
+ return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter(
+ (element) => !element.hasAttribute("disabled") && element.getAttribute("aria-hidden") !== "true",
+ );
+}
+
+export default function Modal({
+ isOpen,
+ onClose,
+ title,
+ description,
+ ariaLabel,
+ children,
+ footer,
+}: ModalProps) {
+ const dialogRef = useRef(null);
+ const triggerRef = useRef(null);
+ const titleId = useId();
+ const descriptionId = useId();
+
+ useEffect(() => {
+ if (!isOpen) {
+ return;
+ }
+
+ triggerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+ const previousOverflow = document.body.style.overflow;
+ document.body.style.overflow = "hidden";
+
+ const focusDialog = () => {
+ if (!dialogRef.current) {
+ return;
+ }
+
+ const [firstFocusable] = getFocusableElements(dialogRef.current);
+ (firstFocusable ?? dialogRef.current).focus();
+ };
+
+ focusDialog();
+
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (event.key === "Escape") {
+ event.preventDefault();
+ onClose();
+ return;
+ }
+
+ if (event.key !== "Tab" || !dialogRef.current) {
+ return;
+ }
+
+ const focusableElements = getFocusableElements(dialogRef.current);
+ if (focusableElements.length === 0) {
+ event.preventDefault();
+ dialogRef.current.focus();
+ return;
+ }
+
+ const firstElement = focusableElements[0];
+ const lastElement = focusableElements[focusableElements.length - 1];
+ const activeElement = document.activeElement;
+
+ if (!event.shiftKey && activeElement === lastElement) {
+ event.preventDefault();
+ firstElement.focus();
+ }
+
+ if (event.shiftKey && activeElement === firstElement) {
+ event.preventDefault();
+ lastElement.focus();
+ }
+ };
+
+ document.addEventListener("keydown", handleKeyDown);
+
+ return () => {
+ document.removeEventListener("keydown", handleKeyDown);
+ document.body.style.overflow = previousOverflow;
+ triggerRef.current?.focus();
+ };
+ }, [isOpen, onClose]);
+
+ const handleBackdropKeyDown = (event: ReactKeyboardEvent) => {
+ if (event.key === "Escape") {
+ event.preventDefault();
+ onClose();
+ }
+ };
+
+ if (!isOpen) {
+ return null;
+ }
+
+ return (
+
+
event.stopPropagation()}
+ onKeyDown={handleBackdropKeyDown}
+ >
+
+
+ {title ? (
+
+ {title}
+
+ ) : null}
+ {description ? (
+
+ {description}
+
+ ) : null}
+
+
+
+
+
{children}
+ {footer ?
{footer}
: null}
+
+
StreamPay
-
- Payment streaming on Stellar
-
-
- Connect your wallet to create and manage payment streams.
-
+
+
+ Stellar stream management
+ StreamPay
+ Payment streaming on Stellar
+
+ Connect your wallet to create, review, and confirm recurring payouts without
+ losing context.
+
+
+
+
+
+
+
+
+ setIsWalletOpen(false)}
+ title="Choose a wallet"
+ description="Select the wallet provider you want to connect to StreamPay."
+ >
+
+ {walletOptions.map((wallet) => (
+
+ ))}
+
+
+
+ setIsConfirmOpen(false)}
+ title="Confirm stream cancellation"
+ description="This stops future payouts for the selected stream."
+ footer={
+ <>
+
+
+
+ }
+ >
+
+ The current recipient will keep funds already settled. Only upcoming payments are affected.
+
+
);
}
From d8ec77a84c366c2a73a79e6527f2fa254a49367c Mon Sep 17 00:00:00 2001
From: Abdul-dev-creator
Date: Mon, 30 Mar 2026 12:44:05 +0100
Subject: [PATCH 012/409] feat: add reduced motion support for skeletons and
modals (#24)
---
app/components/Modal.tsx | 104 ++++++++++++++++++++++++++++++
app/components/Skeleton.tsx | 28 +++++++++
app/globals.css | 46 +++++++++++++-
app/page.tsx | 122 +++++++++++++++++++++++++++++-------
4 files changed, 277 insertions(+), 23 deletions(-)
create mode 100644 app/components/Modal.tsx
create mode 100644 app/components/Skeleton.tsx
diff --git a/app/components/Modal.tsx b/app/components/Modal.tsx
new file mode 100644
index 00000000..383049de
--- /dev/null
+++ b/app/components/Modal.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import React, { PropsWithChildren, useEffect, useState } from "react";
+
+interface ModalProps {
+ isOpen: boolean;
+ onClose: () => void;
+ title: string;
+}
+
+export const Modal: React.FC> = ({
+ isOpen,
+ onClose,
+ title,
+ children,
+}) => {
+ const [shouldRender, setShouldRender] = useState(isOpen);
+
+ useEffect(() => {
+ if (isOpen) setShouldRender(true);
+ }, [isOpen]);
+
+ const handleAnimationEnd = () => {
+ if (!isOpen) setShouldRender(false);
+ };
+
+ if (!shouldRender) return null;
+
+ return (
+
+
e.stopPropagation()}
+ style={{
+ width: "100%",
+ maxWidth: "500px",
+ backgroundColor: "var(--card-surface)",
+ border: "1px solid var(--card-border)",
+ borderRadius: "1rem",
+ padding: "1.5rem",
+ boxShadow: "0 20px 25px -5px rgba(0, 0, 0, 0.5)",
+ animation: `${isOpen ? "scaleIn" : "scaleOut"} var(--motion-duration-medium) var(--motion-easing) forwards`,
+ }}
+ >
+
+ {children}
+
+
+
+
-
-
Status
-
Active
+ {isLoading ? (
+
-
-
Flow rate
-
10 XLM/day
+ ) : (
+
+
+ Status
+ Active
+
+
+ Flow rate
+ 10 XLM/day
+
+
+ Total Streamed
+ 45.2 XLM
+
-
- Total Streamed
- 45.2 XLM
-
-
+ )}
-
-
alert("Card clicked!")}>
+
+
setIsModalOpen(true)}>
View performance charts →
+
+
+
+ Real-time streaming metrics enabled by the Stellar Network.
+
+
+ Chart Preview
+
+
setIsModalOpen(false)} padding="sm">
+ Close
+
+
@@ -32,36 +30,35 @@ describe("Modal", () => {
render(
);
fireEvent.click(screen.getByRole("button", { name: /open modal/i }));
- expect(screen.getByRole("dialog", { name: /confirm action/i })).toBeInTheDocument();
+ expect(screen.getByRole("heading", { name: /confirm action/i })).toBeInTheDocument();
- fireEvent.click(screen.getByRole("button", { name: /close dialog/i }));
- expect(screen.queryByRole("dialog", { name: /confirm action/i })).not.toBeInTheDocument();
+ fireEvent.click(screen.getByRole("button", { name: /×/i }));
+ fireEvent.animationEnd(getOverlay());
+ expect(screen.queryByRole("heading", { name: /confirm action/i })).not.toBeInTheDocument();
});
- it("closes on escape and restores focus to the trigger", async () => {
+ it("closes when clicking backdrop", async () => {
render(
);
- const trigger = screen.getByRole("button", { name: /open modal/i });
- trigger.focus();
-
- fireEvent.click(trigger);
- expect(screen.getByRole("dialog", { name: /confirm action/i })).toBeInTheDocument();
-
- fireEvent.keyDown(document, { key: "Escape" });
+ fireEvent.click(screen.getByRole("button", { name: /open modal/i }));
+ expect(screen.getByRole("heading", { name: /confirm action/i })).toBeInTheDocument();
+ fireEvent.click(getOverlay());
+ fireEvent.animationEnd(getOverlay());
await waitFor(() => {
- expect(screen.queryByRole("dialog", { name: /confirm action/i })).not.toBeInTheDocument();
- expect(trigger).toHaveFocus();
+ expect(screen.queryByRole("heading", { name: /confirm action/i })).not.toBeInTheDocument();
});
});
- it("locks background scroll while open", () => {
+ it("renders children only while open", () => {
render(
);
+ expect(screen.queryByText(/focusable action/i)).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("button", { name: /open modal/i }));
- expect(document.body.style.overflow).toBe("hidden");
+ expect(screen.getByText(/focusable action/i)).toBeInTheDocument();
- fireEvent.click(screen.getByRole("button", { name: /close dialog/i }));
- expect(document.body.style.overflow).toBe("");
+ fireEvent.click(screen.getByRole("button", { name: /×/i }));
+ fireEvent.animationEnd(getOverlay());
+ expect(screen.queryByText(/focusable action/i)).not.toBeInTheDocument();
});
});
diff --git a/app/lib/stream-events.test.ts b/app/lib/stream-events.test.ts
new file mode 100644
index 00000000..5b22855a
--- /dev/null
+++ b/app/lib/stream-events.test.ts
@@ -0,0 +1,424 @@
+import { InMemoryStreamStore, pauseRoute, resumeRoute, type StreamRecord } from "./stream-events";
+
+function createStream(overrides: Partial
= {}): StreamRecord {
+ return {
+ availableBalance: 0n,
+ escrowBalance: 100n,
+ id: "stream-1",
+ lastSettlementAt: 0,
+ status: "active",
+ tenantId: "tenant-a",
+ ...overrides,
+ };
+}
+
+describe("InMemoryStreamStore.applyEvent", () => {
+ it("pauses an active stream", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-1",
+ type: "pause",
+ });
+
+ expect(result.ok).toBe(true);
+ const stream = store.getStream("stream-1");
+ expect(stream?.status).toBe("paused");
+ });
+
+ it("returns 409 for illegal pause transition", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "draft" })]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-2",
+ type: "pause",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(409);
+ expect(result.error.code).toBe("ILLEGAL_TRANSITION");
+ }
+ });
+
+ it("resumes a paused stream", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "paused" })]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-3",
+ type: "resume",
+ });
+
+ expect(result.ok).toBe(true);
+ expect(store.getStream("stream-1")?.status).toBe("active");
+ });
+
+ it("returns 409 for illegal resume transition", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "active" })]);
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-4",
+ type: "resume",
+ });
+
+ const stopResult = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ type: "stop",
+ });
+ expect(stopResult.ok).toBe(true);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-5",
+ type: "resume",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(409);
+ expect(result.error.code).toBe("ILLEGAL_TRANSITION");
+ }
+ });
+
+ it("rejects commands from other tenants", async () => {
+ const store = new InMemoryStreamStore([createStream({ tenantId: "tenant-a" })]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-b",
+ idempotencyKey: "key-6",
+ type: "pause",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(403);
+ expect(result.error.code).toBe("FORBIDDEN");
+ }
+ });
+
+ it("returns 404 for unknown streams", async () => {
+ const store = new InMemoryStreamStore([]);
+
+ const result = await store.applyEvent("unknown", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "key-7",
+ type: "pause",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(404);
+ expect(result.error.code).toBe("NOT_FOUND");
+ }
+
+ expect(store.getStream("unknown")).toBeUndefined();
+ });
+
+ it("supports idempotent pause retries", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const first = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "same-key",
+ type: "pause",
+ });
+
+ const second = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "same-key",
+ type: "pause",
+ });
+
+ expect(first).toEqual(second);
+ expect(store.metrics.pauseAttempts).toBe(2);
+ expect(store.metrics.pauseSuccess).toBe(2);
+ expect(store.getStream("stream-1")?.status).toBe("paused");
+ });
+
+ it("returns 409 when the same idempotency key is reused for a different command", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "active" })]);
+
+ const pause = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "shared-key",
+ type: "pause",
+ });
+ expect(pause.ok).toBe(true);
+
+ const resume = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "shared-key",
+ type: "resume",
+ });
+ expect(resume.ok).toBe(false);
+ if (!resume.ok) {
+ expect(resume.error.httpStatus).toBe(409);
+ expect(resume.error.code).toBe("ILLEGAL_TRANSITION");
+ }
+ expect(store.getStream("stream-1")?.status).toBe("paused");
+ });
+
+ it("settles from escrow into available and enforces non-negative invariants", async () => {
+ const store = new InMemoryStreamStore([createStream({ availableBalance: 1n, escrowBalance: 5n })]);
+
+ const ok = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ at: 99,
+ settleAmount: 5n,
+ type: "settle_tick",
+ });
+
+ expect(ok.ok).toBe(true);
+ const stream = store.getStream("stream-1");
+ expect(stream?.availableBalance).toBe(6n);
+ expect(stream?.escrowBalance).toBe(0n);
+ expect(stream?.lastSettlementAt).toBe(99);
+
+ const insufficient = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ settleAmount: 1n,
+ type: "settle_tick",
+ });
+
+ expect(insufficient.ok).toBe(false);
+ if (!insufficient.ok) {
+ expect(insufficient.error.httpStatus).toBe(409);
+ expect(insufficient.error.code).toBe("INSUFFICIENT_ESCROW");
+ }
+
+ const final = store.getStream("stream-1");
+ expect(final?.availableBalance).toBeGreaterThanOrEqual(0n);
+ expect(final?.escrowBalance).toBeGreaterThanOrEqual(0n);
+ });
+
+ it("rejects settle tick with negative amount", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ settleAmount: -1n,
+ type: "settle_tick",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(400);
+ expect(result.error.code).toBe("INVALID_COMMAND");
+ }
+ });
+
+ it("returns 409 for settle tick on ended streams", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "ended" })]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ settleAmount: 1n,
+ type: "settle_tick",
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(409);
+ expect(result.error.code).toBe("ILLEGAL_TRANSITION");
+ }
+ });
+
+ it("executes concurrent pause + settle atomically without negative balances", async () => {
+ const store = new InMemoryStreamStore([createStream({ availableBalance: 2n, escrowBalance: 10n })]);
+
+ const pausePromise = store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "pause-atomic",
+ processingDelayMs: 20,
+ type: "pause",
+ });
+
+ const settlePromise = store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ at: 77,
+ settleAmount: 4n,
+ type: "settle_tick",
+ });
+
+ const [pauseResult, settleResult] = await Promise.all([pausePromise, settlePromise]);
+ expect(pauseResult.ok).toBe(true);
+ expect(settleResult.ok).toBe(true);
+
+ const final = store.getStream("stream-1");
+ expect(final?.status).toBe("paused");
+ expect(final?.availableBalance).toBeGreaterThanOrEqual(0n);
+ expect(final?.escrowBalance).toBeGreaterThanOrEqual(0n);
+ expect((final?.availableBalance ?? 0n) + (final?.escrowBalance ?? 0n)).toBe(12n);
+ });
+
+ it("executes concurrent resume + stop with exactly one illegal transition", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "paused" })]);
+
+ const resumePromise = store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "resume-atomic",
+ processingDelayMs: 20,
+ type: "resume",
+ });
+
+ const stopPromise = store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ type: "stop",
+ });
+
+ const [resumeResult, stopResult] = await Promise.all([resumePromise, stopPromise]);
+
+ const outcomes = [resumeResult, stopResult].map((item) => (item.ok ? "ok" : item.error.code));
+ expect(outcomes).toContain("ok");
+
+ const final = store.getStream("stream-1");
+ expect(final?.status).toBe("ended");
+
+ const illegalResume = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "resume-illegal",
+ type: "resume",
+ });
+ expect(illegalResume.ok).toBe(false);
+ if (!illegalResume.ok) {
+ expect(illegalResume.error.httpStatus).toBe(409);
+ expect(illegalResume.error.code).toBe("ILLEGAL_TRANSITION");
+ }
+ });
+
+ it("tracks pause and resume metrics including failures", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "active" })]);
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "m1",
+ type: "pause",
+ });
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "m2",
+ type: "pause",
+ });
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "m3",
+ type: "resume",
+ });
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "m4",
+ type: "pause",
+ });
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ type: "stop",
+ });
+
+ await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ idempotencyKey: "m5",
+ type: "resume",
+ });
+
+ expect(store.metrics.pauseAttempts).toBe(3);
+ expect(store.metrics.pauseSuccess).toBe(3);
+ expect(store.metrics.pauseFailures).toBe(0);
+
+ expect(store.metrics.resumeAttempts).toBe(2);
+ expect(store.metrics.resumeSuccess).toBe(1);
+ expect(store.metrics.resumeFailures).toBe(1);
+ });
+
+ it("is idempotent for stop on ended streams", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "ended" })]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ type: "stop",
+ });
+
+ expect(result.ok).toBe(true);
+ expect(store.getStream("stream-1")?.status).toBe("ended");
+ });
+
+ it("returns 400 for unsupported command types", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const result = await store.applyEvent("stream-1", {
+ actorTenantId: "tenant-a",
+ type: "unknown_command" as never,
+ });
+
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.httpStatus).toBe(400);
+ expect(result.error.code).toBe("INVALID_COMMAND");
+ }
+ });
+});
+
+describe("pauseRoute and resumeRoute", () => {
+ it("requires Idempotency-Key for pause and resume", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const pause = await pauseRoute(store, {
+ actorTenantId: "tenant-a",
+ headers: {},
+ streamId: "stream-1",
+ });
+ expect(pause.ok).toBe(false);
+ if (!pause.ok) {
+ expect(pause.error.httpStatus).toBe(400);
+ }
+
+ const resume = await resumeRoute(store, {
+ actorTenantId: "tenant-a",
+ headers: {},
+ streamId: "stream-1",
+ });
+ expect(resume.ok).toBe(false);
+ if (!resume.ok) {
+ expect(resume.error.httpStatus).toBe(400);
+ }
+ });
+
+ it("pipes Idempotency-Key through to command handling", async () => {
+ const store = new InMemoryStreamStore([createStream()]);
+
+ const first = await pauseRoute(store, {
+ actorTenantId: "tenant-a",
+ headers: { "idempotency-key": "route-key" },
+ streamId: "stream-1",
+ });
+ expect(first.ok).toBe(true);
+
+ const second = await pauseRoute(store, {
+ actorTenantId: "tenant-a",
+ headers: { "idempotency-key": "route-key" },
+ streamId: "stream-1",
+ });
+
+ expect(second).toEqual(first);
+ });
+
+ it("resumes through route handler when idempotency key is present", async () => {
+ const store = new InMemoryStreamStore([createStream({ status: "paused" })]);
+
+ const result = await resumeRoute(store, {
+ actorTenantId: "tenant-a",
+ headers: { "idempotency-key": "resume-key" },
+ streamId: "stream-1",
+ });
+
+ expect(result.ok).toBe(true);
+ expect(store.getStream("stream-1")?.status).toBe("active");
+ });
+});
diff --git a/app/lib/stream-events.ts b/app/lib/stream-events.ts
new file mode 100644
index 00000000..cf2125f9
--- /dev/null
+++ b/app/lib/stream-events.ts
@@ -0,0 +1,352 @@
+export type StreamStatus = "draft" | "active" | "paused" | "ended";
+
+export type StreamRecord = {
+ availableBalance: bigint;
+ escrowBalance: bigint;
+ id: string;
+ lastSettlementAt: number;
+ status: StreamStatus;
+ tenantId: string;
+};
+
+export type StreamCommandType = "pause" | "resume" | "settle_tick" | "stop";
+
+export type StreamCommand = {
+ actorTenantId: string;
+ at?: number;
+ idempotencyKey?: string;
+ processingDelayMs?: number;
+ settleAmount?: bigint;
+ type: StreamCommandType;
+};
+
+export type StreamErrorCode =
+ | "NOT_FOUND"
+ | "FORBIDDEN"
+ | "INVALID_COMMAND"
+ | "ILLEGAL_TRANSITION"
+ | "INSUFFICIENT_AVAILABLE"
+ | "INSUFFICIENT_ESCROW";
+
+export type StreamError = {
+ code: StreamErrorCode;
+ httpStatus: 400 | 403 | 404 | 409;
+ message: string;
+};
+
+export type StreamResult =
+ | { ok: true; stream: StreamRecord }
+ | { error: StreamError; ok: false };
+
+export type StreamMetrics = {
+ pauseAttempts: number;
+ pauseFailures: number;
+ pauseSuccess: number;
+ resumeAttempts: number;
+ resumeFailures: number;
+ resumeSuccess: number;
+};
+
+type PersistedResult = {
+ commandType: StreamCommandType;
+ result: StreamResult;
+};
+
+type LockState = {
+ queue: Promise;
+ release: () => void;
+};
+
+function cloneStream(stream: StreamRecord): StreamRecord {
+ return {
+ ...stream,
+ availableBalance: BigInt(stream.availableBalance),
+ escrowBalance: BigInt(stream.escrowBalance),
+ };
+}
+
+function streamError(httpStatus: StreamError["httpStatus"], code: StreamErrorCode, message: string): StreamResult {
+ return {
+ error: { code, httpStatus, message },
+ ok: false,
+ };
+}
+
+function createReleasePromise(): LockState {
+ let release = () => {
+ return;
+ };
+
+ const queue = new Promise((resolve) => {
+ release = resolve;
+ });
+
+ return { queue, release };
+}
+
+function sleep(ms: number): Promise {
+ return new Promise((resolve) => {
+ setTimeout(resolve, ms);
+ });
+}
+
+export class InMemoryStreamStore {
+ private readonly idempotentResults = new Map();
+ private readonly locks = new Map();
+ private readonly streams = new Map();
+
+ readonly metrics: StreamMetrics = {
+ pauseAttempts: 0,
+ pauseFailures: 0,
+ pauseSuccess: 0,
+ resumeAttempts: 0,
+ resumeFailures: 0,
+ resumeSuccess: 0,
+ };
+
+ constructor(initialStreams: StreamRecord[]) {
+ for (const stream of initialStreams) {
+ this.streams.set(stream.id, cloneStream(stream));
+ }
+ }
+
+ getStream(streamId: string): StreamRecord | undefined {
+ const existing = this.streams.get(streamId);
+ if (!existing) {
+ return undefined;
+ }
+ return cloneStream(existing);
+ }
+
+ // Lock ordering policy: always acquire stream lock first. Subordinate rows (escrow/events)
+ // are represented as in-memory fields and can only be touched while this stream lock is held.
+ private async withStreamLock(streamId: string, fn: () => Promise): Promise {
+ const current = this.locks.get(streamId);
+ const next = createReleasePromise();
+ this.locks.set(streamId, next);
+
+ if (current) {
+ await current.queue;
+ }
+
+ try {
+ return await fn();
+ } finally {
+ next.release();
+ if (this.locks.get(streamId) === next) {
+ this.locks.delete(streamId);
+ }
+ }
+ }
+
+ private buildIdempotencyToken(streamId: string, command: StreamCommand): string {
+ return `${streamId}:${command.actorTenantId}:${command.idempotencyKey}`;
+ }
+
+ private maybeGetIdempotentResult(streamId: string, command: StreamCommand): StreamResult | undefined {
+ if (!command.idempotencyKey || (command.type !== "pause" && command.type !== "resume")) {
+ return undefined;
+ }
+
+ const persisted = this.idempotentResults.get(this.buildIdempotencyToken(streamId, command));
+ if (!persisted) {
+ return undefined;
+ }
+
+ if (persisted.commandType !== command.type) {
+ return streamError(409, "ILLEGAL_TRANSITION", "Idempotency key already used for a different command.");
+ }
+
+ return persisted.result;
+ }
+
+ private persistIdempotentResult(streamId: string, command: StreamCommand, result: StreamResult): void {
+ if (!command.idempotencyKey || (command.type !== "pause" && command.type !== "resume")) {
+ return;
+ }
+
+ this.idempotentResults.set(this.buildIdempotencyToken(streamId, command), {
+ commandType: command.type,
+ result,
+ });
+ }
+
+ private validateActor(stream: StreamRecord, command: StreamCommand): StreamResult | undefined {
+ if (stream.tenantId !== command.actorTenantId) {
+ return streamError(403, "FORBIDDEN", "Actor cannot mutate another tenant's stream.");
+ }
+ return undefined;
+ }
+
+ private applyPause(stream: StreamRecord): StreamResult {
+ if (stream.status === "paused") {
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ if (stream.status !== "active") {
+ return streamError(409, "ILLEGAL_TRANSITION", `Pause is illegal from status ${stream.status}.`);
+ }
+
+ stream.status = "paused";
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ private applyResume(stream: StreamRecord): StreamResult {
+ if (stream.status === "active") {
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ if (stream.status !== "paused") {
+ return streamError(409, "ILLEGAL_TRANSITION", `Resume is illegal from status ${stream.status}.`);
+ }
+
+ stream.status = "active";
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ private applySettleTick(stream: StreamRecord, settleAmount: bigint, at: number): StreamResult {
+ if (stream.status === "ended") {
+ return streamError(409, "ILLEGAL_TRANSITION", "Cannot settle an ended stream.");
+ }
+
+ if (settleAmount < 0n) {
+ return streamError(400, "INVALID_COMMAND", "settleAmount must be >= 0.");
+ }
+
+ if (stream.escrowBalance < settleAmount) {
+ return streamError(409, "INSUFFICIENT_ESCROW", "Insufficient escrow for settlement tick.");
+ }
+
+ stream.escrowBalance -= settleAmount;
+ stream.availableBalance += settleAmount;
+ stream.lastSettlementAt = at;
+
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ private applyStop(stream: StreamRecord): StreamResult {
+ if (stream.status === "ended") {
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ stream.status = "ended";
+ return { ok: true, stream: cloneStream(stream) };
+ }
+
+ private trackMetricAttempt(type: StreamCommandType): void {
+ if (type === "pause") {
+ this.metrics.pauseAttempts += 1;
+ }
+
+ if (type === "resume") {
+ this.metrics.resumeAttempts += 1;
+ }
+ }
+
+ private trackMetricResult(type: StreamCommandType, result: StreamResult): void {
+ if (type === "pause") {
+ if (result.ok) {
+ this.metrics.pauseSuccess += 1;
+ } else {
+ this.metrics.pauseFailures += 1;
+ }
+ }
+
+ if (type === "resume") {
+ if (result.ok) {
+ this.metrics.resumeSuccess += 1;
+ } else {
+ this.metrics.resumeFailures += 1;
+ }
+ }
+ }
+
+ async applyEvent(streamId: string, command: StreamCommand): Promise {
+ this.trackMetricAttempt(command.type);
+
+ return this.withStreamLock(streamId, async () => {
+ const idempotent = this.maybeGetIdempotentResult(streamId, command);
+ if (idempotent) {
+ this.trackMetricResult(command.type, idempotent);
+ return idempotent;
+ }
+
+ const stream = this.streams.get(streamId);
+ if (!stream) {
+ const notFound = streamError(404, "NOT_FOUND", `Stream ${streamId} was not found.`);
+ this.trackMetricResult(command.type, notFound);
+ this.persistIdempotentResult(streamId, command, notFound);
+ return notFound;
+ }
+
+ const authError = this.validateActor(stream, command);
+ if (authError) {
+ this.trackMetricResult(command.type, authError);
+ this.persistIdempotentResult(streamId, command, authError);
+ return authError;
+ }
+
+ if (command.processingDelayMs && command.processingDelayMs > 0) {
+ await sleep(command.processingDelayMs);
+ }
+
+ let result: StreamResult;
+
+ switch (command.type) {
+ case "pause":
+ result = this.applyPause(stream);
+ break;
+ case "resume":
+ result = this.applyResume(stream);
+ break;
+ case "settle_tick":
+ result = this.applySettleTick(stream, command.settleAmount ?? 0n, command.at ?? Date.now());
+ break;
+ case "stop":
+ result = this.applyStop(stream);
+ break;
+ default:
+ result = streamError(400, "INVALID_COMMAND", "Unsupported command.");
+ break;
+ }
+
+ this.trackMetricResult(command.type, result);
+ this.persistIdempotentResult(streamId, command, result);
+ return result;
+ });
+ }
+}
+
+export type PauseResumeRouteRequest = {
+ actorTenantId: string;
+ headers: Record;
+ streamId: string;
+};
+
+export async function pauseRoute(store: InMemoryStreamStore, request: PauseResumeRouteRequest): Promise {
+ const idempotencyKey = request.headers["idempotency-key"];
+
+ if (!idempotencyKey) {
+ return streamError(400, "INVALID_COMMAND", "Idempotency-Key header is required.");
+ }
+
+ return store.applyEvent(request.streamId, {
+ actorTenantId: request.actorTenantId,
+ idempotencyKey,
+ type: "pause",
+ });
+}
+
+export async function resumeRoute(store: InMemoryStreamStore, request: PauseResumeRouteRequest): Promise {
+ const idempotencyKey = request.headers["idempotency-key"];
+
+ if (!idempotencyKey) {
+ return streamError(400, "INVALID_COMMAND", "Idempotency-Key header is required.");
+ }
+
+ return store.applyEvent(request.streamId, {
+ actorTenantId: request.actorTenantId,
+ idempotencyKey,
+ type: "resume",
+ });
+}
diff --git a/app/page.test.tsx b/app/page.test.tsx
index 987d41a8..75ba7ea6 100644
--- a/app/page.test.tsx
+++ b/app/page.test.tsx
@@ -1,16 +1,6 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
import Home from "./page";
-const getFocusableNames = (elements: Element[]) =>
- elements.map((element) => {
- const ariaLabel = element.getAttribute("aria-label");
- if (ariaLabel) {
- return ariaLabel;
- }
-
- return element.textContent?.replace(/\s+/g, " ").trim() ?? "";
- });
-
describe("Home", () => {
it("renders the updated stream action heading", () => {
render();
@@ -21,54 +11,18 @@ describe("Home", () => {
).toBeInTheDocument();
});
- it("renders labeled create form controls in review order", () => {
- render();
-
- const form = screen.getByRole("form", { name: /create a stream/i });
- const controls = Array.from(form.querySelectorAll("input, select, textarea, button"));
- const recipientAddress = screen.getByLabelText(/recipient address/i);
- const amount = screen.getByLabelText(/amount/i);
- const distributionInterval = screen.getByLabelText(/distribution interval/i);
- const startDate = screen.getByLabelText(/start date/i);
- const notes = screen.getByLabelText(/notes/i);
- const createStream = screen.getByRole("button", { name: /create stream/i });
- const clearForm = screen.getByRole("button", { name: /clear form/i });
-
- expect(controls).toEqual([
- recipientAddress,
- amount,
- distributionInterval,
- startDate,
- notes,
- createStream,
- clearForm,
- ]);
- });
-
it("does not rely on manual tab index overrides", () => {
const { container } = render();
expect(container.querySelectorAll("[tabindex]")).toHaveLength(0);
});
- it("renders discrete stream actions instead of nested interactive cards", () => {
+ it("renders stream action cards", () => {
render();
- const streamsSection = screen.getByRole("region", { name: /active streams/i });
- const cards = within(streamsSection).getAllByRole("listitem");
-
- expect(cards).toHaveLength(3);
- expect(
- within(cards[0]).getByRole("link", { name: /open details for alma k\./i }),
- ).toBeInTheDocument();
- expect(
- within(cards[0]).getByRole("button", { name: /pause alma k\./i }),
- ).toBeInTheDocument();
- expect(
- within(cards[0]).getByRole("button", {
- name: /copy wallet address for alma k\./i,
- }),
- ).toBeInTheDocument();
+ expect(screen.getByRole("region", { name: /start a new payment stream/i })).toBeInTheDocument();
+ expect(screen.getByRole("region", { name: /pause an active payment stream/i })).toBeInTheDocument();
+ expect(screen.getByRole("region", { name: /withdraw available funds/i })).toBeInTheDocument();
});
it("renders clear wallet and stream action CTAs", () => {
From d88f494fa3e685a836827fe8db6492385a5af0a5 Mon Sep 17 00:00:00 2001
From: shogun444
Date: Tue, 28 Apr 2026 09:44:41 +0530
Subject: [PATCH 019/409] feat(assets): add multi-asset parsing and trustline
pre-flight checks
---
app/lib/assets.test.ts | 82 ++++++++++++++++++++++++++++++++++++++++
app/lib/assets.ts | 82 ++++++++++++++++++++++++++++++++++++++++
docs/supported-assets.md | 28 ++++++++++++++
3 files changed, 192 insertions(+)
create mode 100644 app/lib/assets.test.ts
create mode 100644 app/lib/assets.ts
create mode 100644 docs/supported-assets.md
diff --git a/app/lib/assets.test.ts b/app/lib/assets.test.ts
new file mode 100644
index 00000000..5413af66
--- /dev/null
+++ b/app/lib/assets.test.ts
@@ -0,0 +1,82 @@
+import { parseAssetString, verifyTrustline, NATIVE_ASSET } from './assets';
+
+describe('Asset Engine', () => {
+ describe('parseAssetString', () => {
+ it('parses XLM correctly', () => {
+ expect(parseAssetString('XLM')).toEqual(NATIVE_ASSET);
+ expect(parseAssetString('native')).toEqual(NATIVE_ASSET);
+ });
+
+ it('parses custom assets correctly', () => {
+ const assetStr = 'USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335XOP3IA2M3QC2ED2AAA7Z5TJH';
+ const parsed = parseAssetString(assetStr);
+ expect(parsed.code).toBe('USDC');
+ expect(parsed.issuer).toBe('GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335XOP3IA2M3QC2ED2AAA7Z5TJH');
+ expect(parsed.isNative).toBe(false);
+ });
+
+ it('throws on invalid formats', () => {
+ expect(() => parseAssetString('USDC')).toThrow();
+ expect(() => parseAssetString('USDC:short')).toThrow();
+ });
+ });
+
+ describe('verifyTrustline', () => {
+ const mockPublicKey = 'GBZZ..';
+ const customAsset = {
+ code: 'USDC',
+ issuer: 'GA5Z..',
+ isNative: false
+ };
+
+ beforeEach(() => {
+ global.fetch = jest.fn();
+ });
+
+ it('returns true for native asset without network call', async () => {
+ const result = await verifyTrustline(mockPublicKey, NATIVE_ASSET);
+ expect(result.exists).toBe(true);
+ expect(fetch).not.toHaveBeenCalled();
+ });
+
+ it('returns true if trustline exists', async () => {
+ (fetch as jest.Mock).mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({
+ balances: [
+ { asset_code: 'USDC', asset_issuer: 'GA5Z..' }
+ ]
+ })
+ });
+
+ const result = await verifyTrustline(mockPublicKey, customAsset);
+ expect(result.exists).toBe(true);
+ });
+
+ it('returns false and error if trustline missing', async () => {
+ (fetch as jest.Mock).mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({
+ balances: [
+ { asset_type: 'native' }
+ ]
+ })
+ });
+
+ const result = await verifyTrustline(mockPublicKey, customAsset);
+ expect(result.exists).toBe(false);
+ expect(result.error).toContain('Missing trustline');
+ });
+
+ it('handles 404 account not found', async () => {
+ (fetch as jest.Mock).mockResolvedValue({
+ status: 404,
+ ok: false
+ });
+
+ const result = await verifyTrustline(mockPublicKey, customAsset);
+ expect(result.exists).toBe(false);
+ expect(result.error).toContain('does not exist');
+ });
+ });
+});
diff --git a/app/lib/assets.ts b/app/lib/assets.ts
new file mode 100644
index 00000000..7417d2d9
--- /dev/null
+++ b/app/lib/assets.ts
@@ -0,0 +1,82 @@
+/**
+ * Asset Engine for StreamPay
+ * Handles XLM and Stellar custom assets (Trustlines).
+ */
+
+export interface StellarAsset {
+ code: string;
+ issuer?: string;
+ isNative: boolean;
+}
+
+export const NATIVE_ASSET: StellarAsset = {
+ code: 'XLM',
+ isNative: true,
+};
+
+/**
+ * Parses an asset string (e.g. "USDC:GABC...") or returns native.
+ */
+export function parseAssetString(assetStr: string): StellarAsset {
+ if (!assetStr || assetStr.toUpperCase() === 'XLM' || assetStr.toLowerCase() === 'native') {
+ return NATIVE_ASSET;
+ }
+
+ if (assetStr.includes(':')) {
+ const [code, issuer] = assetStr.split(':');
+ if (code && issuer && issuer.length === 56 && issuer.startsWith('G')) {
+ return { code: code.toUpperCase(), issuer, isNative: false };
+ }
+ }
+
+ throw new Error(`Invalid asset format: ${assetStr}. Expected XLM or CODE:ISSUER`);
+}
+
+/**
+ * Fetches account balances from Horizon and checks for a specific trustline.
+ */
+export async function verifyTrustline(
+ publicKey: string,
+ asset: StellarAsset,
+ horizonUrl: string = 'https://horizon.stellar.org'
+): Promise<{ exists: boolean; error?: string }> {
+ if (asset.isNative) return { exists: true };
+
+ try {
+ const response = await fetch(`${horizonUrl}/accounts/${publicKey}`);
+
+ if (response.status === 404) {
+ return { exists: false, error: 'Recipient account does not exist on-chain.' };
+ }
+
+ if (!response.ok) {
+ return { exists: false, error: `Horizon error: ${response.status}` };
+ }
+
+ const data = await response.json();
+ const hasTrustline = data.balances.some(
+ (b: any) => b.asset_code === asset.code && b.asset_issuer === asset.issuer
+ );
+
+ if (!hasTrustline) {
+ return { exists: false, error: `Missing trustline for ${asset.code}.` };
+ }
+
+ return { exists: true };
+ } catch (err: any) {
+ return { exists: false, error: `Network error: ${err.message}` };
+ }
+}
+
+/**
+ * Validates if an asset can be used for a stream.
+ */
+export function validateAssetPair(sourceAsset: StellarAsset, destAsset: StellarAsset): boolean {
+ // v1 limitation: source and destination must match unless a path payment is used
+ // For now, we enforce same asset
+ return (
+ sourceAsset.isNative === destAsset.isNative &&
+ sourceAsset.code === destAsset.code &&
+ sourceAsset.issuer === destAsset.issuer
+ );
+}
diff --git a/docs/supported-assets.md b/docs/supported-assets.md
new file mode 100644
index 00000000..2cb6cb83
--- /dev/null
+++ b/docs/supported-assets.md
@@ -0,0 +1,28 @@
+# Supported Assets (v1)
+
+StreamPay supports Stellar Native (XLM) and any valid Stellar Classic assets (Alpha-numeric 4 or 12).
+
+## Asset Types
+
+### 1. Stellar Native (XLM)
+- **Code**: `XLM`
+- **Trustline**: Required by default for all Stellar accounts. No pre-flight needed.
+- **Precision**: 7 decimal places (Stroops).
+
+### 2. Stellar Classic Assets (Custom)
+- **Format**: `CODE:ISSUER_ADDRESS`
+- **Trustline**: The recipient **must** establish a trustline for the specific asset before a stream can be successfully funded or paid out.
+- **Pre-flight Check**: StreamPay-Frontend performs an automated check against Horizon to verify trustline existence.
+
+## Validation Matrix
+
+| Case | Result | Actionable Error |
+| :--- | :--- | :--- |
+| Valid XLM | Success | N/A |
+| Valid USDC:G... | Success (if trustline exists) | N/A |
+| Missing Trustline | Reject | "Missing trustline for [CODE]." |
+| Account Not Found | Reject | "Recipient account does not exist on-chain." |
+| Invalid Format | Reject | "Invalid asset format. Expected CODE:ISSUER" |
+
+## Minimum Reserves
+Users must maintain the Stellar base reserve + increments for each trustline. StreamPay does not currently sponsor reserves for trustlines in v1.
From b25d54e2c270280e007f23ac2a18225a13dc89a9 Mon Sep 17 00:00:00 2001
From: shogun444
Date: Tue, 28 Apr 2026 09:51:05 +0530
Subject: [PATCH 020/409] test(streams): property-based invariants for balances
and escrow conservation
---
app/lib/stream-invariants.test.ts | 52 +++++++++++++++++++++++++
app/lib/stream-invariants.ts | 65 +++++++++++++++++++++++++++++++
docs/invariants.md | 26 +++++++++++++
3 files changed, 143 insertions(+)
create mode 100644 app/lib/stream-invariants.test.ts
create mode 100644 app/lib/stream-invariants.ts
create mode 100644 docs/invariants.md
diff --git a/app/lib/stream-invariants.test.ts b/app/lib/stream-invariants.test.ts
new file mode 100644
index 00000000..e00fb292
--- /dev/null
+++ b/app/lib/stream-invariants.test.ts
@@ -0,0 +1,52 @@
+import * as fc from 'fast-check';
+import {
+ checkConservationOfValue,
+ checkNonNegativeBalances,
+ applyStreamEvent,
+ StreamState
+} from './stream-invariants';
+
+describe('Stream Invariants (Property-based)', () => {
+ it('should maintain conservation of value regardless of event sequence', () => {
+ fc.assert(
+ fc.property(
+ fc.array(
+ fc.record({
+ type: fc.constantFrom('deposit', 'withdraw', 'refund'),
+ amount: fc.float({ min: 0, max: 10000, noNaN: true })
+ }),
+ { maxLength: 50 }
+ ),
+ (events) => {
+ let state: StreamState = { deposited: 0, withdrawn: 0, escrow: 0 };
+
+ for (const event of events) {
+ // Guard against negative escrow in this model to simulate "valid" attempts,
+ // or just apply and check the invariant if we want to find failing paths.
+ // Requirement says "randomize a sequence of valid mutating events".
+ if (event.type === 'withdraw' && event.amount > state.escrow) continue;
+ if (event.type === 'refund' && event.amount > state.escrow) continue;
+
+ state = applyStreamEvent(state, event);
+
+ // Assert invariants
+ if (!checkConservationOfValue(state)) return false;
+ if (!checkNonNegativeBalances(state)) return false;
+ }
+ return true;
+ }
+ ),
+ { numRuns: 1000 }
+ );
+ });
+
+ it('regression: should not allow negative escrow via excessive withdrawal', () => {
+ // This is a static test derived from what a property test might find
+ const state: StreamState = { deposited: 100, withdrawn: 0, escrow: 100 };
+ const invalidEvent = { type: 'withdraw' as const, amount: 150 };
+ const newState = applyStreamEvent(state, invalidEvent);
+
+ expect(checkNonNegativeBalances(newState)).toBe(false);
+ expect(newState.escrow).toBe(-50);
+ });
+});
diff --git a/app/lib/stream-invariants.ts b/app/lib/stream-invariants.ts
new file mode 100644
index 00000000..189b3a21
--- /dev/null
+++ b/app/lib/stream-invariants.ts
@@ -0,0 +1,65 @@
+/**
+ * Stream Invariants Module
+ * Pure functions to validate stream state consistency.
+ * These can be used in both frontend validation and tests.
+ */
+
+export interface StreamState {
+ deposited: number;
+ withdrawn: number;
+ escrow: number;
+}
+
+/**
+ * Invariant: Sum of legs matches deposited amount.
+ * Conservation of value: deposited = withdrawn + escrow
+ */
+export function checkConservationOfValue(state: StreamState): boolean {
+ // Using a small epsilon for floating point math if needed,
+ // but for Stellar/Soroban we usually use bigints or fixed precision.
+ // Here we assume basic numbers with truncation handling elsewhere.
+ return Math.abs(state.deposited - (state.withdrawn + state.escrow)) < 0.0000001;
+}
+
+/**
+ * Invariant: Balances must never be negative.
+ */
+export function checkNonNegativeBalances(state: StreamState): boolean {
+ return state.deposited >= 0 && state.withdrawn >= 0 && state.escrow >= 0;
+}
+
+/**
+ * Invariant: Cannot release more than what is in escrow.
+ */
+export function checkSettleLimit(state: StreamState, amountToRelease: number): boolean {
+ return amountToRelease <= state.escrow;
+}
+
+/**
+ * Reducer-like function to model stream mutations safely.
+ */
+export function applyStreamEvent(
+ state: StreamState,
+ event: { type: 'deposit' | 'withdraw' | 'refund'; amount: number }
+): StreamState {
+ const newState = { ...state };
+
+ switch (event.type) {
+ case 'deposit':
+ newState.deposited += event.amount;
+ newState.escrow += event.amount;
+ break;
+ case 'withdraw':
+ // In a real scenario, this would be guarded by logic.
+ // For property tests, we apply it and check invariants.
+ newState.withdrawn += event.amount;
+ newState.escrow -= event.amount;
+ break;
+ case 'refund':
+ newState.deposited -= event.amount;
+ newState.escrow -= event.amount;
+ break;
+ }
+
+ return newState;
+}
diff --git a/docs/invariants.md b/docs/invariants.md
new file mode 100644
index 00000000..bea2b888
--- /dev/null
+++ b/docs/invariants.md
@@ -0,0 +1,26 @@
+# Stream Invariants & Property Testing
+
+To ensure the reliability of StreamPay's accounting, we use property-based testing to verify that stream states remain consistent under any sequence of valid events.
+
+## Core Invariants
+
+1. **Conservation of Value**: `deposited_amount == withdrawn_amount + escrow_balance`. Funds must always be accounted for.
+2. **Non-Negativity**: `deposited`, `withdrawn`, and `escrow` must never be less than zero.
+3. **Escrow Bound**: A withdrawal or refund can never exceed the current `escrow` balance.
+
+## Property Testing Setup
+
+We use `fast-check` to generate randomized sequences of `deposit`, `withdraw`, and `refund` events.
+
+- **Runs**: Default 1000 iterations per test.
+- **Shrinking**: If a failure is found, `fast-check` automatically simplifies the event sequence to the minimal reproduction case.
+- **CI Stability**: Tests use deterministic seeds to ensure failures are reproducible in CI pipelines.
+
+## Security Note
+
+These invariants are modeled in the frontend/middleware to guide users and catch logic errors early. However, they are **not** a substitute for on-chain Soroban contract security. Final enforcement always happens via Soroban smart contracts.
+
+## Future Work
+
+- Integration with [StreamPay-Contracts](https://github.com/Streampay-Org/StreamPay-Contracts) formal verification models.
+- Nightly "heavy" runs with 10,000+ iterations.
From 1fbf718d04a4194f44a812eebcedcd53a0003916 Mon Sep 17 00:00:00 2001
From: shogun444
Date: Tue, 28 Apr 2026 09:56:07 +0530
Subject: [PATCH 021/409] test(streams): add property-based invariants for
balance and escrow safety
---
app/lib/stream-invariants.test.ts | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/app/lib/stream-invariants.test.ts b/app/lib/stream-invariants.test.ts
index e00fb292..533f8232 100644
--- a/app/lib/stream-invariants.test.ts
+++ b/app/lib/stream-invariants.test.ts
@@ -7,7 +7,10 @@ import {
} from './stream-invariants';
describe('Stream Invariants (Property-based)', () => {
- it('should maintain conservation of value regardless of event sequence', () => {
+ const isHeavyMode = process.env.TEST_MODE === 'heavy';
+ const numRuns = isHeavyMode ? 10000 : 1000;
+
+ it(`should maintain conservation of value (${numRuns} runs)`, () => {
fc.assert(
fc.property(
fc.array(
@@ -36,7 +39,7 @@ describe('Stream Invariants (Property-based)', () => {
return true;
}
),
- { numRuns: 1000 }
+ { numRuns, seed: 42 } // Seed for deterministic CI stability
);
});
From b08f191649b193cfd841fc42a2e8384c4883d096 Mon Sep 17 00:00:00 2001
From: Samuel Ojetunde
Date: Tue, 28 Apr 2026 06:02:52 +0100
Subject: [PATCH 022/409] feat(escrow): align DB settlement state with on-chain
hold/release invariants (testnet tests)
---
escrow-invariants.test.ts | 52 +++++++++++++++++++++++++++++++++++++++
escrow-invariants.ts | 49 ++++++++++++++++++++++++++++++++++++
mapping.ts | 23 +++++++++++++++++
types.ts | 28 +++++++++++++++++++++
4 files changed, 152 insertions(+)
create mode 100644 escrow-invariants.test.ts
create mode 100644 escrow-invariants.ts
create mode 100644 mapping.ts
create mode 100644 types.ts
diff --git a/escrow-invariants.test.ts b/escrow-invariants.test.ts
new file mode 100644
index 00000000..61e0084c
--- /dev/null
+++ b/escrow-invariants.test.ts
@@ -0,0 +1,52 @@
+import { EscrowInvariants } from "./escrow-invariants";
+import { ContractStreamStatus, OnChainStream } from "./types";
+
+const mockStream: OnChainStream = {
+ id: "test-stream",
+ recipient_address: "GB...123",
+ total_amount: 1000n,
+ released_amount: 500n,
+ velocity: 10n,
+ last_update_timestamp: Date.now(),
+ status: ContractStreamStatus.ACTIVE,
+};
+
+describe("Escrow Invariants", () => {
+ describe("canSettle", () => {
+ it("allows settlement for active streams with balance", () => {
+ const result = EscrowInvariants.canSettle(mockStream);
+ expect(result.isValid).toBe(true);
+ });
+
+ it("rejects settlement if stream is already settled", () => {
+ const result = EscrowInvariants.canSettle({
+ ...mockStream,
+ status: ContractStreamStatus.SETTLED,
+ });
+ expect(result.isValid).toBe(false);
+ expect(result.error).toContain("not in a settlable state");
+ });
+ });
+
+ describe("canWithdraw", () => {
+ it("allows withdrawal when settled and funds remain", () => {
+ const result = EscrowInvariants.canWithdraw({
+ ...mockStream,
+ status: ContractStreamStatus.SETTLED,
+ });
+ expect(result.isValid).toBe(true);
+ });
+
+ it("rejects withdrawal if status is not settled", () => {
+ const result = EscrowInvariants.canWithdraw(mockStream);
+ expect(result.isValid).toBe(false);
+ expect(result.error).toContain("must be SETTLED");
+ });
+
+ it("rejects withdrawal if no funds remain", () => {
+ const result = EscrowInvariants.canWithdraw({ ...mockStream, status: ContractStreamStatus.SETTLED, released_amount: 1000n });
+ expect(result.isValid).toBe(false);
+ expect(result.error).toContain("No remaining funds");
+ });
+ });
+});
\ No newline at end of file
diff --git a/escrow-invariants.ts b/escrow-invariants.ts
new file mode 100644
index 00000000..386de8af
--- /dev/null
+++ b/escrow-invariants.ts
@@ -0,0 +1,49 @@
+import { OnChainStream, ContractStreamStatus, InvariantResult } from "./types";
+
+/**
+ * Service-layer invariants consistent with on-chain escrow rules.
+ * These checks must pass before the frontend allows a transaction to be submitted.
+ */
+export const EscrowInvariants = {
+ /**
+ * Settlement Invariant:
+ * A stream can only be settled if it is ACTIVE or PAUSED and has
+ * an outstanding balance not yet released.
+ */
+ canSettle(stream: OnChainStream): InvariantResult {
+ const validStatuses = [ContractStreamStatus.ACTIVE, ContractStreamStatus.PAUSED];
+
+ if (!validStatuses.includes(stream.status)) {
+ return { isValid: false, error: "Stream is not in a settlable state (Must be Active or Paused)." };
+ }
+
+ if (stream.released_amount >= stream.total_amount) {
+ return { isValid: false, error: "Funds already fully released." };
+ }
+
+ return { isValid: true };
+ },
+
+ /**
+ * Withdrawal Invariant:
+ * A recipient can only withdraw if the stream is SETTLED and
+ * there are funds in the escrow hold that haven't been claimed.
+ */
+ canWithdraw(stream: OnChainStream): InvariantResult {
+ if (stream.status !== ContractStreamStatus.SETTLED) {
+ return { isValid: false, error: "Contract must be SETTLED before withdrawal is permitted." };
+ }
+
+ const withdrawable = stream.total_amount - stream.released_amount;
+ if (withdrawable <= 0n) {
+ return { isValid: false, error: "No remaining funds available for withdrawal." };
+ }
+
+ return { isValid: true };
+ },
+
+ /**
+ * Security Note: No optimistic credit is permitted.
+ * Always fetch fresh on-chain state via RPC before validating these invariants.
+ */
+};
\ No newline at end of file
diff --git a/mapping.ts b/mapping.ts
new file mode 100644
index 00000000..ff047851
--- /dev/null
+++ b/mapping.ts
@@ -0,0 +1,23 @@
+import { OnChainStream } from "./types";
+
+/**
+ * Documented 1:1 Mapping between DB/UI fields and Contract Storage Keys
+ *
+ * | UI Field | Contract Storage Key (Soroban) | Type |
+ * |--------------------|--------------------------------|-----------|
+ * | id | id | String |
+ * | recipient | recipient_address | Address |
+ * | amount | total_amount | i128 |
+ * | rate | velocity | i128 |
+ * | status | status | u32/Enum |
+ * | lastUpdated | last_update_timestamp | u64 |
+ */
+
+export const mapContractToUI = (contractStream: OnChainStream) => {
+ return {
+ id: contractStream.id,
+ recipient: contractStream.recipient_address,
+ amount: contractStream.total_amount.toString(),
+ status: contractStream.status,
+ };
+};
\ No newline at end of file
diff --git a/types.ts b/types.ts
new file mode 100644
index 00000000..2a1f4a8a
--- /dev/null
+++ b/types.ts
@@ -0,0 +1,28 @@
+/**
+ * On-chain stream states matching StreamPay-Contracts
+ */
+export enum ContractStreamStatus {
+ DRAFT = 0,
+ ACTIVE = 1,
+ PAUSED = 2,
+ SETTLED = 3,
+ CANCELLED = 4,
+}
+
+/**
+ * Representation of the Soroban Contract Storage for a Stream
+ */
+export interface OnChainStream {
+ id: string;
+ recipient_address: string;
+ total_amount: bigint;
+ released_amount: bigint;
+ velocity: bigint; // flow rate per second/block
+ last_update_timestamp: number;
+ status: ContractStreamStatus;
+}
+
+export interface InvariantResult {
+ isValid: boolean;
+ error?: string;
+}
\ No newline at end of file
From bf57a2c57ae3547bd005c7e9a24cc4aac85eab96 Mon Sep 17 00:00:00 2001
From: Samuel Ojetunde
Date: Tue, 28 Apr 2026 06:11:32 +0100
Subject: [PATCH 023/409] feat(security): add anomaly rules for stream and
settlement spikes per tenant
---
detector.test.ts | 46 +++++++++++++++++++++++++++++++++++++
detector.ts | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
types.ts | 37 +++++++++++++----------------
3 files changed, 122 insertions(+), 21 deletions(-)
create mode 100644 detector.test.ts
create mode 100644 detector.ts
diff --git a/detector.test.ts b/detector.test.ts
new file mode 100644
index 00000000..0c98811e
--- /dev/null
+++ b/detector.test.ts
@@ -0,0 +1,46 @@
+import { AnomalyDetector } from "./detector";
+import { MetricSnapshot } from "./types";
+
+describe("AnomalyDetector", () => {
+ const tenantId = "tenant_test_1";
+ const thresholds = { creationBurstLimit: 10, settleRateLimit: 5 };
+
+ const createSnapshot = (creations: number, settles: number): MetricSnapshot => ({
+ tenantId,
+ streamCreations: creations,
+ settleAttempts: settles,
+ timestamp: Date.now(),
+ });
+
+ it("passes under normal load", () => {
+ const alerts = AnomalyDetector.evaluate(createSnapshot(5, 2), thresholds);
+ expect(alerts).toHaveLength(0);
+ });
+
+ it("detects stream creation bursts", () => {
+ const alerts = AnomalyDetector.evaluate(createSnapshot(15, 2), thresholds);
+ expect(alerts).toHaveLength(1);
+ expect(alerts[0].ruleName).toBe("STREAM_CREATION_BURST");
+ expect(alerts[0].observedValue).toBe(15);
+ });
+
+ it("detects settle rate spikes", () => {
+ const alerts = AnomalyDetector.evaluate(createSnapshot(5, 10), thresholds);
+ expect(alerts).toHaveLength(1);
+ expect(alerts[0].ruleName).toBe("SETTLE_RATE_SPIKE");
+ });
+
+ it("detects multiple anomalies simultaneously", () => {
+ const alerts = AnomalyDetector.evaluate(createSnapshot(20, 20), thresholds);
+ expect(alerts).toHaveLength(2);
+ });
+
+ it("respects the whitelist/snooze mechanism", () => {
+ AnomalyDetector.setWhitelist(tenantId, true);
+ const alerts = AnomalyDetector.evaluate(createSnapshot(100, 100), thresholds);
+ expect(alerts).toHaveLength(0);
+
+ // Cleanup
+ AnomalyDetector.setWhitelist(tenantId, false);
+ });
+});
\ No newline at end of file
diff --git a/detector.ts b/detector.ts
new file mode 100644
index 00000000..3817b7f7
--- /dev/null
+++ b/detector.ts
@@ -0,0 +1,60 @@
+import { AnomalyAlert, AnomalyThresholds, MetricSnapshot } from "./types";
+
+/**
+ * Default thresholds tunable via environment variables.
+ */
+const DEFAULT_THRESHOLDS: AnomalyThresholds = {
+ creationBurstLimit: Number(process.env.ANOMALY_CREATION_THRESHOLD) || 50,
+ settleRateLimit: Number(process.env.ANOMALY_SETTLE_THRESHOLD) || 20,
+};
+
+/**
+ * In-memory whitelist for snoozing alerts per tenant during incidents.
+ * In production, this should be backed by a distributed cache or DB.
+ */
+const whitelist = new Set();
+
+/**
+ * Rule-based anomaly detection for early fraud/bug mitigation.
+ * SECURITY NOTE: These alerts are for observation and manual review.
+ * Do not use for unilateral fund freezing without a compliance policy.
+ */
+export const AnomalyDetector = {
+ evaluate(snapshot: MetricSnapshot, config: AnomalyThresholds = DEFAULT_THRESHOLDS): AnomalyAlert[] {
+ if (whitelist.has(snapshot.tenantId)) {
+ return [];
+ }
+
+ const alerts: AnomalyAlert[] = [];
+
+ // Rule 1: High frequency of new stream creation
+ if (snapshot.streamCreations > config.creationBurstLimit) {
+ alerts.push({
+ tenantId: snapshot.tenantId,
+ ruleName: "STREAM_CREATION_BURST",
+ observedValue: snapshot.streamCreations,
+ threshold: config.creationBurstLimit,
+ severity: "high",
+ detectedAt: new Date().toISOString(),
+ });
+ }
+
+ // Rule 2: Abnormal settlement activity
+ if (snapshot.settleAttempts > config.settleRateLimit) {
+ alerts.push({
+ tenantId: snapshot.tenantId,
+ ruleName: "SETTLE_RATE_SPIKE",
+ observedValue: snapshot.settleAttempts,
+ threshold: config.settleRateLimit,
+ severity: "medium",
+ detectedAt: new Date().toISOString(),
+ });
+ }
+
+ return alerts;
+ },
+
+ setWhitelist(tenantId: string, active: boolean) {
+ active ? whitelist.add(tenantId) : whitelist.delete(tenantId);
+ }
+};
\ No newline at end of file
diff --git a/types.ts b/types.ts
index 2a1f4a8a..dd5ea185 100644
--- a/types.ts
+++ b/types.ts
@@ -1,28 +1,23 @@
/**
- * On-chain stream states matching StreamPay-Contracts
+ * Aggregate metric snapshot for a specific tenant within a rolling window.
*/
-export enum ContractStreamStatus {
- DRAFT = 0,
- ACTIVE = 1,
- PAUSED = 2,
- SETTLED = 3,
- CANCELLED = 4,
+export interface MetricSnapshot {
+ tenantId: string;
+ streamCreations: number;
+ settleAttempts: number;
+ timestamp: number;
}
-/**
- * Representation of the Soroban Contract Storage for a Stream
- */
-export interface OnChainStream {
- id: string;
- recipient_address: string;
- total_amount: bigint;
- released_amount: bigint;
- velocity: bigint; // flow rate per second/block
- last_update_timestamp: number;
- status: ContractStreamStatus;
+export interface AnomalyThresholds {
+ creationBurstLimit: number; // e.g., new streams per hour
+ settleRateLimit: number; // e.g., settle attempts per hour
}
-export interface InvariantResult {
- isValid: boolean;
- error?: string;
+export interface AnomalyAlert {
+ tenantId: string;
+ ruleName: "STREAM_CREATION_BURST" | "SETTLE_RATE_SPIKE";
+ observedValue: number;
+ threshold: number;
+ severity: 'low' | 'medium' | 'high';
+ detectedAt: string;
}
\ No newline at end of file
From b33da0d766611753f0ce515c6a08389a0ee8b020 Mon Sep 17 00:00:00 2001
From: nice-bills
Date: Tue, 28 Apr 2026 05:12:15 +0000
Subject: [PATCH 024/409] add backend API routes + OpenAPI 3.1 spec
---
app/activity/page.tsx | 43 +-
app/api/activity/route.ts | 41 ++
app/api/auth/wallet/route.ts | 29 ++
app/api/identity/me/route.ts | 34 ++
app/api/streams/[id]/pause/route.ts | 25 +
app/api/streams/[id]/route.ts | 34 ++
app/api/streams/[id]/settle/route.ts | 33 ++
app/api/streams/[id]/start/route.ts | 25 +
app/api/streams/[id]/stop/route.ts | 25 +
app/api/streams/[id]/withdraw/route.ts | 25 +
app/api/streams/route.ts | 69 +++
app/lib/db.ts | 64 +++
app/streams/StreamsPageContent.tsx | 140 +++++
app/streams/page.test.tsx | 2 +-
app/streams/page.tsx | 141 +----
app/types/openapi.ts | 44 ++
openapi.json | 690 +++++++++++++++++++++++++
scripts/validate-openapi.mjs | 123 +++++
18 files changed, 1409 insertions(+), 178 deletions(-)
create mode 100644 app/api/activity/route.ts
create mode 100644 app/api/auth/wallet/route.ts
create mode 100644 app/api/identity/me/route.ts
create mode 100644 app/api/streams/[id]/pause/route.ts
create mode 100644 app/api/streams/[id]/route.ts
create mode 100644 app/api/streams/[id]/settle/route.ts
create mode 100644 app/api/streams/[id]/start/route.ts
create mode 100644 app/api/streams/[id]/stop/route.ts
create mode 100644 app/api/streams/[id]/withdraw/route.ts
create mode 100644 app/api/streams/route.ts
create mode 100644 app/lib/db.ts
create mode 100644 app/streams/StreamsPageContent.tsx
create mode 100644 app/types/openapi.ts
create mode 100644 openapi.json
create mode 100644 scripts/validate-openapi.mjs
diff --git a/app/activity/page.tsx b/app/activity/page.tsx
index 05bf0a99..3de76a3f 100644
--- a/app/activity/page.tsx
+++ b/app/activity/page.tsx
@@ -1,4 +1,6 @@
-import EmptyState from "../components/EmptyState";
+"use client";
+
+import { EmptyState } from "../components/EmptyState";
export default function ActivityPage() {
return (
@@ -12,44 +14,11 @@ export default function ActivityPage() {
}}
>
- View streams
-
- }
- secondaryAction={
-
- Home dashboard
-
- }
- >
- Keep your wallet connected to see live stream and payment activity in one place.
-
+ actionLabel="View streams"
+ />
);
}
diff --git a/app/api/activity/route.ts b/app/api/activity/route.ts
new file mode 100644
index 00000000..0abff5ae
--- /dev/null
+++ b/app/api/activity/route.ts
@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+import { db, encodeCursor, decodeCursor } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function GET(request: Request) {
+ const { searchParams } = new URL(request.url);
+ const cursor = searchParams.get("cursor");
+ const streamId = searchParams.get("streamId");
+ const type = searchParams.get("type");
+ const limit = Math.min(parseInt(searchParams.get("limit") || "20"), 100);
+
+ let events = Array.from(db.activity.values()).sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+ if (streamId) {
+ events = events.filter((e) => e.streamId === streamId);
+ }
+ if (type) {
+ events = events.filter((e) => e.type === type);
+ }
+
+ if (cursor) {
+ const cursorId = decodeCursor(cursor);
+ const cursorIndex = events.findIndex((e) => e.id === cursorId);
+ if (cursorIndex >= 0) {
+ events = events.slice(cursorIndex + 1);
+ }
+ }
+
+ const paginatedEvents = events.slice(0, limit);
+ const hasNext = events.length > limit;
+ const nextCursor = hasNext && paginatedEvents.length > 0 ? encodeCursor(paginatedEvents[paginatedEvents.length - 1].id) : null;
+
+ return NextResponse.json({
+ data: paginatedEvents,
+ meta: { hasNext, nextCursor, total: db.activity.size },
+ links: { self: `/api/v1/activity?limit=${limit}` },
+ });
+}
diff --git a/app/api/auth/wallet/route.ts b/app/api/auth/wallet/route.ts
new file mode 100644
index 00000000..31dc37fe
--- /dev/null
+++ b/app/api/auth/wallet/route.ts
@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import jwt from "jsonwebtoken";
+
+const JWT_SECRET = process.env.JWT_SECRET || "streampay-dev-secret-do-not-use-in-prod";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(request: Request) {
+ try {
+ const body = await request.json();
+ const { publicKey, signature, message } = body;
+
+ if (!publicKey || !signature || !message) {
+ return createErrorResponse("VALIDATION_ERROR", "Missing required fields: publicKey, signature, message", 422);
+ }
+
+ if (message !== "Sign this message to authenticate with StreamPay. Nonce: abc123") {
+ return createErrorResponse("INVALID_SIGNATURE", "Signature verification failed", 401);
+ }
+
+ const token = jwt.sign({ sub: publicKey, iss: "streampay" }, JWT_SECRET, { expiresIn: "15m" });
+
+ return NextResponse.json({ accessToken: token, expiresIn: 900 });
+ } catch {
+ return createErrorResponse("INVALID_REQUEST", "Request body must be valid JSON", 400);
+ }
+}
diff --git a/app/api/identity/me/route.ts b/app/api/identity/me/route.ts
new file mode 100644
index 00000000..a66bbd5e
--- /dev/null
+++ b/app/api/identity/me/route.ts
@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import jwt from "jsonwebtoken";
+
+const JWT_SECRET = process.env.JWT_SECRET || "streampay-dev-secret-do-not-use-in-prod";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function GET(request: Request) {
+ const authHeader = request.headers.get("authorization");
+ if (!authHeader?.startsWith("Bearer ")) {
+ return createErrorResponse("UNAUTHORIZED", "Missing or invalid authorization header", 401);
+ }
+ const token = authHeader.slice(7);
+ try {
+ const verified = jwt.verify(token, JWT_SECRET) as { sub?: string };
+ if (!verified.sub) {
+ return createErrorResponse("UNAUTHORIZED", "Invalid or expired token", 401);
+ }
+ return NextResponse.json({
+ data: {
+ wallet_address: verified.sub,
+ email: null,
+ display_name: verified.sub.slice(0, 16) + "...",
+ avatar_url: null,
+ created_at: "2026-04-01T09:00:00Z",
+ },
+ links: { self: "/api/v1/identity/me" },
+ });
+ } catch {
+ return createErrorResponse("UNAUTHORIZED", "Invalid or expired token", 401);
+ }
+}
diff --git a/app/api/streams/[id]/pause/route.ts b/app/api/streams/[id]/pause/route.ts
new file mode 100644
index 00000000..2080ae04
--- /dev/null
+++ b/app/api/streams/[id]/pause/route.ts
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status !== "active") {
+ return createErrorResponse("INVALID_STREAM_STATE", "Only active streams can be paused", 409);
+ }
+ stream.status = "paused";
+ stream.nextAction = "start";
+ stream.updatedAt = new Date().toISOString();
+ db.streams.set(id, stream);
+ return NextResponse.json({ data: stream });
+}
diff --git a/app/api/streams/[id]/route.ts b/app/api/streams/[id]/route.ts
new file mode 100644
index 00000000..8db5fed9
--- /dev/null
+++ b/app/api/streams/[id]/route.ts
@@ -0,0 +1,34 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function GET(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ return NextResponse.json({ data: stream, links: { self: `/api/v1/streams/${id}` } });
+}
+
+export async function DELETE(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status === "active" || stream.status === "paused") {
+ return createErrorResponse("STREAM_INACTIVE_STATE", "Cannot delete a stream that is active or paused. Stop it first.", 409);
+ }
+ db.streams.delete(id);
+ return new NextResponse(null, { status: 204 });
+}
diff --git a/app/api/streams/[id]/settle/route.ts b/app/api/streams/[id]/settle/route.ts
new file mode 100644
index 00000000..10de553c
--- /dev/null
+++ b/app/api/streams/[id]/settle/route.ts
@@ -0,0 +1,33 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status !== "active" && stream.status !== "paused") {
+ return createErrorResponse("INVALID_STREAM_STATE", "Only active or paused streams can be settled", 409);
+ }
+ stream.status = "ended";
+ stream.nextAction = "withdraw";
+ stream.updatedAt = new Date().toISOString();
+ db.streams.set(id, stream);
+ return NextResponse.json({
+ data: {
+ ...stream,
+ settlement: {
+ txHash: `fake-tx-${crypto.randomUUID().slice(0, 8)}`,
+ settledAt: new Date().toISOString(),
+ },
+ },
+ });
+}
diff --git a/app/api/streams/[id]/start/route.ts b/app/api/streams/[id]/start/route.ts
new file mode 100644
index 00000000..ca3eee97
--- /dev/null
+++ b/app/api/streams/[id]/start/route.ts
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status !== "draft") {
+ return createErrorResponse("INVALID_STREAM_STATE", "Only draft streams can be started", 409);
+ }
+ stream.status = "active";
+ stream.nextAction = "pause";
+ stream.updatedAt = new Date().toISOString();
+ db.streams.set(id, stream);
+ return NextResponse.json({ data: stream });
+}
diff --git a/app/api/streams/[id]/stop/route.ts b/app/api/streams/[id]/stop/route.ts
new file mode 100644
index 00000000..35af39e9
--- /dev/null
+++ b/app/api/streams/[id]/stop/route.ts
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status !== "active" && stream.status !== "draft") {
+ return createErrorResponse("INVALID_STREAM_STATE", "Only active or draft streams can be stopped", 409);
+ }
+ stream.status = "ended";
+ stream.nextAction = "withdraw";
+ stream.updatedAt = new Date().toISOString();
+ db.streams.set(id, stream);
+ return NextResponse.json({ data: stream });
+}
diff --git a/app/api/streams/[id]/withdraw/route.ts b/app/api/streams/[id]/withdraw/route.ts
new file mode 100644
index 00000000..c60bade0
--- /dev/null
+++ b/app/api/streams/[id]/withdraw/route.ts
@@ -0,0 +1,25 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+
+function createErrorResponse(code: string, message: string, status: number) {
+ return NextResponse.json({ error: { code, message, request_id: "mock-request-id" } }, { status });
+}
+
+export async function POST(
+ _request: Request,
+ { params }: { params: Promise<{ id: string }> }
+) {
+ const { id } = await params;
+ const stream = db.streams.get(id);
+ if (!stream) {
+ return createErrorResponse("STREAM_NOT_FOUND", `Stream '${id}' not found`, 404);
+ }
+ if (stream.status !== "ended") {
+ return createErrorResponse("INVALID_STREAM_STATE", "Only ended streams can be withdrawn from", 409);
+ }
+ stream.status = "withdrawn";
+ stream.nextAction = undefined;
+ stream.updatedAt = new Date().toISOString();
+ db.streams.set(id, stream);
+ return NextResponse.json({ data: stream });
+}
diff --git a/app/api/streams/route.ts b/app/api/streams/route.ts
new file mode 100644
index 00000000..cad9a09c
--- /dev/null
+++ b/app/api/streams/route.ts
@@ -0,0 +1,69 @@
+import { NextResponse } from "next/server";
+import { db } from "@/app/lib/db";
+import { encodeCursor, decodeCursor } from "@/app/lib/db";
+import { v4 as uuidv4 } from "uuid";
+
+function createErrorResponse(code: string, message: string, status: number, requestId = "mock-request-id") {
+ return NextResponse.json({ error: { code, message, request_id: requestId } }, { status });
+}
+
+export async function GET(request: Request) {
+ const { searchParams } = new URL(request.url);
+ const cursor = searchParams.get("cursor");
+ const status = searchParams.get("status");
+ const limit = Math.min(parseInt(searchParams.get("limit") || "20"), 100);
+
+ let streams = Array.from(db.streams.values()).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+
+ if (status) {
+ streams = streams.filter((s) => s.status === status);
+ }
+
+ if (cursor) {
+ const cursorId = decodeCursor(cursor);
+ const cursorIndex = streams.findIndex((s) => s.id === cursorId);
+ if (cursorIndex >= 0) {
+ streams = streams.slice(cursorIndex + 1);
+ }
+ }
+
+ const paginatedStreams = streams.slice(0, limit);
+ const hasNext = streams.length > limit;
+ const nextCursor = hasNext && paginatedStreams.length > 0 ? encodeCursor(paginatedStreams[paginatedStreams.length - 1].id) : null;
+
+ return NextResponse.json({
+ data: paginatedStreams,
+ meta: { hasNext, nextCursor, total: db.streams.size },
+ links: { self: `/api/v1/streams?limit=${limit}` },
+ });
+}
+
+export async function POST(request: Request) {
+ const idempotencyKey = request.headers.get("Idempotency-Key");
+ if (idempotencyKey && db.idempotency.has(idempotencyKey)) {
+ return NextResponse.json(db.idempotency.get(idempotencyKey), { status: 201 });
+ }
+
+ try {
+ const body = await request.json();
+ const { recipient, rate, schedule } = body;
+
+ if (!recipient || !rate || !schedule) {
+ return createErrorResponse("VALIDATION_ERROR", "Missing required fields: recipient, rate, schedule", 422);
+ }
+
+ const id = `stream-${uuidv4().slice(0, 8)}`;
+ const now = new Date().toISOString();
+ const newStream = { id, recipient, rate, schedule, status: "draft" as const, nextAction: "start" as const, createdAt: now, updatedAt: now };
+
+ db.streams.set(id, newStream);
+
+ if (idempotencyKey) {
+ db.idempotency.set(idempotencyKey, newStream);
+ }
+
+ return NextResponse.json({ data: newStream, links: { self: `/api/v1/streams/${id}` } }, { status: 201 });
+ } catch {
+ return createErrorResponse("INVALID_REQUEST", "Request body must be valid JSON", 400);
+ }
+}
diff --git a/app/lib/db.ts b/app/lib/db.ts
new file mode 100644
index 00000000..2270e2bc
--- /dev/null
+++ b/app/lib/db.ts
@@ -0,0 +1,64 @@
+import { Stream, ActivityEvent } from "@/app/types/openapi";
+
+export const db = {
+ streams: new Map([
+ [
+ "stream-ada",
+ {
+ id: "stream-ada",
+ recipient: "Ada Creative Studio",
+ rate: "120 XLM / month",
+ schedule: "Pays every 30 days",
+ status: "active",
+ nextAction: "pause",
+ createdAt: "2026-04-01T09:00:00Z",
+ updatedAt: "2026-04-28T10:30:00Z",
+ },
+ ],
+ [
+ "stream-kemi",
+ {
+ id: "stream-kemi",
+ recipient: "Kemi Onboarding Support",
+ rate: "32 XLM / week",
+ schedule: "Draft stream ready to launch",
+ status: "draft",
+ nextAction: "start",
+ createdAt: "2026-04-10T14:00:00Z",
+ updatedAt: "2026-04-28T11:00:00Z",
+ },
+ ],
+ [
+ "stream-yusuf",
+ {
+ id: "stream-yusuf",
+ recipient: "Yusuf QA Partnership",
+ rate: "18 XLM / day",
+ schedule: "Ended yesterday with funds available",
+ status: "ended",
+ nextAction: "withdraw",
+ createdAt: "2026-04-15T08:00:00Z",
+ updatedAt: "2026-04-27T20:00:00Z",
+ },
+ ],
+ ]),
+
+ activity: new Map([
+ ["a7383234-4224-49dc-b868-0cdf37649fda", { id: "a7383234-4224-49dc-b868-0cdf37649fda", type: "wallet.connected", timestamp: "2026-04-28T09:00:00Z", description: "Wallet connected and authenticated." }],
+ ["2b9d1d0c-bef4-46bc-a783-3073b28353fc", { id: "2b9d1d0c-bef4-46bc-a783-3073b28353fc", type: "stream.created", streamId: "stream-ada", timestamp: "2026-04-01T09:00:00Z", description: "Stream 'Design Retainer' created and set to draft." }],
+ ["d1578871-4be9-4c6a-bef5-12b2b5836478", { id: "d1578871-4be9-4c6a-bef5-12b2b5836478", type: "stream.started", streamId: "stream-ada", timestamp: "2026-04-01T09:05:00Z", description: "Stream 'Design Retainer' activated." }],
+ ["288f315d-5520-46e9-8acf-96994c87b786", { id: "288f315d-5520-46e9-8acf-96994c87b786", type: "stream.created", streamId: "stream-kemi", timestamp: "2026-04-10T14:00:00Z", description: "Stream 'Kemi Onboarding Support' created as draft." }],
+ ["3bea183d-c3b5-4e96-9fbe-804f3aee49e9", { id: "3bea183d-c3b5-4e96-9fbe-804f3aee49e9", type: "stream.created", streamId: "stream-yusuf", timestamp: "2026-04-15T08:00:00Z", description: "Stream 'Yusuf QA Partnership' created." }],
+ ["5ffa85da-27a4-4f7c-bde0-e5c067a28015", { id: "5ffa85da-27a4-4f7c-bde0-e5c067a28015", type: "stream.stopped", streamId: "stream-yusuf", timestamp: "2026-04-27T20:00:00Z", description: "Stream 'Yusuf QA Partnership' stopped and settled automatically." }],
+ ]),
+
+ idempotency: new Map(),
+};
+
+export function encodeCursor(id: string): string {
+ return Buffer.from(id).toString("base64");
+}
+
+export function decodeCursor(cursor: string): string {
+ return Buffer.from(cursor, "base64").toString("utf8");
+}
diff --git a/app/streams/StreamsPageContent.tsx b/app/streams/StreamsPageContent.tsx
new file mode 100644
index 00000000..0137aec7
--- /dev/null
+++ b/app/streams/StreamsPageContent.tsx
@@ -0,0 +1,140 @@
+import { EmptyState } from "../components/EmptyState";
+import { StreamRow, type StreamRowData } from "../components/StreamRow";
+
+export type StreamsViewState = "empty" | "loading" | "populated";
+
+const streamListCopy = {
+ description:
+ "Track recipients, rates, statuses, and the next action from one scan-friendly streams list.",
+ empty: {
+ actionLabel: "Create Your First Stream",
+ description: "No streams yet. Create one to start paying collaborators and vendors on a steady schedule.",
+ eyebrow: "Streams",
+ title: "Your streams list is empty",
+ },
+ heading: "Streams",
+ loadingLabel: "Loading streams",
+ populatedCount: "3 active records",
+ primaryCta: "Create Stream",
+} as const;
+
+export const mockStreams: StreamRowData[] = [
+ {
+ id: "stream-ada",
+ nextAction: "Pause",
+ rate: "120 XLM / month",
+ recipient: "Ada Creative Studio",
+ schedule: "Pays every 30 days",
+ status: "active",
+ },
+ {
+ id: "stream-kemi",
+ nextAction: "Start",
+ rate: "32 XLM / week",
+ recipient: "Kemi Onboarding Support",
+ schedule: "Draft stream ready to launch",
+ status: "draft",
+ },
+ {
+ id: "stream-yusuf",
+ nextAction: "Withdraw",
+ rate: "18 XLM / day",
+ recipient: "Yusuf QA Partnership",
+ schedule: "Ended yesterday with funds available",
+ status: "ended",
+ },
+];
+
+type StreamsPageContentProps = {
+ state?: StreamsViewState;
+ streams?: StreamRowData[];
+};
+
+function StreamListSkeleton() {
+ return (
+
+ {Array.from({ length: 3 }).map((_, index) => (
+
+
+
+
+
+
+
+ ))}
+
+ );
+}
+
+export function StreamsPageContent({
+ state = "populated",
+ streams = mockStreams,
+}: StreamsPageContentProps) {
+ const isEmpty = state === "empty" || streams.length === 0;
+
+ return (
+
+
+
+
{streamListCopy.heading}
+
Manage every stream from one list.
+
{streamListCopy.description}
+
+
+
+ Streams overview
+
+
+ Recipient, rate, status, and the primary next action stay visible at a glance.
+
+
+ {state === "populated" &&
{streamListCopy.populatedCount}
}
+
-
{streamListCopy.heading}
-
Manage every stream from one list.
-
{streamListCopy.description}
-
-
-
- Streams overview
-
-
- Recipient, rate, status, and the primary next action stay visible at a glance.
-
-
- {state === "populated" &&
{streamListCopy.populatedCount}
}
-
@@ -37,9 +69,21 @@ export function StreamRow({ stream }: StreamRowProps) {
-
+
+
+ {errorMsg && (
+
+ {errorMsg}
+
+ )}
+
);
-}
+}
\ No newline at end of file
diff --git a/app/streams/page.tsx b/app/streams/page.tsx
index 86495c28..9f9b5fbe 100644
--- a/app/streams/page.tsx
+++ b/app/streams/page.tsx
@@ -1,5 +1,9 @@
+"use client";
+
+import { useState } from "react";
import { EmptyState } from "../components/EmptyState";
import { StreamRow, type StreamRowData } from "../components/StreamRow";
+import { fetchWithIdempotency } from "../../lib/apiClient";
export type StreamsViewState = "empty" | "loading" | "populated";
@@ -90,8 +94,35 @@ export function StreamsPageContent({
state = "populated",
streams = mockStreams,
}: StreamsPageContentProps) {
+ const [isCreating, setIsCreating] = useState(false);
+ const [errorMsg, setErrorMsg] = useState(null);
+
const isEmpty = state === "empty" || streams.length === 0;
+ const handleCreateStream = async () => {
+ setIsCreating(true);
+ setErrorMsg(null);
+
+ try {
+ await fetchWithIdempotency("/api/streams", {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ rate: "100 XLM / month",
+ recipient: "New Collaborator",
+ }),
+ });
+
+ alert("Stream created successfully!");
+ } catch (error: any) {
+ setErrorMsg(error.message);
+ } finally {
+ setIsCreating(false);
+ }
+ };
+
return (
@@ -100,9 +131,22 @@ export function StreamsPageContent({
Manage every stream from one list.
{streamListCopy.description}
-
+
+
+
+ {errorMsg && (
+
+ {errorMsg}
+
+ )}
+
+
+ {answered} / {total} answered
+ {pct}%
+
+
+
+ {done}/{total} answered
+ {no > 0 && · {no} No}
+ {na > 0 && · {na} N/A}
+
+ );
+}
+
+export function DesignChecklist({ screen }: { screen?: string }) {
+ const [answers, setAnswers] = useState({});
+ const [notes, setNotes] = useState>({});
+ const headingId = useId();
+
+ const answered = Object.values(answers).filter(Boolean).length;
+ const noCount = Object.values(answers).filter((v) => v === "no").length;
+
+ function setAnswer(id: string, value: ChecklistAnswer) {
+ setAnswers((prev: Answers) => ({ ...prev, [id]: value }));
+ }
+
+ function setNote(id: string, value: string) {
+ setNotes((prev: Record) => ({ ...prev, [id]: value }));
+ }
+
+ function handleReset() {
+ setAnswers({});
+ setNotes({});
+ }
+
+ return (
+
+
+
+
+
+ {noCount > 0 && (
+
+ {noCount} item{noCount > 1 ? "s" : ""} marked No — add notes and a ticket reference before handoff.
+
+ )}
+
+
+ {CHECKLIST_SECTIONS.map((section) => (
+ -
+
+
+
{section.title}
+ {section.description && (
+
{section.description}
+ )}
+
+
i.id)}
+ />
+
+ {section.items.map((item, idx) => {
+ const answer = answers[item.id] ?? null;
+ const noteId = `note-${item.id}`;
+ return (
+ -
+
+
+ {idx + 1}
+
+
{item.item}
+
+
setAnswer(item.id, v)} />
+ setAnswer(item.id, v)} />
+ setAnswer(item.id, v)} />
+
+
+
+