Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 john-okeefe
|
86bcdf878b | ||
|
john-okeefe
|
a075a5061f | ||
|
john-okeefe
|
28e40e302c | ||
|
john-okeefe
|
6f271d624f |
No files matched your search
@@ -20,9 +20,6 @@ logs/
|
||||
|
||||
# Dependencies (install fresh in container)
|
||||
node_modules/
|
||||
# Local-only lockfile: a stale one pins old foliate-js commits into builds
|
||||
# (npm reuses name@version without re-resolving the git pin)
|
||||
package-lock.json
|
||||
|
||||
# Environment
|
||||
.env
|
||||
|
||||
@@ -35,9 +35,5 @@ DBPASS=your-secure-database-password-here
|
||||
# BOOKHOARD_CONVERSION_TOOL=/usr/bin/ebook-convert
|
||||
# Conversion Cache TTL: Override default 24h
|
||||
# BOOKHOARD_CONVERSION_CACHE_TTL=48h
|
||||
# Archive Retention: days to keep archived items (files missing from disk for
|
||||
# 2+ scans) before they are purged, deleting their reading history with them.
|
||||
# Set 0 to keep archived items until purged manually on the library admin page.
|
||||
# ARCHIVE_RETENTION_DAYS=90
|
||||
# System timezone (fallback for server-side time operations, defaults to UTC)
|
||||
# TZ=America/New_York
|
||||
@@ -56,9 +56,6 @@ jobs:
|
||||
context: .
|
||||
file: ./Dockerfile
|
||||
push: true
|
||||
# Bake the version into the binary (Admin → Settings → About).
|
||||
build-args: |
|
||||
APP_VERSION=${{ env.TAG }}
|
||||
# Publishes both the exact version (e.g. v0.2.0) and the movable "latest" tag.
|
||||
# Deployments default to "latest" via ${IMAGE_TAG:-latest} in docker-compose.yml;
|
||||
# pin or roll back by setting IMAGE_TAG in .env.
|
||||
|
||||
@@ -79,11 +79,3 @@ web/static/vendor/
|
||||
VALID_TOKEN
|
||||
fresh_token.txt
|
||||
session-*.md
|
||||
|
||||
# Local prod-export scratch: personal annotation/reading data, never commit
|
||||
/export/
|
||||
|
||||
# Binary media fixtures: never commit (generate with ffmpeg at test time,
|
||||
# see docs/contributing/development.md → Media fixtures)
|
||||
internal/services/testdata/
|
||||
test-results
|
||||
@@ -1,289 +0,0 @@
|
||||
# AGENTS.md — Bookhoard server
|
||||
|
||||
Standing rules for any agent or developer working in this repo.
|
||||
Project-wide context lives in the sibling repos' AGENTS.md files
|
||||
(../bookhoard-app/AGENTS.md is the Android client's).
|
||||
|
||||
## Rendering ownership (templ vs TypeScript) — ALWAYS apply
|
||||
|
||||
The point of templ + htmx + Alpine is: the server renders the UI, and
|
||||
JavaScript is kept minimal. The rule that keeps it that way:
|
||||
|
||||
> **JavaScript decides what shows. templ decides what it looks like.**
|
||||
|
||||
- Content derived from **server data** (DB rows, search results, match
|
||||
lists, conflict cards, any list/card/badge/table) is rendered by
|
||||
templ. When it changes client-side, fetch a **templ partial** from an
|
||||
SSR route and swap it in (`htmx.ajax(...)`), never rebuild it from a
|
||||
JSON payload with `innerHTML` string templates.
|
||||
- **Pure functions of client-local state** (open/closed panels, tabs,
|
||||
password strength from a typed value, toasts) may render in
|
||||
TS/Alpine — no server round trip needed.
|
||||
- `web/src` is **TypeScript only** — no new `.js` source files.
|
||||
Vendored third-party and vite build output under `web/static` are
|
||||
exempt.
|
||||
- Inline `<script>` in a `.templ` file needs a reason a bundled module
|
||||
cannot do the job (pre-paint execution). Currently sanctioned:
|
||||
`theme_flash_guard.templ` only.
|
||||
|
||||
Sanctioned JS islands (engines, not UI renderers — exempt from the
|
||||
above): the reader (foliate-js + `web/src/reader/`), Chart.js graphs in
|
||||
stats, toasts, password validation. Anything else that renders app UI
|
||||
in TypeScript is a defect; if a templ twin of it exists, one of the two
|
||||
must be deleted.
|
||||
|
||||
**Documented exception — dashboard sections**: `renderDashboardCollections`
|
||||
/ `renderSectionHTML` in `web/src/dashboard.ts` re-render dashboard
|
||||
sections from `/api/dashboard/sections` JSON (library switch, settings
|
||||
save, refresh button) to preserve the switch fade/transition on a page
|
||||
with heavy interactivity. First-paint section markup is still templ
|
||||
(Dashboard handler in `internal/router/frontend.go`). This exception is
|
||||
deliberate; do not clone it to new pages, and do not "fix" the dashboard
|
||||
without restoring a templ-partial fade path first.
|
||||
|
||||
## CSP discipline (hash-allow-listed script-src) — ALWAYS apply
|
||||
|
||||
script-src carries a sha256 hash, not `'unsafe-inline'` (and never
|
||||
`'unsafe-eval'` — the Alpine build is `@alpinejs/csp` for exactly this
|
||||
reason; keep it in lockstep with alpinejs). The browser therefore
|
||||
refuses, **silently at build/test time**, two authoring patterns:
|
||||
|
||||
- **No inline `<script>` content outside `theme_flash_guard.templ`.**
|
||||
The guard is the app's only inline script; its bytes are pinned by
|
||||
`middleware.ScriptHashThemeFlashGuard` + the drift test. Editing the
|
||||
guard means recomputing the hash (the failing test prints it); adding
|
||||
a *second* inline script means hashing it too and extending
|
||||
`cspSanctionedInlineScripts` in `templates/csp_source_test.go`.
|
||||
Everything else goes in a bundled `web/src` module.
|
||||
- **No native `on*=` handler attributes** (`onclick=`, `onerror=`,
|
||||
`onsubmit=`, `onchange=`, … — quote AND templ brace forms). Inline
|
||||
handlers never go through the hash path; hash-mode CSP refuses them
|
||||
unconditionally. Use Alpine `@click`/`@change`/… bound to component
|
||||
methods (see the 2026-10 CSP-build conversion commits for the
|
||||
pattern), or delegated listeners for htmx-swapped content.
|
||||
- **No htmx eval-dependent bindings** (`hx-on*`, `js:`-prefixed
|
||||
`hx-vals`) — `'unsafe-eval'` is not granted.
|
||||
|
||||
`templates/csp_source_test.go` is the tripwire for all three (it
|
||||
scans the `.templ` sources; it runs in seconds on host). `style-src
|
||||
'unsafe-inline'` remains by design (htmx-injected styles, Alpine
|
||||
`:style`); `'self'` still trusts the origin not to serve
|
||||
attacker-supplied scripts — don't let upload paths become
|
||||
script-executable. Remember: `templ` does not interpolate `{ expr }`
|
||||
inside quoted attribute values (gotcha #1 below), so dynamic
|
||||
`@click={ "fn('" + id + "')" }` attribute values must BE expressions.
|
||||
|
||||
## Library visibility (family-lens rule) — ALWAYS apply
|
||||
|
||||
Per-user library visibility (`library_visibility` table, default-ALLOW:
|
||||
every user sees every library unless an admin hides one) must be
|
||||
enforced on **every endpoint that returns media metadata or content**.
|
||||
It is NOT automatic — enforcement is per-handler.
|
||||
|
||||
- **New endpoints that list/filter media or series** MUST filter by the
|
||||
requesting user's visible-library set, and MUST reject an explicit
|
||||
`library_id` outside that set with 403 (never silently pass).
|
||||
- Helpers (do not hand-roll):
|
||||
- `handlers`: `(*MediaHandler).visibleLibrarySet` /
|
||||
`(*SeriesHandler).visibleLibrarySet` — membership map + id slice.
|
||||
- `router`: `visibleLibraryIDsFor` — same for SSR routes.
|
||||
- `resolveLibrary` (helpers.go) only honors requested library ids
|
||||
inside the visible set.
|
||||
- SQL pattern: `AND (sqlc.narg('visible_library_ids')::uuid[] IS NULL OR
|
||||
library_id = ANY(sqlc.narg('visible_library_ids')::uuid[]))` — see
|
||||
`ListMediaItems`, `GetDistinctSeries`, `SearchMediaItems`.
|
||||
- Content endpoints (file bytes, page images) additionally gate per item
|
||||
like `ReaderHandler.ensureItemVisible` / the download endpoint.
|
||||
- Tests must pin visibility: hidden library → 403 on the endpoint, and
|
||||
absent from unscoped aggregates.
|
||||
|
||||
History: 2026-10-13 (`431fec0`) the series/media listing surfaces
|
||||
leaked hidden libraries to any authenticated account — series endpoints
|
||||
were name-only across ALL libraries. Fixed; do not regress.
|
||||
|
||||
## Tests
|
||||
|
||||
- **THE DOCTRINE — tests are never run against a real/production
|
||||
server.** The dev DB is the test environment, and the invariant every
|
||||
test must uphold is: **leave the testuser experience alone** — its
|
||||
settings, scans, and reading data must be exactly as the suite found
|
||||
them. The helpers exist to enforce this; if a test needs protection
|
||||
the helpers don't provide, EXPAND THE HELPERS rather than hand-rolling
|
||||
(2026-10-21: `setSystemSettingRestored` — snapshot-and-restore for
|
||||
system_settings — exists because a hardcoded ev restore could clobber
|
||||
a deliberate dev bump, and the live dev server obeys that setting on
|
||||
its next poll).
|
||||
- Use `setupTestServer()` from `cmd/server/tests/test_helpers_test.go`
|
||||
(see the Conventions section below for the pool/cleanup rules).
|
||||
- Integration tests run against the SHARED dev database: never write
|
||||
destructive SQL without preserving the dev rows (libraries Manga/
|
||||
Comics/Ebooks, testuser's annotations and progress are real data).
|
||||
- Test-created users must use `@tests.bookhoard.internal` or
|
||||
`@example.com` emails and "test"-named collections/libraries so the
|
||||
harness cleanup can find them.
|
||||
- **NEVER rename or edit the shared admin (`testuser`) in tests** — a
|
||||
renamed admin escapes the cleanup preserve-list and cascades real
|
||||
data (this wiped the dev annotations once; see user_test.go
|
||||
TestUpdateProfileSelfEdit for the dedicated-user pattern).
|
||||
- **`testuser` is a LIVE reader**: the dev account genuinely reads in
|
||||
the web reader while the suite runs, so `reading_history` /
|
||||
`reading_progress` rows accrue on it mid-test. Exact-total
|
||||
assertions against that account flap (three stats/analytics tests
|
||||
broke on 2026-10-14 within hours of session capture shipping).
|
||||
Tests that need deterministic data use `setup.RegularToken` +
|
||||
`getRegularUserID` (the fresh per-test user), or assert ranges
|
||||
instead of equals. Related: **no table-wide DELETEs in test
|
||||
cleanups** — sync_integration's `DELETE FROM reading_history WHERE
|
||||
true` destroyed the live reader's stats data on every suite run
|
||||
until scoped to the test-sync users (cascade via user delete).
|
||||
- **RUN ONLY YOUR OWN TESTS while iterating**: integration tests
|
||||
require the containerized dev DB — a bare host `go test
|
||||
./cmd/server/tests` fails on auth on every machine not running the
|
||||
compose stack. Use the filtered container runner
|
||||
(`docker compose -f docker-compose.yml -f
|
||||
docker-compose.dev.yml --profile tests run --rm tests go test
|
||||
./cmd/server/tests -run 'TestYourPrefix' -v`) and save full-suite
|
||||
runs for pre-commit validation; several tests read live shared
|
||||
state (system_settings, real library folders, the periodic backup
|
||||
scan's websocket broadcasts) and flap on data/timing your change
|
||||
never touched. Full recipes: docs/contributing/development.md
|
||||
→ Testing.
|
||||
- **NEVER COMMIT BINARY MEDIA** (mp3/m4b/flac/... fixtures):
|
||||
`internal/services/testdata/` is gitignored by policy; generate
|
||||
media at test runtime with ffmpeg instead (test images ship it).
|
||||
ffmpeg cannot write Audible freeform atoms — those paths are unit-
|
||||
tested with synthetic ffprobeReport values. Recipes:
|
||||
docs/contributing/development.md → Media fixtures.
|
||||
|
||||
## Web (TypeScript) tests
|
||||
|
||||
- `npm run test` (vp test) runs the vitest suite: colocated `web/src/*.test.ts`
|
||||
files, jsdom environment (configured in vite.config.ts `test`). Do NOT switch
|
||||
to happy-dom — DOMPurify's sanitizer output is mangled under it, which makes
|
||||
the markdown security suite test nothing (verified empirically; jsdom is the
|
||||
documented fallback for exactly this reason).
|
||||
- Static gates: `npx tsc --noEmit`, `npx vp check web/src` (format + lint),
|
||||
`npx vp fmt web/src` to apply formatting.
|
||||
- Tests are never bundled (build entries are main.ts/reader.ts only). When
|
||||
touching build config, re-prove it: back-to-back `npm run build:ts` runs must
|
||||
produce byte-identical hashes, and no test-only strings may appear in
|
||||
web/static.
|
||||
- markdown.test.ts pins the notes XSS defenses (FORBID_TAGS, scheme checks,
|
||||
parser-level html escaping). Loosening any assertion there is a security
|
||||
decision, not cleanup.
|
||||
|
||||
## Timezones
|
||||
|
||||
- The server owns display conversion: clients send instants (RFC3339),
|
||||
the server renders in the requesting user's timezone.
|
||||
- Use `utils.FormatTimeInTimezone` / `utils.UserLocation` — never
|
||||
`time.Now().Format(...)` bare (that is server-UTC).
|
||||
- Analytics day-buckets must bucket in the user's timezone
|
||||
(`CreatedAt.In(loc)`), and date-range end bounds must be end-of-day.
|
||||
|
||||
## Debug discipline (test-failure triage) — 2026-10-17
|
||||
|
||||
When a test or bruno request fails, suspect the TEST FIRST — most
|
||||
failures in this repo are harness/schema/environment drift, not server
|
||||
bugs (2026-10-17 bruno sweep: drifted body keys, bodies pre-truncated
|
||||
at their first `{{var}}`, missing `/api` prefixes; host runs hitting
|
||||
container-only paths/hostnames). Triage order: (1) read the
|
||||
test/fixture/payload schema and diff against a known-good sibling
|
||||
(bruno: the `NewDevDBSetup` files are the reference for `body.data`
|
||||
form); (2) check environment assumptions (host vs container,
|
||||
harness cleanup, live-DB traffic); (3) cheap probe (curl, one SQL
|
||||
query) before any deep dive.
|
||||
|
||||
But test changes are ASYMMETRIC with code changes: server code may be
|
||||
fixed freely when it is the bug; test/contract edits may only
|
||||
(a) fix harness plumbing, (b) WIDEN pins additively with a
|
||||
`docs/contract_pins.md` changelog entry, (c) delete tests of deleted
|
||||
behavior — never narrow an assertion or flip an expectation to match
|
||||
observed behavior. Contract pins were green at a known commit, so git
|
||||
history arbitrates "test stale vs code changed." If a test looks right
|
||||
but fails and no harness bug explains it, that is prima facie evidence
|
||||
of a server bug: stop and flag the user.
|
||||
|
||||
## Known gotchas (do not relearn)
|
||||
|
||||
1. **templ does NOT interpolate `{ expr }` inside quoted attribute
|
||||
values** — it emits the literal text. `x-init="f('{ col.ID }')"`
|
||||
shipped a request to `/api/collections/{ collection.ID }` found by
|
||||
the request logs; the whole attribute value must BE an expression:
|
||||
`x-init={ "f('" + col.ID + "')" }`. (Every occurrence of this bug —
|
||||
including `class="theme-{ user.Theme }"` on 22 page bodies and 26
|
||||
attribute interpolations — was swept and fixed in 2026-10; when
|
||||
adding attributes with dynamic values, the whole value is an
|
||||
expression, and free text goes through `templates.JSONArg`.)
|
||||
2. **SettingsRegistry caches**: writes must go through the settings
|
||||
API (Reload on save). Direct SQL writes to system_settings leave
|
||||
the cache stale until the next API-path write — never "preview"
|
||||
rule changes via psql and expect them applied (2026-10-14: a live
|
||||
curl test flip looked ignored until the API path was used).
|
||||
3. **User collections are not dashboard query types** (amended 2026-10-19,
|
||||
A2c): user collections ARE dashboard sections by default now —
|
||||
GetUserCollectionsForDashboard no longer gates on show_on_dashboard
|
||||
(which remains system-section provisioning state; hiding is
|
||||
dashboard-prefs `hidden_collections` territory). GetDashboardSections
|
||||
still skips genuinely empty user sections, but hide_finished
|
||||
collections emit a Complete section instead of vanishing. Collection
|
||||
detail (JSON + SSR) must still NOT route user rows through the
|
||||
dashboard-section path — a 7ce7321 regression did exactly that
|
||||
(static detail without library_id returned zero books until 0a7fbd6).
|
||||
Only real system query types (continue-reading etc.) route there;
|
||||
`query_type='filter'` is the schema DEFAULT on every user row, not a
|
||||
query type.
|
||||
4. **End-of-day arithmetic**: anchor the END bound to the START of the
|
||||
day, never to NOW(). `now.AddDate(0,0,1) − 1ns` carries this
|
||||
instant's clock time into tomorrow — a range "ending today"
|
||||
resolves tomorrow's calendar date and today's rows land in
|
||||
yesterday's bucket (found twice now: analytics 1601548 and stats
|
||||
2026-10-14). Same trap, two deaths.
|
||||
5. **Test binaries run against the LIVE dev DB**: hand-probes made in
|
||||
psql during debugging (seed rows, fake sessions) will silently
|
||||
pollute the next integration run — DELETE them when done (this
|
||||
burned the first stats suite run: a stray 30-min probe row shipped
|
||||
a phantom "185 minutes" failure).
|
||||
6. **SaveProgressRequest.DeviceID is NOT always a device**: the
|
||||
web/app progress paths have historically stuffed the USER id into
|
||||
it (it only fed a broadcast label before stats). Anything that
|
||||
dereferences it (reading_history device_id FK, device joins) must
|
||||
probe DeviceExistsForUser first — stats capture does.
|
||||
|
||||
## Conventions (absorbed from the retired PROJECT_GUIDELINES.md —
|
||||
## only the rules that still matched reality)
|
||||
|
||||
- **Runtime is Docker** (Makefile auto-detects docker, falls back to
|
||||
podman). The old "podman only" rule is dead.
|
||||
- **The server binary is only built inside the Docker build**
|
||||
(`make rebuild-app`); host-side Go builds are for tests/vet only.
|
||||
- **Schema changes go in place** — edit `database/schema/schema.sql`,
|
||||
never create migration files, until a release splits them.
|
||||
- **Business logic lives in services**, not handlers; handlers parse
|
||||
requests and call services (all DB access goes through services).
|
||||
- **Integration tests**: one `setupTestServer()` per test function;
|
||||
test pools use `max_conns=1`; never create a `pgxpool` per subtest
|
||||
(connection exhaustion); use `t.Cleanup()`-based helpers; table-driven
|
||||
subtests over duplicate functions.
|
||||
7. **Scanner re-extraction is write-after-success** — a failed/empty
|
||||
extraction must NEVER clear scan-derived columns. `updateMediaItem`
|
||||
(generic full-row path) preserves `existing.AudioMetadata` when the
|
||||
new extraction carries no audio payload, and `updateAudioBookItem`
|
||||
refuses empty payloads over populated rows (both guarded 2026-10-21
|
||||
after an ev-gated re-extract NULLed every multi-file audiobook's
|
||||
audio_metadata — books displayed as 1 second long and lost their
|
||||
track manifests). New scan-owned column writes need the same guard.
|
||||
8. **templ double-escapes style attribute values** — the codegen wraps
|
||||
style exprs in a sanitizer AND `templ.EscapeString`, so ANY quote
|
||||
character (even inside `templ.SafeCSS`) reaches the DOM as literal
|
||||
`'` text and the CSS never parses (2026-10-21: every book-detail
|
||||
hero backdrop broken + Firefox fetched `/media/&` → 500 spam).
|
||||
Emit quote-free CSS: unquoted `url(...)` tokens via `SafeCSS` +
|
||||
`cssURL()` in book_detail.templ.
|
||||
9. **`vp test` runs the vite config** — plugins with build hooks fire
|
||||
in the test context too. `cleanStaleChunks` guards on
|
||||
`produced.size === 0` precisely because a bare sweep deleted every
|
||||
hashed chunk in `web/static` when run under vitest (2026-10-21:
|
||||
`npm run test` gutted the build; every page 404'd its imports).
|
||||
Any future outDir-mutating plugin needs the same "am I a build?"
|
||||
guard.
|
||||
@@ -1065,7 +1065,7 @@ If there's a section about documentation features, mention the new search functi
|
||||
|
||||
## Git Commit Strategy
|
||||
|
||||
Follow AGENTS.md conventions - make multiple logical commits:
|
||||
Follow PROJECT_GUIDELINES.md - make multiple logical commits:
|
||||
|
||||
1. **Backend implementation** (search.go, http_handler.go, router changes)
|
||||
2. **Unit tests** (search_test.go)
|
||||
|
||||
+4
-26
@@ -15,10 +15,7 @@ RUN --mount=type=cache,target=/root/go/pkg/mod \
|
||||
|
||||
# Copy package files and install npm dependencies (cached unless package.json changes)
|
||||
COPY package*.json ./
|
||||
# npm cache mount renamed from /root/.npm: the old volume held a stale
|
||||
# foliate-js tarball (name@version reuse) that --no-cache and builder prune
|
||||
# could not evict; a new mount id guarantees a clean fetch.
|
||||
RUN --mount=type=cache,target=/root/.npm-cache2 \
|
||||
RUN --mount=type=cache,target=/root/.npm \
|
||||
npm install
|
||||
|
||||
# Copy Go mod files (cached unless go.mod changes)
|
||||
@@ -37,41 +34,22 @@ RUN cd templates && templ generate
|
||||
RUN npm run build:css:prod
|
||||
RUN npm run build:ts
|
||||
|
||||
# App version baked into the binary (shown in Admin → Settings → About).
|
||||
# Declared after `COPY . .` so a version bump only invalidates this layer.
|
||||
# The release workflow passes the git tag, e.g. APP_VERSION=v1.5.
|
||||
ARG APP_VERSION=dev
|
||||
|
||||
# Build Go binary (cached unless Go files or generated code changes)
|
||||
RUN --mount=type=cache,target=/root/go/pkg/mod \
|
||||
--mount=type=cache,target=/root/.cache/go-build \
|
||||
CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo \
|
||||
-ldflags "-X bookhoard/internal/version.Version=${APP_VERSION}" \
|
||||
-o main ./cmd/server
|
||||
|
||||
# Materialize the Go module cache into an image layer so the test-runner
|
||||
# stage can restore it. GOMODCACHE is /go/pkg/mod; cache mounts elsewhere are
|
||||
# ignored by the go tool, and without this copy `go test` in the tests
|
||||
# container re-downloads every dependency on each invocation.
|
||||
RUN cp -r /go/pkg/mod /app/go-module-cache
|
||||
CGO_ENABLED=0 GOOS=linux go build -installsuffix cgo -o main ./cmd/server
|
||||
|
||||
# Test runner stage - includes Go runtime and test dependencies
|
||||
# This stage is ONLY used for running tests, never deployed to production
|
||||
FROM golang:1.26-alpine AS test-runner
|
||||
|
||||
# ffmpeg/ffprobe match the runtime stage: the audio ingestion (tag
|
||||
# fallbacks, embedded covers, cue probing) must be exercised in tests
|
||||
# exactly as it runs in production.
|
||||
RUN apk --no-cache add ca-certificates curl poppler-utils ffmpeg
|
||||
RUN apk --no-cache add ca-certificates curl
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy everything from builder (includes compiled binary, source code, and dependencies)
|
||||
COPY --from=builder /app ./
|
||||
|
||||
# Restore the materialized Go module cache so `go test` works offline.
|
||||
RUN mkdir -p /go/pkg/mod && cp -r /app/go-module-cache/. /go/pkg/mod/ && rm -rf /app/go-module-cache
|
||||
|
||||
# Install kepubify for conversion tests
|
||||
RUN wget -O /usr/bin/kepubify https://github.com/pgaskin/kepubify/releases/latest/download/kepubify-linux-64bit \
|
||||
&& chmod +x /usr/bin/kepubify
|
||||
@@ -87,7 +65,7 @@ CMD ["go", "test", "./cmd/server/tests", "-v", "-timeout", "5m", "-parallel=1",
|
||||
# Final stage
|
||||
FROM alpine:latest
|
||||
|
||||
RUN apk --no-cache add ca-certificates curl poppler-utils ffmpeg
|
||||
RUN apk --no-cache add ca-certificates curl
|
||||
|
||||
# Install kepubify for EPUB→KEPUB conversion
|
||||
RUN wget -O /usr/bin/kepubify https://github.com/pgaskin/kepubify/releases/latest/download/kepubify-linux-64bit \
|
||||
|
||||
@@ -1,661 +1,232 @@
|
||||
GNU AFFERO GENERAL PUBLIC LICENSE
|
||||
Version 3, 19 November 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU Affero General Public License is a free, copyleft license for
|
||||
software and other kinds of works, specifically designed to ensure
|
||||
cooperation with the community in the case of network server software.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
our General Public Licenses are intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
Developers that use our General Public Licenses protect your rights
|
||||
with two steps: (1) assert copyright on the software, and (2) offer
|
||||
you this License which gives you legal permission to copy, distribute
|
||||
and/or modify the software.
|
||||
|
||||
A secondary benefit of defending all users' freedom is that
|
||||
improvements made in alternate versions of the program, if they
|
||||
receive widespread use, become available for other developers to
|
||||
incorporate. Many developers of free software are heartened and
|
||||
encouraged by the resulting cooperation. However, in the case of
|
||||
software used on network servers, this result may fail to come about.
|
||||
The GNU General Public License permits making a modified version and
|
||||
letting the public access it on a server without ever releasing its
|
||||
source code to the public.
|
||||
|
||||
The GNU Affero General Public License is designed specifically to
|
||||
ensure that, in such cases, the modified source code becomes available
|
||||
to the community. It requires the operator of a network server to
|
||||
provide the source code of the modified version running there to the
|
||||
users of that server. Therefore, public use of a modified version, on
|
||||
a publicly accessible server, gives the public access to the source
|
||||
code of the modified version.
|
||||
|
||||
An older license, called the Affero General Public License and
|
||||
published by Affero, was designed to accomplish similar goals. This is
|
||||
a different license, not a version of the Affero GPL, but Affero has
|
||||
released a new version of the Affero GPL which permits relicensing under
|
||||
this license.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU Affero General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Remote Network Interaction; Use with the GNU General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, if you modify the
|
||||
Program, your modified version must prominently offer all users
|
||||
interacting with it remotely through a computer network (if your version
|
||||
supports such interaction) an opportunity to receive the Corresponding
|
||||
Source of your version by providing access to the Corresponding Source
|
||||
from a network server at no charge, through some standard or customary
|
||||
means of facilitating copying of software. This Corresponding Source
|
||||
shall include the Corresponding Source for any work covered by version 3
|
||||
of the GNU General Public License that is incorporated pursuant to the
|
||||
following paragraph.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the work with which it is combined will remain governed by version
|
||||
3 of the GNU General Public License.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU Affero General Public License from time to time. Such new versions
|
||||
will be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU Affero General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU Affero General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU Affero General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU Affero General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU General Public License is a free, copyleft license for software and other kinds of works.
|
||||
|
||||
The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
|
||||
|
||||
To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
|
||||
|
||||
For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
|
||||
|
||||
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
|
||||
|
||||
For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
|
||||
|
||||
Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
|
||||
|
||||
Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
|
||||
|
||||
The precise terms and conditions for copying, distribution and modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
“This License” refers to version 3 of the GNU General Public License.
|
||||
|
||||
“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
|
||||
|
||||
“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
|
||||
|
||||
To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
|
||||
|
||||
A “covered work” means either the unmodified Program or a work based on the Program.
|
||||
|
||||
To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
|
||||
|
||||
To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
|
||||
|
||||
A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
|
||||
|
||||
The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
|
||||
|
||||
c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
|
||||
|
||||
A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
|
||||
|
||||
“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
|
||||
|
||||
An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
|
||||
|
||||
A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
|
||||
|
||||
A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Use with the GNU Affero General Public License.
|
||||
Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
|
||||
|
||||
bookhoard
|
||||
Copyright (C) 2026 john-okeefe
|
||||
|
||||
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If your software can interact with users remotely through a computer
|
||||
network, you should also make sure that it provides a way for users to
|
||||
get its source. For example, if your program is a web application, its
|
||||
interface could display a "Source" link that leads users to an archive
|
||||
of the code. There are many ways you could offer source, and different
|
||||
solutions will be better for different programs; see section 13 for the
|
||||
specific requirements.
|
||||
If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU AGPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
bookhoard Copyright (C) 2026 john-okeefe
|
||||
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
||||
This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
|
||||
|
||||
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about box”.
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <https://www.gnu.org/philosophy/why-not-lgpl.html>.
|
||||
@@ -1,4 +1,4 @@
|
||||
.PHONY: help test test-integration test-all rebuild-app rebuild-app-force rebuild rebuild-force rebuild-force-db clean restart up down logs ps test-env-up test-env-down release
|
||||
.PHONY: help test test-integration test-all rebuild rebuild-force rebuild-app rebuild-app-force rebuild-force-db clean restart up down logs ps test-env-up test-env-down verify-guidelines verify-quick release
|
||||
|
||||
# Include .env file for environment variables (single source of truth)
|
||||
# Ignore if .env doesn't exist yet
|
||||
@@ -42,41 +42,16 @@ help:
|
||||
@echo " make test-env-down - Stop test environment"
|
||||
@echo ""
|
||||
@echo "Verification:"
|
||||
@echo " make verify-guidelines - Run comprehensive guidelines check"
|
||||
@echo " make verify-quick - Run quick guidelines check"
|
||||
@echo ""
|
||||
@echo "Release:"
|
||||
@echo " ./release v0.3.0 - Tag, push, and release (notes auto-generated from commits)"
|
||||
|
||||
# Run unit tests locally (fast, no containers)
|
||||
test: lint-rendering
|
||||
test:
|
||||
go test ./internal/... -v -short
|
||||
|
||||
# Rendering-ownership guard (AGENTS.md → Rendering ownership): templ renders
|
||||
# UI markup, JS orchestrates. Fails when a web/src file builds more HTML
|
||||
# template literals than its recorded baseline (web/src/rendering-allowlist.txt),
|
||||
# or when a .templ file gains an inline <script> block (theme_flash_guard.templ
|
||||
# is the only sanctioned one). *.test.ts files are excluded: jsdom fixtures
|
||||
# build DOM in tests, they don't render shipped UI. Shrink baselines as
|
||||
# fragments move to templ
|
||||
# partials; grow one only with a written reason.
|
||||
lint-rendering:
|
||||
@violations=""; \
|
||||
for f in $$(grep -rlE 'innerHTML[[:space:]]*=[[:space:]]*' web/src --include='*.ts' | grep -v 'web/src/reader/' | grep -v '\.test\.ts$$'); do \
|
||||
count=$$(grep -E 'innerHTML[[:space:]]*=[[:space:]]*' $$f | grep -cvE 'innerHTML[[:space:]]*=[[:space:]]*""[[:space:]]*$$'); \
|
||||
allowed=$$(grep -F "$$f:" web/src/rendering-allowlist.txt | cut -d: -f2); \
|
||||
allowed=$${allowed:-0}; \
|
||||
if [ $$count -gt $$allowed ]; then \
|
||||
violations="$$violations $$f ($$count > $$allowed)"; \
|
||||
fi; \
|
||||
done; \
|
||||
for f in $$(grep -rln '<script>' templates --include='*.templ'); do \
|
||||
case $$f in *theme_flash_guard*) continue;; esac; \
|
||||
violations="$$violations $$f (inline script)"; \
|
||||
done; \
|
||||
if [ -n "$$violations" ]; then \
|
||||
echo "rendering-ownership violations:$$violations"; exit 1; \
|
||||
fi; \
|
||||
echo "rendering ownership OK"
|
||||
|
||||
# Run integration tests in containers (matches production environment)
|
||||
test-integration:
|
||||
@echo "Building test containers..."
|
||||
@@ -178,7 +153,14 @@ test-env-up:
|
||||
test-env-down:
|
||||
$(COMPOSE) down -v
|
||||
|
||||
# Verify project guidelines compliance
|
||||
verify-guidelines:
|
||||
@echo "Running comprehensive project guidelines verification..."
|
||||
@./scripts/verify-guidelines.sh
|
||||
|
||||
verify-quick:
|
||||
@echo "Running quick project guidelines verification..."
|
||||
@./scripts/verify-quick.sh
|
||||
|
||||
# Create an annotated version tag carrying auto-generated release notes (git-cliff)
|
||||
# and push it. The tag push triggers .gitea/workflows/release.yml, which builds the
|
||||
|
||||
@@ -0,0 +1,480 @@
|
||||
# Combined Project Guidelines for Bookhoard
|
||||
|
||||
## 🚨 CRITICAL PROHIBITIONS (Never violate these)
|
||||
|
||||
### Backend & Database
|
||||
|
||||
- ❌ **NEVER modify backend code when working on frontend-only tasks*
|
||||
- ❌ **NEVER modify database schema** unless explicitly instructed for full-stack changes
|
||||
- ❌ **NEVER use Docker** - use Podman only
|
||||
- ❌ **NEVER build server binaries locally** - all builds through Dockerfile/docker-compose
|
||||
- ❌ **NEVER create new migration files** - merge changes into current one until release
|
||||
- ❌ **NEVER use `git checkout` on schema files** without checking what will be lost
|
||||
- ❌ **NEVER break existing functionality** unless explicitly instructed
|
||||
- ❌ **NEVER duplicate business logic** - keep logic in services, not handlers
|
||||
- ❌ **NEVER bypass service layer** - all database operations must go through services
|
||||
|
||||
### Testing
|
||||
|
||||
- ✅ **ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers_test.go`*
|
||||
- ✅ **Share one test setup across all subtests** - call `setupTestServer()` once at test function level, not per subtest
|
||||
- ✅ **Prefer table-driven tests** - use `t.Run()` with test cases instead of duplicate test functions
|
||||
- ✅ **Configure database pools efficiently** - use `max_conns=1` for test pools (via `pgxpool.ParseConfig()`) to prevent connection exhaustion
|
||||
- ❌ **NEVER create separate `pgxpool` per test** - each pool creates 4 connections by default; 78 tests = 312 potential connections > PostgreSQL's 100 limit
|
||||
- ❌ **NEVER call `setupTestServer()` in loops or within subtests** - creates unnecessary database pools and exhausts connections
|
||||
- ✅ **DO verify tests pass** - run full test suite before completing work
|
||||
- ✅ **Use `t.Cleanup()` properly** - the `TestServerSetup` pattern automatically handles cleanup via `t.Cleanup()`
|
||||
|
||||
### Frontend & Styling
|
||||
|
||||
- ❌ **NEVER modify backend/API for frontend features without user confirmation*
|
||||
- ❌ **NEVER use custom CSS** - TailwindCSS classes only
|
||||
- **⚠️ EXCEPTION**: `templates/error.templ` may have inline CSS because error pages must work when main app fails (404, server errors, CSS fails to load)
|
||||
- ❌ **NEVER use JavaScript** - convert all to TypeScript
|
||||
- **⚠️ EXCEPTION**: Inline JS function calls in HTML attributes (e.g., `onclick="myFunction()"`) are acceptable for simple interactions
|
||||
- ❌ **NEVER use Object-Oriented Programming** (no classes, inheritance, or this-capture)
|
||||
- ✅ **DO use procedural/imperative style** as your default
|
||||
- ✅ **DO borrow functional techniques** when they simplify code
|
||||
- ✅ **DO avoid ideological purity** - the best paradigm is the one that fits the problem
|
||||
- ❌ **NEVER add new Dockerfiles without user confirmation*
|
||||
- ❌ **NEVER fetch initial data via AJAX on page load** - use server-side rendering instead
|
||||
- ❌ **NEVER break progressive enhancement** - pages must work without JavaScript
|
||||
|
||||
**Note:** Go methods in the backend are fine and encouraged. This guideline applies to TypeScript/JavaScript frontend code only.
|
||||
|
||||
### General
|
||||
|
||||
- ❌ **NEVER skip pre-commit hooks** unless explicitly requested
|
||||
- ❌ **NEVER force push to main/master** branches
|
||||
- ❌ **NEVER commit files with secrets** (.env, credentials.json, etc.)
|
||||
- ❌ **NEVER make assumptions** - ask clarifying questions when uncertain
|
||||
- ❌ **NEVER delete code without reading full context first** (minimum 20 lines before/after)
|
||||
- ❌ **NEVER make cascading fix-up edits without git diff review*
|
||||
- After compilation error: STOP, review `git diff`, understand full impact
|
||||
- Use revert/reapply pattern instead of blind fixes
|
||||
- ❌ **NEVER skip post-edit verification** - must compile after each file edit
|
||||
- ❌ **NEVER run git commands concurrently** - always run sequentially:
|
||||
- Run `git add <files>` and wait for completion
|
||||
- Run `git commit -m "<message>"` and wait for completion
|
||||
- Run `git push` and wait for completion
|
||||
- Never use `&&` to chain git commands together
|
||||
- ✅ **Make good organized git commits for the entire project (not just what you changed) and push - run git add, commit, push sequentially as separate commands, no need to repeatedly check status*
|
||||
- ✅ **Indentation is always 2 spaces unless the language prohibits it*
|
||||
|
||||
### Cascading Fix-up Pattern (PROHIBITED)
|
||||
|
||||
**WHAT NOT TO DO** - This caused critical bugs:
|
||||
|
||||
```go
|
||||
// ❌ WRONG: Blindly making fixes after compilation error
|
||||
|
||||
Edit 1: Delete deprecated code
|
||||
[Compilation error: undefined Register]
|
||||
|
||||
Edit 2: Try to fix error (over-broad deletion)
|
||||
[More errors: undefined Login, GetProfile, etc.]
|
||||
|
||||
Edit 3: Try to fix again (worse damage)
|
||||
[Even more errors: major functionality broken]
|
||||
```
|
||||
|
||||
**CORRECT APPROACH**:
|
||||
|
||||
```go
|
||||
// ✅ CORRECT: Stop, understand, then fix deliberately
|
||||
|
||||
Edit 1: Delete deprecated code
|
||||
[Compilation error: undefined Register]
|
||||
|
||||
STOP → Review git diff → Understand Register was accidentally deleted
|
||||
RESTORE → Get exact Register function from git history
|
||||
VERIFY → Compile successfully
|
||||
```
|
||||
|
||||
**Key Principle**: When compilation errors occur after edits:
|
||||
|
||||
1. STOP - Don't make more edits
|
||||
2. ANALYZE - Use `git diff` to understand what was changed
|
||||
3. RECOVER - Restore what was accidentally deleted/broken
|
||||
4. VERIFY - Compile and test before proceeding
|
||||
|
||||
---
|
||||
|
||||
## 🎯 CONTEXT-SPECIFIC RULES
|
||||
|
||||
### When Working on Frontend-Only Tasks
|
||||
|
||||
- **DO NOT touch backend code** - handlers, services, database layer
|
||||
- **DO NOT modify API routes** - use existing endpoints only
|
||||
- **DO NOT change database schema** - work with existing structure
|
||||
- **If backend change seems necessary**:
|
||||
1. Identify the required change
|
||||
2. Explain why you need it
|
||||
3. Provide impact analysis
|
||||
4. **ASK FOR USER CONFIRMATION before proceeding*
|
||||
|
||||
### When Working on Full-Stack Tasks
|
||||
|
||||
- Backend changes are allowed when explicitly part of the task
|
||||
- Still follow all database protocols (atomic changes, validation, etc.)
|
||||
- **If modifying database schema:** Update local database after schema.sql changes (see Database Operations section)
|
||||
- Still use Podman for all builds
|
||||
- Still include Bruno requests for API changes
|
||||
|
||||
---
|
||||
|
||||
## ✅ MANDATORY REQUIREMENTS
|
||||
|
||||
### Database Operations (Full-Stack Tasks Only)
|
||||
|
||||
- ✅ Follow **pgx v5 standards** for all database operations
|
||||
- ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection
|
||||
- ✅ **⚠️ CRITICAL: This is a pre-production application (NO production deployments exist)*
|
||||
- When `database/schema/schema.sql` is updated, local databases must be updated
|
||||
- **Option 1 (Recommended):** Recreate database with fresh schema:
|
||||
```bash
|
||||
podman compose down -v # Delete volumes (WARNING: loses all data)
|
||||
podman compose up -d # Start fresh with new schema
|
||||
```
|
||||
- **Option 2:** Manually apply schema changes to existing database using psql
|
||||
- **DO NOT create migration files** - no legacy schema support needed
|
||||
- ✅ Use **pre-change checklist**: read schema → identify columns → plan changes → verify → read back
|
||||
- ✅ **Post-change validation**: ensure schema.sql, models.go, and queries.sql are in sync
|
||||
|
||||
### Build & Deployment
|
||||
|
||||
- ✅ Use **Podman** exclusively (not Docker)
|
||||
- ✅ All builds through existing **Dockerfile** and **docker-compose.yml*
|
||||
- ✅ Stop building server binaries - everything goes through containers
|
||||
|
||||
### API Changes (Full-Stack Tasks Only)
|
||||
|
||||
- ✅ Include **Bruno OpenCollection YAML requests** with all API documentation
|
||||
- ✅ Integration Tests (cmd/server/tests) must be **comprehensive and cover three contexts**: no user, user, and admin
|
||||
- ✅ Maintain backward compatibility for mobile apps and external consumers
|
||||
|
||||
### Frontend & Styling
|
||||
|
||||
- ✅ Always use **TailwindCSS classes** for all styling
|
||||
- ✅ Convert all JavaScript to **TypeScript**
|
||||
- ✅ **Never use Object-Oriented Programming** (no classes, inheritance, or this-capture)
|
||||
- ✅ **Use procedural/imperative style** as your default
|
||||
- ✅ **Borrow functional techniques** when they simplify code
|
||||
- ✅ **Avoid ideological purity** - the best paradigm is the one that fits the problem
|
||||
- ✅ **Extract domain concepts/types only when clearly beneficial** - apply YAGNI, avoid over-engineering
|
||||
- ✅ **Render initial data server-side** in Go templates for fast page loads
|
||||
- ✅ **Use JavaScript/HTMX for CRUD operations** (create, update, delete)
|
||||
- ✅ **Ensure progressive enhancement** - pages work without JavaScript
|
||||
|
||||
### Service Layer Architecture
|
||||
|
||||
- ✅ **All business logic in services** - never in handlers
|
||||
- ✅ **Services must be reusable** by both SSR handlers and API endpoints
|
||||
- ✅ **Database operations through services only** - never direct from handlers
|
||||
- ✅ **When adding features**: Add service logic → Create API endpoint → Use SSR for initial render → Use JS for updates
|
||||
|
||||
### Code Organization
|
||||
|
||||
- ✅ Minimize project structure changes
|
||||
- ✅ Place new files in **contextually appropriate directories*
|
||||
- ✅ Follow **KISS**, **DRY**, and **YAGNI** principles
|
||||
- ✅ Use **multiple, logical git commits** with clear messages
|
||||
- ❌ **NEVER duplicate types between handlers and templates** - define data types in handlers, reuse directly in templates
|
||||
- ✅ **DO share handler types with templates** - templates should use handlers.CollectionData, handlers.BookInfo, etc. directly
|
||||
- ❌ **NEVER create parallel type systems** - no templates.XxxData types for data that originates from handlers
|
||||
- ✅ **DO enhance handler types with template-specific fields** when needed (e.g., add Icon, FormattedDate fields to handlers structs)
|
||||
- ✅ **DO keep template-only types in templates package** - PageData, UnsafeHTML, and template-specific utilities are appropriate
|
||||
- ❌ **NEVER create conversion helper functions** to map between handler and template types - use handler types directly
|
||||
|
||||
### Configuration & Environment
|
||||
|
||||
- ✅ If **.env is missing**, auto-generate secure values
|
||||
- ✅ Never commit secrets to repository
|
||||
|
||||
### Code Modification Safety
|
||||
|
||||
- ✅ **Post-Edit Verification (MANDATORY for ALL file modifications)**:
|
||||
- Run `go build` for affected packages immediately after each edit
|
||||
- Review `git diff filename` to verify only intended changes
|
||||
- Validate functionality still works as expected
|
||||
- Never proceed to next file until current edit is verified
|
||||
- ✅ **Backup Before Large Changes**:
|
||||
- Create a stash: `git stash push -m "Pre-cleanup snapshot"` before removing >50 lines
|
||||
- Or create a backup branch: `git branch backup-before-cleanup`
|
||||
- This allows instant recovery if mistakes occur
|
||||
- ✅ **Large Deletion Safety Pattern**:
|
||||
- Read at least 20 lines before/after deletion target
|
||||
- Include unique identifiers in match (function signatures, specific comments)
|
||||
- Use narrow matches - avoid generic patterns
|
||||
- Verify line numbers match intended section
|
||||
|
||||
### Documentation
|
||||
|
||||
**Documentation Structure** (updated with full docs system):
|
||||
|
||||
- ✅ **README.md** - Project overview, quick start, and setup instructions only
|
||||
- ✅ **docs/** - Comprehensive documentation system with search
|
||||
- ✅ **docs/developer/api/** - API reference documentation (split by endpoint/category)
|
||||
- ✅ **docs/user/** - User-facing features, guides, and workflows
|
||||
- ✅ **docs/user/devices/** - Device setup guides (KOBO, KOReader, etc.)
|
||||
- ✅ **docs/contributing/** - Development and contribution guides
|
||||
|
||||
**Where to document changes**:
|
||||
|
||||
| Change Type | Location | Examples |
|
||||
| ----------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| **User-facing features** | `docs/user/` | New features, UI changes, workflows |
|
||||
| **API endpoints** | `docs/developer/api/<category>/<endpoint>.md` | New endpoints, modified responses, authentication changes |
|
||||
| **API behavior** | Update existing `docs/developer/api/` files | Parameter changes, error codes, rate limits |
|
||||
| **Device setup** | `docs/user/devices/` | New device support, setup instructions |
|
||||
| **Development** | `docs/contributing/` | Build changes, architecture decisions |
|
||||
| **Quick start/setup** | `README.md` | Installation, environment setup, first-run |
|
||||
| **Breaking changes** | Both `README.md` and relevant `docs/` | Migration guides, deprecation notices |
|
||||
| **Bug fixes** | Update relevant `docs/` only if user-visible | Clarifications, troubleshooting additions |
|
||||
| **Bruno OpenCollection YAML requests** | `.yml` files in bruno folder in appropriate folder/sub-folder | API contract testing, examples |
|
||||
|
||||
**Documentation Update Workflow**:
|
||||
|
||||
1. **Identify the audience** (end users, developers, API consumers)
|
||||
2. **Choose appropriate location** based on table above
|
||||
3. **Update documentation** before or with code changes
|
||||
4. **Verify documentation renders** at `/docs` endpoint
|
||||
5. **Test search** finds new/updated content
|
||||
6. **For API changes**: Update both `docs/developer/api/` files, integration test files (cmd/server/tests) AND Bruno OpenCollection YAML `.yml` files
|
||||
7. **Commit separately** with clear message: `docs: <description>`
|
||||
|
||||
**When in doubt**:
|
||||
|
||||
- End-user visible → `docs/user/`
|
||||
- API reference → `docs/developer/api/`
|
||||
- Setup/onboarding → `README.md`
|
||||
- Development related → `docs/contributing/`
|
||||
|
||||
### Process & Continuity
|
||||
|
||||
- ✅ If mid-task and receive "no response", **continue the task*
|
||||
- ✅ Verify no regressions before modifying/removing code
|
||||
|
||||
---
|
||||
|
||||
## 🔧 TECHNICAL STANDARDS
|
||||
|
||||
### Backend Stack
|
||||
|
||||
- **Language**: Go 1.25+
|
||||
- **Database**: PostgreSQL 15+ with **pgx v5 driver** only
|
||||
- **Authentication**: JWT tokens with bcrypt password hashing
|
||||
- **Architecture**: Service layer pattern (handlers → services → database)
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
- **Rendering**: SSR-first - Go templates render initial page with all data
|
||||
- **Interactivity**: Alpine.js for UI state (modals, dropdowns, transitions)
|
||||
- **Dynamic Updates**: HTMX for CRUD operations (no full page reloads)
|
||||
- **Styling**: TailwindCSS (no custom CSS)
|
||||
- **Language**: TypeScript (no JavaScript)
|
||||
- **Patterns**: Procedural/imperative with functional techniques where helpful (no OOP)
|
||||
|
||||
### SSR-First Principles
|
||||
|
||||
- ❌ **NEVER fetch initial data via AJAX** - server renders complete page
|
||||
- ❌ **NEVER fetch data in Alpine x-init** - data already SSR'd
|
||||
- ✅ **Use Alpine.js only for UI state** - modal visibility, dropdown toggles
|
||||
- ✅ **Use HTMX for dynamic operations** - form submissions, partial page updates
|
||||
- ✅ **x-init is for setup only** - event listeners, not data fetching
|
||||
- ✅ **Data fetching happens after user actions** - not on page load
|
||||
|
||||
### Page Type Classifications
|
||||
|
||||
1. **Type 1: 80% SSR (most pages)**
|
||||
- Backend provides all initial data
|
||||
- Alpine handles modals/dropdowns only
|
||||
- x-init NEVER fetches data
|
||||
|
||||
2. **Type 2: SSR + Interactive (dashboard, bookshelf)**
|
||||
- Backend provides initial data
|
||||
- Alpine handles interactivity (drag-drop, filtering)
|
||||
- x-init ONLY sets up event listeners
|
||||
|
||||
3. **Type 3: 80% TypeScript (analytics, complex dashboards)**
|
||||
- Some client-side data fetching acceptable
|
||||
- Still prefer SSR when possible
|
||||
|
||||
### Containerization
|
||||
|
||||
- **Runtime**: Podman (not Docker)
|
||||
- **Build**: Existing Dockerfile and docker-compose.yml only
|
||||
- **No local builds** allowed
|
||||
|
||||
---
|
||||
|
||||
## 🔄 ERROR RECOVERY PROTOCOL
|
||||
|
||||
When code modification mistakes occur (deleted wrong code, broke compilation, etc.):
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
1. **STOP** - Don't make more edits
|
||||
2. **ASSESS** - What was deleted? Is it critical?
|
||||
3. **REVIEW** - Run `git diff` to see exact changes
|
||||
4. **RESTORE** - Choose appropriate recovery method:
|
||||
- **Recent mistake**: `git checkout -- filename`
|
||||
- **Complex restoration**: Use `git show HEAD:filename` to recover deleted code
|
||||
- **Multiple files**: `git reset HEAD~1` (if safe)
|
||||
5. **VERIFY** - Compile and test restored code
|
||||
6. **DOCUMENT** - Note what went wrong for future reference
|
||||
|
||||
### Recovery Examples
|
||||
|
||||
```bash
|
||||
# Recover a deleted function from original file
|
||||
git show HEAD:internal/handlers/auth.go | sed -n '70,275p' > recovery.txt
|
||||
|
||||
# Revert entire file to original state
|
||||
git checkout HEAD -- internal/handlers/auth.go
|
||||
|
||||
# Use git stash to save current state before rollback
|
||||
git stash push -m "Broken state before fix"
|
||||
git checkout -- internal/handlers/auth.go
|
||||
```
|
||||
|
||||
### Prevention (Learn From Mistakes)
|
||||
|
||||
- Why did the mistake happen?
|
||||
- Was it too-broad matching?
|
||||
- Was it insufficient context reading?
|
||||
- Was it cascading fix-up attempts?
|
||||
- Update guidelines to prevent recurrence
|
||||
|
||||
---
|
||||
|
||||
## 📋 WORKFLOW CHECKLISTS
|
||||
|
||||
### Before Making Frontend-Only Changes
|
||||
|
||||
- [ ] Identify if backend modification could make implementation simpler
|
||||
- [ ] Plan to use existing API endpoints only
|
||||
- [ ] If backend change seems necessary, prepare confirmation request:
|
||||
- Required change description
|
||||
- Why it would help
|
||||
- Impact analysis
|
||||
- Alternative approaches considered
|
||||
- [ ] Plan git commit structure (multiple logical commits)
|
||||
- [ ] **Identify documentation location** (see Documentation section):
|
||||
- [ ] User-facing feature → `docs/user/`
|
||||
- [ ] UI/workflow changes → `docs/user/`
|
||||
- [ ] Setup instructions → `README.md`
|
||||
|
||||
### Before Making Full-Stack Changes
|
||||
|
||||
- [ ] Read current schema completely (if database changes)
|
||||
- [ ] Identify all columns that must be preserved
|
||||
- [ ] Plan exact changes needed
|
||||
- [ ] Verify Podman will be used for builds
|
||||
- [ ] Plan git commit structure (multiple logical commits)
|
||||
- [ ] **Identify documentation location**:
|
||||
- [ ] API changes → `docs/developer/api/<category>/`
|
||||
- [ ] New endpoints → Create new `.md` file in `docs/developer/api/`
|
||||
- [ ] API behavior → Update existing `docs/developer/api/` files
|
||||
- [ ] Breaking changes → Both `README.md` + relevant `docs/`
|
||||
- [ ] Bruno OpenCollection YAML `.yml` files → Update/create alongside API changes
|
||||
- [ ] Integration tests (cmd/server/tests) → Update/create alongside API changes
|
||||
|
||||
### During Schema Changes (Full-Stack Only)
|
||||
|
||||
- [ ] Read current schema completely
|
||||
- [ ] Identify all columns that must be preserved
|
||||
- [ ] Plan exact changes needed
|
||||
- [ ] Set up verification step
|
||||
- [ ] Make intended changes
|
||||
- [ ] Immediately verify by reading back modified sections
|
||||
- [ ] Confirm ALL expected columns are present
|
||||
- [ ] Verify schema.sql, models.go, and queries.sql are in sync
|
||||
- [ ] **Update local database** (choose ONE):
|
||||
- [ ] **Option 1 - Recreate database** (recommended, loses data):
|
||||
```bash
|
||||
podman compose down -v # Delete all volumes
|
||||
podman compose up -d # Start with fresh schema
|
||||
```
|
||||
- [ ] **Option 2 - Manual SQL migration** (preserves data):
|
||||
```bash
|
||||
podman exec bookhoard_db psql -U postgres -d bookhoard -c "YOUR SQL HERE"
|
||||
```
|
||||
- [ ] Verify database has new schema (check column types, indexes, etc.)
|
||||
|
||||
### After API Changes
|
||||
|
||||
- [ ] Create/update Bruno OpenCollection YAML requests
|
||||
- [ ] Create/update Integration tests (cmd/server/tests)
|
||||
- [ ] Test with no user context
|
||||
- [ ] Test with regular user context
|
||||
- [ ] Test with admin context
|
||||
- [ ] Verify backward compatibility
|
||||
|
||||
### Before Committing
|
||||
|
||||
- [ ] **Run verification script**: `bash scripts/verify-guidelines.sh`
|
||||
- [ ] **Fix any errors** - verification must pass (0 errors) to commit
|
||||
- [ ] **Note warnings** - informational only, do not auto-fix
|
||||
- [ ] Run tests: `go test ./... -v`
|
||||
- [ ] Run lint/typecheck if available
|
||||
- [ ] Ensure no secrets in changes
|
||||
- [ ] Verify logical commit structure
|
||||
- [ ] **Update documentation** (see Documentation section):
|
||||
- [ ] User-facing changes → `docs/user/`
|
||||
- [ ] API changes → `docs/developer/api/` + Integration tests + Bruno OpenCollection YAML `.yml` files
|
||||
- [ ] Setup/onboarding → `README.md`
|
||||
- [ ] Development changes → `docs/contributing/`
|
||||
- [ ] **Verify docs render** at `/docs` endpoint
|
||||
- [ ] **Test docs search** finds new content
|
||||
|
||||
### Error Recovery Protocol (If Code Mistakes Occur)
|
||||
|
||||
- [ ] **Stop immediately** - don't make more edits
|
||||
- [ ] **Assess impact**: What was deleted? Is it critical?
|
||||
- [ ] **Review git diff**: See exact changes made
|
||||
- [ ] **Restore strategy**:
|
||||
- If recent mistake: `git checkout -- filename`
|
||||
- If complex: Reconstruct from git diff using `git show HEAD:filename`
|
||||
- [ ] **Verify recovery**: Compile and test restored code
|
||||
- [ ] **Document mistake**: Note what went wrong for future reference
|
||||
|
||||
### Phase Completion Verification (Before Declaring "Complete")
|
||||
|
||||
- [ ] All target code is removed/intact as intended
|
||||
- [ ] No unintended code was deleted
|
||||
- [ ] All affected files compile successfully
|
||||
- [ ] Run `go build ./...` for entire project
|
||||
- [ ] **Run verification script**: `bash scripts/verify-guidelines.sh` - must pass (0 errors)
|
||||
- [ ] No critical functionality was broken
|
||||
- [ ] Git diff shows only intended changes
|
||||
- [ ] Review all modified files with `git diff --stat`
|
||||
|
||||
---
|
||||
|
||||
## 🏗 ARCHITECTURAL PATTERNS
|
||||
|
||||
### Current: SSR-First with Alpine.js + HTMX
|
||||
|
||||
```
|
||||
Browser → Go template (SSR with all data) → Display instantly
|
||||
↓
|
||||
Alpine.js for UI state (modals, dropdowns)
|
||||
↓
|
||||
HTMX for CRUD (forms, updates)
|
||||
↓
|
||||
Shared service layer (Go)
|
||||
```
|
||||
|
||||
**Layer Responsibilities:**
|
||||
|
||||
| Layer | Responsibility |
|
||||
|-------|---------------|
|
||||
| **Go Template** | SSR initial page with real data |
|
||||
| **Alpine.js** | UI state only (x-data, x-show, transitions) |
|
||||
| **HTMX** | Dynamic updates without page reload |
|
||||
| **TypeScript** | Pure business logic (API calls, data processing) |
|
||||
|
||||
**See also:** `SSR_FIRST_ALPINE_GUIDE.md` and `ALPINE_COMPLETION_GUIDE.md`
|
||||
|
||||
Ultimately, whenever you are unsure just ask for confirmation.
|
||||
@@ -1,10 +1,10 @@
|
||||
# <img src="web/static/favicon.svg" width="32" alt="Bookhoard logo"> Bookhoard
|
||||
# 📚 Bookhoard
|
||||
|
||||
A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring **universal cross-device sync**, beautiful dark themes, and comprehensive media management.
|
||||
|
||||
## ✨ Why Bookhoard?
|
||||
|
||||
**🔄 Universal Sync**: Your reading position, bookmarks, highlights, and notes sync automatically between KOReader and the web - with native Kobo sync and mobile apps coming later.
|
||||
**🔄 Universal Sync**: Your reading progress, highlights, and notes sync automatically across all your devices - KOReader, Kobo, web, and mobile.
|
||||
|
||||
**📱 Multi-Library**: Organize your ebooks, comics, and manga with per-library folders and smart collections.
|
||||
|
||||
@@ -52,13 +52,13 @@ The first user to register automatically becomes an admin.
|
||||
|
||||
### Universal Cross-Platform Sync
|
||||
|
||||
- **Real-Time Progress**: Turn a page on your e-reader, see it in your browser
|
||||
- **Real-Time Progress**: Turn a page on your Kindle, see it on your phone
|
||||
- **Format-Aware**: EPUB CFI, page numbers, percentages - all handled correctly
|
||||
- **Offline Queue**: Changes sync when you reconnect, priority-processed
|
||||
- **Conflict Resolution**: Smart handling when same book read on multiple devices
|
||||
- **Book Matching**: Automatic matching using SHA-256, ISBN, UUID
|
||||
- **OPDS Catalog**: Wireless book delivery to e-readers over Wi-Fi
|
||||
- **Format Conversion**: On-the-fly EPUB→KEPUB conversion (for upcoming native Kobo support)
|
||||
- **Format Conversion**: On-the-fly EPUB→KEPUB for Kobo devices
|
||||
|
||||
### Media Management
|
||||
|
||||
@@ -74,7 +74,7 @@ The first user to register automatically becomes an admin.
|
||||
### Smart Collections
|
||||
|
||||
- **Auto-Assign Rules**: Automatically add books based on genre, author, series, tags, language, publisher, year
|
||||
- **Device Shelf Mappings**: Map collections to device shelves (used by native Kobo sync, coming soon)
|
||||
- **Device Shelf Mappings**: Sync collections to Kobo shelves and KOReader categories
|
||||
- **Test Before Creating**: Preview which books match your rules
|
||||
|
||||
### Library Organization
|
||||
@@ -102,8 +102,8 @@ The first user to register automatically becomes an admin.
|
||||
|
||||
- **[docs/user/calibre-integration.md](docs/user/calibre-integration.md)** - Calibre library integration
|
||||
- **[docs/user/sync-guide.md](docs/user/sync-guide.md)** - Understanding and using universal sync
|
||||
- **[docs/user/devices/kobo-setup.md](docs/user/devices/kobo-setup.md)** - Kobo e-reader configuration
|
||||
- **[docs/user/devices/koreader-setup.md](docs/user/devices/koreader-setup.md)** - KOReader configuration
|
||||
- **[docs/user/devices/kobo-setup.md](docs/user/devices/kobo-setup.md)** - Kobo e-reader configuration (coming soon)
|
||||
- **[docs/user/user-guide.md](docs/user/user-guide.md)** - General user guide
|
||||
- **[docs/user/admin-guide.md](docs/user/admin-guide.md)** - Admin features and configuration
|
||||
- **[docs/user/settings-guide.md](docs/user/settings-guide.md)** - Settings and preferences
|
||||
@@ -111,45 +111,18 @@ The first user to register automatically becomes an admin.
|
||||
### For Developers
|
||||
|
||||
- **[docs/developer/api/api-reference.md](docs/developer/api/api-reference.md)** - Complete API documentation
|
||||
- **[docs/developer/android-app.md](docs/developer/android-app.md)** - Android app design & roadmap
|
||||
- **[docs/contributing/development.md](docs/contributing/development.md)** - Development workflow
|
||||
- **[docs/contributing/DEVELOPMENT.md](docs/contributing/DEVELOPMENT.md)** - Development workflow
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Supported Devices
|
||||
|
||||
| Platform | Sync | OPDS | Status |
|
||||
| ---------------- | ---- | ---- | ------------------------------------------------------------- |
|
||||
| **Web Browser** | ✅ | ✅ | Full support |
|
||||
| **KOReader** | ✅ | ✅ | Runs on Kindle, Kobo, PocketBook hardware |
|
||||
| **Kobo Devices** | 🚧 | 🚧 | Native Kobo sync coming soon (use KOReader on Kobo today) |
|
||||
| **Mobile Apps** | 🚧 | 🚧 | Native Android app in design ([docs](docs/developer/android-app.md)); iOS later |
|
||||
|
||||
---
|
||||
|
||||
## 💾 Network Storage (NAS / NFS / SMB)
|
||||
|
||||
Libraries on network mounts are supported for everyday use — serving,
|
||||
reading, progress, and annotation sync all work over the mount — with a
|
||||
few behaviors worth knowing:
|
||||
|
||||
- **Outage hysteresis.** When the mount drops, files miss one scan
|
||||
(marked missing, hidden) then a second (archived, still recoverable).
|
||||
When the mount returns — by path or by identical content elsewhere —
|
||||
everything is restored automatically: annotations, progress, and
|
||||
covers included.
|
||||
- **Retention purge.** Archived items older than `ARCHIVE_RETENTION_DAYS`
|
||||
(default **90**, `0` = never auto-purge) are deleted for good by
|
||||
library scans, annotations included. A NAS offline longer than the
|
||||
retention window loses those books' metadata on return.
|
||||
- **Deleting while the storage is down is refused.** Deleting a book
|
||||
cascades its annotations, so deletes are rejected with a clear error
|
||||
while the item's library storage is unreachable. Archive the item
|
||||
instead, or retry when the mount is back.
|
||||
- **Watch mode does not fire on network mounts** (inotify doesn't work
|
||||
over NFS/SMB). The periodic scan is the change detector.
|
||||
- **Latency** — folder reachability checks are cached ~30s; large
|
||||
libraries on slow mounts will still feel slower than local disk.
|
||||
| Platform | Sync | OPDS | Status |
|
||||
| ---------------- | ---- | ---- | ------------------------ |
|
||||
| **Web Browser** | ✅ | ✅ | Full support |
|
||||
| **KOReader** | ✅ | ✅ | Kindle, Kobo, PocketBook |
|
||||
| **Kobo Devices** | ✅ | ✅ | Clara, Libra, Sage, etc. |
|
||||
| **Mobile Apps** | 🚧 | 🚧 | Coming Q2 2026 |
|
||||
|
||||
---
|
||||
|
||||
@@ -182,20 +155,20 @@ bruno run
|
||||
## 📊 Project Status
|
||||
|
||||
**Version**: 1.0
|
||||
**License**: AGPL-3.0
|
||||
**License**: GPL-3.0
|
||||
**Status**: Production-ready ✅
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We welcome contributions! Please see [docs/developer/development.md](docs/developer/development.md) for guidelines.
|
||||
We welcome contributions! Please see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for guidelines.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
AGPL-3.0 - See [LICENSE](LICENSE) file for details.
|
||||
GPL-3.0 - See [LICENSE](LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -1,3 +1,3 @@
|
||||
#!/bin/bash
|
||||
|
||||
bru run --env Bookhoard --delay 500 "NewDevDBSetup/RegisterUser.yml" "NewDevDBSetup/SetBaseUrl.yml" "NewDevDBSetup/CreateEbookLibrary.yml" "NewDevDBSetup/CreateComicLibrary.yml" "NewDevDBSetup/CreateMangaLibrary.yml" "NewDevDBSetup/AddEbookLibraryFolder.yml" "NewDevDBSetup/AddComicLibraryFolder.yml" "NewDevDBSetup/AddMangaLibraryFolder.yml" "NewDevDBSetup/ScanAllLibraries.yml"
|
||||
bru run --env Bookhoard --delay 500 "NewDevDBSetup/RegisterUser.yml" "NewDevDBSetup/CreateEbookLibrary.yml" "NewDevDBSetup/CreateComicLibrary.yml" "NewDevDBSetup/CreateMangaLibrary.yml" "NewDevDBSetup/AddEbookLibraryFolder.yml" "NewDevDBSetup/AddComicLibraryFolder.yml" "NewDevDBSetup/AddMangaLibraryFolder.yml" "NewDevDBSetup/ScanAllLibraries.yml"
|
||||
@@ -1,37 +0,0 @@
|
||||
info:
|
||||
name: SetBaseUrl
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/system/config'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: "{\n \"base_url\": \"http://localhost:8765\"\n}"
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token}}
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
docs: '## Set Base URL
|
||||
|
||||
|
||||
Configures the server''s base_url during initial dev database setup.
|
||||
|
||||
|
||||
Must be run after RegisterUser (which provides the auth token) and before
|
||||
|
||||
any library/device creation (which require setup to be complete).
|
||||
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/system/config
|
||||
|
||||
**Auth:** Bearer token (from RegisterUser)'
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Get Admin Library
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/admin/library'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Admin Library Page
|
||||
|
||||
Retrieves the admin library page for administrative access.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /admin/library
|
||||
|
||||
**Headers:**
|
||||
- `Authorization` (string): Bearer token
|
||||
|
||||
**Response:**
|
||||
- HTML content for the admin library page
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
@@ -0,0 +1,39 @@
|
||||
info:
|
||||
name: Get Admin Profile
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/admin/profile'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
|
||||
docs: |-
|
||||
## Get Admin Profile
|
||||
|
||||
Retrieves the admin profile information for administrative access.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /admin/profile
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Response:**
|
||||
- JSON object containing admin profile details
|
||||
- `id` (string): Admin user ID
|
||||
- `email` (string): Admin email
|
||||
- `username` (string): Admin username
|
||||
- `theme` (string): Theme preference
|
||||
- `first_name` (string): First name
|
||||
- `last_name` (string): Last name
|
||||
- `is_admin` (boolean): Admin status
|
||||
- `created_at` (string): Account creation timestamp
|
||||
- `updated_at` (string): Last update timestamp
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden (non-admin users)
|
||||
- 404: Profile not found
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Hash Conflicts (API)
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/admin/hash-conflicts'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Hash Conflicts (API)
|
||||
|
||||
`GET /api/admin/hash-conflicts` — auth: jwt+admin.
|
||||
|
||||
Canonical reference: docs/developer/api/admin/hash_conflicts_api.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: List Users
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/auth/users'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# List Users
|
||||
|
||||
`GET /api/auth/users` — auth: jwt+admin.
|
||||
|
||||
Canonical reference: docs/developer/api/admin/list_users.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,37 +0,0 @@
|
||||
info:
|
||||
name: Update User Max Devices
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/auth/users/{{media_item_id}}/max-devices'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"max_devices": 15
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Update User Max Devices
|
||||
|
||||
`PUT /api/auth/users/:id/max-devices` — auth: jwt+admin.
|
||||
|
||||
Canonical reference: docs/developer/api/admin/update_user_max_devices.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,47 @@
|
||||
info:
|
||||
name: Get Device Usage
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/device-usage'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get usage statistics for all devices.
|
||||
|
||||
**Endpoint**: GET /api/analytics/device-usage
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| devices | array | List of device usage statistics |
|
||||
| devices[].id | string | Device ID |
|
||||
| devices[].device_name | string | Device name |
|
||||
| devices[].device_type | string | Device type (kobo, kindle, koreader) |
|
||||
| devices[].sync_count | int | Number of sync operations |
|
||||
| devices[].last_sync | string | Last sync timestamp |
|
||||
| devices[].total_reading_minutes | int | Total reading time on device |
|
||||
| devices[].books_read | int | Number of books completed on device |
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"id": "789e4567-e89b-12d3-a456-426614174001",
|
||||
"device_name": "My Kobo Clara",
|
||||
"device_type": "kobo",
|
||||
"sync_count": 45,
|
||||
"last_sync": "2026-02-08T17:25:00Z",
|
||||
"total_reading_minutes": 1250,
|
||||
"books_read": 3
|
||||
@@ -0,0 +1,57 @@
|
||||
info:
|
||||
name: Get Popular Books
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/popular-books?limit=10'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get popular books sorted by read count.
|
||||
|
||||
**Endpoint**: GET /api/analytics/popular-books
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| limit | int | No | Maximum number of books to return (default: 10) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| books | array | List of popular books |
|
||||
| books[].media_item_id | string | Book ID |
|
||||
| books[].title | string | Book title |
|
||||
| books[].author | string | Book author |
|
||||
| books[].read_count | int | Number of times read |
|
||||
| books[].avg_completion | float | Average completion rate (0-1) |
|
||||
| books[].cover_url | string | Cover image URL |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/popular-books?limit=10
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"books": [
|
||||
{
|
||||
"media_item_id": "323e4567-e89b-12d3-a456-426614174002",
|
||||
"title": "The Great Gatsby",
|
||||
"author": "F. Scott Fitzgerald",
|
||||
"read_count": 5,
|
||||
"avg_completion": 0.85,
|
||||
"cover_url": "/api/books/323e4567-e89b-12d3-a456-426614174002/cover"
|
||||
@@ -0,0 +1,58 @@
|
||||
info:
|
||||
name: Get Reading Stats Date Range
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/reading-stats?start_date=2024-01-01&end_date=2024-01-31'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get reading statistics for a specific date range.
|
||||
|
||||
**Endpoint**: GET /api/analytics/reading-stats
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| start_date | string | No | Start date (ISO 8601 format, default: 30 days ago) |
|
||||
| end_date | string | No | End date (ISO 8601 format, default: today) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| total_books_read | int | Total books completed in range |
|
||||
| total_pages_read | int | Total pages read in range |
|
||||
| total_reading_time_minutes | int | Total reading time in minutes |
|
||||
| completion_rate | float | Percentage of books completed (0-1) |
|
||||
| daily_reading_minutes | array | Daily reading time per day |
|
||||
| daily_reading_minutes[].date | string | Date (ISO 8601) |
|
||||
| daily_reading_minutes[].minutes | int | Minutes read on that date |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/reading-stats?start_date=2024-01-01&end_date=2024-01-31
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"total_books_read": 2,
|
||||
"total_pages_read": 450,
|
||||
"total_reading_time_minutes": 720,
|
||||
"completion_rate": 0.85,
|
||||
"daily_reading_minutes": [
|
||||
{
|
||||
"date": "2024-01-01",
|
||||
"minutes": 30
|
||||
@@ -0,0 +1,58 @@
|
||||
info:
|
||||
name: Get Reading Stats
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/reading-stats'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200\", function() {\n expect(res.status).to.eql(200);"
|
||||
|
||||
docs: |-
|
||||
Get overall reading statistics for the authenticated user.
|
||||
|
||||
**Endpoint**: GET /api/analytics/reading-stats
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|-----------|-------------|
|
||||
| start_date | string | No | Start date (ISO 8601 format) |
|
||||
| end_date | string | No | End date (ISO 8601 format) |
|
||||
|
||||
## Response Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| total_books_read | int | Total books completed |
|
||||
| total_pages_read | int | Total pages read |
|
||||
| total_reading_time_minutes | int | Total reading time in minutes |
|
||||
| completion_rate | float | Average book completion rate (0-1) |
|
||||
| daily_reading_minutes | array | Daily reading time breakdown |
|
||||
| daily_reading_minutes[].date | string | Date (ISO 8601) |
|
||||
| daily_reading_minutes[].minutes | int | Minutes read on that date |
|
||||
|
||||
## Example Request
|
||||
|
||||
```
|
||||
GET /api/analytics/reading-stats
|
||||
```
|
||||
|
||||
## Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"total_books_read": 12,
|
||||
"total_pages_read": 3450,
|
||||
"total_reading_time_minutes": 5400,
|
||||
"completion_rate": 0.78,
|
||||
"daily_reading_minutes": [
|
||||
{
|
||||
"date": "2026-01-15",
|
||||
"minutes": 45
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Reading Statistics
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/reading-stats'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Reading Statistics
|
||||
|
||||
`GET /api/analytics/reading-stats` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/analytics/get_analytics.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Device Usage
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/device-usage'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Device Usage
|
||||
|
||||
`GET /api/analytics/device-usage` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/analytics/get_device_usage.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Popular Books
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/analytics/popular-books'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Popular Books
|
||||
|
||||
`GET /api/analytics/popular-books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/analytics/get_popular_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,59 +0,0 @@
|
||||
info:
|
||||
name: Login User
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/login'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"login": "user@example.com",
|
||||
"password": "SecureP@ss123!"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: after-response
|
||||
code: |-
|
||||
function onResponse(res) {
|
||||
try {
|
||||
const responseBody = res.getBody();
|
||||
const token = responseBody.access_token;
|
||||
const refreshToken = responseBody.refresh_token;
|
||||
if (token) {
|
||||
bru.setEnvVar("token", token, { persist: true });
|
||||
console.log("Access token saved");
|
||||
}
|
||||
if (refreshToken) {
|
||||
bru.setEnvVar("refresh_token", refreshToken, { persist: true });
|
||||
console.log("Refresh token saved");
|
||||
}
|
||||
} catch (error) {
|
||||
console.error("Token capture failed:", error.message);
|
||||
}
|
||||
}
|
||||
onResponse();
|
||||
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Login User
|
||||
|
||||
`POST /api/auth/login` — auth: none.
|
||||
|
||||
Canonical reference: docs/developer/api/authentication/login.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Logout User
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/logout'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Logout User
|
||||
|
||||
`POST /api/auth/logout` — auth: none.
|
||||
|
||||
Canonical reference: docs/developer/api/authentication/logout.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Password Rules
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/auth/password-rules'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Password Rules
|
||||
|
||||
`GET /api/auth/password-rules` — auth: none.
|
||||
|
||||
Canonical reference: docs/developer/api/authentication/password_rules.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,58 +0,0 @@
|
||||
info:
|
||||
name: Refresh Token
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/refresh'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"refresh_token": "d4f5g6h7..."
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: after-response
|
||||
code: |-
|
||||
function onResponse(res) {
|
||||
try {
|
||||
const responseBody = res.getBody();
|
||||
const token = responseBody.access_token;
|
||||
const refreshToken = responseBody.refresh_token;
|
||||
if (token) {
|
||||
bru.setEnvVar("token", token, { persist: true });
|
||||
console.log("Access token saved");
|
||||
}
|
||||
if (refreshToken) {
|
||||
bru.setEnvVar("refresh_token", refreshToken, { persist: true });
|
||||
console.log("Refresh token saved");
|
||||
}
|
||||
} catch (error) {
|
||||
console.error("Token capture failed:", error.message);
|
||||
}
|
||||
}
|
||||
onResponse();
|
||||
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Refresh Token
|
||||
|
||||
`POST /api/auth/refresh` — auth: none.
|
||||
|
||||
Canonical reference: docs/developer/api/authentication/refresh_token.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,62 +0,0 @@
|
||||
info:
|
||||
name: Register User
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/register'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"username": "john",
|
||||
"password": "SecureP@ss123!",
|
||||
"first_name": "John",
|
||||
"last_name": "Doe"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: after-response
|
||||
code: |-
|
||||
function onResponse(res) {
|
||||
try {
|
||||
const responseBody = res.getBody();
|
||||
const token = responseBody.access_token;
|
||||
const refreshToken = responseBody.refresh_token;
|
||||
if (token) {
|
||||
bru.setEnvVar("token", token, { persist: true });
|
||||
console.log("Access token saved");
|
||||
}
|
||||
if (refreshToken) {
|
||||
bru.setEnvVar("refresh_token", refreshToken, { persist: true });
|
||||
console.log("Refresh token saved");
|
||||
}
|
||||
} catch (error) {
|
||||
console.error("Token capture failed:", error.message);
|
||||
}
|
||||
}
|
||||
onResponse();
|
||||
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 201", function() {
|
||||
expect(res.status).to.eql(201);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Register User
|
||||
|
||||
`POST /api/auth/register` — auth: none.
|
||||
|
||||
Canonical reference: docs/developer/api/authentication/register.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,40 +0,0 @@
|
||||
info:
|
||||
name: Register - Admin Role Unauthenticated (403)
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/register'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"email": "smoke-admin-attempts@tests.bookhoard.internal",
|
||||
"username": "smokeadminattempts",
|
||||
"password": "Sm0ke@Pass123!",
|
||||
"role": "admin"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 403", function() {
|
||||
expect(res.status).to.eql(403);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Register - Admin Role Unauthenticated (403)
|
||||
|
||||
With admins already present, an unauthenticated register attempt
|
||||
carrying role=admin must be rejected with 403 and create nothing.
|
||||
Repeats safely.
|
||||
type: text/markdown
|
||||
@@ -1,39 +0,0 @@
|
||||
info:
|
||||
name: Register - Duplicate Email (409)
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/register'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"email": "testuser@tests.bookhoard.internal",
|
||||
"username": "testuser",
|
||||
"password": "Wh4t3v3r@Pass!"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 409", function() {
|
||||
expect(res.status).to.eql(409);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Register - Duplicate Email (409)
|
||||
|
||||
Registering with an email that already exists must fail with 409 and
|
||||
create nothing. Negative scenario — hand-authored (the generated set
|
||||
covers only happy paths). Repeats safely.
|
||||
type: text/markdown
|
||||
@@ -1,38 +0,0 @@
|
||||
info:
|
||||
name: Register - Weak Password (400)
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/auth/register'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"email": "smoke-weak-attempts@tests.bookhoard.internal",
|
||||
"username": "smokeweakattempts",
|
||||
"password": "weak"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 400", function() {
|
||||
expect(res.status).to.eql(400);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Register - Weak Password (400)
|
||||
|
||||
Passwords below the configured complexity rules (see
|
||||
GET /api/auth/password-rules) must be rejected with 400. Repeats safely.
|
||||
type: text/markdown
|
||||
@@ -1,38 +0,0 @@
|
||||
info:
|
||||
name: Auto Link Books
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/auto-link-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"confidence_threshold": 0.8,
|
||||
"limit": 100
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Auto Link Books
|
||||
|
||||
`POST /api/sync/auto-link-books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/auto_link_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,48 +0,0 @@
|
||||
info:
|
||||
name: Bulk Link Books
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/bulk-link-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"links": [
|
||||
{
|
||||
"unlinked_book_id": "770e8400-e29b-41d4-a716-446655440002",
|
||||
"media_item_id": "660e8400-e29b-41d4-a716-446655440001",
|
||||
"confidence_score": 0.95
|
||||
},
|
||||
{
|
||||
"unlinked_book_id": "880e8400-e29b-41d4-a716-446655440003",
|
||||
"media_item_id": "990e8400-e29b-41d4-a716-446655440004",
|
||||
"confidence_score": 0.87
|
||||
}
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Link Books
|
||||
|
||||
`POST /api/sync/bulk-link-books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/bulk_link_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,39 +0,0 @@
|
||||
info:
|
||||
name: Create Device File Alias
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"media_item_id": "550e8400-e29b-41d4-a716-446655440001",
|
||||
"file_name": "book.epub",
|
||||
"file_hash": "abc123..."
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 201", function() {
|
||||
expect(res.status).to.eql(201);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Create Device File Alias
|
||||
|
||||
`POST /api/devices/:id/file-aliases` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/create_device_file_alias.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Delete Device File Alias
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases/{{alias_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Delete Device File Alias
|
||||
|
||||
`DELETE /api/devices/:id/file-aliases/:aliasId` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/delete_device_file_alias.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Book Matches
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/books/match'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Book Matches
|
||||
|
||||
`GET /api/books/match` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/get_book_matches.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Device File Aliases
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Device File Aliases
|
||||
|
||||
`GET /api/devices/:id/file-aliases` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/get_device_file_aliases.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Unlinked Book Suggestions
|
||||
type: http
|
||||
seq: 7
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/sync/unlinked-books/{{unlinked_book_id}}/suggestions'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Unlinked Book Suggestions
|
||||
|
||||
`GET /api/sync/unlinked-books/:id/suggestions` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/get_unlinked_book_suggestions.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Unlinked Books
|
||||
type: http
|
||||
seq: 8
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/sync/unlinked-books'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Unlinked Books
|
||||
|
||||
`GET /api/devices/:deviceId/sync/unlinked-books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/get_unlinked_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,43 +0,0 @@
|
||||
info:
|
||||
name: Link Book
|
||||
type: http
|
||||
seq: 9
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/sync/link-book'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"device_file": {
|
||||
"file_path": "/books/hobbit.epub",
|
||||
"sha256": "abc123...",
|
||||
"title": "The Hobbit"
|
||||
},
|
||||
"media_item_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"confidence_score": 1.0
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Link Book
|
||||
|
||||
`POST /api/devices/:deviceId/sync/link-book` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/link_book.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,41 +0,0 @@
|
||||
info:
|
||||
name: Search Books for Matching
|
||||
type: http
|
||||
seq: 10
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/sync/books/query'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"identifiers": ["isbn:978-0345391802", "uuid:abc-123"],
|
||||
"sha256": "a1b2c3d4e5f6abc123...",
|
||||
"title": "The Hobbit",
|
||||
"author": "J.R.R. Tolkien",
|
||||
"file_size": 2456789
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Search Books for Matching
|
||||
|
||||
`POST /api/sync/books/query` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/search_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,38 +0,0 @@
|
||||
info:
|
||||
name: Update Device File Alias
|
||||
type: http
|
||||
seq: 11
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/file-aliases/{{alias_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"file_name": "updated-book.epub",
|
||||
"file_hash": "newhash123..."
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Update Device File Alias
|
||||
|
||||
`PUT /api/devices/:id/file-aliases/:aliasId` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/book-matching/update_device_file_alias.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,50 @@
|
||||
info:
|
||||
name: Bulk Delete Media Items
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/media-items/bulk-delete'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"media_item_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Delete Media Items
|
||||
|
||||
Deletes multiple media items in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/media-items/bulk-delete
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `media_item_ids` (array of strings): Array of media item UUIDs to delete
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each deletion attempt
|
||||
- `total` (number): Total number of media items processed
|
||||
- `deleted` (number): Number of successfully deleted media items
|
||||
- `failed` (number): Number of failed deletions
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"media_item_ids": [
|
||||
"uuid-1",
|
||||
"uuid-2",
|
||||
"uuid-3"
|
||||
]
|
||||
@@ -0,0 +1,55 @@
|
||||
info:
|
||||
name: Bulk Update Media Items
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/media-items/bulk-update'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"media_item_updates\": [\n {\n \"media_item_id\"\
|
||||
: \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Update Media Items
|
||||
|
||||
Updates multiple media items in a single request with different fields for each item.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/media-items/bulk-update
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `media_item_updates` (array): Array of update objects
|
||||
- `media_item_id` (string): Media item UUID to update
|
||||
- `updates` (object): Fields to update (can include title, author, genre, tags, contributors, etc.)
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each update attempt
|
||||
- `total` (number): Total number of media items processed
|
||||
- `updated` (number): Number of successfully updated media items
|
||||
- `failed` (number): Number of failed updates
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"media_item_updates": [
|
||||
{
|
||||
"media_item_id": "uuid-1",
|
||||
"updates": {
|
||||
"title": "New Title",
|
||||
"genre": "Fiction",
|
||||
"tags": ["fiction", "adventure"]
|
||||
@@ -0,0 +1,38 @@
|
||||
info:
|
||||
name: Add Books to Collection
|
||||
type: http
|
||||
seq: 6
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{book_id_1}}"
|
||||
|
||||
docs: |-
|
||||
## Add Books to Collection
|
||||
|
||||
Adds multiple books to an existing collection.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}/books
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Request Body:**
|
||||
- `book_ids` (array of strings, required): List of book IDs to add
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
- `added_count` (integer): Number of books added
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
@@ -0,0 +1,47 @@
|
||||
info:
|
||||
name: Create Collection
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"name\": \"Science Fiction\",\n \"description\": \"My favorite\
|
||||
\ sci-fi books\",\n \"color\": \"#ff0000\",\n \"icon\": \"\U0001F680\"\
|
||||
,\n \"auto_assign_rules\": [\n {\n \"id\": \"rule-1\",\n \
|
||||
\ \"field\": \"genre\",\n \"operator\": \"equals\",\n \"value\"\
|
||||
: \"Science Fiction\",\n \"priority\": 8"
|
||||
|
||||
docs: |-
|
||||
## Create Collection
|
||||
|
||||
Creates a new collection for organizing books.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
- `name` (string, required): Collection name (max 100 chars)
|
||||
- `description` (string, optional): Collection description (max 500 chars)
|
||||
- `color` (string, optional): Hex color code (default #3498db)
|
||||
- `icon` (string, optional): Emoji icon (default 📚)
|
||||
- `auto_assign_rules` (array, optional): Auto-assignment rules
|
||||
- `id` (string): Rule ID
|
||||
- `field` (string): Field to match (genre, author, series, etc.)
|
||||
- `operator` (string): Comparison operator (equals, contains, startsWith)
|
||||
- `value` (string): Value to match
|
||||
- `priority` (integer): Rule priority (1-10)
|
||||
|
||||
**Response:**
|
||||
- Collection object with generated ID
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Created
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 409: Collection name already exists
|
||||
@@ -0,0 +1,39 @@
|
||||
info:
|
||||
name: Create Device Mapping
|
||||
type: http
|
||||
seq: 9
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"collection_id\": \"{{collection_id}}"
|
||||
|
||||
docs: |-
|
||||
## Create Device Mapping
|
||||
|
||||
Maps a collection to a device shelf for synchronization.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Request Body:**
|
||||
- `collection_id` (string, required): Collection ID to map
|
||||
- `device_shelf_name` (string, optional): Custom shelf name on device
|
||||
- `sync_direction` (string, optional): sync direction (book_to_device, device_to_book, bidirectional)
|
||||
|
||||
**Response:**
|
||||
- Mapping object with generated ID
|
||||
|
||||
**Status Codes:**
|
||||
- 201: Created
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Device or collection not found
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Delete Collection
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Delete Collection
|
||||
|
||||
Permanently deletes a collection and all its mappings.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
@@ -0,0 +1,31 @@
|
||||
info:
|
||||
name: Delete Device Mapping
|
||||
type: http
|
||||
seq: 11
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{mapping_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Delete Device Mapping
|
||||
|
||||
Removes a collection-to-device mapping.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections/{mapping_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `mapping_id` (string): Mapping ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device or mapping not found
|
||||
@@ -0,0 +1,44 @@
|
||||
info:
|
||||
name: Get Book Collections
|
||||
type: http
|
||||
seq: 12
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: "{{base_url}}/api/collections/books"
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"collection_id": "{{collection_id}}"
|
||||
}
|
||||
auth: inherit
|
||||
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs: |-
|
||||
## Get Book Collections
|
||||
|
||||
Retrieves all collections that a specific book belongs to.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections/books
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `book_id` (string, required): Book ID
|
||||
|
||||
**Response:**
|
||||
- Array of collection objects containing the book
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Book not found
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Get Collection
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Collection
|
||||
|
||||
Retrieves detailed information about a specific collection.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Response:**
|
||||
- Collection object with all fields including books, rules, and mappings
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
@@ -0,0 +1,31 @@
|
||||
info:
|
||||
name: Get Collections
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections?include_auto=true&sort_by=name'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Collections
|
||||
|
||||
Retrieves all collections for the authenticated user.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Query Parameters:**
|
||||
- `include_auto` (boolean, optional): Include auto-created collections (default false)
|
||||
- `sort_by` (string, optional): Sort field (name, created_at, book_count)
|
||||
- `order` (string, optional): Sort order (asc, desc)
|
||||
|
||||
**Response:**
|
||||
- Array of collection objects
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Get Device Mappings
|
||||
type: http
|
||||
seq: 8
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Get Device Mappings
|
||||
|
||||
Retrieves all collection mappings for a specific device.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
|
||||
**Response:**
|
||||
- Array of device mapping objects with collection details
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Device not found
|
||||
@@ -0,0 +1,31 @@
|
||||
info:
|
||||
name: Remove Book from Collection
|
||||
type: http
|
||||
seq: 7
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/{{book_id}}'
|
||||
auth: inherit
|
||||
|
||||
docs: |-
|
||||
## Remove Book from Collection
|
||||
|
||||
Removes a single book from a collection.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}/books/{book_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
- `book_id` (string): Book ID
|
||||
|
||||
**Response:**
|
||||
- `message` (string): Success message
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 404: Collection or book not found
|
||||
@@ -0,0 +1,46 @@
|
||||
info:
|
||||
name: Update Collection
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"name\": \"Sci-Fi Favorites\",\n \"description\": \"Updated\
|
||||
\ description\",\n \"color\": \"#00ff00\",\n \"icon\": \"⭐\",\n \"\
|
||||
auto_assign_rules\": [\n {\n \"id\": \"rule-2\",\n \"field\"\
|
||||
: \"series\",\n \"operator\": \"equals\",\n \"value\": \"Foundation\"\
|
||||
,\n \"priority\": 9"
|
||||
|
||||
docs: |-
|
||||
## Update Collection
|
||||
|
||||
Updates an existing collection's properties.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `collection_id` (string): Collection ID
|
||||
|
||||
**Request Body:**
|
||||
- `name` (string, optional): New collection name
|
||||
- `description` (string, optional): New description
|
||||
- `color` (string, optional): New hex color code
|
||||
- `icon` (string, optional): New emoji icon
|
||||
- `auto_assign_rules` (array, optional): Updated auto-assignment rules
|
||||
|
||||
**Response:**
|
||||
- Updated collection object
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Collection not found
|
||||
- 409: Collection name already exists
|
||||
@@ -0,0 +1,40 @@
|
||||
info:
|
||||
name: Update Device Mapping
|
||||
type: http
|
||||
seq: 10
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{mapping_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"device_shelf_name\": \"Science Fiction\",\n \"sync_direction\"\
|
||||
: \"book_to_device\""
|
||||
|
||||
docs: |-
|
||||
## Update Device Mapping
|
||||
|
||||
Updates settings for a collection-to-device mapping.
|
||||
|
||||
**Method:** PUT
|
||||
|
||||
**Endpoint:** /api/devices/{device_id}/collections/{mapping_id}
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Path Parameters:**
|
||||
- `device_id` (string): Device ID
|
||||
- `mapping_id` (string): Mapping ID
|
||||
|
||||
**Request Body:**
|
||||
- `device_shelf_name` (string, optional): Custom shelf name on device
|
||||
- `sync_direction` (string, optional): Sync direction (book_to_device, device_to_book, bidirectional)
|
||||
|
||||
**Response:**
|
||||
- Updated mapping object
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 400: Invalid request
|
||||
- 401: Unauthorized
|
||||
- 404: Device or mapping not found
|
||||
@@ -1,41 +0,0 @@
|
||||
info:
|
||||
name: Add Auto-Assign Rule
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"field": "genre",
|
||||
"operator": "equals",
|
||||
"value": "Science Fiction",
|
||||
"priority": 1,
|
||||
"enabled": true
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 201", function() {
|
||||
expect(res.status).to.eql(201);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Add Auto-Assign Rule
|
||||
|
||||
`POST /api/collections/:id/rules` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/add_auto_assign_rule.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,36 +0,0 @@
|
||||
info:
|
||||
name: Bulk Add Books
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/bulk-add-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"operations": [
|
||||
{
|
||||
"collection_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"book_ids": [
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Add Books
|
||||
|
||||
`POST /api/collections/bulk-add-books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/bulk_add_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,41 +0,0 @@
|
||||
info:
|
||||
name: Bulk Assign Books
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"book_ids": [
|
||||
"660e8400-e29b-41d4-a716-446655440000",
|
||||
"770e8400-e29b-41d4-a716-446655440000",
|
||||
"880e8400-e29b-41d4-a716-446655440000"
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Assign Books
|
||||
|
||||
`POST /api/collections/:id/books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/bulk_assign.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,32 +0,0 @@
|
||||
info:
|
||||
name: Bulk Remove Books
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"book_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Remove Books
|
||||
|
||||
`POST /api/collections/:id/books/bulk-remove` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/bulk_remove_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,47 @@
|
||||
meta:
|
||||
name: Create Custom Section with Manual Books
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"library_id\": \"{{library_id}}\",\n \"name\": \"My Favorites\"\
|
||||
,\n \"icon\": \"⭐\",\n \"description\": \"My favorite books\",\n \"show_on_dashboard\"\
|
||||
: true,\n \"auto_assign_rules\": \"\",\n \"manual_book_ids\": [\"{{media_item_id}}\"\
|
||||
],\n \"match_type\": \"all\"\n}"
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 201 with valid request\", function() {\n expect(res.status).to.eql(201);\n\
|
||||
});\n\ntest(\"response contains collection id\", function() {\n expect(res.body.id).to.exist;\n\
|
||||
expect(res.body.id).to.be.a('string');\n });\n\ntest(\"response contains\
|
||||
\ collection name\", function() {\n expect(res.body.name).to.eql(\"My Favorites\"\
|
||||
);\n });"
|
||||
|
||||
docs: |-
|
||||
Create a custom collection with manually selected books.
|
||||
|
||||
**Endpoint**: POST /api/collections
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
|
||||
"name": "My Favorites",
|
||||
"icon": "⭐",
|
||||
"description": "My favorite books",
|
||||
"show_on_dashboard": true,
|
||||
"auto_assign_rules": "",
|
||||
"manual_book_ids": ["book-id-1", "book-id-2"],
|
||||
"match_type": "all"
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns the created collection with generated ID.
|
||||
@@ -0,0 +1,23 @@
|
||||
meta:
|
||||
name: Create Custom Section Missing Required Fields
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"library_id\": \"{{library_id}}\",\n \"icon\": \"📚\"\
|
||||
\n}"
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 400 with missing name\", function() {\n expect(res.status).to.eql(400);\n\
|
||||
});\n\ntest(\"response contains error message\", function() {\n expect(res.body.error).to.exist;\n\
|
||||
\ });"
|
||||
|
||||
docs: |-
|
||||
Test error handling when creating a collection without required fields.
|
||||
|
||||
**Expected Response**: 400 Bad Request with error message.
|
||||
@@ -0,0 +1,64 @@
|
||||
meta:
|
||||
name: Create Custom Section with Filter Rules
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"library_id\": \"{{library_id}}\",\n \"name\": \"Science Fiction\
|
||||
\ Books\",\n \"icon\": \"🚀\",\n \"description\": \"All my sci-fi books\",\n\
|
||||
\ \"show_on_dashboard\": true,\n \"auto_assign_rules\": \"{\\\"rules\\\":[{\\\
|
||||
\"id\\\":\\\"rule1\\\",\\\"field\\\":\\\"genre\\\",\\\"operator\\\":\\\"equals\\\"\
|
||||
,\\\"value\\\":\\\"Sci-Fi\\\",\\\"priority\\\":1}]}\",\n \"manual_book_ids\"\
|
||||
: [],\n \"match_type\": \"all\"\n}"
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 201 with valid request\", function() {\n expect(res.status).to.eql(201);\n\
|
||||
});\n\ntest(\"response contains collection id\", function() {\n expect(res.body.id).to.exist;\n\
|
||||
expect(res.body.id).to.be.a('string');\n });\n\ntest(\"response contains\
|
||||
\ collection name\", function() {\n expect(res.body.name).to.eql(\"Science\
|
||||
\ Fiction Books\");\n });\n\ntest(\"response contains is_system false\", function()\
|
||||
\ {\n expect(res.body.is_system).to.exist;\n expect(res.body.is_system).to.eql(false);\n\
|
||||
\ });"
|
||||
|
||||
docs: |-
|
||||
Create a custom collection with filter rules.
|
||||
|
||||
**Endpoint**: POST /api/collections
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| library_id | string | Yes | Library UUID |
|
||||
| name | string | Yes | Collection name |
|
||||
| icon | string | No | Emoji icon |
|
||||
| description | string | No | Collection description |
|
||||
| show_on_dashboard | boolean | No | Show on dashboard (default: true) |
|
||||
| auto_assign_rules | string | No | JSON string of filter rules |
|
||||
| manual_book_ids | array | No | Array of book IDs |
|
||||
| match_type | string | No | "all" (AND) or "any" (OR) |
|
||||
|
||||
## Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
|
||||
"name": "Science Fiction Books",
|
||||
"icon": "🚀",
|
||||
"description": "All my sci-fi books",
|
||||
"show_on_dashboard": true,
|
||||
"auto_assign_rules": "{\"rules\":[{\"id\":\"rule1\",\"field\":\"genre\",\"operator\":\"equals\",\"value\":\"Sci-Fi\",\"priority\":1}]}",
|
||||
"manual_book_ids": [],
|
||||
"match_type": "all"
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns the created collection with generated ID.
|
||||
@@ -1,35 +0,0 @@
|
||||
info:
|
||||
name: Create Collection
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"name": "To Read",
|
||||
"description": "Books I want to read soon",
|
||||
"color": "#00FF00",
|
||||
"icon": "📖",
|
||||
"collection_type": "static",
|
||||
"auto_assign_rules": [],
|
||||
"view_settings": { "kobo": { "view_mode": "grid" } }
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Create Collection
|
||||
|
||||
`POST /api/collections` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/create_collection.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,39 +0,0 @@
|
||||
info:
|
||||
name: Create Shelf Mapping
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"collection_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"device_shelf_name": "Sci-Fi",
|
||||
"sync_direction": "bidirectional"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 201", function() {
|
||||
expect(res.status).to.eql(201);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Create Shelf Mapping
|
||||
|
||||
`POST /api/devices/:id/collections` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/create_shelf_mapping.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Delete Collection
|
||||
type: http
|
||||
seq: 7
|
||||
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Delete Collection
|
||||
|
||||
`DELETE /api/collections/:id` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/delete_collection.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Delete Shelf Mapping
|
||||
type: http
|
||||
seq: 8
|
||||
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/devices/{{device_id}}/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Delete Shelf Mapping
|
||||
|
||||
`DELETE /api/devices/:id/collections/:collectionId` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/delete_shelf_mapping.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Collection
|
||||
type: http
|
||||
seq: 9
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Collection
|
||||
|
||||
`GET /api/collections/:id` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/get_collection.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Book Collections
|
||||
type: http
|
||||
seq: 10
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Book Collections
|
||||
|
||||
`GET /api/collections/:id/books` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/get_collection_books.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: List Collections
|
||||
type: http
|
||||
seq: 11
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/collections'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# List Collections
|
||||
|
||||
`GET /api/collections` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/list_collections.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,60 @@
|
||||
meta:
|
||||
name: Preview Collection
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/preview'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"library_id\": \"{{library_id}}\",\n \"rules\": [\n\
|
||||
{\n \"id\": \"rule1\",\n \"field\": \"genre\",\n\
|
||||
\"operator\": \"equals\",\n \"value\": \"Fiction\",\n\
|
||||
\"priority\": 1\n }\n ],\n \"manual_book_ids\": [],\n \"limit\": 20\n}"
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: "test(\"status must be 200 with valid request\", function() {\n expect(res.status).to.eql(200);\n\
|
||||
});\n\ntest(\"response contains items array\", function() {\n expect(res.body.items).to.exist;\n\
|
||||
expect(res.body.items).to.be.an('array');\n });"
|
||||
|
||||
docs: |-
|
||||
Preview collection with filter rules before saving.
|
||||
|
||||
**Endpoint**: POST /api/collections/preview
|
||||
**Auth**: Required (Bearer token)
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| library_id | string | Yes | Library UUID |
|
||||
| rules | array | No | Filter rules to evaluate |
|
||||
| manual_book_ids | array | No | Manually selected book IDs |
|
||||
| limit | int | No | Max items to return (default: 20, max: 100) |
|
||||
|
||||
## Example Request
|
||||
|
||||
```json
|
||||
{
|
||||
"library_id": "cc23c3a7-f8fb-451a-a78d-2a16df1b725a",
|
||||
"rules": [
|
||||
{
|
||||
"id": "rule1",
|
||||
"field": "genre",
|
||||
"operator": "equals",
|
||||
"value": "Fiction",
|
||||
"priority": 1
|
||||
}
|
||||
],
|
||||
"manual_book_ids": [],
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
Returns array of matching book items.
|
||||
|
||||
This endpoint is used by the Custom Section Builder to show users what books will match their filter rules before they save the collection.
|
||||
@@ -1,32 +0,0 @@
|
||||
info:
|
||||
name: Preview Collection
|
||||
type: http
|
||||
seq: 12
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/preview'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"library_id": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"rules": [],
|
||||
"manual_book_ids": [],
|
||||
"limit": 20
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Preview Collection
|
||||
|
||||
`POST /api/collections/preview` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/preview_collection.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Remove Auto-Assign Rule
|
||||
type: http
|
||||
seq: 13
|
||||
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/rules/{{rule_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Remove Auto-Assign Rule
|
||||
|
||||
`DELETE /api/collections/:id/rules/:ruleId` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/remove_auto_assign_rule.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,32 +0,0 @@
|
||||
info:
|
||||
name: Reorder Collection Items
|
||||
type: http
|
||||
seq: 14
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/items/order'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"item_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Reorder Collection Items
|
||||
|
||||
`PUT /api/collections/:id/items/order` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/reorder_items.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,53 @@
|
||||
info:
|
||||
name: Bulk Add Books to Collections
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/bulk-add-books'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"operations\": [\n {\n \"collection_id\": \"{{collectionId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Add Books to Collections
|
||||
|
||||
Adds multiple books to multiple collections in a single request. Each operation specifies a collection and a list of books to add.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/bulk-add-books
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `operations` (array): Array of collection-book operations
|
||||
- `collection_id` (string): Collection UUID
|
||||
- `book_ids` (array): Array of book UUIDs to add to the collection
|
||||
|
||||
**Response:**
|
||||
- `results` (array): Results for each operation
|
||||
- `total` (number): Total number of operations
|
||||
- `success` (number): Number of successful operations
|
||||
- `failed` (number): Number of failed operations
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success (with partial results if some failed)
|
||||
- 400: Invalid request data
|
||||
- 401: Unauthorized
|
||||
- 403: Forbidden
|
||||
- 500: Internal server error
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"operations": [
|
||||
{
|
||||
"collection_id": "collection-uuid-1",
|
||||
"book_ids": ["book-1", "book-2"]
|
||||
@@ -0,0 +1,23 @@
|
||||
info:
|
||||
name: Bulk Remove Books - All Books
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books from Collection
|
||||
|
||||
Removes multiple books from a collection in a single request.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/{collection_id
|
||||
@@ -0,0 +1,27 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Empty List
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": []"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Empty List Validation
|
||||
|
||||
Tests validation behavior when providing an empty book_ids array.
|
||||
|
||||
**Expected Result:** 400 Bad Request
|
||||
|
||||
**Validation Rule:** book_ids array must contain at least one book UUID.
|
||||
|
||||
**Purpose:** Ensures the API properly validates input and rejects empty removal requests.
|
||||
@@ -0,0 +1,31 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Invalid IDs
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Invalid IDs
|
||||
|
||||
Tests behavior when the book_ids array contains invalid UUID formats or non-existent books.
|
||||
|
||||
**Expected Result:** 200 OK with partial success
|
||||
|
||||
**Purpose:** Verifies that:
|
||||
- Invalid UUID formats don't crash the endpoint
|
||||
- Non-existent book IDs are handled gracefully
|
||||
- Valid IDs in the same request are still processed
|
||||
- Response includes detailed results showing which succeeded/failed
|
||||
|
||||
**Note:** The endpoint should process all valid IDs and report failures for invalid ones, allowing clients to handle partial failures appropriately.
|
||||
@@ -0,0 +1,27 @@
|
||||
info:
|
||||
name: Bulk Remove Books - Single Book
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/books/bulk-remove'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"book_ids\": [\n \"{{bookId1"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Bulk Remove Books - Single Book
|
||||
|
||||
Tests that bulk remove endpoint works correctly with a single book.
|
||||
|
||||
**Expected Result:** 200 OK with removed: 1, total: 1
|
||||
|
||||
**Purpose:** Verifies the bulk remove endpoint handles single-item arrays correctly, providing flexibility for clients to use the same endpoint for both single and multiple removals.
|
||||
|
||||
**Note:** Using bulk remove for a single book is functionally equivalent to the single remove endpoint but allows for consistent error handling and response format.
|
||||
@@ -0,0 +1,30 @@
|
||||
info:
|
||||
name: Test Collection Rules - Author Contains
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"author\",\n \
|
||||
\ \"operator\": \"contains\",\n \"value\": \"Asimov\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Author Contains
|
||||
|
||||
Tests the "contains" operator on the author field to find books by a specific author (partial match).
|
||||
|
||||
**Example Use Case:** Finding all books by an author whose name contains "Asimov" (e.g., "Isaac Asimov").
|
||||
|
||||
**Operator:** `contains` - Matches if the field contains the specified value as a substring (case-insensitive typically).
|
||||
|
||||
**Expected Result:** Returns all books where the author field contains "Asimov".
|
||||
|
||||
**Purpose:** Demonstrates text-based partial matching for author searches, useful when you don't need the exact author name or want to find books by authors with similar names.
|
||||
@@ -0,0 +1,32 @@
|
||||
info:
|
||||
name: Test Collection Rules - Copyright Year Greater Than
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"copyright_year\"\
|
||||
,\n \"operator\": \"greater_than\",\n \"value\": \"2000\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Copyright Year Greater Than
|
||||
|
||||
Tests the "greater_than" operator on the copyright_year field to find books published after a specific year.
|
||||
|
||||
**Example Use Case:** Creating a "Modern Books" collection with books published after 2000.
|
||||
|
||||
**Operator:** `greater_than` - Matches if the field value is greater than the specified value (numeric comparison).
|
||||
|
||||
**Field:** `copyright_year` - The year the book was copyrighted/published.
|
||||
|
||||
**Expected Result:** Returns all books with copyright_year greater than 2000 (i.e., published in 2001 or later).
|
||||
|
||||
**Purpose:** Demonstrates numeric comparison operators for creating date-based collections, useful for organizing books by publication era.
|
||||
@@ -0,0 +1,29 @@
|
||||
info:
|
||||
name: Test Collection Rules - Empty Rules Array
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": []"
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - Empty Rules Array
|
||||
|
||||
Tests validation behavior when providing an empty rules array.
|
||||
|
||||
**Expected Result:** 400 Bad Request
|
||||
|
||||
**Validation Rule:** rules array must contain at least one rule object.
|
||||
|
||||
**Purpose:** Ensures the API properly validates input and rejects empty rule sets, preventing accidental queries that would return all books or cause performance issues.
|
||||
|
||||
**Use Case:** Client-side validation should prevent sending empty rules, but the API should also validate to catch malformed requests.
|
||||
@@ -0,0 +1,34 @@
|
||||
info:
|
||||
name: Test Collection Rules - No Matches
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"genre\",\n \
|
||||
\ \"operator\": \"equals\",\n \"value\": \"NonExistentGenre123456\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules - No Matches
|
||||
|
||||
Tests behavior when collection rules don't match any books in the library.
|
||||
|
||||
**Example Use Case:** Validating that a new genre name doesn't exist before creating a collection for it, or testing edge cases.
|
||||
|
||||
**Expected Result:** 200 OK with empty matches array and total: 0
|
||||
|
||||
**Purpose:** Verifies that the API handles zero-match scenarios gracefully:
|
||||
- Returns 200 (success) not 404
|
||||
- Returns empty array, not null
|
||||
- Returns total: 0 for clarity
|
||||
- No errors thrown for no results
|
||||
|
||||
**Note:** An empty result set is a valid response and doesn't indicate an error. This allows users to test rules confidently before creating collections.
|
||||
@@ -0,0 +1,67 @@
|
||||
info:
|
||||
name: Test Collection Rules
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"rules\": [\n {\n \"field\": \"genre\",\n \
|
||||
\ \"operator\": \"equals\",\n \"value\": \"Science Fiction\""
|
||||
headers:
|
||||
- key: Content-Type
|
||||
value: application/json
|
||||
- key: Authorization
|
||||
value: Bearer {{authToken
|
||||
|
||||
docs: |-
|
||||
## Test Collection Rules
|
||||
|
||||
Tests collection rules against the library to see which books match, without creating a collection. Useful for previewing what books would be included in a collection with specific rules.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/collections/test-rules
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Request Body:**
|
||||
- `rules` (array): Array of rule objects to test
|
||||
- `field` (string): Field to test (genre, author, copyright_year, tags, etc.)
|
||||
- `operator` (string): Comparison operator
|
||||
- `equals`: Exact match
|
||||
- `contains`: Contains substring (for text fields)
|
||||
- `greater_than`: Greater than (for numeric fields)
|
||||
- `less_than`: Less than (for numeric fields)
|
||||
- `not_equals`: Not equal to
|
||||
- `starts_with`: Starts with
|
||||
- `ends_with`: Ends with
|
||||
- `is_empty`: Field is empty or null
|
||||
- `is_not_empty`: Field is not empty and not null
|
||||
- `value` (string): Value to compare against (not required for is_empty/is_not_empty)
|
||||
|
||||
**Response:**
|
||||
- `matches` (array): Array of matching books
|
||||
- `id` (string): Book UUID
|
||||
- `title` (string): Book title
|
||||
- `author` (string): Book author
|
||||
- `genre` (string): Book genre
|
||||
- Additional book metadata
|
||||
- `total` (number): Total number of matching books
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success - returns matching books
|
||||
- 400: Invalid request (empty rules array, invalid field/operator)
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Request:**
|
||||
```json
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"field": "genre",
|
||||
"operator": "equals",
|
||||
"value": "Science Fiction"
|
||||
@@ -1,48 +0,0 @@
|
||||
info:
|
||||
name: Test Rule
|
||||
type: http
|
||||
seq: 15
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/collections/test-rules'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"field": "genre",
|
||||
"operator": "equals",
|
||||
"value": "Science Fiction"
|
||||
},
|
||||
{
|
||||
"field": "author",
|
||||
"operator": "contains",
|
||||
"value": "Asimov"
|
||||
}
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Test Rule
|
||||
|
||||
`POST /api/collections/test-rules` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/test_rule.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,36 +0,0 @@
|
||||
info:
|
||||
name: Update Collection
|
||||
type: http
|
||||
seq: 16
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"name": "To Read (2026)",
|
||||
"description": "Updated description",
|
||||
"color": "#33CCFF",
|
||||
"icon": "📚",
|
||||
"auto_assign_rules": [],
|
||||
"view_settings": { "hide_finished": true },
|
||||
"hide_finished": ["true"],
|
||||
"show_up_next": ["true"]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Update Collection
|
||||
|
||||
`PUT /api/collections/:id` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/update_collection.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,29 +0,0 @@
|
||||
info:
|
||||
name: Update Collection Rule
|
||||
type: http
|
||||
seq: 17
|
||||
|
||||
http:
|
||||
method: PUT
|
||||
url: '{{base_url}}/api/collections/{{collection_id}}/rules/{{rule_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"enabled": false
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Update Collection Rule
|
||||
|
||||
`PUT /api/collections/:id/rules/:ruleId` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/collections/update_rule.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Delete Conflict
|
||||
type: http
|
||||
seq: 4
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Delete Conflict
|
||||
|
||||
Permanently deletes a specific conflict record from the system.
|
||||
|
||||
**Method:** DELETE
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -0,0 +1,37 @@
|
||||
info:
|
||||
name: Dismiss All Resolved Conflicts
|
||||
type: http
|
||||
seq: 5
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/dismiss-all'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Dismiss All Resolved Conflicts
|
||||
|
||||
Deletes all resolved conflicts for the authenticated user, cleaning up the conflict list.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/dismiss-all
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Response:**
|
||||
- `deleted` (number): Number of conflict records that were deleted
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success - conflicts deleted
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"deleted": 5
|
||||
@@ -0,0 +1,22 @@
|
||||
info:
|
||||
name: Get Conflict Details
|
||||
type: http
|
||||
seq: 2
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Get Conflict Details
|
||||
|
||||
Retrieves detailed information about a specific conflict, including side-by-side comparison of conflicting data from all sources.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -0,0 +1,74 @@
|
||||
info:
|
||||
name: List Conflicts
|
||||
type: http
|
||||
seq: 1
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts?status=unresolved'
|
||||
auth: inherit
|
||||
body:
|
||||
type: none
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## List Conflicts
|
||||
|
||||
Lists all sync conflicts for the authenticated user with optional filtering.
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Endpoint:** /api/conflicts
|
||||
|
||||
**Authentication:** Bearer token
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string, optional): Filter by resolution status
|
||||
- `unresolved`: Only unresolved conflicts (default)
|
||||
- `user_resolved`: Conflicts resolved by user
|
||||
- `auto_resolved`: Automatically resolved conflicts
|
||||
- `all`: All conflicts regardless of status
|
||||
- `type` (string, optional): Filter by conflict type
|
||||
- `progress`: Reading progress conflicts
|
||||
- `note`: Bookmark/note conflicts
|
||||
- `highlight`: Highlight conflicts
|
||||
|
||||
**Response:**
|
||||
- `conflicts` (array): Array of conflict objects
|
||||
- `total` (number): Total number of conflicts matching filters
|
||||
- `unresolved` (number): Number of unresolved conflicts
|
||||
|
||||
**Each Conflict Object:**
|
||||
- `id` (string): Conflict UUID
|
||||
- `media_item_id` (string): Associated book UUID
|
||||
- `media_item_title` (string): Book title
|
||||
- `conflict_type` (string): Type of conflict (progress, note, highlight)
|
||||
- `conflict_data` (object): Side-by-side comparison of conflicting data
|
||||
- `koreader`: Data from KOReader device
|
||||
- `kobo`: Data from Kobo device
|
||||
- `web`: Data from web interface
|
||||
- `resolution_status` (string): Current status (unresolved, user_resolved, auto_resolved)
|
||||
- `created_at` (string): ISO 8601 timestamp when conflict was detected
|
||||
|
||||
**Status Codes:**
|
||||
- 200: Success
|
||||
- 401: Unauthorized
|
||||
- 500: Internal server error
|
||||
|
||||
**Example Request:**
|
||||
```
|
||||
GET /api/conflicts?status=unresolved&type=progress
|
||||
```
|
||||
|
||||
**Example Response:**
|
||||
```json
|
||||
{
|
||||
"conflicts": [
|
||||
{
|
||||
"id": "conflict-uuid",
|
||||
"media_item_id": "book-uuid",
|
||||
"media_item_title": "Foundation",
|
||||
"conflict_type": "progress",
|
||||
"conflict_data": {
|
||||
"koreader": { "percentage": 0.65, "epubcfi": "..."
|
||||
@@ -0,0 +1,25 @@
|
||||
info:
|
||||
name: Resolve Conflict
|
||||
type: http
|
||||
seq: 3
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/{{conflict_id}}/resolve'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
jsonBody: "{\n \"winner\": \"koreader\",\n \"manual_data\": null,\n \"\
|
||||
apply_to_all_future_conflicts\": false,\n \"reason\": \"User chose more recent\
|
||||
\ progress\""
|
||||
headers:
|
||||
- key: Authorization
|
||||
value: Bearer {{token
|
||||
|
||||
docs: |-
|
||||
## Resolve Conflict
|
||||
|
||||
Resolves a sync conflict by choosing which source to use for the conflicting data.
|
||||
|
||||
**Method:** POST
|
||||
|
||||
**Endpoint:** /api/conflicts/{conflict_id
|
||||
@@ -1,40 +0,0 @@
|
||||
info:
|
||||
name: Bulk Dismiss Conflicts
|
||||
type: http
|
||||
seq: 1
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/bulk-dismiss'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"conflict_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
]
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Dismiss Conflicts
|
||||
|
||||
`POST /api/conflicts/bulk-dismiss` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/bulk_dismiss_conflicts.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,41 +0,0 @@
|
||||
info:
|
||||
name: Bulk Resolve Conflicts
|
||||
type: http
|
||||
seq: 2
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/bulk-resolve'
|
||||
auth: inherit
|
||||
body:
|
||||
type: json
|
||||
data: |-
|
||||
{
|
||||
"conflict_ids": [
|
||||
"550e8400-e29b-41d4-a716-446655440000",
|
||||
"660e8400-e29b-41d4-a716-446655440001"
|
||||
],
|
||||
"strategy": "highest_progress"
|
||||
}
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Bulk Resolve Conflicts
|
||||
|
||||
`POST /api/conflicts/bulk-resolve` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/bulk_resolve_conflicts.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Delete Conflict
|
||||
type: http
|
||||
seq: 3
|
||||
|
||||
http:
|
||||
method: DELETE
|
||||
url: '{{base_url}}/api/conflicts/{{media_item_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 204", function() {
|
||||
expect(res.status).to.eql(204);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Delete Conflict
|
||||
|
||||
`DELETE /api/conflicts/:id` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/delete_conflict.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Dismiss All Resolved
|
||||
type: http
|
||||
seq: 4
|
||||
|
||||
http:
|
||||
method: POST
|
||||
url: '{{base_url}}/api/conflicts/dismiss-all'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Dismiss All Resolved
|
||||
|
||||
`POST /api/conflicts/dismiss-all` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/dismiss_all_resolved.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: Get Conflict Details
|
||||
type: http
|
||||
seq: 5
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts/{{media_item_id}}'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# Get Conflict Details
|
||||
|
||||
`GET /api/conflicts/:id` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/get_conflict.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
@@ -1,31 +0,0 @@
|
||||
info:
|
||||
name: List Conflicts
|
||||
type: http
|
||||
seq: 6
|
||||
|
||||
http:
|
||||
method: GET
|
||||
url: '{{base_url}}/api/conflicts'
|
||||
auth: inherit
|
||||
settings:
|
||||
encodeUrl: true
|
||||
timeout: 0
|
||||
followRedirects: true
|
||||
maxRedirects: 5
|
||||
|
||||
runtime:
|
||||
scripts:
|
||||
- type: tests
|
||||
code: |-
|
||||
test("status is 200", function() {
|
||||
expect(res.status).to.eql(200);
|
||||
});
|
||||
|
||||
docs:
|
||||
content: |-
|
||||
# List Conflicts
|
||||
|
||||
`GET /api/conflicts` — auth: jwt.
|
||||
|
||||
Canonical reference: docs/developer/api/conflicts/list_conflicts.md (docs site → Developer → API). This request is GENERATED from that doc; edit the doc, then run the drift test with -update.
|
||||
type: text/markdown
|
||||
Loaded 100 of 1051 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user