catalogue-server 0.1.0__py3-none-any.whl

catalogue_server/API.md

@@ -0,0 +1,274 @@
+# Book catalogue API (v1)
+
+A catalogue-server site publishes its books, cards, audiobooks and music at
+`/api/v1/` (here `https://catalogue.example.org/api/v1/`). Other sites use it to show
+books, prices for the visitor's country and where to buy them, without keeping
+their own copies. The examples below use made-up data.
+
+- Read-only JSON. `GET`, `HEAD` and `OPTIONS` only; anything else gets `405`.
+- No authentication. CORS is open: `Access-Control-Allow-Origin: *`, so you can call it from
+  browser JavaScript on any site.
+- Responses carry `Cache-Control: public, max-age=3600` (setting `CATALOGUE_API_CACHE_SECONDS`).
+  Cache them on your side too.
+- Text is UTF-8. `description_html` and `purchase.note` contain trusted HTML from the catalogue
+  editors; all other strings are plain text.
+- Errors return `{"detail": "..."}` with a 404 or 405 status.
+
+## Countries and prices
+
+Each book has default buying options (price, shops) plus optional rows for particular
+countries (for example "UK & Ireland" in GBP with UK shops). The `purchase` object in
+every book is already resolved for one country:
+
+1. `?country=XX` (ISO 3166 code, e.g. `GB`, `CZ`) when you pass it, **otherwise**
+2. the country detected from the request: the `country` cookie on the catalogue site,
+   Cloudflare's `CF-IPCountry` header, or a GeoIP lookup of the caller's IP.
+
+**Server-side callers should always pass `country`**: without it, the country is
+detected from *your server's* IP, not your visitor's. Browser calls from your
+visitor's page can leave it out, but passing it is still clearer. `?country=` (empty)
+asks for the international defaults.
+
+`purchase.is_country_specific` tells you whether a country row matched. When it is
+`false`, show the defaults as general "Buying options" and link to the
+distributors page (`https://catalogue.example.org/books/distributors/`).
+
+## Endpoints
+
+### `GET /api/v1/books/`
+
+All published books (editions), ordered by work and edition.
+
+| Parameter | Meaning |
+|-----------|---------|
+| `language` | Language code(s), comma-separated: `en`, `cs,sk` |
+| `country` | ISO country for `purchase` (see above) |
+| `work` | Work slug(s): all editions of a title, e.g. `movement-and-focus` |
+| `format` | `book`, `ebook`, `audiobook`, `cards`, `music`, `other` (comma-separated) |
+| `slug` | Book slug(s), comma-separated, in any order |
+| `q` | Text search in title, subtitle, author, descriptions, ISBN and work title |
+| `limit`, `offset` | Paging; `limit` defaults to 50, max 200 |
+
+```bash
+curl 'https://catalogue.example.org/api/v1/books/?language=en&country=GB'
+curl 'https://catalogue.example.org/api/v1/books/?work=movement-and-focus&country=CZ'
+curl 'https://catalogue.example.org/api/v1/books/?slug=quiet-river,forest-notes&country=US'
+curl 'https://catalogue.example.org/api/v1/books/?format=music'
+curl 'https://catalogue.example.org/api/v1/books/?q=training&limit=10&offset=10'
+```
+
+Response:
+
+```json
+{
+  "count": 16,
+  "limit": 50,
+  "offset": 0,
+  "country": "GB",
+  "results": [ { "...book..." } ]
+}
+```
+
+### `GET /api/v1/books/<slug>/`
+
+One book, same shape as in the list. Accepts `country`.
+
+```bash
+curl 'https://catalogue.example.org/api/v1/books/movement-and-focus/?country=GB'
+```
+
+```json
+{
+  "slug": "movement-and-focus",
+  "title": "Movement and Focus",
+  "subtitle": "Attention in everyday movement",
+  "author": "Ann Author",
+  "language": "en",
+  "format": "book",
+  "work": {"slug": "movement-and-focus", "title": "Movement and Focus"},
+  "short_description": "A practical guide to bringing attention into training and competition, ...",
+  "description_html": "<p>In this book the author ...</p>",
+  "isbn": "978-3-89532-213-6",
+  "publisher": "Example Press",
+  "year": null,
+  "pages": 220,
+  "cover_url": "https://catalogue.example.org/media/catalogue/movement-and-focus.jpg",
+  "images": ["https://catalogue.example.org/media/catalogue/movement-and-focus-3d.png"],
+  "url": "https://catalogue.example.org/books/movement-and-focus/",
+  "external_url": "https://publisher.example.org/movement-and-focus/",
+  "editions": [
+    {"slug": "pohyb-a-soustredeni", "language": "cs", "title": "Pohyb a soustředění", "format": "book",
+     "url": "https://catalogue.example.org/books/pohyb-a-soustredeni/"}
+  ],
+  "purchase": {
+    "country": "GB",
+    "is_country_specific": true,
+    "region_label": "UK & Ireland",
+    "currency": "GBP",
+    "price": "16.99",
+    "formatted_price": "£16.99",
+    "best_offer": {
+      "shop": "Example Books UK", "distributor": "example-books-uk",
+      "url": "https://books-uk.example/product/...", "countries": ["GB", "IE"],
+      "region_label": "Great Britain & Ireland", "price": "13.99", "currency": "GBP",
+      "formatted_price": "£13.99", "in_stock": true, "last_seen": "2026-10-22T06:00:00+00:00"
+    },
+    "offers": [{"shop": "Example Books UK", "...": "..."}, {"shop": "Worldwide Books", "...": "..."}],
+    "other_offers": [{"shop": "Example Books US", "countries": ["US"], "...": "..."}],
+    "store_links": [
+      {"label": "Example Books UK", "url": "https://books-uk.example/product/..."},
+      {"label": "Worldwide Books", "url": "https://worldwide.example.org/books/123"}
+    ],
+    "note": "<p>Also at Watkins Books ...</p>",
+    "available_from": null,
+    "streaming_links": [],
+    "distributors": [
+      {"name": "Example Books UK", "url": "https://books-uk.example",
+       "region_label": "Great Britain & Ireland", "kind": "retail"}
+    ]
+  }
+}
+```
+
+Field notes:
+
+- `slug` is stable; store it if you link a page on your site to a catalogue book.
+- `work` groups editions of the same title (translations, audiobook, new editions); it is
+  `null` for a standalone title. `editions` lists the other published editions in the work.
+- `url` is the book's page on the catalogue site (a dedicated page when one exists,
+  otherwise the generated one).
+- `cover_url` and `images` are absolute URLs; `cover_url` is `""` when there is no image.
+- `year`, `pages` may be `null`; other missing values are `""`.
+- `purchase.price` is a string as entered (`"16.99"`, `"17,95"`, `"Free"`); show
+  `formatted_price`, which adds the currency symbol. It is `""` when no price is known.
+- `purchase.available_from` is an ISO date or `null`. Only worth showing when it is in the future.
+- `purchase.offers`: the shops delivering to that country, best first (in stock, shops in the
+  country before shops sending there, a distributor before other shops, cheapest).
+  A distributor delivers to its own countries, or to its `ships_to` list when that is known.
+  Without a country they are the shops selling everywhere. `other_offers` are all the other
+  shops. `best_offer` is the first offer; when no shop delivers to the country it is the best
+  shop anywhere, and `best_offer_ships` says whether it delivers there: `true`, `false`, or
+  `null` when unknown (or no country) — show a warning unless it is `true`. Shop prices come from the distributors' online shops (`last_seen`
+  is when they were last read; `null` for links entered by hand) and are in the shop's
+  `currency`; `price` is a decimal string or `null`, `in_stock` is `null` when unknown.
+- `purchase.store_links`: `offers` as `[{label, url}]`, kept for older clients.
+- `purchase.streaming_links`: `[{label, url}]`, for music.
+- `purchase.distributors`: retail distributors serving that country that have no offer for the
+  book (empty without a country).
+
+### `GET /api/v1/works/`
+
+Every work with its published editions.
+
+```bash
+curl 'https://catalogue.example.org/api/v1/works/'
+```
+
+```json
+{"count": 16, "results": [
+  {"slug": "movement-and-focus", "title": "Movement and Focus", "books": [
+    {"slug": "movement-and-focus", "language": "en", "title": "Movement and Focus", "format": "book",
+     "url": "https://catalogue.example.org/books/movement-and-focus/"}
+  ]}
+]}
+```
+
+### `GET /api/v1/distributors/?country=XX[&kind=retail|trade]`
+
+Published distributors and shops. With `country`, those serving that country followed by worldwide
+ones (`countries: ["*"]`); without it, all of them. `kind=trade` are the wholesalers for
+bookshops ("For booksellers"). `page_url` is the distributor's page on the catalogue site
+(with the books it sells and their prices); `url` is its own website.
+
+```bash
+curl 'https://catalogue.example.org/api/v1/distributors/?country=AU'
+curl 'https://catalogue.example.org/api/v1/distributors/?kind=trade'
+```
+
+```json
+{"country": "AU", "count": 3, "results": [
+  {"name": "Example Books Australia", "slug": "example-books-australia",
+   "url": "https://www.bookshop.example.au/books.htm",
+   "region_label": "Australia", "kind": "retail",
+   "page_url": "https://catalogue.example.org/books/distributors/example-books-australia/", "countries": ["AU"],
+   "logo_url": "https://catalogue.example.org/media/catalogue/example-books-australia.jpg",
+   "address": "", "phone": "03 0000 0000", "email": "info@bookshop.example.au", "note": ""}
+]}
+```
+
+### `GET /api/v1/countries/`
+
+The countries that have their own buying information: a country row on at least one book,
+or a local distributor. Useful to build a country picker or to decide whether to show a
+"prices for your country" hint.
+
+```bash
+curl 'https://catalogue.example.org/api/v1/countries/'
+```
+
+```json
+{"count": 17, "results": [
+  {"code": "GB", "name": "United Kingdom", "books": 9, "distributors": 4}
+]}
+```
+
+## Recipe: books in my language, with prices for my visitor's country
+
+Say your site is in Czech and you want a "Books" block.
+
+1. Work out the visitor's country on your side: your own GeoIP, Cloudflare's
+   `CF-IPCountry` header, or the visitor's choice. Fall back to your site's home country.
+2. Fetch the books in your language for that country, and cache the response
+   (per language + country) for an hour:
+
+   ```bash
+   curl 'https://catalogue.example.org/api/v1/books/?language=cs&country=SK'
+   ```
+
+3. For each result show `cover_url`, `title`, `subtitle`, `short_description` and
+   `purchase.formatted_price`, linking the title to `url` (or to your own page about the book).
+4. For the buying box show `purchase.best_offer` as the main button ("Buy from {shop}",
+   `formatted_price`), the rest of `purchase.offers` / `other_offers` as "Also available from",
+   then `purchase.note`.
+   If `purchase.is_country_specific` is `false`, title it "Buying options" and add a link to
+   `https://catalogue.example.org/books/distributors/`; `purchase.distributors` gives the
+   local shops when there are any.
+5. Few books in your language? Make a second call with `language=en` and show them as
+   "Also in English", or use `editions` on an English book to link to your translation.
+
+From the browser (no server code; the visitor's country is detected from their own request):
+
+```html
+<div id="books"></div>
+<script>
+fetch('https://catalogue.example.org/api/v1/books/?language=cs')
+  .then(r => r.json())
+  .then(data => {
+    document.getElementById('books').innerHTML = data.results.map(b => `
+      <article>
+        <a href="${b.url}"><img src="${b.cover_url}" alt="" width="120"></a>
+        <h3><a href="${b.url}">${b.title}</a></h3>
+        <p>${b.short_description}</p>
+        <p><strong>${b.purchase.formatted_price}</strong></p>
+      </article>`).join('');
+  });
+</script>
+```
+
+(Escape the strings if you build HTML from them like this; `title` and `short_description`
+are plain text.)
+
+From Python on a server:
+
+```python
+import requests
+
+def catalogue_books(language, country):
+    response = requests.get(
+        'https://catalogue.example.org/api/v1/books/',
+        params={'language': language, 'country': country, 'limit': 200},
+        timeout=10,
+    )
+    response.raise_for_status()
+    return response.json()['results']
+```

catalogue_server/admin.py

@@ -0,0 +1,151 @@
+from django.contrib import admin, messages
+from django.utils.html import format_html
+
+from .models import Book, BookCountryInfo, BookImage, Distributor, Offer, Work
+
+
+class BookInline(admin.TabularInline):
+    model = Book
+    fields = ('title', 'slug', 'language', 'format', 'published', 'order')
+    show_change_link = True
+    extra = 0
+
+
+@admin.register(Work)
+class WorkAdmin(admin.ModelAdmin):
+    list_display = ('title', 'slug', 'edition_count', 'order')
+    list_editable = ('order',)
+    search_fields = ('title', 'slug', 'books__title')
+    prepopulated_fields = {'slug': ('title',)}
+    inlines = [BookInline]
+
+    @admin.display(description='Editions')
+    def edition_count(self, obj):
+        return obj.books.count()
+
+
+class BookImageInline(admin.TabularInline):
+    model = BookImage
+    fields = ('image', 'caption', 'order')
+    extra = 0
+
+
+class BookCountryInfoInline(admin.StackedInline):
+    model = BookCountryInfo
+    fields = (
+        ('countries', 'label'), ('currency', 'price', 'available_from'),
+        'note', 'description', 'order',
+    )
+    extra = 0
+
+
+class BookOfferInline(admin.TabularInline):
+    model = Offer
+    fk_name = 'book'
+    fields = ('distributor', 'shop_name', 'countries', 'url', 'price', 'currency', 'in_stock', 'source', 'hidden', 'order')
+    readonly_fields = ('source',)
+    autocomplete_fields = ('distributor',)
+    extra = 0
+    verbose_name_plural = 'Shops (offers): scanned ones are updated by scan_shops; add other shops by hand'
+
+
+@admin.register(Book)
+class BookAdmin(admin.ModelAdmin):
+    list_display = ('cover_thumb', 'title', 'language', 'format', 'work', 'price_display', 'country_count', 'published')
+    list_display_links = ('cover_thumb', 'title')
+    list_filter = ('published', 'language', 'format', 'work')
+    search_fields = ('title', 'subtitle', 'slug', 'isbn', 'author', 'publisher', 'work__title')
+    list_select_related = ('work',)
+    raw_id_fields = ('display_page',)
+    autocomplete_fields = ('work',)
+    prepopulated_fields = {'slug': ('title',)}
+    inlines = [BookImageInline, BookCountryInfoInline, BookOfferInline]
+    fieldsets = (
+        (None, {'fields': ('work', 'title', 'subtitle', 'slug', 'author', ('language', 'format'), 'published', 'order')}),
+        ('Description', {'fields': ('short_description', 'description', 'cover', 'display_page', 'external_url')}),
+        ('Details', {'fields': (('isbn', 'publisher'), ('year', 'pages'))}),
+        ('Default buying options', {
+            'description': 'Used where no country row below matches the visitor\'s country.',
+            'fields': (('currency', 'price'), 'streaming_links', 'purchase_note'),
+        }),
+        ('Internal', {'classes': ('collapse',), 'fields': ('source', 'notes')}),
+    )
+
+    def get_queryset(self, request):
+        return super().get_queryset(request).prefetch_related('country_infos')
+
+    @admin.display(description='Cover')
+    def cover_thumb(self, obj):
+        cover = obj.cover
+        if not cover:
+            return ''
+        return format_html('<img src="{}" alt="" style="height:48px;width:auto">', cover.get_absolute_url())
+
+    @admin.display(description='Default price')
+    def price_display(self, obj):
+        return obj.purchase_info().formatted_price
+
+    @admin.display(description='Countries')
+    def country_count(self, obj):
+        return len(obj.country_infos.all())
+
+
+@admin.register(Distributor)
+class DistributorAdmin(admin.ModelAdmin):
+    list_display = ('name', 'kind', 'region_label', 'countries', 'shop_parser', 'last_scanned', 'published', 'order')
+    list_editable = ('order',)
+    list_filter = ('kind', 'published', 'shop_parser')
+    search_fields = ('name', 'countries', 'region_label', 'url')
+    prepopulated_fields = {'slug': ('name',)}
+    readonly_fields = ('last_scanned', 'scan_report')
+    actions = ['scan_shops']
+    fieldsets = (
+        (None, {'fields': ('name', 'slug', 'kind', 'published', 'order')}),
+        ('Where', {'fields': (('countries', 'region_label'), 'ships_to', 'ships_to_locked')}),
+        ('Page', {'fields': ('logo', 'url', 'note', 'description')}),
+        ('Contact', {'fields': ('address', ('phone', 'email'))}),
+        ('Online shop', {'fields': ('shop_parser', 'shop_options', 'last_scanned', 'scan_report')}),
+    )
+
+    @admin.action(description='Scan the shops now')
+    def scan_shops(self, request, queryset):
+        from .shops.base import make_session
+        from .shops.scan import scan_distributor
+
+        session = make_session()
+        for distributor in queryset.exclude(shop_parser=''):
+            result = scan_distributor(distributor, session=session)
+            level = messages.ERROR if result.error else messages.SUCCESS
+            self.message_user(request, f'{distributor.name}: {result.summary()}', level)
+
+
+@admin.register(Offer)
+class OfferAdmin(admin.ModelAdmin):
+    """Every offer; filter "Book: none" for scanned products waiting to be linked to a book."""
+
+    list_display = ('title_or_url', 'book', 'shop', 'price_display', 'in_stock', 'match', 'source', 'hidden', 'last_seen')
+    list_filter = (('book', admin.EmptyFieldListFilter), 'distributor', 'source', 'match', 'hidden', 'in_stock')
+    list_editable = ('book', 'hidden')
+    list_select_related = ('book', 'distributor')
+    search_fields = ('title', 'url', 'shop_name', 'book__title', 'isbn')
+    autocomplete_fields = ('distributor',)
+    raw_id_fields = ('book',)
+    readonly_fields = ('last_seen', 'created')
+
+    def save_model(self, request, obj, form, change):
+        # Also called for the list's editable "book" column; scans keep an editor's choice.
+        if 'book' in form.changed_data:
+            obj.match = Offer.MATCH_MANUAL
+        super().save_model(request, obj, form, change)
+
+    @admin.display(description='Product', ordering='title')
+    def title_or_url(self, obj):
+        return format_html('<a href="{}" target="_blank" rel="noopener">{}</a>', obj.url, obj.title or obj.url)
+
+    @admin.display(description='Shop')
+    def shop(self, obj):
+        return obj.shop_label
+
+    @admin.display(description='Price', ordering='price')
+    def price_display(self, obj):
+        return obj.formatted_price

catalogue_server/api_urls.py

@@ -0,0 +1,13 @@
+from django.urls import path
+
+from . import api_views
+
+app_name = 'catalogue_api'
+
+urlpatterns = [
+    path('books/', api_views.books, name='books'),
+    path('books/<slug:slug>/', api_views.book, name='book'),
+    path('works/', api_views.works, name='works'),
+    path('distributors/', api_views.distributors, name='distributors'),
+    path('countries/', api_views.country_list, name='countries'),
+]