{ "@context": "https://schema.org", "@type": "WebApplication", "@id": "https://pointcast.xyz/sparrow", "name": "Sparrow", "description": "A hosted reader client for PointCast. Tune in at dawn — the broadcast arrives at your perch. Sibling of Magpie (the publisher); Sparrow reads what Magpie and others have pushed into the PointCast graph.", "url": "https://pointcast.xyz/sparrow", "applicationCategory": "CommunicationApplication", "operatingSystem": "Any (web)", "license": "MIT", "version": "0.38", "protocol_version": "0.38", "sibling_of": "https://pointcast.xyz/magpie", "routes": { "home": "/sparrow", "about": "/sparrow/about", "deck": "/sparrow/deck", "connect": "/sparrow/connect", "channel": "/sparrow/ch/", "block_reader": "/sparrow/b/", "saved": "/sparrow/saved", "friends": "/sparrow/friends", "friends_activity": "/sparrow/friends/activity", "signals": "/sparrow/signals", "tv": "/sparrow/tv", "tv_channel": "/sparrow/tv/ch/", "tv_friends": "/sparrow/tv/friends", "federation_json": "/sparrow/federation.json", "digest_subscribe_api": "/api/sparrow/digest-subscribe", "manifest": "/sparrow.json", "atom": "/sparrow/feed.xml", "latest_api": "/sparrow/api/latest.json", "pwa_manifest": "/sparrow/manifest.webmanifest", "service_worker": "/sparrow/sw.js" }, "companion_app": { "name": "Sparrow.app", "role": "native macOS menu-bar companion", "platform": "macOS 13+", "language": "Swift 5.9", "distribution": "source (github.com/mhoydich/sparrow-app)", "landing": "https://pointcast.xyz/sparrow/connect", "repository": "https://github.com/mhoydich/sparrow-app", "polls": "/sparrow/api/latest.json", "default_poll_interval_seconds": 300, "poll_range_seconds": [ 30, 3600 ], "features": [ "Menu-bar ✦ glyph; ember new-count appears when fresh blocks arrive", "Notification Center alerts (one per block up to 3; digest beyond)", "Preferences panel — feed URL, poll interval, notifications toggle", "LSUIElement: no Dock icon, no Cmd-Tab presence", "First-run seeds last-seen store from archive (no alert avalanche)" ], "privacy": "Opens one network connection to the configured feed URL. No telemetry, no phone-home." }, "deck": { "url": "/sparrow/deck", "format": "single-page technical memorandum", "typography": "EB Garamond · Courier Prime · Space Mono", "palette": "cream paper · oxblood stamp · CRT phosphor · weathered ink", "sections": [ "abstract", "1.0 introduction", "2.0 system architecture", "3.0 user interface", "4.0 keyboard protocol", "5.0 data model", "6.0 implementation notes", "7.0 future work", "references", "appendix A · manifest surface", "appendix B · AI image prompts for figure plates" ], "print_ready": true, "document_code": "SPA-TM-26-0421" }, "pwa": { "installable": true, "manifest": "/sparrow/manifest.webmanifest", "service_worker": { "url": "/sparrow/sw.js", "scope": "/sparrow/", "version": "sparrow-v0.19.0" }, "cache_policy": { "shell": "stale-while-revalidate (home, about, saved, 9 channel pages, manifest, atom feed)", "block_readers": "cache-first, max 48 entries, LRU-style trim", "assets": "cache-first, max 120 entries (Astro hashed assets + per-block OG images + Google Fonts)", "non_sparrow": "network-only (SW does not shadow the rest of pointcast.xyz)" }, "offline_fallback": { "mode": "navigation-only", "chrome": "inline Sparrow-styled HTML shipped with the SW so cold cache first-visit still lands" }, "install_triggers": [ "browser-native beforeinstallprompt event surfaces \"install ↓\" button in the HUD + a larger CTA on /sparrow/about", "app shortcuts pre-seeded in the manifest: Front Door, Saved, About" ] }, "reading_list": { "storage": "localStorage", "key": "sparrow:saved", "shape": "string[] — array of block IDs, newest-added first", "sync": "none in v0.3; v0.6 plans Nostr kind-7 cross-device sync via NIP-44" }, "visited_list": { "storage": "localStorage", "key": "sparrow:visited", "shape": "string[] — array of block IDs, newest-visited first, max 120", "ui_signal": ".is-visited class on [data-sp-block-id] — softens title + adds \"read\" chip" }, "reactions": { "storage": "localStorage", "key": "sparrow:reactions", "shape": "{ [blockId: string]: Array<\"ember\" | \"moss\" | \"lilac\"> }", "kinds": [ { "id": "ember", "label": "lit", "glyph": "🔥", "accent": "var(--sp-ember)" }, { "id": "moss", "label": "evergreen", "glyph": "🌿", "accent": "var(--sp-moss)" }, { "id": "lilac", "label": "rare", "glyph": "💜", "accent": "var(--sp-lilac)" } ], "ui": "Three-chip toolbar on /sparrow/b/, below the article body. Each chip toggles; active picks pulse their accent ring.", "emit_policy": "On ADD only (v0.8). Deletion does not emit a kind-5 delete event yet — deferred to v0.9 alongside cross-device sync." }, "nostr": { "client_protocol": "NIP-07 (window.nostr.signEvent)", "event_kind": 7, "tag_convention": [ [ "r", "https://pointcast.xyz/b/", "canonical block URL the reaction targets" ], [ "t", "sparrow" ], [ "t", "sparrow-" ], [ "client", "sparrow", "https://pointcast.xyz/sparrow" ] ], "content": "Unicode glyph for the chosen kind (🔥 | 🌿 | 💜).", "relay_pool": { "storage_key": "sparrow:nostr-relays", "default": [ "wss://relay.damus.io", "wss://relay.primal.net", "wss://nos.lol" ], "transport": "WebSocket — one connection per emit, fire-and-forget with 4s timeout" }, "pubkey_cache": { "storage_key": "sparrow:nostr-pubkey", "note": "Cached hex x-only pubkey after first getPublicKey(); Sparrow never persists secret material." }, "emitted_log": { "storage_key": "sparrow:nostr-emitted", "shape": "{ [`${blockId}:${kind}`]: { id: string, at: number } }", "purpose": "Prevents accidental re-broadcast on hydrate/reload. v0.9 also uses this as the target for kind-5 retractions (points at the original event id)." }, "ui_states": [ "local", "available", "connected", "emitting" ], "aggregation": { "enabled": true, "modes": { "reader": { "mechanism": "One REQ per [data-sp-reactions] panel", "filter": { "kinds": [ 7 ], "#r": [ "https://pointcast.xyz/b/" ], "limit": 200 }, "count_ui": ".sp-react-count badge appended to each reaction chip", "since": "v0.9" }, "reel": { "mechanism": "One REQ per relay with every visible block URL in #r (bulk fan-in)", "filter": { "kinds": [ 7 ], "#r": [ "https://pointcast.xyz/b/", "https://pointcast.xyz/b/", "..." ], "limit": 500 }, "count_ui": "Compact \"🔥 3 · 🌿 1\" row painted into .sp-r-foot on each receipt (.sp-r-react-counts). Hidden until at least one pick lands.", "scope": "Any page with [data-sp-block-id] receipts outside a [data-sp-reactions] panel — index, channel, saved, drawer, etc.", "since": "v0.10" } }, "deduplication": "By Nostr event.id (Set per blockId × kind), shared state between reader + reel paint paths", "kind_resolution": "Glyph-in-content first (🔥/🌿/💜); t=sparrow- tag as fallback for non-glyph reactions", "cleanup": "beforeunload closes every open WebSocket — no leaks across navigation", "signer_required": false }, "unreact": { "event_kind": 5, "tag_convention": [ [ "e", "" ], [ "k", "7" ], [ "t", "sparrow" ], [ "client", "sparrow", "https://pointcast.xyz/sparrow" ] ], "trigger": "On reaction REMOVE, only when sparrow:nostr-emitted has a prior event id for this blockId:kind", "content": "sparrow: unreact" }, "cross_device_sync": { "since": "v0.21", "event_kind": 30078, "d_tag": "sparrow-reader-state-v1", "encryption": "NIP-44 self-encryption (window.nostr.nip44.encrypt(selfPubkey, plaintext)); only the same npub can decrypt", "payload": "JSON body — same shape as /reader-state POST: { saved, visited, reactions }, each with { value, updated_at }", "opt_in_storage": "localStorage[\"sparrow:sync-enabled\"] (\"1\" | \"0\")", "throttle": "at most one relay push per 4 seconds (sparrow:sync-last-emitted-at floor) plus the 1.2s debounce stacked on top of the 600ms LAN mirror debounce", "pull_strategy": "On page load (when enabled) + on signer connect, one REQ per relay filtered by {kinds:[30078], authors:[self], #d:[sparrow-reader-state-v1], limit:1}. Newest created_at across relays wins; merge applied per top-level key via the same MIRROR_KEYS apply callbacks the LAN mirror uses.", "coexistence": "Nostr sync and the LAN peer-node mirror are orthogonal — both run when enabled. On save/visit/react, scheduleReaderMirror() fires both the LAN push and (if enabled) the Nostr push. On load, mirrorPull() populates from the LAN peer; subscribeNostrSync() then merges in anything newer from the relay pool.", "requires": [ "NIP-07 signer connected (window.nostr.getPublicKey)", "NIP-44 support on the signer (window.nostr.nip44.{encrypt,decrypt}) — nos2x, Alby recent builds" ], "ui_toggle": ".sp-sync-toggle pill in the HUD · states: unavailable (no signer / no NIP-44) · off · on", "not_shipped_yet": "Cross-device conflict UX beyond newest-wins; per-key opt-out (e.g. \"sync saved only\"); key rotation after an NIP-44 change" }, "participation": { "since": "v0.31", "surface": "/sparrow/friends (top of page, before publisher + following list)", "components": { "getting_started": { "steps": [ "signer: has a NIP-07 pubkey cached (sparrow:nostr-pubkey)", "public: sparrow:public-saved-enabled === \"1\"", "follow: sparrow:friends[] has at least one entry", "ambient: sparrow:ambient-enabled === \"1\" (optional)" ], "ui": "ordered list · ○ default, ✓ on done · moss color when complete · \"N of 4 steps done\" meta · repaints on any storage change via window.addEventListener(\"storage\",…) cross-tab" }, "share_invite": { "surface": "card below getting-started, shown only when signer is connected", "link_shape": "${origin}/sparrow/friends?follow=", "copy_button": "navigator.clipboard.writeText with execCommand fallback; ✓ copied feedback for 1.6s" }, "starters": { "surface": "card below invite", "storage": "hard-coded STARTERS array in the page — scaffold only, edit this array to curate", "one_click_follow": "+ follow button writes to sparrow:friends[] with the starter alias", "hides_when": "every starter is already followed, or the entire list is empty" }, "follow_deep_link": { "param": "?follow=", "accepts_both": "parsePubkey normalizes to hex — same codec the add-form uses", "behavior": "pre-fills the add-form pubkey input + scrolls into view + pulses the submit button (\"follow →\") for 2 cycles. User still clicks to confirm — no silent follow.", "no_op_when": "already following, or param is malformed" }, "opml_round_trip": { "surface": "dashed panel inside the \"people I'm following\" card", "export": { "filename": "sparrow-friends-.opml", "element_shape": "\" xmlUrl=\"nostr:\" htmlUrl=\"/sparrow/friends?follow=\" x-sparrow-pubkey=\"\" x-sparrow-muted=\"true|absent\" />", "root": " with carrying title/dateCreated/ownerName/docs → /sparrow.json" }, "import": { "accepts": ".opml, .xml, application/xml, text/xml", "parser": "DOMParser · walks every · prefers x-sparrow-pubkey attr, falls back to npubToHex(xmlUrl match)", "merge": "union with existing sparrow:friends[]; preserves mute state via x-sparrow-muted", "privacy": "entirely client-side — no upload leaves the browser beyond the user-initiated file selection" } } }, "why_this_sprint": "The federation surface shipped end-to-end from v0.22 → v0.30 but had no obvious on-ramp. v0.31 collapses the \"now what?\" gap between first page load and actually seeing friends' reads." }, "federated_lists": { "since": "v0.22", "surface": "/sparrow/friends", "publisher": { "opt_in_storage": "localStorage[\"sparrow:public-saved-enabled\"] (\"1\" | \"0\")", "event_kind": 30078, "d_tag": "sparrow-public-saved-v1", "encryption": "none — content is clear JSON so any follower can read without a signer", "payload_shape": { "schema": "sparrow-public-saved-v1", "saved": { "value": "string[] · saved block ids (newest-saved first, capped at 240)", "updated_at": "ISO 8601 — mirrors sparrow:saved:updated_at" }, "profile": { "client": "\"sparrow\"", "client_url": "\"https://pointcast.xyz/sparrow\"", "version": "\"0.22\"" } }, "throttle": "shares the 4s floor with private sync (sparrow:public-saved-last-emitted-at), runs on the same scheduleReaderMirror() debounce", "scope_guarantee": "ONLY the saved list is in this event — visited state, reactions, and private kind-30078 (sparrow-reader-state-v1) stay untouched. Visibility is a separate consent from cross-device sync." }, "consumer": { "friends_storage": "localStorage[\"sparrow:friends\"] · Array<{ pubkey: \"64-hex\", alias?: string (≤40 chars) }>", "subscribe_filter": "{ kinds: [30078], authors: , \"#d\": [\"sparrow-public-saved-v1\"], limit: friends.length * 2 }", "dedup_policy": "newest created_at per author wins; earlier events ignored", "title_resolution": "server ships a { [id]: {id, title, dek, channel, type} } lookup for every non-draft block in the Astro content collection; client hydrates each saved id against it. Blocks absent from the current Sparrow build render as \"unknown block · not in this Sparrow build\" with a dead-but-valid link.", "render_cap": "first 24 block receipts per author; \"+ N more\" footer if the list is longer" }, "accepted_formats": "v0.23 · pubkey input accepts both 64-hex AND npub1… (NIP-19 bech32). parsePubkey() in /sparrow/friends normalizes to lowercase hex. Self-pubkey display in the HUD + publisher signature line also renders as short-npub1 instead of hex.", "privacy_story": "Two distinct opt-ins: cross-device sync (v0.21, NIP-44 self-encrypted) and public saved list (v0.22, unencrypted). Either can be on without the other. No visited/reaction data ever leaves the device unencrypted.", "profile_lookup": { "since": "v0.23", "event_kind": 0, "subscribe_filter": "{ kinds: [0], authors: , limit: friends.length }", "cache_storage": "localStorage[\"sparrow:profiles\"] — { [hex]: { name?, display_name?, picture?, nip05?, nip05_verified?, nip05_verified_at?, fetched_at } }", "ttl_ms": 86400000, "fields_read": [ "name", "display_name", "picture", "nip05" ], "alias_priority": "local alias (sparrow:friends[].alias) > kind-0 display_name > kind-0 name > nothing", "render": "friends list + feed card header both show the resolved display name; a 🛰 glyph appears next to names sourced from the relay so users can tell what's local vs federated" }, "picture_rendering": { "since": "v0.24", "storage_gate": "kind-0 `picture` accepted only when /^https?:\\/\\//i.test(value), capped at 400 chars", "render_element": "", "placeholder": "sp-friends-pic-placeholder span with a ✦ glyph when no picture is known", "sizes": { "list": "28px circle", "feed_card": "18px inline" }, "why_no_proxy": "Loading via Cloudflare/image proxy would add a TTL layer but also cost bandwidth + privacy. Lazy + no-referrer gets 90% of the benefit." }, "friends_motion": { "since": "v0.26", "watcher": { "transport": "persistent WebSocket REQ per relay (never limited, never closed until beforeunload)", "filter": "{ kinds:[30078], authors:, \"#d\":[\"sparrow-public-saved-v1\"], since: }", "since_policy": "bootTime = Math.floor(Date.now() / 1000) on script run → only events newer than the current tab fire toasts", "dedup": "Set so the same event seen across multiple relays only toasts once", "gated_on": [ "sparrow:friends non-empty", "sparrow:friends-motion-disabled !== \"1\"", "friend not flagged muted" ] }, "toast": { "container": "aside.sp-motion-toasts fixed bottom-right; column-reverse stack", "max_visible": 3, "ttl_ms": 7000, "shape": "avatar + \" · just saved · № \" — click opens the block, × dismisses", "animation": "sp-motion-in 260ms (slide-from-right + fade) on mount, sp-motion-out 300ms on leave", "profile_source": "same sparrow:profiles cache populated by /sparrow/friends (one-pass hydration)" }, "chime": { "opt_in_storage": "localStorage[\"sparrow:friends-chime-enabled\"] (\"1\" | \"0\")", "sound": "two overlapping sine oscillators (A5 880Hz + E6 1318.5Hz) · exponential fade · ~450ms total · Web Audio only · no asset request", "default": "off", "scope": "plays only alongside a toast — never on historical events, never when friend is muted" }, "disable_all": "localStorage[\"sparrow:friends-motion-disabled\"] === \"1\" short-circuits the watcher entirely (keeps toasts off for privacy-minded sessions without unfollowing)" }, "per_friend_mute": { "since": "v0.26", "storage_shape_change": "sparrow:friends[] now accepts an optional `muted: boolean` field on each entry; legacy entries without the field are treated as unmuted", "applied_in": [ "/sparrow/friends subscribe filter", "/sparrow/friends feed render", "/sparrow dashboard lane", "SparrowLayout live motion watcher" ], "ui": "🔈 mute / 🔇 unmute button per row · row fades to 45% opacity when muted · \"muted\" pill next to the pubkey", "why_not_unfollow": "unfollow is destructive (loses the alias, loses future reinstate) — mute lets users quiet noisy signers without losing track of them" }, "signals": { "since": "v0.28", "surface": "/sparrow/signals", "subscribe_filter": "{ kinds:[30078], authors:, \"#d\":[\"sparrow-public-saved-v1\"], limit: friends.length * 2 }", "newest_per_author": "Map keyed by pubkey — only latest created_at per friend is aggregated, matching the rest of the federation surface", "panels": { "top_co_saved": { "purpose": "blocks saved by 2+ followed signers — overlap is the signal", "min_count": 2, "cap": 12, "sort": "count desc, then block id asc for stability", "shows_savers": "up to 4 saver names inline + \"+N\" overflow" }, "recent_adds": { "purpose": "friends who published a fresh saved list in the last 7 days", "window_seconds": 604800, "row": "avatar · name · \"published N · Xh ago\" · freshest saved receipt", "sort": "event created_at desc" }, "channel_distribution": { "purpose": "where attention is aggregated right now", "computation": "sum distinct saves per channel across all newest-per-author lists; proportional bar against total", "row": "channel code · name · bar · count → links to /sparrow/ch/" } }, "shared_state": "reads the same sparrow:profiles cache + block lookup the rest of /sparrow federation surfaces use; no extra round-trips", "first_picker_attribution": { "since": "v0.29", "computation": "among current savers of a block, the one whose newest kind-30078 event has the earliest created_at wins the ⭐ attribution", "caveat": "kind-30078 is replaceable — this reflects \"most recently re-published\" per author, not the true first-save moment; across a group re-publishing regularly, the pattern stabilizes", "surface": "top co-saved panel: ⭐ chip in the savers row" }, "export_json": { "since": "v0.29", "trigger": "⤓ export JSON button in the signals nav", "filename": "sparrow-signals-.json", "schema": "sparrow-signals-v1", "payload_keys": [ "generated_at", "boot_origin", "friends[]", "relays[]", "newest_events[]", "top_co_saved[]", "notes" ], "privacy_posture": "bundle contains pubkeys + aliases + profile metadata the user already has cached locally; no secret material. Entirely client-side Blob download." }, "not_yet": "opt-in email digest (still requires sidecar worker infra — now the ONLY remaining v0.28 bundle item)" }, "native_ambient": { "since": "v0.33", "source": "/Users/michaelhoydich/sparrow-app/Sources/SparrowApp/{NostrRelayClient.swift, FriendsService.swift}", "reads_from": "UserDefaults[\"sparrow.readerState\"] (the SparrowServer peer-node storage; v0.32 mirror extension writes friends + profiles here)", "subscriptions": { "ambient": "kinds:[20078] · authors: · #t:[\"sparrow-presence\"] · since: ", "saved": "kinds:[30078] · authors: · #d:[\"sparrow-public-saved-v1\"] · limit: authors*2 (closed on EOSE)" }, "freshness_window_s": 90, "decay_cadence_s": 20, "tray_ui": "MenuBarController.setFriendsPresence(count, aliases) adds a \"✦ N here · alias1, alias2, +K\" menu item above the separator. Hidden when count is zero.", "not_yet": "NIP-01 kind-0 profile lookup inside the native app (so aliases can auto-populate); NIP-05 verification; avatar image rendering in the tray", "trust_model": "Relay events are not signature-verified inside the native app yet — same posture as the web client. Future sprint can add secp256k1 verification in Swift." }, "ambient_friends": { "since": "v0.30", "opt_in_storage": "localStorage[\"sparrow:ambient-enabled\"] (\"1\" | \"0\")", "publisher": { "event_kind": 20078, "tags": "[[\"t\",\"sparrow-presence\"], [\"client\",\"sparrow\",...], [\"expiration\", ]]", "content": "empty — presence is the fact of emission, not the payload", "cadence": "broadcast every 60s (AMBIENT_BROADCAST_MS) while the tab is foregrounded; re-emits on visibilitychange → visible", "fan_out": "short-lived WebSocket per relay, EVENT frame, 3s timeout", "why_ephemeral": "kind 20078 is in the 20000-29999 NIP-16 ephemeral range — relays relay in real-time but don't persist. Presence is moot the instant it's stale." }, "subscriber": { "filter": "{ kinds:[20078], authors:, \"#t\":[\"sparrow-presence\"], since: }", "fresh_window_ms": 90000, "render": "fixed bottom-left .sp-ambient strip · ✦ here now label + up to 8 avatars + \"+N\" overflow; hidden when nobody's fresh", "decay_tick": "setInterval(15s) repaints so avatars drop off as they exceed AMBIENT_FRESH_MS", "mute_respected": "friend.muted filtered at ingest + paint" }, "privacy_story": "Publishing announces your liveness to the public relay pool; off by default. Not publishing still lets you see ambient friends (subscription is passive)." }, "digest_sidecar": { "since": "v0.30", "status": "v0.32: endpoint live (ack only · no cron yet)", "signup_ui": "/sparrow/signals weekly-digest panel", "storage_key": "sparrow:digest-subscription", "subscription_shape": { "schema": "sparrow-digest-subscription-v1", "email": "string · user-supplied", "frequency": "\"weekly\" | \"biweekly\" | \"monthly\"", "npub": "hex pubkey or null (from sparrow:nostr-pubkey)", "relays": "string[] · copies getRelays() so the worker can re-aggregate from the same relay pool", "created_at": "ISO 8601" }, "endpoint": "POST /api/sparrow/digest-subscribe (v0.32 · Cloudflare Pages Function)", "responses": { "202": "intent accepted · stored in SPARROW_DIGEST_KV if bound", "400": "malformed body (invalid JSON, unknown schema, bad email, bad frequency)", "413": "body exceeds 8 KB" }, "kv_binding": "SPARROW_DIGEST_KV · optional · when missing, responses still 202 with { stored: false, note } so the client stops retrying", "unsubscribe": { "since": "v0.33", "endpoint": "DELETE /api/sparrow/digest-subscribe", "modes": { "local-clear": { "header": "x-unsub-intent: local-clear", "body": "{ email }", "response": "200 { ok, removed, mode, note }", "auth": "none — web-initiated from a browser that just cleared sparrow:digest-subscription; same-user implicit trust" }, "token-verified": { "since": "v0.34", "header": "x-unsub-token: .. · also accepted as ?unsub_token query param so email-footer links work from any browser", "token_shape": "...\">", "ttl_seconds": 2592000, "response": "200 { ok, removed, email, mode } on verify · 410 on expired · 400 on malformed/bad-hmac/missing-secret", "signing_key_env": "SPARROW_DIGEST_SIGNING_KEY · must be bound with the same value on BOTH the Pages Function and the cron worker so the footer links the worker signs verify here", "helpers": "workers/sparrow-digest/src/signing.ts is the canonical implementation (signUnsubToken, verifyUnsubToken, buildUnsubUrl). The Pages Function inlines a byte-identical verify helper because Pages + Workers are separate deploy targets.", "rotation": "rotating SPARROW_DIGEST_SIGNING_KEY invalidates all outstanding tokens; subscribers get a new token on the next digest send", "constant_time_compare": "HMAC comparison uses a constant-time equal to avoid timing-oracle leakage of the correct HMAC prefix" } } }, "cron_worker": { "since": "v0.33", "status": "v0.36 · dead-letter bucket live (3-strike threshold + immediate on non-retriable); /ops/dead-letter + /ops/release routes (bearer-token gated). Full signals aggregation (co-saves + channel distribution) planned for v0.37 after it got rolled back during branch churn.", "location": "workers/sparrow-digest/ (wrangler.toml + src/{index,signing,send,nostr}.ts + README.md)", "schedule": "0 8 * * 1 (Mondays 08:00 UTC) — biweekly/monthly gates applied per-subscriber based on last_sent_at", "transport": "MailChannels · retry-with-jitter: 3 attempts max, exponential backoff with full jitter (800ms/1600ms/3200ms ceilings). 5xx + 429 + 408 retriable; 401/403/422 fail-fast and do not touch last_sent_at (ops can redeploy and the next cron tick retries).", "kv_binding": "SPARROW_DIGEST_KV (shared with the Pages Function)", "signing_binding": "SPARROW_DIGEST_SIGNING_KEY (shared with the Pages Function)", "nostr_client": "workers/sparrow-digest/src/nostr.ts — URLSessionWebSocketTask-style WebSocket client ported from sparrow-app/Sources/SparrowApp/NostrRelayClient.swift. collectFromRelay + collectAcrossRelays + newestPerAuthorByDTag helpers. 6s timeout per relay, 500-event safety cap. No signature verification yet — downstream re-filters by author.", "email_body_v035": "Subscribers with npub + relays: live fetch of their kind-3 contact list + kind-30078 saved events across their relays; surfaces \"N of M followed signers published public saved lists · K total saved-block references.\" Subscribers without npub get a short \"open signals\" prompt.", "dry_run": "GET /dry-run on the worker returns {total, due, now, worker_version:\"v0.35\"} without sending", "not_yet": "full signals aggregation (co-saves + channel distribution mirror) · block-lookup prefetch · native Sparrow.app NIP-01 kind-0 profile lookup · /sparrow/digest preview page", "dead_letter": { "since": "v0.36", "module": "workers/sparrow-digest/src/deadletter.ts", "kv_keys": { "fail:": "consecutive-failure counter · 60-day TTL · cleared on success", "dl:": "dead-letter record · 1-year TTL · persists until /ops/release" }, "thresholds": { "retriable": "3 consecutive retriable failures (5xx/429/408) → dead-letter", "permanent": "any non-retriable failure (401/403/422) → immediate dead-letter" }, "sub_row_untouched": "main sub: subscription row is never deleted; scheduled() just skips dead-lettered entries", "release_path": "POST /ops/release?email= with Bearer SPARROW_OPS_TOKEN clears both dl: and fail: entries" }, "ops_endpoints": { "since": "v0.36", "auth": "Bearer on the Authorization header · missing secret returns 503 ops-not-configured", "routes": { "GET /ops/dead-letter": "{ ok, count, records[], now } · records sorted by dead_lettered_at desc", "POST /ops/release?email=": "{ ok, released } · clears dl: + fail:" }, "token_setup": "wrangler secret put SPARROW_OPS_TOKEN · not bound on the Pages Function (ops is a worker-only concern)" } }, "worker_security_posture": "never holds secret material — stores email + npub + relay list + frequency only. Recomputes signals bundle at send time by subscribing to the same public kind-30078 d-tag the web client uses.", "why_client_first": "We shipped the intent capture + schema doc in v0.30 before the worker went live so early users were queued, not blocked. v0.32 lands the endpoint; v0.33 lands the cron scaffold + DELETE modes; v0.34 lands the actual email dispatch + token signing." }, "federation_json": { "since": "v0.32", "endpoint": "GET /sparrow/federation.json", "schema": "sparrow-federation-v1", "cache_control": "public, max-age=900", "shape": { "schema": "sparrow-federation-v1", "version": "0.32", "curated_at": "ISO date", "starters": "Array<{ hex: 64-hex, alias: string (≤40), note?: string (≤160) }>", "notes": "object · scope + caveat + editing instructions" }, "consumer": "/sparrow/friends fetches on boot; sanitizes entries (requires valid hex); falls back to a 2-item internal seed on fetch failure", "curation_flow": "add a line to starters[] in src/pages/sparrow/federation.json.ts, ship. No friends.astro change needed.", "not_a_whitelist": "Starter seeds are suggestions, not gatekeeping. Follow-/-unfollow is always one click." }, "channel_friends": { "since": "v0.29", "surface": "/sparrow/ch/ (above the main reel)", "scope": "filter friends' saved ids to the server-shipped channelBlockSet for the current channel", "subscribe_filter": "{ kinds:[30078], authors:, \"#d\":[\"sparrow-public-saved-v1\"], limit: friends.length * 2 }", "sort": "count desc, then block id asc for stability", "max_rows": 6, "row": "badge ×N · block № · title · ⭐ first-picker chip", "hides_when": "no followed friends, all muted, or no saves intersect this channel", "opt_out_storage": "localStorage[\"sparrow:ch-friends-hidden\"] === \"1\" hides the panel across every channel page until re-enabled", "lookup_shipped": "{ [id]: { title } } for every block in the current channel only — keeps per-page payload minimal" }, "friends_activity": { "since": "v0.27", "surface": "/sparrow/friends/activity", "subscriptions": { "initial": "{ kinds:[30078], authors:, \"#d\":[\"sparrow-public-saved-v1\"], limit: 50 } — closed on EOSE", "live": "{ kinds:[30078], authors:, \"#d\":[\"sparrow-public-saved-v1\"], since: } — kept open until beforeunload" }, "dedup_strategy": "per-event.id Map so the same event across multiple relays only renders once; author replaceable events land as distinct entries by their event id", "render_policy": "newest-wins sort by created_at desc, capped at 50 visible entries", "per_event_card": "avatar + display name + \"saved N blocks\" + relative timestamp + first 3 saved-block receipts (title + channel chip) + \"+N more\" footer", "new_badge": "events with created_at >= bootTime get .is-new styling (moss border + shadow pulse animation + \"new\" pill). Interval tick demotes them 12s after arrival.", "title_resolution": "server-shipped lookup { [id]: { title, channel, channelName } } for every non-draft block", "share_with": "/sparrow/friends + /sparrow dashboard lane + SparrowLayout motion watcher all read the same sparrow:profiles cache, so avatars/names are one-pass", "mute_respected": "muted friends filtered out of the authors list AND re-checked on ingest (mute can happen mid-subscribe)" }, "friends_lane": { "since": "v0.25", "surface": "/sparrow (dashboard) · between rosette and reel", "max_rows": 6, "sort": "freshest friend event first (created_at desc)", "row_contents": "avatar (kind-0 picture) · display name · \"saved\" · block № · title · channel chip · \"+N more\" (when friend has >1 saved)", "lookup": "inline