From 9e0b7367307d863eca649c3219a41160424e6cb4 Mon Sep 17 00:00:00 2001
From: jarik2014 <jarik2014@users.noreply.github.com>
Date: Fri, 25 Sep 2026 11:37:25 +0000
Subject: [PATCH] feat: add 'add to calendar' (.ics) action for stream end
 dates (#566)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add an accessible 'Calendar' button on /stream/[id] that downloads a
standard RFC 5545 .ics invitation for a bounded stream's end date:

- lib/calendar.ts — buildStreamEndIcs (UTC timestamps, TEXT escaping,
  75-octet line folding, deterministic UID, VALARM reminder) and
  downloadIcs (Blob + anchor download with object-URL cleanup)
- components/stream/AddToCalendarButton.tsx — icon button matching the
  PDF header button, aria-label, success/failure toasts
- rendered only when info.endTime > 0 (open-ended streams have no date
  to schedule)
- tests: lib/calendar.test.ts (27), AddToCalendarButton.test.tsx (7),
  StreamPage calendar-action presence/absence (2)
- CHANGELOG entry, CalendarPlus lucide mock stub

Closes #566
---
 CHANGELOG.md                                  |   4 +
 __mocks__/lucide-react.tsx                    |   1 +
 app/stream/[id]/__tests__/page.test.tsx       |  50 ++++
 app/stream/[id]/page.tsx                      |  12 +
 components/stream/AddToCalendarButton.tsx     | 110 ++++++++
 .../__tests__/AddToCalendarButton.test.tsx    | 103 ++++++++
 lib/calendar.test.ts                          | 250 ++++++++++++++++++
 lib/calendar.ts                               | 180 +++++++++++++
 8 files changed, 710 insertions(+)
 create mode 100644 components/stream/AddToCalendarButton.tsx
 create mode 100644 components/stream/__tests__/AddToCalendarButton.test.tsx
 create mode 100644 lib/calendar.test.ts
 create mode 100644 lib/calendar.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b128c6e..0c8ad91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,10 @@ All notable changes are documented here. Format based on [Keep a Changelog](http
   and export controls (#555)
 - `/stream/[id]` — **PDF** button triggers `window.print()` to produce a formatted single-stream
   summary document via the print stylesheet; actions and back-link hidden in print view (#571)
+- `/stream/[id]` — **Calendar** button downloads a standard `.ics` invitation for the stream's
+  end date (one-hour event, one-hour reminder, deterministic UID so re-importing updates the
+  existing entry instead of duplicating it), built by the new `lib/calendar.ts`; rendered only
+  for bounded streams, since an open-ended stream has no end date to schedule (#566)
 - `app/globals.css` — `@media print` block scoped to `.print-receipt` class: resets body
   to white/black, collapses table borders, hides interactive chrome, preserves monospace
   addresses and amounts, renders status badges in monochrome, adds a print footer with the
diff --git a/__mocks__/lucide-react.tsx b/__mocks__/lucide-react.tsx
index 7821913..9779f72 100644
--- a/__mocks__/lucide-react.tsx
+++ b/__mocks__/lucide-react.tsx
@@ -28,6 +28,7 @@ export const AlertCircle   = createIconStub('AlertCircle');
 export const ArrowDownToLine = createIconStub('ArrowDownToLine');
 export const ArrowLeft     = createIconStub('ArrowLeft');
 export const ArrowRight    = createIconStub('ArrowRight');
+export const CalendarPlus  = createIconStub('CalendarPlus');
 export const Check         = createIconStub('Check');
 export const CheckCircle   = createIconStub('CheckCircle');
 export const Clock         = createIconStub('Clock');
diff --git a/app/stream/[id]/__tests__/page.test.tsx b/app/stream/[id]/__tests__/page.test.tsx
index 3078d67..69f3c99 100644
--- a/app/stream/[id]/__tests__/page.test.tsx
+++ b/app/stream/[id]/__tests__/page.test.tsx
@@ -45,6 +45,14 @@ vi.mock('@/components/stream/StreamActions', () => ({
   StreamActions: ({ token }: { token: string }) =>
     React.createElement('div', { 'data-testid': 'stream-actions' }, token),
 }));
+vi.mock('@/components/stream/AddToCalendarButton', () => ({
+  AddToCalendarButton: ({ streamId, endTime }: { streamId: string; endTime: number }) =>
+    React.createElement('div', {
+      'data-testid': 'add-to-calendar',
+      'data-stream-id': streamId,
+      'data-end-time': String(endTime),
+    }),
+}));
 
 import { useWallet } from '@/contexts/WalletContext';
 import { getStreamAddress, getStreamInfo, getWithdrawable } from '@/lib/stream';
@@ -269,4 +277,46 @@ describe('StreamPage (app/stream/[id]/page.tsx)', () => {
     // silently stale "active" state from the first request.
     expect(container.querySelector('[data-testid="badge"]')?.textContent).toBe('cancelled');
   });
+
+  it('#566 — offers the calendar action with the stream end date when the stream is bounded', async () => {
+    mockUseWallet.mockReturnValue({
+      publicKey: 'GRECIPIENT',
+      connected: true,
+    } as unknown as ReturnType<typeof useWallet>);
+    mockAddr.mockResolvedValue('STREAM_ADDR');
+    const endTime = Math.floor(Date.now() / 1000) + 3600;
+    mockInfo.mockResolvedValue(makeInfo({ endTime }));
+    mockWithdrawable.mockResolvedValue(0n);
+
+    await act(async () => {
+      root.render(React.createElement(StreamPage));
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    const action = container.querySelector('[data-testid="add-to-calendar"]');
+    expect(action).not.toBeNull();
+    expect(action?.getAttribute('data-stream-id')).toBe('42');
+    expect(action?.getAttribute('data-end-time')).toBe(String(endTime));
+  });
+
+  it('#566 — omits the calendar action for an open-ended stream (nothing to schedule)', async () => {
+    mockUseWallet.mockReturnValue({
+      publicKey: 'GRECIPIENT',
+      connected: true,
+    } as unknown as ReturnType<typeof useWallet>);
+    mockAddr.mockResolvedValue('STREAM_ADDR');
+    mockInfo.mockResolvedValue(makeInfo({ endTime: 0 }));
+    mockWithdrawable.mockResolvedValue(0n);
+
+    await act(async () => {
+      root.render(React.createElement(StreamPage));
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(container.querySelector('[data-testid="add-to-calendar"]')).toBeNull();
+  });
 });
diff --git a/app/stream/[id]/page.tsx b/app/stream/[id]/page.tsx
index 89cc865..2f0b48a 100644
--- a/app/stream/[id]/page.tsx
+++ b/app/stream/[id]/page.tsx
@@ -14,6 +14,7 @@ import { StreamFlowChart } from "@/components/stream/StreamFlowChart";
 import { StreamActions } from "@/components/stream/StreamActions";
 import { OperatorInfo } from "@/components/stream/OperatorInfo";
 import { StreamNoteEditor } from "@/components/stream/StreamNoteEditor";
+import { AddToCalendarButton } from "@/components/stream/AddToCalendarButton";
 import { useWallet } from "@/contexts/WalletContext";
 import { useStreamNote } from "@/hooks/useStreamNote";
 import {
@@ -293,6 +294,17 @@ export default function StreamPage() {
             <FileText className="w-3.5 h-3.5" aria-hidden="true" />
             PDF
           </button>
+          {/* Add the stream's end date to an external calendar (#566) — only
+              bounded streams have an end date to schedule. */}
+          {info.endTime > 0 && (
+            <AddToCalendarButton
+              streamId={id}
+              endTime={info.endTime}
+              startTime={info.startTime}
+              streamAddress={streamAddress}
+              tokenSymbol={tokenSymbol}
+            />
+          )}
         </div>
       </div>
 
diff --git a/components/stream/AddToCalendarButton.tsx b/components/stream/AddToCalendarButton.tsx
new file mode 100644
index 0000000..bbb3404
--- /dev/null
+++ b/components/stream/AddToCalendarButton.tsx
@@ -0,0 +1,110 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { CalendarPlus, Check } from 'lucide-react';
+import toast from 'react-hot-toast';
+
+import {
+  buildStreamEndIcs,
+  downloadIcs,
+  streamEndIcsFilename,
+} from '@/lib/calendar';
+
+interface AddToCalendarButtonProps {
+  /** Stream id as it appears in the URL. */
+  streamId: string;
+  /** Stream end time in unix seconds — the date the event is built for. */
+  endTime: number;
+  /** Stream start time in unix seconds, when known. */
+  startTime?: number;
+  /** On-chain stream contract address, when known. */
+  streamAddress?: string;
+  /** Display symbol of the streamed token, when it resolves. */
+  tokenSymbol?: string;
+  /** URL of the stream page, when one can be built. */
+  appUrl?: string;
+}
+
+/**
+ * "Add to calendar" action for a stream's end date (#566).
+ *
+ * Downloads a standard `.ics` invitation for the stream's completion date so a
+ * recipient can set a reminder without re-entering the date. Rendered by
+ * `/stream/[id]` only for bounded streams — an open-ended stream has no end
+ * date to schedule.
+ */
+export function AddToCalendarButton({
+  streamId,
+  endTime,
+  startTime,
+  streamAddress,
+  tokenSymbol,
+  appUrl,
+}: AddToCalendarButtonProps) {
+  const [saved, setSaved] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const mounted = useRef(true);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, []);
+
+  function handleClick() {
+    try {
+      const ics = buildStreamEndIcs({
+        streamId,
+        endTime,
+        startTime,
+        streamAddress,
+        tokenSymbol,
+        // Only meaningful on the client, and only used at click time.
+        appUrl:
+          appUrl ??
+          (typeof window !== 'undefined'
+            ? `${window.location.origin}/stream/${streamId}`
+            : undefined),
+      });
+      downloadIcs(streamEndIcsFilename(streamId), ics);
+
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      setSaved(true);
+      timeoutRef.current = setTimeout(() => {
+        if (mounted.current) setSaved(false);
+        timeoutRef.current = null;
+      }, 2500);
+
+      toast.success('Calendar file downloaded');
+    } catch {
+      // Reached for open-ended streams (endTime === 0) or a blocked download —
+      // say so instead of failing silently.
+      toast.error('Could not create the calendar file.');
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded text-xs font-medium border border-gray-300 dark:border-gray-700 text-black dark:text-white hover:bg-gray-50 dark:hover:bg-gray-900 transition-colors print:hidden"
+      aria-label="Add stream end date to calendar"
+      title="Download an .ics file for the stream end date"
+    >
+      {saved ? (
+        <Check
+          className="w-3.5 h-3.5 text-green-600 dark:text-green-400"
+          aria-hidden="true"
+        />
+      ) : (
+        <CalendarPlus className="w-3.5 h-3.5" aria-hidden="true" />
+      )}
+      {saved ? 'Saved' : 'Calendar'}
+    </button>
+  );
+}
diff --git a/components/stream/__tests__/AddToCalendarButton.test.tsx b/components/stream/__tests__/AddToCalendarButton.test.tsx
new file mode 100644
index 0000000..e1bd9b9
--- /dev/null
+++ b/components/stream/__tests__/AddToCalendarButton.test.tsx
@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import toast from 'react-hot-toast';
+
+import { AddToCalendarButton } from '../AddToCalendarButton';
+import { downloadIcs } from '@/lib/calendar';
+
+// The download itself is exercised in lib/calendar.test.ts — here the component's
+// wiring is what matters, so capture the call instead of touching the DOM plumbing.
+vi.mock('@/lib/calendar', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/lib/calendar')>();
+  return { ...actual, downloadIcs: vi.fn() };
+});
+
+vi.mock('react-hot-toast', () => ({
+  default: { success: vi.fn(), error: vi.fn() },
+}));
+
+const END = 1767225600; // 2026-01-01T00:00:00Z
+const mockDownloadIcs = vi.mocked(downloadIcs);
+
+describe('AddToCalendarButton', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders an accessible action for the stream end date', () => {
+    render(<AddToCalendarButton streamId="42" endTime={END} />);
+
+    const button = screen.getByRole('button', { name: 'Add stream end date to calendar' });
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveTextContent('Calendar');
+  });
+
+  it('downloads an .ics file named after the stream, containing the end date', () => {
+    render(<AddToCalendarButton streamId="42" endTime={END} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add stream end date to calendar' }));
+
+    expect(mockDownloadIcs).toHaveBeenCalledTimes(1);
+    const [filename, ics] = mockDownloadIcs.mock.calls[0];
+    expect(filename).toBe('stream-42-end.ics');
+    expect(ics).toContain('DTSTART:20260101T000000Z');
+    expect(ics).toContain('SUMMARY:Stream #42 completes');
+    expect(toast.success).toHaveBeenCalledWith('Calendar file downloaded');
+  });
+
+  it('links back to the stream page on the current origin', () => {
+    render(<AddToCalendarButton streamId="42" endTime={END} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add stream end date to calendar' }));
+
+    const [, ics] = mockDownloadIcs.mock.calls[0];
+    expect(ics).toContain(`URL:${window.location.origin}/stream/42`);
+  });
+
+  it('passes the stream metadata through to the event', () => {
+    render(
+      <AddToCalendarButton
+        streamId="7"
+        endTime={END}
+        startTime={END - 3600}
+        streamAddress="CSTREAMADDRESS"
+        tokenSymbol="XLM"
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add stream end date to calendar' }));
+
+    const [, ics] = mockDownloadIcs.mock.calls[0];
+    // Unfold continuation lines before substring-matching folded content.
+    const unfolded = (ics as string).replace(/\r\n /g, '');
+    expect(unfolded).toContain('Token: XLM');
+    expect(unfolded).toContain('Contract: CSTREAMADDRESS');
+  });
+
+  it('shows the saved state after a download and keeps its label stable', () => {
+    render(<AddToCalendarButton streamId="42" endTime={END} />);
+    const button = screen.getByRole('button', { name: 'Add stream end date to calendar' });
+
+    fireEvent.click(button);
+
+    expect(button).toHaveTextContent('Saved');
+    expect(button).toHaveAccessibleName('Add stream end date to calendar');
+  });
+
+  it('reports a failure instead of downloading when the stream has no end date', () => {
+    render(<AddToCalendarButton streamId="42" endTime={0} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add stream end date to calendar' }));
+
+    expect(mockDownloadIcs).not.toHaveBeenCalled();
+    expect(toast.error).toHaveBeenCalledWith('Could not create the calendar file.');
+  });
+
+  it('unmounts cleanly while the saved state is pending', () => {
+    const { unmount } = render(<AddToCalendarButton streamId="42" endTime={END} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Add stream end date to calendar' }));
+
+    expect(() => unmount()).not.toThrow();
+    cleanup();
+  });
+});
diff --git a/lib/calendar.test.ts b/lib/calendar.test.ts
new file mode 100644
index 0000000..b77d8b8
--- /dev/null
+++ b/lib/calendar.test.ts
@@ -0,0 +1,250 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  buildStreamEndIcs,
+  downloadIcs,
+  escapeIcsText,
+  foldIcsLine,
+  streamEndIcsFilename,
+  toIcsTimestamp,
+} from './calendar';
+
+// 2026-01-01T00:00:00Z — a fixed end date so every assertion is deterministic.
+const END = 1767225600;
+const NOW = 1767225000; // 2025-12-31T23:50:00Z
+
+describe('toIcsTimestamp', () => {
+  it('formats unix seconds as an iCalendar UTC timestamp', () => {
+    expect(toIcsTimestamp(END)).toBe('20260101T000000Z');
+  });
+
+  it('drops sub-second precision, which some clients reject', () => {
+    expect(toIcsTimestamp(END + 0.75)).toBe('20260101T000000Z');
+  });
+
+  it('renders the epoch instead of throwing on zero', () => {
+    expect(toIcsTimestamp(0)).toBe('19700101T000000Z');
+  });
+});
+
+describe('escapeIcsText', () => {
+  it('escapes the characters RFC 5545 reserves', () => {
+    expect(escapeIcsText('a,b;c\\d')).toBe('a\\,b\\;c\\\\d');
+  });
+
+  it('escapes newlines so they cannot terminate the content line', () => {
+    expect(escapeIcsText('line one\nline two')).toBe('line one\\nline two');
+    expect(escapeIcsText('line one\r\nline two')).toBe('line one\\nline two');
+  });
+
+  it('leaves ordinary text alone', () => {
+    expect(escapeIcsText('Stream #42 completes')).toBe('Stream #42 completes');
+  });
+});
+
+describe('foldIcsLine', () => {
+  it('leaves lines of 75 octets or fewer untouched', () => {
+    const line = 'A'.repeat(75);
+    expect(foldIcsLine(line)).toBe(line);
+  });
+
+  it('folds a long line with space-prefixed continuations of at most 75 octets', () => {
+    const folded = foldIcsLine('A'.repeat(200));
+    const parts = folded.split('\r\n');
+    expect(parts.length).toBeGreaterThan(1);
+    for (const part of parts) {
+      expect(part.length).toBeLessThanOrEqual(75);
+    }
+    // Every continuation line starts with the single unfolding space.
+    for (const part of parts.slice(1)) {
+      expect(part.startsWith(' ')).toBe(true);
+    }
+  });
+
+  it('round-trips: unfolding restores the original line', () => {
+    const line = `DESCRIPTION:${'long contract address '.repeat(12)}`;
+    const unfolded = foldIcsLine(line).replace(/\r\n /g, '');
+    expect(unfolded).toBe(line);
+  });
+});
+
+describe('streamEndIcsFilename', () => {
+  it('names the file after the stream', () => {
+    expect(streamEndIcsFilename('42')).toBe('stream-42-end.ics');
+  });
+
+  it('strips characters that are unsafe in a file name', () => {
+    expect(streamEndIcsFilename('../../etc/passwd')).toBe('stream-etcpasswd-end.ics');
+  });
+
+  it('falls back to a generic name when nothing usable is left', () => {
+    expect(streamEndIcsFilename('///')).toBe('stream-unknown-end.ics');
+  });
+});
+
+describe('buildStreamEndIcs', () => {
+  it('builds a complete VCALENDAR for the stream end date', () => {
+    const ics = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW });
+
+    expect(ics).toBe(
+      [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        'PRODID:-//Conduit Protocol//StreamFi//EN',
+        'CALSCALE:GREGORIAN',
+        'METHOD:PUBLISH',
+        'BEGIN:VEVENT',
+        'UID:stream-42-end@streamfi',
+        'DTSTAMP:20251231T235000Z',
+        'DTSTART:20260101T000000Z',
+        'DTEND:20260101T010000Z',
+        'SUMMARY:Stream #42 completes',
+        // The description exceeds 75 octets, so it is folded (RFC 5545 §3.1).
+        'DESCRIPTION:Stream #42 completes and its remaining balance becomes withdraw',
+        ' able.',
+        'TRANSP:TRANSPARENT',
+        'BEGIN:VALARM',
+        'TRIGGER:-PT1H',
+        'ACTION:DISPLAY',
+        'DESCRIPTION:Stream #42 completes in one hour',
+        'END:VALARM',
+        'END:VEVENT',
+        'END:VCALENDAR',
+      ]
+        .join('\r\n')
+        .concat('\r\n'),
+    );
+  });
+
+  it('uses CRLF line endings everywhere — bare LF breaks strict clients', () => {
+    const ics = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW });
+    expect(ics.replace(/\r\n/g, '')).not.toContain('\n');
+    expect(ics.endsWith('\r\n')).toBe(true);
+    expect(ics.startsWith('BEGIN:VCALENDAR\r\n')).toBe(true);
+  });
+
+  it('schedules a one-hour block that starts at the end time', () => {
+    const ics = buildStreamEndIcs({ streamId: '7', endTime: END, now: NOW });
+    expect(ics).toContain(`DTSTART:${toIcsTimestamp(END)}`);
+    expect(ics).toContain(`DTEND:${toIcsTimestamp(END + 3600)}`);
+  });
+
+  it('carries a stable UID so a re-import updates the existing event', () => {
+    const first = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW });
+    const second = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW + 86_400 });
+    const uidOf = (ics: string) => ics.split('\r\n').find((l) => l.startsWith('UID:'));
+
+    expect(uidOf(first)).toBe('UID:stream-42-end@streamfi');
+    expect(uidOf(second)).toBe(uidOf(first));
+  });
+
+  it('includes the token, contract address, start date and link when they are known', () => {
+    const ics = buildStreamEndIcs({
+      streamId: '42',
+      endTime: END,
+      startTime: END - 86_400,
+      streamAddress: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAHHAGK4VC',
+      tokenSymbol: 'XLM',
+      appUrl: 'https://app.example/stream/42',
+      now: NOW,
+    });
+
+    // Unfold continuation lines before substring-matching folded content.
+    const unfolded = ics.replace(/\r\n /g, '');
+    expect(unfolded).toContain('Token: XLM');
+    expect(unfolded).toContain('Contract: CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQAHHAGK4VC');
+    expect(unfolded).toContain('Stream started: 2025-12-31T00:00:00.000Z');
+    expect(unfolded).toContain('URL:https://app.example/stream/42');
+  });
+
+  it('folds the long description instead of writing an over-long line', () => {
+    const ics = buildStreamEndIcs({
+      streamId: '42',
+      endTime: END,
+      streamAddress: 'C'.repeat(60),
+      now: NOW,
+    });
+    for (const line of ics.split('\r\n')) {
+      expect(line.length).toBeLessThanOrEqual(75);
+    }
+    expect(ics.replace(/\r\n /g, '')).toContain(`Contract: ${'C'.repeat(60)}`);
+  });
+
+  it('escapes reserved characters in the summary', () => {
+    const ics = buildStreamEndIcs({
+      streamId: 'id;with,reserved\\chars',
+      endTime: END,
+      now: NOW,
+    });
+    const summary = ics.split('\r\n').find((l) => l.startsWith('SUMMARY:'));
+    expect(summary).toBe('SUMMARY:Stream #id\\;with\\,reserved\\\\chars completes');
+  });
+
+  it('omits the URL line when no link can be built', () => {
+    const ics = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW });
+    expect(ics).not.toContain('URL:');
+  });
+
+  it.each([
+    ['an open-ended stream', 0],
+    ['a negative end time', -1],
+    ['a NaN end time', Number.NaN],
+    ['an infinite end time', Number.POSITIVE_INFINITY],
+  ])('refuses to build an event for %s', (_label, endTime) => {
+    expect(() => buildStreamEndIcs({ streamId: '42', endTime, now: NOW })).toThrow(
+      /no end date/i,
+    );
+  });
+
+  it('names the stream in the error so the caller can report which one failed', () => {
+    expect(() => buildStreamEndIcs({ streamId: '99', endTime: 0, now: NOW })).toThrow(
+      'stream #99',
+    );
+  });
+});
+
+describe('downloadIcs', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it('creates a text/calendar blob, clicks a download link and cleans up', () => {
+    const createObjectURL = vi.fn(() => 'blob:mock-url');
+    const revokeObjectURL = vi.fn();
+    vi.stubGlobal('URL', { ...URL, createObjectURL, revokeObjectURL });
+
+    const ics = buildStreamEndIcs({ streamId: '42', endTime: END, now: NOW });
+    const clicked: string[] = [];
+    const clickSpy = vi
+      .spyOn(HTMLAnchorElement.prototype, 'click')
+      .mockImplementation(function (this: HTMLAnchorElement) {
+        clicked.push(this.download);
+      });
+
+    downloadIcs('stream-42-end.ics', ics);
+
+    expect(createObjectURL).toHaveBeenCalledTimes(1);
+    const blob = createObjectURL.mock.calls[0][0] as Blob;
+    expect(blob.type).toBe('text/calendar;charset=utf-8');
+    expect(blob.size).toBe(ics.length);
+    expect(clicked).toEqual(['stream-42-end.ics']);
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+    // The temporary anchor is removed again — the DOM is left as it was found.
+    expect(document.querySelectorAll('a[download]')).toHaveLength(0);
+  });
+
+  it('revokes the object URL after the click so the download still starts', () => {
+    const revoke = vi.fn();
+    vi.stubGlobal('URL', { ...URL, createObjectURL: vi.fn(() => 'blob:mock-url'), revokeObjectURL: revoke });
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {});
+    vi.useFakeTimers();
+    try {
+      downloadIcs('stream-42-end.ics', 'BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n');
+      expect(revoke).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(1000);
+      expect(revoke).toHaveBeenCalledWith('blob:mock-url');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
diff --git a/lib/calendar.ts b/lib/calendar.ts
new file mode 100644
index 0000000..b351bac
--- /dev/null
+++ b/lib/calendar.ts
@@ -0,0 +1,180 @@
+/**
+ * Calendar-event (.ics) generation for stream end dates (#566).
+ *
+ * `/stream/[id]` surfaces a bounded stream's end date through `StreamTimeline`,
+ * but there was no way to carry that date into an external calendar — a
+ * recipient waiting on a stream to complete (for accounting, invoicing, a
+ * reminder) had to re-type it by hand.
+ *
+ * `buildStreamEndIcs` turns the on-chain end timestamp into an RFC 5545
+ * iCalendar document that Google Calendar, Apple Calendar and Outlook all
+ * import, and `downloadIcs` hands it to the browser as a file download.
+ *
+ * Only bounded streams have something to schedule: an open-ended stream
+ * (`endTime === 0`) has no end date, so building an event for it throws rather
+ * than writing a bogus 1970 timestamp into somebody's calendar.
+ */
+
+/** Product identifier required by RFC 5545 — names the app the event came from. */
+const PRODID = '-//Conduit Protocol//StreamFi//EN';
+
+/** The event is scheduled as a one-hour block starting at the stream end time. */
+const EVENT_DURATION_S = 3600;
+
+/** Reminder that precedes the event by one hour. */
+const ALARM_TRIGGER = '-PT1H';
+
+export interface StreamCalendarEventInput {
+  /** Numeric stream id exactly as it appears in the URL (`/stream/42` → `"42"`). */
+  streamId: string;
+  /** Stream end time in unix seconds. Required — open-ended streams have none. */
+  endTime: number;
+  /** Stream start time in unix seconds; added to the description when known. */
+  startTime?: number;
+  /** On-chain stream contract address; added to the description when known. */
+  streamAddress?: string;
+  /** Display symbol of the streamed token, when it resolves. */
+  tokenSymbol?: string;
+  /** Page URL of the stream, when one can be built. */
+  appUrl?: string;
+  /**
+   * Timestamp (unix seconds) used for `DTSTAMP`. Injectable so tests can assert
+   * the exact document instead of chasing the wall clock.
+   */
+  now?: number;
+}
+
+/**
+ * Escape a value for an iCalendar TEXT field (RFC 5545 §3.3.11): backslash,
+ * semicolon, comma and newlines must be escaped, and a raw newline would
+ * otherwise terminate the content line and corrupt the document.
+ */
+export function escapeIcsText(value: string): string {
+  return value
+    .replace(/\\/g, '\\\\')
+    .replace(/;/g, '\\;')
+    .replace(/,/g, '\\,')
+    .replace(/\r?\n/g, '\\n');
+}
+
+/**
+ * Unix seconds → iCalendar UTC timestamp (`20261001T120000Z`).
+ *
+ * Sub-second precision is dropped: RFC 5545 DATE-TIME with the `Z` suffix is
+ * second-resolution, and a malformed fractional part makes some clients reject
+ * the whole file.
+ */
+export function toIcsTimestamp(unixSeconds: number): string {
+  return new Date(unixSeconds * 1000)
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * Fold a content line at 75 octets with a leading-space continuation
+ * (RFC 5545 §3.1). Everything written here is ASCII, so octets and characters
+ * line up; long contract addresses in the description are the reason this exists.
+ */
+export function foldIcsLine(line: string): string {
+  if (line.length <= 75) return line;
+  const folded = [line.slice(0, 75)];
+  let rest = line.slice(75);
+  while (rest.length > 0) {
+    // A continuation line carries a leading space, so only 74 octets of payload fit.
+    folded.push(` ${rest.slice(0, 74)}`);
+    rest = rest.slice(74);
+  }
+  return folded.join('\r\n');
+}
+
+/** File name for the downloaded invitation, safe for every filesystem. */
+export function streamEndIcsFilename(streamId: string): string {
+  const safeId = String(streamId).replace(/[^A-Za-z0-9_-]/g, '');
+  return `stream-${safeId || 'unknown'}-end.ics`;
+}
+
+/**
+ * Build the `.ics` document for a stream's end date.
+ *
+ * @throws Error when the stream has no usable end time (open-ended streams), so
+ * callers can surface a real message instead of importing a 1970 event.
+ */
+export function buildStreamEndIcs(input: StreamCalendarEventInput): string {
+  const { streamId, endTime, startTime, streamAddress, tokenSymbol, appUrl } = input;
+
+  if (typeof endTime !== 'number' || !Number.isFinite(endTime) || endTime <= 0) {
+    throw new Error(
+      `Cannot build a calendar event for stream #${streamId}: it has no end date (open-ended stream).`,
+    );
+  }
+
+  const dtstamp = toIcsTimestamp(Math.floor(input.now ?? Date.now() / 1000));
+
+  const descriptionParts = [
+    `Stream #${streamId} completes and its remaining balance becomes withdrawable.`,
+  ];
+  if (tokenSymbol) descriptionParts.push(`Token: ${tokenSymbol}`);
+  if (startTime !== undefined && startTime > 0) {
+    descriptionParts.push(`Stream started: ${new Date(startTime * 1000).toISOString()}`);
+  }
+  if (streamAddress) descriptionParts.push(`Contract: ${streamAddress}`);
+
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    `PRODID:${PRODID}`,
+    'CALSCALE:GREGORIAN',
+    'METHOD:PUBLISH',
+    'BEGIN:VEVENT',
+    // Deterministic UID: re-importing the same stream updates the existing event
+    // instead of piling up duplicates.
+    `UID:stream-${streamId}-end@streamfi`,
+    `DTSTAMP:${dtstamp}`,
+    `DTSTART:${toIcsTimestamp(endTime)}`,
+    `DTEND:${toIcsTimestamp(endTime + EVENT_DURATION_S)}`,
+    `SUMMARY:${escapeIcsText(`Stream #${streamId} completes`)}`,
+    `DESCRIPTION:${escapeIcsText(descriptionParts.join('\n'))}`,
+    'TRANSP:TRANSPARENT',
+  ];
+
+  if (appUrl) lines.push(`URL:${escapeIcsText(appUrl)}`);
+
+  lines.push(
+    'BEGIN:VALARM',
+    `TRIGGER:${ALARM_TRIGGER}`,
+    'ACTION:DISPLAY',
+    `DESCRIPTION:${escapeIcsText(`Stream #${streamId} completes in one hour`)}`,
+    'END:VALARM',
+    'END:VEVENT',
+    'END:VCALENDAR',
+  );
+
+  // CRLF is mandatory in iCalendar; some clients silently reject bare LF.
+  return lines.map(foldIcsLine).join('\r\n') + '\r\n';
+}
+
+/**
+ * Trigger a browser download of an `.ics` document.
+ *
+ * Kept here rather than in the component so the DOM plumbing is testable on its
+ * own (jsdom has no real download).
+ */
+export function downloadIcs(filename: string, ics: string): void {
+  const blob = new Blob([ics], { type: 'text/calendar;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  link.rel = 'noopener';
+  link.style.display = 'none';
+  document.body.appendChild(link);
+  try {
+    link.click();
+  } finally {
+    document.body.removeChild(link);
+    // Release the object URL once the browser has had a chance to start the
+    // download — revoking synchronously can cancel it in some browsers.
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  }
+}