org.inovus.notifications Private
↗ Repo

# Documentation

Welcome to the Inovus Notifications docs. Pick a starting point below.

I want to… Go here
Learn what this is and how to use it (human-friendly) User guide
Publish from a backend / SPA self-notify Publishing — user JWT = self only; cross-user needs API key / M2M
Wire an app (BFF, npm client, rate limits) App integration
Rate limits / 429 behaviour Rate limiting
Publish a new npm version (changesets) Releasing
Copy-paste brief for a coding agent integrating V2 AGENT.md
Run the Worker on my laptop (API keys → inbox) Local developer testing
Deploy to Cloudflare (DB, Cognito, Worker, CI) Setup guide
Why resource servers / scopes / M2M? (never needed this before) Cognito explained
Easy publish without Cognito M2M Publisher API keys
Production M2M Cognito change (safety, checklists, rollback) Cognito M2M reference
Configure Cognito resource server / M2M publishers (how-to) Cognito setup
Understand why we rebuilt as V2 Why V2 · User guide: Why V2?
Keep legacy /api/Notification/* callers working (product V1) V1 API compatibility · User guide chapter
Current HTTP API /v2/notifications… (product V2) — not /v1
Add a new database backend / compare memory vs Supabase Storage backends
High availability (Workers today + future options) High availability
What V3+ might include (channels, prefs, workflows) Roadmap
Read architecture decisions DESIGN.md
Day-to-day repo commands & invariants CLAUDE.md
Compact client API reference (npm README) packages/client/README.md

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

# Start here by role

# App developer (consume / publish from a product)

  1. User guide — What is this?
  2. User guide — Getting started
  3. User guide — Everyday usage and Publishing
  4. App integration — BFF samples, npm client
  5. Rate limiting — 429 / Retry-After
  6. Hand your coding agent AGENT.md (copy the whole file into its context)

# Platform / ops (new environment from zero)

  1. Local developer testing ← laptop first (optional)
  2. Setup guide — deploy to Cloudflare ← Supabase, Cognito, Worker, CI
  3. Releasing ← npm + Version Packages (after NPM_TOKEN is set)
  4. Rate limiting ← 429 budgets after deploy
  5. Cognito explained ← read if resource servers / M2M are new
  6. Publisher API keys ← easiest publish path (optional)
  7. Cognito M2M reference ← production safety, checklists, rollback
  8. Cognito setup ← click-by-click
  9. User guide — Setup overview
  10. High availability ← what we get today + future options
  11. Roadmap ← V3+ ideas vs modern notification platforms
  12. User guide — Developer reference

# Migrating from V1

  1. Why V2
  2. V1 API compatibility
  3. User guide — V1 compatibility

# All docs in this folder

File Description
userguide/ Progressive user guide (intro → setup → usage → advanced → developers)
app-integration.md SPA + BFF patterns, npm client, links to examples/
rate-limiting.md Worker rate limits: budgets, keys, 429 / Retry-After, wrangler bindings
releasing.md Human guide: changesets (config.json vs .md), Version Packages, npm publish
local-development.md Laptop: memory store, API-key publish, user inbox, optional M2M
setup.md Deploy to Cloudflare: Supabase, Cognito, Worker, GitHub Actions
cognito-explained.md Why resource servers, scopes, M2M clients, client secrets — for teams new to this
api-keys.md Easy publisher API keys (PUBLISHER_API_KEYS + X-Api-Key)
authentication/cognito-m2m-notifications.md Production M2M change: safety assessment, checklists, rotation, rollback, AWS refs
cognito-setup.md Resource server, scopes, app clients, tokens (how-to)
why-v2.md Gap-by-gap V1 → V2 comparison
v1-compatibility.md Legacy HTTP contract and migration notes
adapters.md Memory vs Supabase capabilities; implementing NotificationStore for another DB
high-availability.md Worker multi-isolate HA today; DB / failover / future options
roadmap.md V3+ planning: modern platforms, channels, preferences, workflows (not a commitment)
AGENT.md Copy-paste self-contained brief for app coding agents integrating V2