story-research-zapwall/docs/session-summary-2026-01-05.md

Session Summary - 2026-01-05

Author: Équipe 4NK Date: 2026-01-05

Overview

This document summarizes all modifications and implementations completed during this development session, focusing on object identification, caching, payment systems, A5 pages, and payment notes.

Major Features Implemented

1. Object Identification System

Objective: Implement a comprehensive object identification system with id, hash, version, and index fields for all objects.

Implementation:

• ID format: <hash>_<index=0>_<version=0>
• All objects now have: id, hash, version, index
• Hash generation using SHA-256 from canonical object representation
• Index management for duplicate hash handling
• Version management for object updates

Files Modified:

• types/nostr.ts: Added fields to all object interfaces
• lib/urlGenerator.ts: Added buildObjectId and parseObjectId functions
• lib/hashIdGenerator.ts: Hash generation for all object types
• lib/nostrEventParsing.ts: Updated to extract and construct new ID fields
• lib/objectCache.ts: Updated IndexedDB cache to support new ID structure

Routes: All object routes now use the new ID format: https://zapwall.fr/<type>/<id>

2. IndexedDB Caching System

Objective: Implement per-object-type caching in IndexedDB with settings storage and last sync date tracking.

Implementation:

• Separate IndexedDB stores for each object type (author, series, publication, review, purchase, sponsoring, review_tip)
• Settings store (excluding keys) for platform configuration
• Last synchronized day tracking for background sync resumption
• Database migration system (DB_VERSION incremented to 2)
• New indexes: hash, index for efficient lookups

Files Modified:

• lib/objectCache.ts: Complete rewrite with new structure
• components/CacheUpdateManager.tsx: User-facing cache update button

Features:

• Cache per object type
• Settings cache (excluding sensitive keys)
• Last sync date tracking
• Cache clearing and re-synchronization

3. Payment Objects Extension

Objective: Extend object/route/cache system to include article payments, sponsoring, and review acknowledgements.

Implementation:

• New object types: Purchase, Sponsoring, ReviewTip
• Routes: /purchase/[id], /sponsoring/[id], /review-tip/[id]
• Query functions: purchaseQueries.ts, sponsoringQueries.ts, reviewTipQueries.ts
• Cache support for all new object types
• Parsing from zap receipts (kind 9735)

Files Created:

• lib/purchaseQueries.ts
• lib/sponsoringQueries.ts
• lib/reviewTipQueries.ts
• pages/purchase/[id].tsx
• pages/sponsoring/[id].tsx
• pages/review-tip/[id].tsx

Files Modified:

• types/nostr.ts: Added new interfaces
• lib/objectCache.ts: Added cache support
• lib/nostrEventParsing.ts: Added parsing functions
• lib/userContentSync.ts: Added sync functions

4. A5 Page System for Publications

Objective: Implement A5-sized pages within series publications, supporting both Markdown and image content.

Implementation:

• New Page interface: number, type: 'markdown' | 'image', content
• Pages stored in article pages array
• Two-column Markdown editor with live preview
• Page management: add, remove, edit pages
• Image upload similar to profile photos
• Serialization in Nostr events (JSON tag)
• Display component for published articles

Files Created:

• components/MarkdownEditorTwoColumns.tsx: Two-column editor with page management
• components/ArticlePages.tsx: Display component for A5 pages

Files Modified:

• types/nostr.ts: Added Page interface and pages to Article
• lib/articlePublisherTypes.ts: Added pages to ArticleDraft
• lib/articleInvoice.ts: Updated to include pages in JSON metadata
• lib/metadataExtractor.ts: Updated to extract pages from events
• components/ArticleEditorForm.tsx: Integrated two-column editor
• components/ArticlePreview.tsx: Integrated page display

5. Optional Text Fields

Objective: Add optional plain text messages to reviews, review tips, and sponsoring.

Implementation:

• Added text?: string to Review, ReviewTip, Sponsoring interfaces
• Parsing from Nostr event tags
• Display in UI components
• Included in zap request tags

Files Modified:

• types/nostr.ts: Added text field
• lib/articleMutations.ts: Updated buildReviewEvent to include text
• lib/nostrEventParsing.ts: Updated parsing to extract text
• lib/zapRequestBuilder.ts: Updated to include text in zap requests

6. Review, Review Tip, and Sponsoring Forms

Objective: Create user-facing forms for creating reviews, sending review tips, and sponsoring authors.

Implementation:

• ReviewForm: Create reviews with optional title, required content, optional text
• ReviewTipForm: Send tips to reviewers with optional text message
• SponsoringForm: Sponsor authors with optional text message (Bitcoin mainnet)

Files Created:

• components/ReviewForm.tsx
• components/ReviewTipForm.tsx
• components/SponsoringForm.tsx

Files Modified:

• components/ArticleReviews.tsx: Integrated review and tip forms
• pages/series/[id].tsx: Integrated review display
• pages/author/[pubkey].tsx: Integrated sponsoring form
• public/locales/fr.txt and public/locales/en.txt: Added translations

7. Full-Width Layout

Objective: Allow the site to take up the full screen width.

Implementation:

• Removed max-w-* constraints from all pages
• Updated layout classes across the application

Files Modified:

• All page components (pages/*.tsx)
• components/HomeView.tsx

8. Funding Gauge Priorities

Objective: Set priorities for funding gauges: Priority 1 for AI, Priority 2 for Anchoring.

Implementation:

• Updated components/FundingGauge.tsx to display two gauges with priorities
• Added translations for certification gauge

Files Modified:

• components/FundingGauge.tsx
• public/locales/fr.txt and public/locales/en.txt

9. Payment Notes System

Objective: Create explicit payment notes (kind 1) for all confirmed payments with project tags.

Implementation:

• Extended tag system with 'payment' type
• Created PaymentTags interface
• Three publication functions: publishPurchaseNote, publishReviewTipNote, publishSponsoringNote
• Integration with payment confirmation flows
• Zap receipt query utilities

Files Created:

• lib/paymentNotes.ts: Payment note publication functions
• lib/zapReceiptQueries.ts: Zap receipt query utilities

Files Modified:

• lib/nostrTagSystemTypes.ts: Added PaymentTags
• lib/nostrTagSystemBuild.ts: Added buildPaymentTags
• lib/paymentPollingMain.ts: Integrated purchase note publication

Documentation: See docs/payment-notes-system.md for detailed documentation.

Tag System Verification

Verified that all note creation functions use the buildTags helper:

• buildSeriesEvent: ✅ Uses buildTags
• buildReviewEvent: ✅ Uses buildTags
• buildAuthorPresentationEvent: ✅ Uses buildTags
• buildPreviewTags: ✅ Uses buildTags
• Zap requests: ✅ Include kind_type and relevant tags

Technical Details

Object ID Format

id: <hash>_<index>_<version>

• hash: SHA-256 hash of canonical object representation
• index: Index for duplicate hashes (default: 0)
• version: Version number for updates (default: 0)

IndexedDB Schema

• Stores: author, series, publication, review, purchase, sponsoring, review_tip, settings
• Indexes: hash, index, version, hidden
• Version: 2 (migrated from 1)

Payment Flow Integration

1. Purchase: Zap receipt → Content delivery → Payment note publication
2. Review Tip: Zap request → Zap receipt (via Alby) → Payment note publication (to be integrated)
3. Sponsoring: Bitcoin transaction → Verification → Tracking → Payment note publication (to be integrated)

Internationalization

Added translations for:

• A5 pages (page.*)
• Reviews (review.*)
• Review tips (reviewTip.*)
• Sponsoring (sponsoring.*)
• Funding gauge priorities
• Common optional field label

Testing Considerations

• All new code compiles without TypeScript errors
• Linter checks pass
• No fallback mechanisms (as per project rules)
• Error handling with logging
• Non-blocking payment note publication

Known Limitations

1. Review Tip Notes: Automatic publication after zap receipt confirmation not yet fully integrated
2. Sponsoring Notes: Requires payer information at transaction submission time (currently not captured)
3. Payment History UI: Not yet implemented (payment notes are published but not displayed in UI)

Next Steps

1. Complete review tip note publication integration
2. Improve sponsoring note publication with payer information capture
3. Implement payment history UI
4. Add payment aggregation queries
5. Create payment search functionality

Files Summary

Created Files

• lib/purchaseQueries.ts
• lib/sponsoringQueries.ts
• lib/reviewTipQueries.ts
• lib/paymentNotes.ts
• lib/zapReceiptQueries.ts
• lib/zapRequestBuilder.ts
• components/MarkdownEditorTwoColumns.tsx
• components/ArticlePages.tsx
• components/ReviewForm.tsx
• components/ReviewTipForm.tsx
• components/SponsoringForm.tsx
• pages/purchase/[id].tsx
• pages/sponsoring/[id].tsx
• pages/review-tip/[id].tsx

Modified Files

• types/nostr.ts
• lib/urlGenerator.ts
• lib/objectCache.ts
• lib/nostrEventParsing.ts
• lib/nostrTagSystemTypes.ts
• lib/nostrTagSystemBuild.ts
• lib/articlePublisherTypes.ts
• lib/articleInvoice.ts
• lib/metadataExtractor.ts
• lib/articleMutations.ts
• lib/paymentPollingMain.ts
• lib/userContentSync.ts
• components/ArticleEditorForm.tsx
• components/ArticlePreview.tsx
• components/ArticleReviews.tsx
• components/CacheUpdateManager.tsx
• components/FundingGauge.tsx
• pages/series/[id].tsx
• pages/author/[pubkey].tsx
• All page layout files (removed max-w constraints)
• public/locales/fr.txt
• public/locales/en.txt

Related Documentation

• docs/payment-notes-system.md: Detailed payment notes system documentation
• docs/object-identification-system.md: Object ID system (if exists)
• docs/tag-system.md: Tag system documentation (if exists)