Skip to content

claude.md

Latest commit

 

History

History
184 lines (146 loc) · 5.4 KB

claude.md

File metadata and controls

184 lines (146 loc) · 5.4 KB
Raw

Papers ISBN Importer

A macOS menubar utility that imports books into ReadCube Papers with full metadata lookup from ISBN.

Overview

ReadCube Papers has weak metadata matching for books (it's journal-focused). This tool intercepts the import workflow: you provide an ISBN, it fetches rich metadata from multiple sources, and creates a properly-populated item in your Papers library.

Core Workflow

  1. User activates via menubar icon or global hotkey
  2. User enters ISBN (manual entry, paste, or barcode scan via camera)
  3. Tool queries metadata APIs in priority order:
    • Open Library (openlibrary.org/api)
    • Google Books API
    • Library of Congress
  4. User reviews/edits the fetched metadata
  5. Tool creates item in Papers via their sync API
  6. Optionally attaches a PDF if user provides one

Technical Architecture

Authentication

Papers uses cookie-based auth. Options:

  • Manual cookie extraction: User pastes cookies from browser dev tools (simplest, what the Joplin plugin does)
  • Embedded WebView login: Present Papers login in a WebView, capture cookies automatically (better UX, more complex)

Store credentials securely in macOS Keychain.

Papers API Endpoints

All require cookies: _readcube_session, user_web_token, _readcube-login_token

# Get user's collections (libraries)
GET https://sync.readcube.com/collections/

# Create new item in a collection
POST https://sync.readcube.com/collections/{collectionId}/items
Content-Type: application/json
{"item": { ... metadata ... }}

# Upload/attach PDF (needs investigation - may require separate endpoint)

Item Schema (observed fields)

{
  "item": {
    "title": "Book Title",
    "authors": [
      {"first_name": "First", "last_name": "Last"}
    ],
    "year": "2024",
    "publisher": "Publisher Name",
    "isbn": "9781234567890",
    "item_type": "book",
    "abstract": "Description/summary",
    "pages": "320",
    "language": "en",
    "user_data": {
      "notes": "",
      "tags": []
    }
  }
}

Metadata Sources

Open Library (preferred - no API key required)

GET https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&format=json&jscmd=data

Google Books (good fallback, may need API key for volume)

GET https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn}

Library of Congress (authoritative but slower)

GET https://lccn.loc.gov/2024xxxxx/marcxml

Tech Stack

  • Swift with SwiftUI for menubar UI
  • Combine for async API calls
  • KeychainAccess or native Security framework for credential storage
  • VisionKit for barcode scanning (macOS 13+)

UI Components

Menubar Popover

  • ISBN input field with paste detection
  • "Scan Barcode" button (opens camera sheet)
  • Recent imports list
  • Settings gear

Metadata Review Sheet

  • Editable fields for all metadata
  • Source indicator (which API provided data)
  • Cover image preview if available
  • Collection/folder picker for destination
  • "Import" and "Import + Attach PDF" buttons

Settings

  • Cookie management (paste or WebView login)
  • Default collection selection
  • API key configuration (if using Google Books)
  • Global hotkey assignment

Edge Cases

  • Multiple editions: Present picker if ISBN returns multiple results
  • No results: Allow manual entry, offer to search by title/author
  • Stale cookies: Detect 401 responses, prompt re-authentication
  • Duplicate detection: Check if ISBN already exists in library before import
  • ISBN-10 vs ISBN-13: Normalize to ISBN-13, accept either as input

File Structure

PapersISBNImporter/
├── App/
│   ├── PapersISBNImporterApp.swift
│   ├── AppDelegate.swift
│   └── MenuBarController.swift
├── Views/
│   ├── MainPopoverView.swift
│   ├── MetadataReviewView.swift
│   ├── SettingsView.swift
│   └── BarcodeScannerView.swift
├── Services/
│   ├── PapersAPIClient.swift
│   ├── MetadataService.swift
│   ├── OpenLibraryProvider.swift
│   ├── GoogleBooksProvider.swift
│   └── KeychainService.swift
├── Models/
│   ├── BookMetadata.swift
│   ├── PapersItem.swift
│   └── PapersCollection.swift
└── Utilities/
    ├── ISBNValidator.swift
    └── HTTPClient.swift

Development Phases

Phase 1: Core functionality

  • Manual cookie entry
  • Open Library lookup only
  • Basic item creation
  • Single default collection

Phase 2: Enhanced UX

  • WebView-based login
  • Multiple metadata sources with fallback
  • Collection picker
  • Duplicate detection

Phase 3: Polish

  • Barcode scanning
  • Global hotkey
  • Cover image display
  • PDF attachment support

Open Questions

  1. PDF upload endpoint: Need to trace network requests when manually adding PDF in Papers to find the upload mechanism
  2. Item type taxonomy: What values does Papers accept for item_type? (book, chapter, edited-book, etc.)
  3. Rate limiting: Do the APIs have rate limits we need to respect?
  4. Cookie refresh: How long do Papers cookies remain valid? Is there a refresh mechanism?

References