add progress history over time support

Author: Henri93

CLAUDE.md

@@ -0,0 +1,68 @@
+# Reader Progress
+
+KOReader-compatible reading progress sync server. Syncs reading position across devices (Kindle/KOReader, Readest on iOS/Android).
+
+## Tech Stack
+- **Framework**: FastAPI + Uvicorn
+- **Language**: Python 3.12
+- **Local DB**: SQLite / PostgreSQL (SQLAlchemy)
+- **AWS DB**: DynamoDB (boto3)
+- **Auth**: HTTP headers (`x-auth-user`, `x-auth-key`) with bcrypt
+- **Testing**: Behave (BDD)
+- **Deploy**: AWS Lambda + CloudFront + DynamoDB via Terraform
+
+## Local Development
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn main:app --reload --port 8080
+# Swagger UI: http://localhost:8080/docs
+```
+
+```bash
+# Or with Docker
+docker compose up -d
+```
+
+## Testing
+```bash
+# Activate the virtual environment first, then run behave
+source .venv/bin/activate
+DB_BACKEND=sql behave
+
+# Run a specific feature file
+DB_BACKEND=sql behave features/progress_history.feature
+```
+
+## Deployment (AWS Lambda)
+```bash
+cd deployment
+./bootstrap.sh          # one-time: creates S3 state bucket
+# copy and edit terraform/terraform.tfvars
+./deploy.sh             # builds Lambda package + applies Terraform
+```
+
+## Key Files
+- `main.py` — all FastAPI endpoints
+- `repositories/protocols.py` — database-agnostic interfaces
+- `repositories/sql.py` — SQLAlchemy implementation
+- `repositories/dynamodb.py` — DynamoDB implementation
+- `auth.py` — authentication helpers
+- `svg_card.py` — public progress card SVG renderer
+- `features/` — Behave BDD test scenarios
+
+## Environment Variables
+- `DB_BACKEND` — `sql` (default) or `dynamodb`
+- `PASSWORD_SALT` — password hashing salt
+- `DATABASE_URL` — SQLite/PostgreSQL connection string
+- `DYNAMODB_USERS_TABLE`, `DYNAMODB_PROGRESS_TABLE` — table names
+- `RATE_LIMIT_ENABLED` — set to `false` during tests
+
+## API Endpoints
+- `POST /users/create` — register
+- `GET /users/auth` — verify credentials
+- `PUT /syncs/progress` — upload progress
+- `GET /syncs/progress` — get progress for a document
+- `POST /documents/link` — link document hashes (same book, different formats)
+- `GET /books` — list all books with progress
+- `GET /card/{username}` — public SVG progress card

README.md

@@ -114,6 +114,7 @@ This creates:
 | `PASSWORD_SALT` | Salt for password hashing (set via Terraform) |
 | `DYNAMODB_USERS_TABLE` | Users table name (set via Terraform) |
 | `DYNAMODB_PROGRESS_TABLE` | Progress table name (set via Terraform) |
+| `DYNAMODB_PROGRESS_HISTORY_TABLE` | Progress history table name (set via Terraform) |
 | `AWS_REGION` | AWS region (set via Terraform) |
 
 ## KOReader Setup
@@ -325,6 +326,49 @@ curl -X PUT http://localhost:8080/syncs/progress \
 |--------|----------|
 | 200 | `{"status": "success"}` |
 
+##### GET `/syncs/progress/{document}/history`
+
+Return reading position at two points in time, useful for seeing how much was read during a session.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `document` | string | Yes (path) | MD5 hash of the document |
+| `start` | integer | Yes (query) | Unix timestamp for the start of the window |
+| `end` | integer | Yes (query) | Unix timestamp for the end of the window |
+
+**At-or-before semantics:** Returns the most recent sync record whose timestamp is ≤ the requested time. If no sync occurred before a given timestamp, that snapshot's fields will be `null`.
+
+```bash
+# What did I read today? (yesterday midnight → now)
+curl "http://localhost:8080/syncs/progress/0b229176d4e8db7f6d2b5a4952368d7a/history?start=1711065600&end=1711152000" \
+  -H "x-auth-user: myuser" \
+  -H "x-auth-key: a029d0df84eb5549c641e04a9ef389e5"
+```
+
+**Response (200):**
+```json
+{
+  "document": "0b229176d4e8db7f6d2b5a4952368d7a",
+  "at_start": {
+    "progress": "/body/DocFragment[10]/body/p[3]/text().0",
+    "percentage": 0.31,
+    "timestamp": 1711027200
+  },
+  "at_end": {
+    "progress": "/body/DocFragment[22]/body/p[22]/text().1001",
+    "percentage": 0.58,
+    "timestamp": 1711148000
+  }
+}
+```
+
+If `at_start.timestamp == at_end.timestamp`, no reading occurred in the queried window. If either snapshot has `null` fields, no history record existed before that timestamp.
+
+| Status | Response |
+|--------|----------|
+| 200 | History response with two snapshots |
+| 400 | `{"detail": "start must be <= end"}` |
+
 ##### GET `/syncs/progress/{document}`
 
 Retrieve the latest progress for a document.

features/book_management.feature

@@ -83,7 +83,7 @@ Feature: Book Management
     When I request the SVG card for user "reader"
     Then the SVG response should succeed
     And the response content type should be "image/svg+xml"
-    And the SVG should contain "Currently Reading"
+    And the SVG should contain "In Progress"
 
   Scenario: SVG card returns valid SVG for user with no books
     When I request the SVG card for user "reader"

features/progress_history.feature

@@ -0,0 +1,73 @@
+Feature: Progress History
+  As a KOReader user
+  I want to query my reading progress at two points in time
+  So that I can see how much I read during a session
+
+  Background:
+    Given a user "reader" with password "readerpass" exists
+
+  Scenario: History records are created when progress is synced
+    When user "reader" updates progress for document "bookA"
+      | progress   | /body/p[10]       |
+      | percentage | 0.10              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    Then user "reader" should have history for document "bookA"
+
+  Scenario: Query returns progress at two points in time
+    Given user "reader" has saved progress for document "book1"
+      | progress   | /body/p[10]       |
+      | percentage | 0.10              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    And user "reader" updates progress for document "book1" after a delay
+      | progress   | /body/p[50]       |
+      | percentage | 0.50              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    When user "reader" queries history for document "book1" around those two syncs
+    Then at_start should show percentage 0.10
+    And at_end should show percentage 0.50
+
+  Scenario: Returns null fields when no history exists before start timestamp
+    Given user "reader" has saved progress for document "book2"
+      | progress   | /body/p[20]       |
+      | percentage | 0.20              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    When user "reader" queries history for document "book2" with start=0 and end=1
+    Then at_start should have null fields
+    And at_end should have null fields
+
+  Scenario: No reading detected when queried window has no new syncs
+    Given user "reader" has saved progress for document "book3"
+      | progress   | /body/p[10]       |
+      | percentage | 0.10              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    When user "reader" queries history for document "book3" with a future window
+    Then at_start and at_end should have the same timestamp
+
+  Scenario: History resolves linked document to canonical hash
+    Given user "reader" has saved progress for document "hashA"
+      | progress   | /body/p[30]       |
+      | percentage | 0.30              |
+      | device     | Kindle            |
+      | device_id  | k-001             |
+    And user "reader" has linked documents "hashA" and "hashB"
+    When user "reader" queries history for document "hashB" up to now
+    Then at_end should have a non-null percentage
+
+  Scenario: start greater than end returns 400
+    When user "reader" queries history for document "anydoc" with start=2000 and end=1000
+    Then the request should fail with status 400
+
+  Scenario: All-books history endpoint returns records in range
+    Given user "reader" has saved progress for document "chartbook"
+      | progress   | /body/p[10] |
+      | percentage | 0.10        |
+      | device     | Kindle      |
+      | device_id  | k-001       |
+    When user "reader" queries all history with start=0 and end=9999999999
+    Then the response should contain a book entry for document "chartbook"
+    And that book entry should have at least 1 record