# Inovus Notifications — User Guide

Welcome. If you need in-app notifications (the kind that live in a bell icon, not fleeting toast popups) and you’re not sure where to start — you’re in the right place.

This guide is written for humans: product folks wiring a feature, app developers integrating a client, and engineers standing up or extending the service. You do not need to understand Cloudflare Workers or Cognito on day one.

Start at the top and stop when you’ve got what you need — or jump via the paths below.

# What you’ll learn

If you want to…	Start here
Understand what this service is and whether it’s for you	What is this?
See the moving parts (API, client, database…)	Components
Know why we rebuilt this as V2	Why V2?
Get something working in your app today	Getting started
Hand a coding agent the integration contract	AGENT.md (copy the whole file)
Run the Worker on a laptop (no Cloudflare deploy)	Local developer testing
Stand up Cognito / Supabase / Cloudflare (from scratch, including DB)	Setup
Use the inbox day-to-day (list, read, React, convenience API)	Everyday usage
Publish from a backend / background job	Publishing
Use a user JWT to publish?	Publishing — Can an app use a user’s JWT?
BFF / edge proxy so API keys stay server-side	App integration
Rate limits / HTTP 429	Rate limiting
Keep old V1 HTTP callers working	V1 compatibility
Go deeper (pagination, retries, metadata, polling)	Advanced usage
Fix 401s, duplicates, “not realtime” confusion…	Troubleshooting
Extend the service, run tests, read the contract	Developer reference
Publish a new npm version	Releasing — changesets, Version Packages, what `.changeset/` contains
High availability / future failover	High availability

# The 30-second pitch

Inovus Notifications is a shared inbox service:

Other apps (or your own backend) publish a notification to a user.
That user sees it in their inbox (bell dropdown, badge count, mark read, delete).
Identity comes from the Cognito tokens you already use — no new login system.
You get a typed npm client so you don’t hand-roll fetch, retries, and polling.

flowchart LR
  Producer["Your backend / M2M app"] -->|publish| API["Notifications API"]
  Browser["User's browser"] -->|list / subscribe| API
  API --> DB[(Supabase Postgres)]
  Browser --> Bell["Your bell UI"]

Tip: Toasts (those temporary “Saved!” banners) are not this service. Keep toast UI in your app. This service is for persistent notifications that belong in an inbox.

# Suggested reading paths

# Show a bell in my React app

What is this? (skim)
Getting started
Everyday usage → React section

# Notify users when a job finishes

Getting started
Publishing — especially dedupeKey
Troubleshooting if anything fails

# Migrate off old Video Library notifications

Why V2?
V1 compatibility
Everyday usage → convenience API
Full gap analysis: why-v2.md

# Deploy / operate the service

Local developer testing (optional laptop first)
Setup — from scratch including the database
Detailed Cloudflare / CI walkthrough: setup.md
Developer reference

# Other docs (deeper / specialised)

Doc	When you need it
Docs index	Catalogue of everything under `/docs`
AGENT.md	Copy-paste brief for a coding agent integrating V2 in an app
Local development	Laptop: memory store, API keys → inbox
Setup guide	Deploy to Cloudflare (DB → Cognito → Worker → CI)
Cognito setup	Resource server, scopes, M2M clients
Cognito explained	Why we need resource servers / M2M (plain language)
Publisher API keys	Easy publish without Cognito M2M
Cognito M2M reference	Production M2M change: safety, checklists, rollback
Why V2 (detailed)	Gap-by-gap comparison with V1
V1 API compatibility	Exact endpoint / envelope contract
Storage backends	Memory vs Supabase; implementing a new database backend
High availability	What Worker HA we get today; future DB / failover options
DESIGN.md	Architecture decisions and invariants
Client package README	Compact API reference for `@inovus-medical/notifications`

Live API docs (when the service is deployed): https://notifications.totumcloud.com/docs