Skip to content

Added a web app guide and the optional outnote.api helpers - #43

Merged
PianoNic merged 1 commit into
mainfrom
feature/api-helpers
Nov 3, 2026
Merged

PianoNic merged 1 commit into
mainfrom
feature/api-helpers

Conversation

@PianoNic

@PianoNic PianoNic commented Nov 3, 2026

Copy link
Copy Markdown
Owner

Adds a guide to building a native-feeling web app on OutNote, and an optional module that makes the API side easier.

docs/frontend-and-api.md

Uses only normal calls like emails() and chats(), not stream() or SQLiteCache.

  • Frontend: draws saved data first, one startup request, loading ahead, instant actions that undo if refused, offline start, and one database per user.
  • API layer: a per-user cache shown two ways, with outnote.api and without it, so you can own all the code.
  • Rules: user separation, sign-out, several servers, sensitive data and how to choose cache times.

outnote.api

Optional and framework-free, using only the standard library plus OutNote's existing dependencies. import outnote doesn't load it, and a test checks that.

  • ApiCache: answers from memory, refreshes in the background, and merges identical requests. A slow old read can't overwrite a newer write.
  • ClientPool: one client per user, with token requests one at a time per user. It calls your save_token when a refresh token rotates, which previously could only be saved to a file.
  • respond() and error_response(): ETag and 304 handling, and GraphError to a status and Retry-After.

Testing

  • 144 tests pass, including tests/test_api.py, and Ruff and mypy are clean.
  • Both API versions in the guide were extracted from the doc and run as printed, against a fake client with a delay. Each passed 21 cache and API checks.
  • Each also passed the same test in a real browser. With the API delayed by 1.5 s, a return visit drew its list in 70-100 ms. Also checked: 304, instant and undone actions, API down, fully offline, user separation and sign-out clearing.
  • Real token rotation ran on a live account through both versions: 4 rotations each, and a new client worked from the saved token.

Not tested: the complete app against Microsoft, real authentication, many users at once, or several API servers.

The guide shows a native-feeling frontend and an API-layer cache, both with
and without outnote.api. ClientPool saves rotated refresh tokens through
your own function, and ApiCache adds a per-user cache to any framework.
@PianoNic PianoNic added the enhancement New feature or request label Nov 3, 2026
@PianoNic
PianoNic merged commit e51164e into main Nov 3, 2026
3 checks passed
@PianoNic
PianoNic deleted the feature/api-helpers branch November 6, 2026 07:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant