From 9ae584f0ec60eb18cc17fe956fcac1eeec0a17f7 Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Wed, 30 Sep 2026 08:59:42 -0700 Subject: [PATCH] Feature: Bookorbit service widget (#7202) --- docs/widgets/services/bookorbit.md | 21 ++++ docs/widgets/services/index.md | 1 + mkdocs.yml | 1 + public/locales/en/common.json | 8 ++ src/widgets/bookorbit/component.jsx | 44 +++++++ src/widgets/bookorbit/component.test.jsx | 67 +++++++++++ src/widgets/bookorbit/proxy.js | 137 ++++++++++++++++++++++ src/widgets/bookorbit/proxy.test.js | 139 +++++++++++++++++++++++ src/widgets/bookorbit/widget.js | 8 ++ src/widgets/bookorbit/widget.test.js | 11 ++ src/widgets/components.js | 1 + src/widgets/widgets.js | 2 + 12 files changed, 440 insertions(+) create mode 100644 docs/widgets/services/bookorbit.md create mode 100644 src/widgets/bookorbit/component.jsx create mode 100644 src/widgets/bookorbit/component.test.jsx create mode 100644 src/widgets/bookorbit/proxy.js create mode 100644 src/widgets/bookorbit/proxy.test.js create mode 100644 src/widgets/bookorbit/widget.js create mode 100644 src/widgets/bookorbit/widget.test.js diff --git a/docs/widgets/services/bookorbit.md b/docs/widgets/services/bookorbit.md new file mode 100644 index 000000000..13d8b2d46 --- /dev/null +++ b/docs/widgets/services/bookorbit.md @@ -0,0 +1,21 @@ +--- +title: BookOrbit +description: BookOrbit Widget Configuration +--- + +Learn more about [BookOrbit](https://github.com/bookorbit/bookorbit). + +```yaml +widget: + type: bookorbit + url: http://bookorbit.host.or.ip:3000 + username: username + password: password + fields: ["books", "authors", "reading", "finished"] # optional +``` + +## Fields + +Allowed fields: `["books", "authors", "series", "storage", "reading", "finished"]` (maximum of 4). + +Default fields: `["books", "authors", "reading", "finished"]`. diff --git a/docs/widgets/services/index.md b/docs/widgets/services/index.md index 270a7492e..c3d5ea738 100644 --- a/docs/widgets/services/index.md +++ b/docs/widgets/services/index.md @@ -19,6 +19,7 @@ You can also find a list of all available service widgets in the sidebar navigat - [Backrest](backrest.md) - [Bazarr](bazarr.md) - [Booklore](booklore.md) +- [BookOrbit](bookorbit.md) - [Beszel](beszel.md) - [Caddy](caddy.md) - [Calendar](calendar.md) diff --git a/mkdocs.yml b/mkdocs.yml index 6edfcebc4..5b8534ed1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: - widgets/services/backrest.md - widgets/services/bazarr.md - widgets/services/booklore.md + - widgets/services/bookorbit.md - widgets/services/beszel.md - widgets/services/caddy.md - widgets/services/calendar.md diff --git a/public/locales/en/common.json b/public/locales/en/common.json index 4363427d7..f818143d6 100644 --- a/public/locales/en/common.json +++ b/public/locales/en/common.json @@ -869,6 +869,14 @@ "reading": "Reading", "finished": "Finished" }, + "bookorbit": { + "books": "Books", + "authors": "Authors", + "series": "Series", + "storage": "Storage", + "reading": "Reading", + "finished": "Finished" + }, "jdownloader": { "downloadCount": "Queue", "downloadBytesRemaining": "Remaining", diff --git a/src/widgets/bookorbit/component.jsx b/src/widgets/bookorbit/component.jsx new file mode 100644 index 000000000..ea4bcfd01 --- /dev/null +++ b/src/widgets/bookorbit/component.jsx @@ -0,0 +1,44 @@ +import { useTranslation } from "next-i18next/pages"; + +import Block from "components/services/widget/block"; +import Container from "components/services/widget/container"; +import useWidgetAPI from "utils/proxy/use-widget-api"; +import withWidgetFields from "utils/widget-fields"; + +const DEFAULT_FIELDS = ["books", "authors", "reading", "finished"]; + +export default function Component({ service: configuredService }) { + const { t } = useTranslation(); + const service = withWidgetFields(configuredService, DEFAULT_FIELDS); + const { widget } = service; + + const { data, error } = useWidgetAPI(widget); + + if (error) { + return ; + } + + if (!data) { + return ( + + + + + + + + + ); + } + + return ( + + + + + + + + + ); +} diff --git a/src/widgets/bookorbit/component.test.jsx b/src/widgets/bookorbit/component.test.jsx new file mode 100644 index 000000000..126b88c71 --- /dev/null +++ b/src/widgets/bookorbit/component.test.jsx @@ -0,0 +1,67 @@ +// @vitest-environment jsdom + +import { screen } from "@testing-library/react"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +import { renderWithProviders } from "test-utils/render-with-providers"; +import { expectBlockValue } from "test-utils/widget-assertions"; + +const { useWidgetAPI } = vi.hoisted(() => ({ useWidgetAPI: vi.fn() })); +vi.mock("utils/proxy/use-widget-api", () => ({ default: useWidgetAPI })); + +import Component from "./component"; + +const data = { books: 1200, authors: 300, series: 45, storage: 1024, reading: 2, finished: 80 }; + +describe("widgets/bookorbit/component", () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it("renders default placeholders while loading", () => { + useWidgetAPI.mockReturnValue({ data: undefined, error: undefined }); + + const { container } = renderWithProviders(, { + settings: { hideErrors: false }, + }); + + expect(container.querySelectorAll(".service-block")).toHaveLength(4); + expect(screen.getByText("bookorbit.books")).toBeInTheDocument(); + expect(screen.getByText("bookorbit.authors")).toBeInTheDocument(); + expect(screen.getByText("bookorbit.reading")).toBeInTheDocument(); + expect(screen.getByText("bookorbit.finished")).toBeInTheDocument(); + }); + + it("renders error UI when the endpoint errors", () => { + useWidgetAPI.mockReturnValue({ data: undefined, error: { message: "nope" } }); + + renderWithProviders(, { settings: { hideErrors: false } }); + + expect(screen.getAllByText(/widget\.api_error/i).length).toBeGreaterThan(0); + }); + + it("renders the default fields", () => { + useWidgetAPI.mockReturnValue({ data, error: undefined }); + + const { container } = renderWithProviders(, { + settings: { hideErrors: false }, + }); + + expect(container.querySelectorAll(".service-block")).toHaveLength(4); + expectBlockValue(container, "bookorbit.books", 1200); + expectBlockValue(container, "bookorbit.authors", 300); + expectBlockValue(container, "bookorbit.reading", 2); + expectBlockValue(container, "bookorbit.finished", 80); + }); + + it("renders configured fields", () => { + useWidgetAPI.mockReturnValue({ data, error: undefined }); + + const service = { widget: { type: "bookorbit", fields: ["series", "storage"] } }; + const { container } = renderWithProviders(, { settings: { hideErrors: false } }); + + expect(container.querySelectorAll(".service-block")).toHaveLength(2); + expectBlockValue(container, "bookorbit.series", 45); + expectBlockValue(container, "bookorbit.storage", 1024); + }); +}); diff --git a/src/widgets/bookorbit/proxy.js b/src/widgets/bookorbit/proxy.js new file mode 100644 index 000000000..49b9e4395 --- /dev/null +++ b/src/widgets/bookorbit/proxy.js @@ -0,0 +1,137 @@ +import cache from "memory-cache"; + +import getServiceWidget from "utils/config/service-helpers"; +import createLogger from "utils/logger"; +import { formatApiCall } from "utils/proxy/api-helpers"; +import { httpProxy } from "utils/proxy/http"; +import widgets from "widgets/widgets"; + +const proxyName = "bookorbitProxyHandler"; +const accessTokenCacheKey = `${proxyName}__accessToken`; +const refreshTokenCacheKey = `${proxyName}__refreshToken`; +const logger = createLogger(proxyName); + +async function requestTokens(widget, service, endpoint, body) { + const url = new URL(formatApiCall(widgets[widget.type].api, { ...widget, endpoint })); + const [status, , data] = await httpProxy(url, { + method: "POST", + headers: { "Content-Type": "application/json", accept: "application/json" }, + body: JSON.stringify(body), + }); + + if (status !== 200) { + logger.debug("BookOrbit %s failed for service '%s' with status %d", endpoint, service, status); + return null; + } + + try { + const { accessToken, refreshToken } = JSON.parse(data.toString()); + if (!accessToken) return null; + + // expired tokens are replaced when a request gets a 401 + cache.put(`${accessTokenCacheKey}.${service}`, accessToken); + if (refreshToken) cache.put(`${refreshTokenCacheKey}.${service}`, refreshToken); + return accessToken; + } catch (e) { + logger.error("Unable to parse BookOrbit %s response: %s", endpoint, e); + } + + return null; +} + +async function loginOrRefresh(widget, service, forceNew = false) { + if (!forceNew) { + const cached = cache.get(`${accessTokenCacheKey}.${service}`); + if (cached) return cached; + } + + const refreshToken = cache.get(`${refreshTokenCacheKey}.${service}`); + if (refreshToken) { + const accessToken = await requestTokens(widget, service, "auth/refresh", { refreshToken }); + if (accessToken) return accessToken; + cache.del(`${refreshTokenCacheKey}.${service}`); + } + + // native clients get the refresh token in the body + return requestTokens(widget, service, "auth/login", { + username: widget.username, + password: widget.password, + clientKind: "native", + deviceLabel: "Homepage", + }); +} + +async function apiCall(widget, endpoint, service) { + const url = new URL(formatApiCall(widgets[widget.type].api, { ...widget, endpoint })); + const request = async (accessToken) => + httpProxy(url, { + method: "GET", + headers: { accept: "application/json", Authorization: `Bearer ${accessToken}` }, + }); + + let accessToken = await loginOrRefresh(widget, service); + if (!accessToken) return { status: 401, data: null }; + + let [status, , data] = await request(accessToken); + + if (status === 401) { + logger.debug("BookOrbit API rejected the request, attempting to obtain a new access token"); + cache.del(`${accessTokenCacheKey}.${service}`); + accessToken = await loginOrRefresh(widget, service, true); + if (!accessToken) return { status, data: null }; + [status, , data] = await request(accessToken); + } + + if (status !== 200) { + logger.error("Error getting data from BookOrbit: %s status %d. Data: %s", url, status, data); + return { status, data: null }; + } + + try { + return { status, data: JSON.parse(data.toString()) }; + } catch (e) { + logger.error("Error parsing BookOrbit response: %s", e); + } + + return { status: 500, data: null }; +} + +export default async function bookorbitProxyHandler(req, res) { + const { group, service, index } = req.query; + + if (!group || !service) { + logger.debug("Invalid or missing service '%s' or group '%s'", service, group); + return res.status(400).json({ error: "Invalid proxy service type" }); + } + + const widget = await getServiceWidget(group, service, index); + + if (!widget) { + logger.debug("Invalid or missing widget for service '%s' in group '%s'", service, group); + return res.status(400).json({ error: "Invalid proxy service type" }); + } + + if (!widget.username || !widget.password) { + logger.debug("Missing credentials for BookOrbit widget in service '%s'", service); + return res.status(400).json({ error: "Missing BookOrbit credentials" }); + } + + const library = await apiCall(widget, "statistics/summary", service); + if (!library.data) { + return res.status(library.status).json({ error: "Error fetching BookOrbit library statistics" }); + } + + const reading = await apiCall(widget, "user-statistics/summary", service); + if (!reading.data) { + return res.status(reading.status).json({ error: "Error fetching BookOrbit reading statistics" }); + } + + return res.status(200).json({ + books: library.data.totalBooks, + authors: library.data.totalAuthors, + series: library.data.totalSeries, + storage: library.data.totalStorageBytes, + reading: reading.data.inProgressBooks, + finished: reading.data.completedBooks, + }); +} diff --git a/src/widgets/bookorbit/proxy.test.js b/src/widgets/bookorbit/proxy.test.js new file mode 100644 index 000000000..c13e5f73d --- /dev/null +++ b/src/widgets/bookorbit/proxy.test.js @@ -0,0 +1,139 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +import createMockRes from "test-utils/create-mock-res"; + +const { httpProxy, getServiceWidget, cache, logger } = vi.hoisted(() => { + const store = new Map(); + + return { + httpProxy: vi.fn(), + getServiceWidget: vi.fn(), + cache: { + get: vi.fn((k) => store.get(k)), + put: vi.fn((k, v) => store.set(k, v)), + del: vi.fn((k) => store.delete(k)), + _reset: () => store.clear(), + }, + logger: { + debug: vi.fn(), + error: vi.fn(), + }, + }; +}); + +vi.mock("utils/logger", () => ({ default: () => logger })); +vi.mock("utils/config/service-helpers", () => ({ default: getServiceWidget })); +vi.mock("utils/proxy/http", () => ({ httpProxy })); +vi.mock("memory-cache", () => ({ default: cache, ...cache })); +vi.mock("widgets/widgets", () => ({ + default: { bookorbit: { api: "{url}/api/v1/{endpoint}" } }, +})); + +import bookorbitProxyHandler from "./proxy"; + +const widget = { type: "bookorbit", url: "http://bookorbit", username: "u", password: "p" }; +const req = { query: { group: "g", service: "svc", index: "0" } }; + +const json = (body, status = 200) => [status, "application/json", Buffer.from(JSON.stringify(body))]; +const tokens = (n) => ({ accessToken: `access${n}`, refreshToken: `refresh${n}` }); +const summary = { totalBooks: 10, totalAuthors: 4, totalSeries: 2, totalStorageBytes: 2048 }; +const userSummary = { inProgressBooks: 1, completedBooks: 3 }; + +describe("widgets/bookorbit/proxy", () => { + beforeEach(() => { + vi.clearAllMocks(); + cache._reset(); + }); + + it("returns 400 when credentials are missing", async () => { + getServiceWidget.mockResolvedValue({ type: "bookorbit", url: "http://bookorbit" }); + const res = createMockRes(); + + await bookorbitProxyHandler(req, res); + + expect(res.statusCode).toBe(400); + expect(res.body).toEqual({ error: "Missing BookOrbit credentials" }); + }); + + it("logs in as a native client and combines library and reading stats", async () => { + getServiceWidget.mockResolvedValue(widget); + httpProxy + .mockResolvedValueOnce(json(tokens(1))) + .mockResolvedValueOnce(json(summary)) + .mockResolvedValueOnce(json(userSummary)); + const res = createMockRes(); + + await bookorbitProxyHandler(req, res); + + expect(httpProxy).toHaveBeenCalledTimes(3); + expect(JSON.parse(httpProxy.mock.calls[0][1].body)).toEqual( + expect.objectContaining({ username: "u", password: "p", clientKind: "native" }), + ); + expect(httpProxy.mock.calls[1][0].toString()).toBe("http://bookorbit/api/v1/statistics/summary"); + expect(httpProxy.mock.calls[1][1].headers.Authorization).toBe("Bearer access1"); + expect(res.statusCode).toBe(200); + expect(res.body).toEqual({ books: 10, authors: 4, series: 2, storage: 2048, reading: 1, finished: 3 }); + }); + + it("reuses the cached access token", async () => { + getServiceWidget.mockResolvedValue(widget); + httpProxy + .mockResolvedValueOnce(json(tokens(1))) + .mockResolvedValueOnce(json(summary)) + .mockResolvedValueOnce(json(userSummary)) + .mockResolvedValueOnce(json(summary)) + .mockResolvedValueOnce(json(userSummary)); + + await bookorbitProxyHandler(req, createMockRes()); + await bookorbitProxyHandler(req, createMockRes()); + + const loginCalls = httpProxy.mock.calls.filter(([url]) => url.toString().includes("auth/")); + expect(loginCalls).toHaveLength(1); + }); + + it("uses the refresh token when the access token is rejected", async () => { + getServiceWidget.mockResolvedValue(widget); + httpProxy + .mockResolvedValueOnce(json(tokens(1))) + .mockResolvedValueOnce(json({}, 401)) + .mockResolvedValueOnce(json(tokens(2))) + .mockResolvedValueOnce(json(summary)) + .mockResolvedValueOnce(json(userSummary)); + const res = createMockRes(); + + await bookorbitProxyHandler(req, res); + + expect(httpProxy.mock.calls[2][0].toString()).toBe("http://bookorbit/api/v1/auth/refresh"); + expect(JSON.parse(httpProxy.mock.calls[2][1].body)).toEqual({ refreshToken: "refresh1" }); + expect(httpProxy.mock.calls[3][1].headers.Authorization).toBe("Bearer access2"); + expect(res.statusCode).toBe(200); + }); + + it("falls back to logging in when the refresh token is rejected", async () => { + getServiceWidget.mockResolvedValue(widget); + httpProxy + .mockResolvedValueOnce(json(tokens(1))) + .mockResolvedValueOnce(json({}, 401)) + .mockResolvedValueOnce(json({}, 401)) + .mockResolvedValueOnce(json(tokens(3))) + .mockResolvedValueOnce(json(summary)) + .mockResolvedValueOnce(json(userSummary)); + const res = createMockRes(); + + await bookorbitProxyHandler(req, res); + + expect(httpProxy.mock.calls[3][0].toString()).toBe("http://bookorbit/api/v1/auth/login"); + expect(httpProxy.mock.calls[4][1].headers.Authorization).toBe("Bearer access3"); + expect(res.statusCode).toBe(200); + }); + + it("returns an error when login fails", async () => { + getServiceWidget.mockResolvedValue(widget); + httpProxy.mockResolvedValueOnce(json({ message: "Invalid credentials" }, 401)); + const res = createMockRes(); + + await bookorbitProxyHandler(req, res); + + expect(res.statusCode).toBe(401); + }); +}); diff --git a/src/widgets/bookorbit/widget.js b/src/widgets/bookorbit/widget.js new file mode 100644 index 000000000..71a40165f --- /dev/null +++ b/src/widgets/bookorbit/widget.js @@ -0,0 +1,8 @@ +import bookorbitProxyHandler from "./proxy"; + +const widget = { + api: "{url}/api/v1/{endpoint}", + proxyHandler: bookorbitProxyHandler, +}; + +export default widget; diff --git a/src/widgets/bookorbit/widget.test.js b/src/widgets/bookorbit/widget.test.js new file mode 100644 index 000000000..dc5e9debe --- /dev/null +++ b/src/widgets/bookorbit/widget.test.js @@ -0,0 +1,11 @@ +import { describe, it } from "vitest"; + +import { expectWidgetConfigShape } from "test-utils/widget-config"; + +import widget from "./widget"; + +describe("bookorbit widget config", () => { + it("exports a valid widget config", () => { + expectWidgetConfigShape(widget); + }); +}); diff --git a/src/widgets/components.js b/src/widgets/components.js index 7ae5ff9de..78d0e310d 100644 --- a/src/widgets/components.js +++ b/src/widgets/components.js @@ -14,6 +14,7 @@ const components = { bazarr: dynamic(() => import("./bazarr/component")), beszel: dynamic(() => import("./beszel/component")), booklore: dynamic(() => import("./booklore/component")), + bookorbit: dynamic(() => import("./bookorbit/component")), caddy: dynamic(() => import("./caddy/component")), calendar: dynamic(() => import("./calendar/component")), calibreweb: dynamic(() => import("./calibreweb/component")), diff --git a/src/widgets/widgets.js b/src/widgets/widgets.js index 3691e648f..c1c1d43d3 100644 --- a/src/widgets/widgets.js +++ b/src/widgets/widgets.js @@ -11,6 +11,7 @@ import backrest from "./backrest/widget"; import bazarr from "./bazarr/widget"; import beszel from "./beszel/widget"; import booklore from "./booklore/widget"; +import bookorbit from "./bookorbit/widget"; import caddy from "./caddy/widget"; import calendar from "./calendar/widget"; import calibreweb from "./calibreweb/widget"; @@ -173,6 +174,7 @@ const widgets = { backrest, bazarr, booklore, + bookorbit, beszel, caddy, calibreweb,