api

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Classes

ApiError

HTTP failure from Bookclerk JSON APIs, including optional machine code.

Extends

  • Error

Constructors

Constructor
new ApiError(
   status, 
   message, 
   extras?
): ApiError;
Parameters
Parameter Type
status number
message string
extras? { code?: string; pluginId?: string; summary?: string[]; }
extras.code? string
extras.pluginId? string
extras.summary? string[]
Returns

ApiError

Overrides

Error.constructor

Properties

code?
code?: string;

Machine slug from JSON error bodies when present.

pluginId?
pluginId?: string;
status
status: number;
summary?
summary?: string[];

Interfaces

AccountHolder

A listing held by a store account.

Properties

account_id
account_id: string;

The account's id on that storefront.

kind
kind: "account";

Discriminant.

plugin_key
plugin_key: string;

The account's storefront plugin (audible, libro, ...).


ActionResponse

Ack payload for scan / acquire job triggers.

Properties

error?
error?: string | null;
job_id
job_id: string;
message
message: string;
ok
ok: boolean;

AuthMeImpersonating

Active impersonation target when an administrator is viewing as another user.

Properties

display_name
display_name: string | null;
user_id
user_id: number;

AuthMeUser

Signed-in administrator or member profile from /api/auth/me.

Properties

avatar_source?
avatar_source?: string | null;

auto, monogram, gravatar, upload, or sso:{id}.

display_name
display_name: string | null;
email?
email?: string | null;
gravatar_hash?
gravatar_hash?: string | null;

SHA-256 hex of the contact email for Gravatar.

has_avatar?
has_avatar?: boolean;

True when a profile picture file is stored for this user.

has_password?
has_password?: boolean;
id
id: number;
login_name?
login_name?: string | null;
role
role: string;
sso_pictures?
sso_pictures?: object[];

IdP-supplied pictures the user can pick.

identity_id
identity_id: number;
last_used_at?
last_used_at?: string | null;
picture_path?
picture_path?: string | null;

Same-origin 128 px copy of picture_url, when the server signed one.

picture_url
picture_url: string;
provider
provider: string;
status?
status?: string;

AuthSecondFactor

Host MFA policy plus this user's TOTP / passkey enrollment.

Properties

enrolled
enrolled: boolean;
passkey_count
passkey_count: number;
required
required: boolean;
totp
totp: boolean;

AuthSession

Normalized client session used to gate SPA views and actions.

Properties

administers_nodes?
administers_nodes?: boolean;

Whether the session reaches node administration and the Status page: the operator, an Owner or Administrator, or a Member who owns a node.

authenticated
authenticated: boolean;
can_acquire
can_acquire: boolean;
default_view
default_view: AppView;
elevated?
elevated?: boolean;
impersonating?
impersonating?: AuthMeImpersonating;
portal?
portal?: PortalInfo;
role?
role?: AuthRole;
second_factor?
second_factor?: AuthSecondFactor;
see_prices
see_prices: boolean;

Whether the caller may see prices and store links. When false the library already drops them from its answers, and the app shows no store links of its own either.

user?
user?: AuthMeUser;

BootstrapAdministratorResponse

Bootstrap response for the first owner.

Properties

claim_ticket
claim_ticket: string;
has_password
has_password: boolean;
invite_url?
invite_url?: string | null;
login_name
login_name: string | null;
ok
ok: boolean;
user_id
user_id: number;

BranchAvailability

One branch of this library that can supply a title (it answered a catalog lookup for the title's work).

Properties

node_id
node_id: string;

The branch node id.

owner_name?
owner_name?: string | null;

The branch owner's display name, when the owner has one.

product_id
product_id: string;

The store's product id of the branch's copy.

store
store: string;

The store the branch has the book from (audible).

work_id
work_id: string;

This library's work the branch supplies; what requestFromBranch asks for.


BranchRequestQueued

POST /api/branch-requests answer.

Properties

already_queued
already_queued: boolean;

true when a request for this work to this branch was already waiting.

job_id
job_id: string;

The request's job, as /api/jobs lists it.

node_id
node_id: string;

The branch the request went to.


CatalogListingView

The signed-in user's catalog listing choice.

Properties

always_listed
always_listed: boolean;

true for an Owner, whose books are always listed; listed then has no effect.

libraries
libraries: number;

Libraries this server is currently a branch of; the choice matters only above zero.

listed
listed: boolean;

true (the default) unless the user keeps their books out of catalog answers.


CatalogSearchHit

One hit from /api/discover/search.

Properties

asin
asin: string | null;
authors
authors: string | null;
available_through?
available_through?: BranchAvailability[];

Branches of this library that currently list this title.

cover_path?
cover_path?: string | null;

Same-origin path of this cover's processed images; see coverSrc.

cover_url?
cover_url?: string | null;
description?
description?: string | null;
genres?
genres?: string | null;
is_abridged?
is_abridged?: boolean | null;
isbn
isbn: string | null;
language?
language?: string | null;
length_minutes?
length_minutes?: number | null;
narrators
narrators: string | null;
price_cents?
price_cents?: number | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
purchase_hints?
purchase_hints?: PurchaseHint[];
rating_count?
rating_count?: number | null;
rating_overall?
rating_overall?: number | null;
series
series: string | null;
series_index?
series_index?: string | null;
sources
sources: string[];
store_editions
store_editions: StoreEdition[];
subtitle?
subtitle?: string | null;
title
title: string;
work_key
work_key: string;

CatalogSearchPage

Cursor-paginated catalog search page.

Properties

has_more
has_more: boolean;
items
items: CatalogSearchHit[];
next_cursor?
next_cursor?: string | null;
page_size
page_size: number;
sort
sort: string;
sort_dir?
sort_dir?: string;

ConfigNodeView

One library node as GET /api/config/nodes returns it.

Properties

implicit_labels
implicit_labels: string[];

Labels every node carries (node=<id>, target=<target>).

kind
kind: "shared" | "branch";

shared (shares the database) or branch (its own database, enrolled to contribute).

labels
labels: string[];

Operator labels.

live
live: boolean;

True while the node's daemon heartbeats.

node_id
node_id: string;
owner
owner: 
  | {
  display_name: string | null;
  role: string;
  user_id: number;
}
  | null;

User who administers this node, when one is assigned.

relationship
relationship: BranchRelationship;

shared_branch (shares the database), remote_branch (a branch that reports a public address) or local_branch (a branch with none).

runtime
runtime: NodeRuntimeView;
software_version?
software_version?: string;
status
status: NodeStatusView | null;

Latest heartbeat; null when the node's daemon never ran.

target
target: string;
this_node
this_node: boolean;

True for the node serving this request.


DiagnosticsReport

One diagnostics report this install sent (GET /api/diagnostics/reports).

Properties

access_code
access_code: string | null;

The code that reads it back or deletes it (XXXX-XXXX-XXXX-XXXX), or null when the collector issued none.

deleted_at_unix_ms
deleted_at_unix_ms: number | null;

When this install deleted the collector's stored copy, Unix milliseconds, or null.

report_id
report_id: string;

The collector's ID for the report; the GitHub issue filed for it mentions this ID.

sent_at_unix_ms
sent_at_unix_ms: number;

When the collector accepted it, Unix milliseconds.

trigger
trigger: string;

Why it was sent: crash, error_burst, slow_burst, job_failed, cli_error, ….

version
version: string;

The Bookclerk version that sent it.


DiagnosticsReportEvent

One logged event in a stored report.

Properties

fields
fields: object[];

Redacted fields recorded with it.

name
name: string;
value
value: string;
level
level: "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE";

Severity.

message
message: string;

The redacted message.

target
target: string;

Where it was logged.

ts_unix_ms
ts_unix_ms: number;

When it happened, Unix milliseconds, or 0 when unknown.


DiagnosticsReportLookup

A report read back from the collector (GET /api/diagnostics/reports/{id}).

Properties

deleted_at_unix_ms
deleted_at_unix_ms: number | null;

When its stored copy was deleted, Unix milliseconds, or null.

fix
fix: 
  | {
  fixed_in: string | null;
  pr_number: number | null;
  pr_url: string | null;
}
  | null;

The tracking issue's fix, or null.

issues
issues: object[];

GitHub issues tracking it, the tracking issue first.

number
number: number;
state
state: "open" | "closed";
title
title: string;
url
url: string;
received_at_unix_ms
received_at_unix_ms: number;

When the collector received it, Unix milliseconds.

report
report: 
  | {
  arch: string;
  distro: string;
  events: DiagnosticsReportEvent[];
  os: string;
  trigger: string;
  version: string;
}
  | null;

The stored report, or null once deleted.

Union Members
Type Literal
{
  arch: string;
  distro: string;
  events: DiagnosticsReportEvent[];
  os: string;
  trigger: string;
  version: string;
}
arch
arch: string;

CPU architecture.

distro
distro: string;

Linux distribution, or empty.

events
events: DiagnosticsReportEvent[];

Events, oldest first.

os
os: string;

Operating system.

trigger
trigger: string;

Why it was sent.

version
version: string;

Version that sent it.


null

report_id
report_id: string;

The report's ID.


DiscoverFeed

Discover recommendations feed payload.

Properties

computed_at?
computed_at?: string;

RFC 3339 time the stored shelves were ranked.

shelf_kinds?
shelf_kinds?: ShelfKindInfo[];
shelves
shelves: DiscoverShelf[];
state?
state?: DiscoverFeedState;

How current the stored shelves are: preparing (none stored yet), refreshing (newer ones queued) or ready.


DiscoverShelf

One Discover feed shelf (id, copy, items).

Properties

id
id: string;
items
items: Recommendation[];
subtitle
subtitle: string | null;
title
title: string;

DiscoverStatus

Stored state of the caller's Discover shelves (GET /api/discover/status).

Properties

candidates_fetched_at?
candidates_fetched_at?: string | null;
feed_computed_at?
feed_computed_at?: string | null;
ready
ready: boolean;
scope?
scope?: string | null;
subject
subject: string;
updating
updating: boolean;

True while a fetch or ranking for the caller is waiting or running.


Edition

One edition of a work, with its listings.

Properties

abridgement
abridgement: Abridgement;

Whether it is abridged.

acquire_status
acquire_status: AcquireStatus;

Its acquire state.

cover_path
cover_path: string | null;

Same-origin path of its processed cover; see coverSrc.

duration_minutes
duration_minutes: number | null;

Runtime in minutes, when known.

expression_id
expression_id: string;

Its expression.

expression_kind
expression_kind: ExpressionKind;

How the expression renders the work.

id
id: string;

Edition id; acquire takes it in editions.

language
language: string | null;

Language code, when known.

listings
listings: Listing[];

Store listings that sell it.

media_kind
media_kind: MediaKind;

How it is consumed.

published_at
published_at: string | null;

Publication date (ISO-8601), when known.

subtitle
subtitle: string | null;

Subtitle, when known.

title
title: string;

Edition title.

work_id
work_id: string;

The work it belongs to (an episode for a podcast's editions).


EventDeliveryInfo

Operator delivery row from /api/events/deliveries.

Properties

attemptCount
attemptCount: number;
cancelRequested
cancelRequested: boolean;
errorMessage
errorMessage: string | null;
eventId
eventId: string;
hasCheckpoint
hasCheckpoint: boolean;
id
id: string;
invocationSequence
invocationSequence: number;
leaseGeneration
leaseGeneration: number;
outcome
outcome: string | null;
pluginId
pluginId: string;
resourceClass
resourceClass: string;
resumePending
resumePending: boolean;
runAfter
runAfter: string;
state
state: string;
updatedAt
updatedAt: string;

EventQueueStatus

Durable domain-event delivery-queue counters from /api/status.

Properties

acked
acked: number;
dead_letter
dead_letter: number;
dead_letters_total?
dead_letters_total?: number;
dispatch_latency_ms_avg?
dispatch_latency_ms_avg?: number | null;
handler_latency_ms_avg?
handler_latency_ms_avg?: number | null;
oldest_pending_age_secs
oldest_pending_age_secs: number | null;
pending
pending: number;
retries_total?
retries_total?: number;
running
running: number;
suspended
suspended: number;
suspensions_total?
suspensions_total?: number;

FacetValue

One value of a facet, from GET /api/library/works/facets/{facet}.

Properties

value
value: string;

The value, as WorksQuery.value takes it.

works
works: number;

How many held works have it.


FacetValuesPage

A page of a facet's values and the cursor of the next one.

Properties

next_cursor?
next_cursor?: string | null;

Pass as cursor for the next page; absent on the last.

values
values: FacetValue[];

The page's values, by their lower-cased spelling.


GlobalQueueEntry

Aggregated global request-queue entry (shared wishlist demand).

Properties

asin
asin: string | null;
authors
authors: string | null;
cover_path?
cover_path?: string | null;

Same-origin path of this cover's processed images; see coverSrc.

cover_url?
cover_url?: string | null;
description?
description?: string | null;
first_requested_at
first_requested_at: string;
genres?
genres?: string | null;
isbn
isbn: string | null;
language?
language?: string | null;
last_requested_at
last_requested_at: string;
length_minutes?
length_minutes?: number | null;
narrators?
narrators?: string | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
purchase_hints?
purchase_hints?: PurchaseHint[];
reasons?
reasons?: string[];
sample_uuids
sample_uuids: string[];
score?
score?: number;

Final rank (taste_score + wish_count boost).

series?
series?: string | null;
series_index?
series_index?: string | null;
store_editions?
store_editions?: StoreEdition[];
subtitle?
subtitle?: string | null;
taste_score?
taste_score?: number;
title
title: string;
wish_count
wish_count: number;
wishers?
wishers?: QueueWisher[];

Distinct people who have this title on an open wishlist.

work_id
work_id: string;

Library work the entry's wishes are for. Wishes for one work share an entry even when their work_keys differ, so match on this first.

work_key
work_key: string;

Holding

One holding of a store listing.

Properties

added_at
added_at: string;

When the library first saw it (ISO-8601).

entitlement
entitlement: Entitlement;

How it is held.

holder
holder: Holder;

Who holds it.

id
id: string;

Holding id.

purchased_at
purchased_at: string | null;

When the store says it was bought (ISO-8601), when known.


JobInfo

Background job row from /api/jobs.

Properties

attempt_count?
attempt_count?: number;
created_at?
created_at?: string | null;
detail
detail: string | null;
error_kind?
error_kind?: string | null;
finished_at?
finished_at?: string | null;
id
id: string;
kind
kind: string;
max_attempts?
max_attempts?: number;
progress?
progress?: string | null;
status
status: string;

LibraryCollection

One collection: a name and the storage key prefixes whose files belong to it.

Properties

name
name: string;

The name people see and scope rules match.

prefixes
prefixes: string[];

Folders relative to a destination's root, each ending in /.


LibraryCollections

The library's collections.

Properties

collections
collections: LibraryCollection[];

The collections, in the order shown.


LibraryConsentsResponse

GET /api/config/library-consents.

Properties

consents
consents: RemoteConsentView[];

Every recorded owner plugin request, approved or not.

libraries
libraries: LibraryLinkView[];

Every library link this install holds, in any state.


LibraryLinkView

A library this install is enrolled in as a host (no key material).

Properties

enrolled_at
enrolled_at: string;

RFC 3339 time of the latest enrollment (a re-enrollment resets it).

include_branches?
include_branches?: boolean;

"Include books from my own branches" (on by default).

job_share?
job_share?: number;

Jobs the library may have running here now; absent while its link is not running.

keep_copies?
keep_copies?: boolean;

"Keep copies on this computer" (on by default): take the library's copies of this server's person's books.

keep_member_copies?
keep_member_copies?: boolean;

"Keep copies of other members' books" (off by default).

library_id
library_id: string;

Id of the library; one link per library.

list_members_books?
list_members_books?: boolean;

"List my members' books" when the library asks (on by default).

max_jobs?
max_jobs?: number | null;

The most jobs this host runs for the library at once; null is an equal share of the machine.

node_id
node_id: string;

Node id the owner minted for this install.

owner_origin
owner_origin: string;

Canonical origin (https://host[:port]) this host dials the owner at.

pinned
pinned: boolean;

True when the link pins the owner's self-signed certificate.

share_books?
share_books?: boolean;

"Share this branch's books with <library>" (on by default).

state
state: string;

active, revoked (by the owner), or left (by this host).

work_for_members?
work_for_members?: boolean;

"Download for other members of <library>" (off by default).


LibraryStatusResponse

GET /api/library-status: library health plus the nodes the caller may see.

Extends

Properties

capabilities
capabilities: NodeCapabilities;
Inherited from

NodesResponse.capabilities

library
library: LibrarySummary;
node_id
node_id: string;
Inherited from

NodesResponse.node_id

nodes
nodes: ConfigNodeView[];
Inherited from

NodesResponse.nodes


LibrarySummary

Library-wide health from GET /api/library-status.

Properties

active_jobs
active_jobs: number;
branch_nodes
branch_nodes: number;
cpu_budget_millicores
cpu_budget_millicores: number;
cpu_reserved_millicores
cpu_reserved_millicores: number;
deliveries
deliveries: object;
dead_letter
dead_letter: number;
oldest_pending_age_secs
oldest_pending_age_secs: number | null;
pending
pending: number;
running
running: number;
drained
drained: number;
live
live: number;
memory_budget_bytes
memory_budget_bytes: number;
memory_reserved_bytes
memory_reserved_bytes: number;
nodes
nodes: number;
running_guests
running_guests: number;

LinkedIdentity

Linked portal identity (local or oidc:{id}).

Properties

external_user_id
external_user_id: string;
label
label: string | null;
provider
provider: string;

ListedPasskey

Registered passkey row.

Properties

credential_id
credential_id: string;
id
id: number;
name?
name?: string | null;

ListedSession

Active auth session row visible to the current principal.

Properties

channel?
channel?: "browser" | "clerk" | "player" | null;

For a portal session: browser, clerk for a clerk's library card, or player for a player app's card.

client_label?
client_label?: string | null;
created_at
created_at: string;
device_type?
device_type?: string | null;
elevated?
elevated?: boolean;
expires_at
expires_at: string;
id
id: number;
impersonating_user_id?
impersonating_user_id?: number | null;
is_current?
is_current?: boolean;
kind
kind: string;
last_used_at?
last_used_at?: string | null;
user_agent?
user_agent?: string | null;

ListedUser

User row from GET /api/users (administrator settings).

Properties

avatar_source?
avatar_source?: string | null;

auto, monogram, gravatar, upload, or sso:{id}.

controls?
controls?: MemberControls;

What the user may do here: the member controls that apply to them.

display_name
display_name: string | null;
email?
email?: string | null;
gravatar_hash?
gravatar_hash?: string | null;

SHA-256 hex of the contact email for Gravatar.

has_avatar?
has_avatar?: boolean;

True when a profile picture file is stored for this user.

has_password
has_password: boolean;
id
id: number;
identities?
identities?: object[];

Linked login identities (local + OIDC).

external_user_id
external_user_id: string;
label
label: string | null;
provider
provider: string;
integrations?
integrations?: object[];

Linked storefront / integration accounts.

account_id
account_id: string;
label
label: string | null;
source
source: string;
last_active_at?
last_active_at?: string | null;

Most recent unexpired portal session activity (RFC 3339). Active vs idle is ~5 minutes.

last_seen_at?
last_seen_at?: string | null;

Durable last portal use (RFC 3339); survives logout. Null means never signed in.

listening?
listening?: 
  | {
  last_listened_at: string;
  provider: string;
  title: string | null;
}
  | null;

Unfinished listen within ~30 minutes (waveform uses the last ~5 minutes).

login_name
login_name: string | null;
online?
online?: boolean;

Non-expired portal session present (true even when idle).

role
role: string;
sso_pictures?
sso_pictures?: object[];

IdP-supplied pictures the user can pick.

identity_id
identity_id: number;
last_used_at?
last_used_at?: string | null;
picture_path?
picture_path?: string | null;

Same-origin 128 px copy of picture_url, when the server signed one.

picture_url
picture_url: string;
provider
provider: string;
status
status: string;

Listing

One store listing of an edition.

Properties

holdings
holdings: Holding[];

Who holds it.

id
id: string;

Listing id.

marketplace
marketplace: string;

Marketplace code (us, uk, …).

plugin_key
plugin_key: string;

Storefront plugin (audible, libro, …).

product_id
product_id: string;

The store's product id (ASIN, ISBN, …).

url
url: string | null;

The listing's store page, when known.


NodeCapabilities

What the caller may do on the nodes it was sent.

Properties

can_assign_owner
can_assign_owner: boolean;
can_edit_labels
can_edit_labels: boolean;
can_edit_runtime
can_edit_runtime: boolean;
scope
scope: "all" | "owned";

all for an operator; owned for a user who owns nodes.


NodeHolder

A listing held by a branch library's node.

Properties

kind
kind: "node";

Discriminant.

node_id
node_id: string;

The holding node's id.


NodeRuntimeView

A node's runtime document (node.runtime): its label, the share of its detected capacity the scheduler may commit, and the drain switch.

Properties

cpu_budget_percent
cpu_budget_percent: number;

Share of detected CPU the scheduler may commit (1..=100).

label
label: string;
memory_budget_percent
memory_budget_percent: number;

Share of detected memory the scheduler may commit (1..=100).

schedulable
schedulable: boolean;

False drains the node: nothing new is placed there.


NodesResponse

GET /api/config/nodes.

Extended by

Properties

capabilities
capabilities: NodeCapabilities;
node_id
node_id: string;
nodes
nodes: ConfigNodeView[];

NodeStatusView

A node's latest heartbeat (every 15 s while its daemon runs).

Properties

availability_ppm
availability_ppm: number;

Recent online fraction in parts per million (decays over about a day).

cpu_budget_millicores
cpu_budget_millicores: number;
cpu_millicores
cpu_millicores: number;

Detected CPU capacity in millicores.

cpu_used_millicores
cpu_used_millicores: number | null;

Measured CPU in use since the previous heartbeat.

files_dir_free_bytes
files_dir_free_bytes: number | null;
heartbeat_at
heartbeat_at: string;
interval_ms
interval_ms: number;
memory_available_bytes
memory_available_bytes: number | null;

Measured memory available to new work.

memory_budget_bytes
memory_budget_bytes: number | null;
memory_bytes
memory_bytes: number | null;

Detected memory in bytes, when the node could read it.

public_origin?
public_origin?: string | null;

The address other installs reach a branch at, as its heartbeat last reported it; null for a local branch and for a shared node.

reserved
reserved: object;

Sum of the running guests' jail ceilings.

cpu_millicores
cpu_millicores: number;
memory_bytes
memory_bytes: number;
running_guests
running_guests: number;
schedulable
schedulable: boolean;
started_at
started_at: string;

OidcAsClient

Bookclerk-as-IdP OAuth client (secrets never listed after create/rotate).

Properties

allowed_scopes
allowed_scopes: string[];
client_id
client_id: string;
client_secret?
client_secret?: string | null;

Plaintext secret, returned only on create or rotate.

confidential
confidential: boolean;
enabled
enabled: boolean;
has_secret
has_secret: boolean;
issue_refresh_token
issue_refresh_token: boolean;
name?
name?: string | null;
plugin_id?
plugin_id?: string | null;

Set when a plugin owns this client (redirects are read-only).

redirect_uris
redirect_uris: string[];

OidcAsClientWrite

Body for creating or updating a Bookclerk-as-IdP client.

Properties

allowed_scopes
allowed_scopes: string[];
client_id?
client_id?: string;
confidential
confidential: boolean;
enabled
enabled: boolean;
issue_refresh_token
issue_refresh_token: boolean;
name?
name?: string | null;
redirect_uris
redirect_uris: string[];

OidcBrokerConfigUpdate

Body for PUT /api/auth/oidc/config.

Properties

allowed_email_domains
allowed_email_domains: string[];
enabled
enabled: boolean;
providers
providers: OidcProviderConfigUpdate[];
public_origin?
public_origin?: string | null;

Omit to leave unchanged; empty string clears integrations.public_origin.


OidcBrokerConfigView

Owner/operator identity-broker settings payload.

Properties

allowed_email_domains
allowed_email_domains: string[];
authorization_endpoint?
authorization_endpoint?: string;
callback_url?
callback_url?: string | null;
detected_origin?
detected_origin?: string;

Origin detected from this request when it is a bound loopback listen address.

discovery_url?
discovery_url?: string;

Absolute OpenID discovery URL.

enabled
enabled: boolean;
issuer_url?
issuer_url?: string;

Effective issuer origin (public_origin, else bound loopback, else localhost).

providers
providers: OidcProviderConfigView[];
public_origin?
public_origin?: string | null;

Configured integrations.public_origin (issuer / callback / invite base).

revocation_endpoint?
revocation_endpoint?: string;
token_endpoint?
token_endpoint?: string;
userinfo_endpoint?
userinfo_endpoint?: string;

OidcProvider

Enabled upstream OIDC/OAuth login providers.

Properties

id
id: string;
name
name: string;
preset?
preset?: string | null;

Built-in social preset (google, github, apple, discord) when set.


OidcProviderConfigUpdate

Provider fields accepted by PUT /api/auth/oidc/config.

Properties

allowed_email_domains
allowed_email_domains: string[];
allowed_emails
allowed_emails: string[];
allowed_subjects
allowed_subjects: string[];
apple_key_id?
apple_key_id?: string | null;
apple_private_key?
apple_private_key?: string;
apple_team_id?
apple_team_id?: string | null;
client_id
client_id: string;
client_secret?
client_secret?: string;

Omit to keep; empty string to clear; non-empty to store.

default_role
default_role: string;
id
id: string;
issuer?
issuer?: string | null;
link_by_email: boolean;
name
name: string;
preset?
preset?: string | null;
provision
provision: OidcProvisionMode;
role_claim
role_claim: string;
role_map
role_map: Record<string, string>;
scopes
scopes: string[];

OidcProviderConfigView

Owner/operator view of one [auth.oidc] provider (secrets redacted).

Properties

allowed_email_domains
allowed_email_domains: string[];
allowed_emails
allowed_emails: string[];
allowed_subjects
allowed_subjects: string[];
apple_key_id?
apple_key_id?: string | null;
apple_team_id?
apple_team_id?: string | null;
client_id
client_id: string;
default_role
default_role: string;
has_apple_private_key?
has_apple_private_key?: boolean;
has_client_secret
has_client_secret: boolean;
id
id: string;
issuer?
issuer?: string | null;
link_by_email: boolean;
name
name: string;
preset?
preset?: string | null;
provision
provision: OidcProvisionMode;
role_claim
role_claim: string;
role_map
role_map: Record<string, string>;
scopes
scopes: string[];
secret_source
secret_source: OidcSecretSource;

OutputCopy

One copy of a book: a format at a quality, as output.copies names it.

Properties

format
format: string;

m4b, mp3, mp3_chapters, opus (or original, which a convert refuses).

quality
quality: string;

original, a bitrate such as 64k or 64k-mono, or an MP3 VBR level such as v2.


PatronScope

Which part of the library a patron sees.

Properties

explicit?
explicit?: ExplicitContent;

Whether books a store or metadata file marks explicit are visible; left out means allow.

rules
rules: ScopeRule[];

Visibility rules; empty means every book is visible.


PluginConsentBrand

Branded display metadata for a plugin consent dialog.

Properties

accent?
accent?: string | null;
bg?
bg?: string | null;
fg?
fg?: string | null;
logo?: string | null;
name
name: string;

PluginConsentLimits

Host-capped consent limit defaults (workerd budgets + shared jail/disk).

Jail CPU fields are cores (2 d.p.) from the daemon — no percent conversion.

Properties

cpu_cores
cpu_cores: number;

Manifest / default jail CPU in cores.

cpu_ms
cpu_ms: number;
disk_mib
disk_mib: number;
extra_processes
extra_processes: number;

Default extra process/thread budget (native).

jail_cpu_cores?
jail_cpu_cores?: number | null;

Optional Settings global jail CPU ceiling in cores.

known_bindings
known_bindings: string[];
max_cpu_cores
max_cpu_cores: number;

Host max jail CPU in cores.

max_cpu_ms
max_cpu_ms: number;
max_disk_mib
max_disk_mib: number;
max_extra_processes
max_extra_processes: number;

Host hard cap for extra process budget.

max_memory_mib
max_memory_mib: number;
max_subrequests
max_subrequests: number;
memory_mib
memory_mib: number;
subrequests
subrequests: number;

PluginConsentPending

The difference between a plugin's request and its stored grant.

Properties

addressCidrs
addressCidrs: string[];

CIDRs the request adds.

allowUndeclaredPublicRedirects
allowUndeclaredPublicRedirects: boolean;

Whether the request newly asks to follow undeclared public redirects.

domains
domains: string[];

Fetch host patterns the request adds (* is any public host).

lines
lines: string[];

Operator-facing lines naming every capability awaiting consent (the CLI prints the same).

tcp
tcp: object[];

TCP host:ports the request adds, narrowed to the new ports.

host
host: string;
ports
ports: number[];

PluginConsentResponse

Network/capability consent status for a plugin.

Properties

brand?
brand?: PluginConsentBrand;
covered
covered: boolean;
existing?
existing?: PluginGrant;
host_user_agent?
host_user_agent?: string;

The User-Agent the host sends, except to the request's ownUserAgentHosts.

limits
limits: PluginConsentLimits;
pending?
pending?: PluginConsentPending;

What the request asks for beyond the stored grant (a plugin upgrade that widened its capabilities); absent when no grant is stored. The plugin runs under the stored grant until these are approved.

plugin_id
plugin_id: string;
plugin_key?
plugin_key?: string;
provenance?
provenance?: string;
request
request: PluginGrant;
runtime
runtime: string;

Guest runtime: native or workerd.

setting_destinations?
setting_destinations?: PluginSettingDestination[];

The destination each network setting names on each instance and whether it is approved. A pending row is unreachable until approved, and covered is false while one is.

summary
summary: string[];

PluginDeploymentView

This node's deployment of a plugin instance, with its latest observation.

Properties

applied_config_revision?
applied_config_revision?: number;
deployment_id
deployment_id: string;
desired
desired: string;

present / absent when an operator manages the instance (the Enabled switch), placed / unplaced when the library scheduler does. The host runs it for present and placed.

detail?
detail?: string;
node_id
node_id: string;
observed_at?
observed_at?: string;
revision
revision: number;
status?
status?: string;

materialized, running, healthy, error, or retired when observed.


PluginGrant

Plugin consent grant shape serialized by the daemon.

Properties

addressCidrs?
addressCidrs?: string[];
allowUndeclaredPublicRedirects?
allowUndeclaredPublicRedirects?: boolean;
approvedAt
approvedAt: string;
authorityRevision?
authorityRevision?: string;
bindings
bindings: string[];
compatibilityFlags
compatibilityFlags: string[];
consumers?
consumers?: object[];

Approved event-consumer subscriptions (type + schemas + suspend + filter).

eventType
eventType: string;
filter?
filter?: string | null;
schemaVersions
schemaVersions: number[];
supportsSuspend
supportsSuspend: boolean;
cpuCores?
cpuCores?: number;

Jail CPU in cores (2 d.p.) from the daemon.

cpuMs?
cpuMs?: number;
diskMib?
diskMib?: number;
domains
domains: string[];
entrypoints
entrypoints: string[];

Exported entrypoints the operator approved (storefront, cli, …).

extraProcesses?
extraProcesses?: number;

Extra process/thread budget beyond launcher overhead (native).

jobs?
jobs?: string[];

Approved [triggers].jobs types.

manifestDomains?
manifestDomains?: string[];
memoryMib?
memoryMib?: number;
networkMode
networkMode: string;
operatorAddedCidrs?
operatorAddedCidrs?: string[];
operatorAddedDomains?
operatorAddedDomains?: string[];
operatorAddedTcp?
operatorAddedTcp?: object[];
host
host: string;
ports
ports: number[];
operatorDeniedCidrs?
operatorDeniedCidrs?: string[];
operatorDeniedDomains?
operatorDeniedDomains?: string[];
operatorDeniedTcp?
operatorDeniedTcp?: object[];
host
host: string;
ports
ports: number[];
ownUserAgentHosts?
ownUserAgentHosts?: string[];

Hosts that receive the plugin's own User-Agent; every other request carries the host's. Absent on a grant approved before this permission existed, which keeps whatever the plugin declares.

ownUserAgentReason?
ownUserAgentReason?: string;

The plugin's reason for ownUserAgentHosts, from plugin.toml.

pluginId
pluginId: string;
pluginKey?
pluginKey?: string;
producers
producers: string[];

Event types the operator approved the plugin to publish.

subrequests?
subrequests?: number;
tcp?
tcp?: object[];
host
host: string;
ports
ports: number[];

PluginInstanceConfig

Instance document as GET /api/config/plugin-instances/{id}/config returns it.

Properties

effective
effective: Record<string, unknown>;

Schema defaults under the stored settings.

plugin_instance_id
plugin_instance_id: string;
plugin_key
plugin_key: string;
revision
revision: number;
secret_refs
secret_refs: object[];

Secret refs (names only).

key
key: string;
name
name: string;
settings
settings: Record<string, InstanceSettingValue>;

Stored settings (operator writes only; defaults are not stored).


PluginInstanceConfigWrite

Body for PUT /api/config/plugin-instances/{id}/config.

Properties

expected_revision
expected_revision: number;
secret_refs
secret_refs: object[];
key
key: string;
name
name: string;
secrets?
secrets?: Record<string, string>;

Secret values to seal; never echoed back.

settings
settings: Record<string, InstanceSettingValue>;

PluginPlacementView

Scheduler placement of a plugin instance: the operator's intent and the last scheduler pass's result.

Properties

constraints
constraints: string[];

Label constraints (nas, zone=eu, !slow, host=<id>).

detail
detail: string;

Why fewer than requested are placed; empty when satisfied.

placed
placed: number;

Replicas the last scheduler pass placed.

replicas
replicas: number | "all";

Nodes that should run the instance: a count (0 stops every replica) or "all" (every live, schedulable host with budget room).

revision
revision: number;

Compare-and-swap revision of the intent.

scheduled_at
scheduled_at: string;
updated_at
updated_at: string;

PluginSettingChoice

Select option for a plugin setting.

Properties

label
label: string;
value
value: string;

PluginSettingColumn

One column of a table setting: the record field each row fills.

Properties

choices?
choices?: PluginSettingChoice[];

Dropdown values of an enum column.

default?
default?: string;

String form of the value a new row starts with.

key
key: string;

Field name in each row object.

label
label: string;

Column heading.

required?
required?: boolean;

True when every row must have a value in this column.

value_type
value_type: "string" | "number" | "boolean";

PluginSettingDestination

One network setting's destination on one plugin instance.

Properties

destination?
destination?: string;

scheme://host:port for a fetch, host:port for TCP; absent when unset or invalid.

error?
error?: string;

Why the value names no destination, when state is invalid.

instanceId?
instanceId?: string;

The instance whose settings name it; absent while the plugin has no instance.

label
label: string;

The setting's label.

network
network: "fetch" | "tcp";

fetch (HTTP requests) or tcp (a raw socket).

scope?
scope?: SettingDestinationScope;

name may resolve to a local-network address for this name only; localAddress is exactly that one local-network address; restricted (loopback, link-local, localhost) also needs an address grant.

setting
setting: string;

The setting key the grant is stored under.

state
state: "approved" | "pending" | "unset" | "invalid";

Approval state of the destination.

tls?
tls?: boolean;

True for an https fetch; false trusts the network's DNS answer.


PluginSettingDestinationApproval

A setting destination the operator approves, as the consent response shows it.

Properties

destination
destination: string;

The destination exactly as PluginSettingDestination.destination shows it.

setting
setting: string;

The setting key.


PluginSettingOption

Editable plugin setting descriptor from the settings API.

For a plugin instance group the key is the bare [[settings]] key from the plugin's manifest and value is the effective value (document over schema default). A secret option never carries its value.

Properties

choices?
choices?: PluginSettingChoice[];
columns?
columns?: PluginSettingColumn[];

Columns of a table setting, in display order.

key
key: string;
label
label: string;
secret?
secret?: boolean;

True for a secret setting; value is always empty.

secret_set?
secret_set?: boolean;

For a secret setting, whether a sealed value is stored for the instance.

value
value: string;

String form of the value; for a table setting, the rows as JSON text.

value_type
value_type: "string" | "number" | "boolean" | "table" | "secret";

PluginSettingsGroup

Settings group for one plugin instance, or for a bootstrap database adapter.

Properties

config_revision?
config_revision?: number;

Instance document revision for compare-and-swap writes.

deployment?
deployment?: PluginDeploymentView;

This node's deployment of the instance, when one exists.

display_name?
display_name?: string;

Operator-facing instance name, when set.

family
family: string;

Handler family (source, integration, output, database).

id
id: string;
is_default?
is_default?: boolean;

True when a bare plugin key or alias routes to this instance.

logo?
logo?: string;

Same-origin logo for Settings list rows (embedded, or a copy of the remote logo).

placement?
placement?: PluginPlacementView;

Scheduler placement; absent when the instance is managed by hand.

plugin_instance_id?
plugin_instance_id?: string;

Instance this group edits; absent for a config.toml-backed database adapter.

plugin_key?
plugin_key?: string;

Provenance-qualified PluginKey when this row came from a discovered install.

present_on?
present_on?: string[];

Nodes whose deployment of the instance is present.

provenance?
provenance?: string;

Host-evaluated provenance (platform_bundled, verified_staged, installed, …).

settings
settings: PluginSettingOption[];
storage_sync?
storage_sync?: StorageSyncView;

How a storage destination follows outside changes; absent until its first sync pass.


PortalBrand

Storefront brand colors and logo URL for Accounts UI.

Properties

accent
accent: string;
bg
bg: string;
fg
fg: string;
logo
logo: string;

PortalConnection

Linked store account for the current portal user.

Properties

account_id
account_id: string;
brand?
brand?: PortalBrand;
connection_status
connection_status: string;
label
label: string | null;
pace
pace: PortalPace;

How fast Bookclerk downloads from this account when it starts the downloads itself.

plugin_key
plugin_key: string;

Provenance-qualified PluginKey that owns the account.

source
source: string;
source_enabled
source_enabled: boolean;

PortalInfo

Linked portal identity attached to a user session.

Properties

external_user_id
external_user_id: string;
identity_id
identity_id: number;
label
label: string | null;
provider
provider: string;

PortalMe

Portal identity from /api/portal/me.

Properties

external_user_id
external_user_id: string;
label
label: string | null;
provider
provider: string;

PortalPace

A store account's download pace from /api/portal/connections: the limits in force for downloads Bookclerk starts itself (auto-acquire, upgrades, requests from other libraries). Downloads a person starts are counted but never held.

Properties

cooldown_until
cooldown_until: string | null;

End of the store's cool-down (RFC 3339), when one is running.

custom_downloads_per_day
custom_downloads_per_day: number | null;

The custom daily budget, when mode is custom.

custom_min_gap_seconds
custom_min_gap_seconds: number | null;

The custom gap, when mode is custom.

downloads_last_day
downloads_last_day: number;

Downloads from this account in the last 24 hours.

downloads_per_day
downloads_per_day: number | null;

Downloads allowed in any rolling 24 hours; null for no daily budget.

min_gap_seconds
min_gap_seconds: number;

Seconds between two downloads.

mode
mode: PortalPaceMode;

default (the store's pace), custom or unlimited.

next_automatic_at
next_automatic_at: string | null;

When the next automatic download may start (RFC 3339); null for now.

store_downloads_per_day
store_downloads_per_day: number | null;

The store's declared daily budget; null when none or its plugin isn't deployed here.

store_min_gap_seconds
store_min_gap_seconds: number | null;

The store's declared gap; null when its plugin isn't deployed here.


PortalPaceChange

Body of portalSetConnectionPace.

Properties

clear_cooldown?
clear_cooldown?: boolean;

Also end a cool-down the store asked for.

downloads_per_day?
downloads_per_day?: number;

Custom downloads per rolling 24 hours (1 to 10000); custom only.

min_gap_seconds?
min_gap_seconds?: number;

Custom seconds between downloads (0 to 86400); custom only.

mode?
mode?: PortalPaceMode;

default, custom or unlimited. Leave it out to only end the cool-down (with clear_cooldown: true) and keep the stored pace.


PortalSource

Connectable storefront advertised by /api/portal/sources.

Properties

auth
auth: string;
brand
brand: PortalBrand;
id
id: string;
name
name: string;

PurchaseHint

Live or seeded storefront price / buy URL for a title.

Properties

currency?
currency?: string | null;
list_price_cents?
list_price_cents?: number | null;
list_price_label?
list_price_label?: string | null;
member_price_cents?
member_price_cents?: number | null;
member_price_label?
member_price_label?: string | null;
price_cents?
price_cents?: number | null;
price_label?
price_label?: string | null;
product_id
product_id: string;
source
source: string;
title
title: string | null;
url
url: string | null;

PurchaseHintsQuery

Query used to resolve purchase hints for a title.

Properties

asin?
asin?: string | null;
authors?
authors?: string | null;
candidate_product_id?
candidate_product_id?: string | null;
candidate_source?
candidate_source?: string | null;
isbn?
isbn?: string | null;
region?
region?: string;
store_editions?
store_editions?: StoreEdition[];
title
title: string;

PurchaseHintsResponse

Purchase hint list plus optional best pick.

Properties

best
best: PurchaseHint | null;
hints
hints: PurchaseHint[];
incomplete?
incomplete?: boolean;

True when the server's batch deadline cut the lookup short: the hints are links without prices, so the answer is not cached and should be asked for again later.


QueueWisher

Person who has a title on an open wishlist (global queue avatars).

Properties

avatar_source?
avatar_source?: string | null;

Explicit picture choice (auto / monogram / gravatar / upload / sso:{id}).

display_name?
display_name?: string | null;

Display name, identity label, or Operator.

gravatar_hash?
gravatar_hash?: string | null;

SHA-256 hex of the contact email for Gravatar.

has_avatar?
has_avatar?: boolean;

True when an uploaded avatar file exists.

identity_id?
identity_id?: number | null;

Portal identity that created the wish.

login_name?
login_name?: string | null;

Local login name when set.

operator?
operator?: boolean;

True when the wish came from the operator token.

picture_path?
picture_path?: string | null;

Same-origin 128 px copy of picture_url, when the server signed one.

picture_url?
picture_url?: string | null;

HTTPS picture from the wishing identity, when any; never loaded directly.

user_id?
user_id?: number | null;

First-party user id when the portal identity is linked.


Recommendation

Discover shelf recommendation item.

Properties

asin
asin: string | null;
authors
authors: string | null;
available_through?
available_through?: BranchAvailability[];

Branches of this library that currently list this title.

candidate_product_id
candidate_product_id: string | null;
candidate_source
candidate_source: string | null;
categories?
categories?: string[];

Stable shelf-kind tags (finish_series, author, requests, …).

cover_path?
cover_path?: string | null;

Same-origin path of this cover's processed images; see coverSrc.

cover_url?
cover_url?: string | null;
description?
description?: string | null;
from_request
from_request: boolean;
genres?
genres?: string | null;
isbn
isbn: string | null;
language?
language?: string | null;
length_minutes?
length_minutes?: number | null;
narrators
narrators: string | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
purchase_hints
purchase_hints: PurchaseHint[];
reasons
reasons: string[];
request_uuid
request_uuid: string | null;
score
score: number;
seed_categories?
seed_categories?: string | null;
seed_title?
seed_title?: string | null;

Title of the book or wish the storefront was asked about to find this card.

series
series: string | null;
series_index
series_index: string | null;
starter_genre?
starter_genre?: string | null;

Starter genre this card was browsed from while the taste was thin.

store_editions?
store_editions?: StoreEdition[];
subtitle?
subtitle?: string | null;
title
title: string;
wish_count?
wish_count?: number;

Distinct wisher count (may exceed wishers.length).

wishers?
wishers?: QueueWisher[];

People who have this title on an open wishlist.

work_id
work_id: string | null;
work_key?
work_key?: string;

Stable bibliographic key (isbn: / asin: / soft:…).


RemoteApprovalBody

Body of an approval: the reviewed request and what of it to leave out. An approval can only narrow the request, never widen it.

Properties

deny_bindings?
deny_bindings?: string[];

Host bindings to remove (secrets, oauth, kv, …).

deny_domains?
deny_domains?: string[];

Outbound domain patterns to remove from the grant.

deny_network?
deny_network?: boolean;

True turns outbound network off altogether (no domains, TCP or CIDRs).

deny_own_user_agent_hosts?
deny_own_user_agent_hosts?: string[];

Requested hosts refused the plugin's own User-Agent; they get Bookclerk's agent.

library_id
library_id: string;

Library of the request.

plugin_key
plugin_key: string;

Plugin key of the request.

request_digest
request_digest: string;

The request_digest reviewed; refused when the recorded request is another one.


RemoteConsentView

One owner plugin's request to run on this host, and this host's answer.

Properties

approved_at
approved_at: string | null;

RFC 3339 time of the approval, if approved.

approved_by
approved_by: string | null;

Who approved: the operator's audit identity, or platform for an automatic approval.

approved_version
approved_version: string | null;

Version this host approved, if any.

grant
grant: RemoteGrantView | null;

What this host granted (the request, narrowed), if approved.

library_id
library_id: string;

Library that asks; matches a LibraryLinkView.library_id.

pending?
pending?: string[];

What the current request asks for beyond the request this host approved, as the lines the CLI prints; empty when nothing was approved yet.

plugin_key
plugin_key: string;

Canonical plugin key the request is for.

request_digest
request_digest: string;

Digest of the whole request (version, grant, archive); approve by it.

requested_artifact?
requested_artifact?: object;

The archive this host would fetch for that version (hex SHA-256 digests).

archive_sha256
archive_sha256: string;

Digest of the archive file.

payload_root_sha256
payload_root_sha256: string;

Digest of the unpacked payload tree.

url
url: string;

blob: (served by the owner) or https: archive URL.

requested_grant
requested_grant: RemoteGrantView | null;

What that version asks for; null when the stored request does not parse.

requested_version
requested_version: string;

Version the owner now asks to run.

revoked_at?
revoked_at?: string | null;

RFC 3339 time this host's operator revoked it; a revoke holds until approved again.

state
state: RemoteConsentState;

Whether the guest may run here now, or what it waits on.

updated_at?
updated_at?: string;

RFC 3339 time the row last changed.


RemoteGrantView

The parts of a plugin grant the consent screen shows. Every field is optional because the screen renders whatever the host sent; a missing set means the grant asks for none of it, and a missing or null limit leaves that limit to the version's manifest.

Properties

addressCidrs?
addressCidrs?: string[];

CIDR ranges beyond the public Internet (private or local addresses).

allowUndeclaredPublicRedirects?
allowUndeclaredPublicRedirects?: boolean;

Follow a redirect to a public host it did not declare.

bindings?
bindings?: string[];

Host bindings (config, secrets, kv, …).

compatibilityFlags?
compatibilityFlags?: string[];

workerd compatibility flags the isolate runs with.

consumers?
consumers?: unknown[];

Events and queues it consumes (shape owned by the host).

cpuMs?
cpuMs?: number | null;

workerd CPU budget per request, in milliseconds.

cpuRatePercent?
cpuRatePercent?: number | null;

CPU rate as a percent of one logical CPU (above 100 asks for more than one core).

diskMib?
diskMib?: number | null;

Disk budget in MiB for each of its data/ and tmp/ directories.

domains?
domains?: string[];

Outbound domain patterns the guest may dial first (redirect hops aside).

entrypoints?
entrypoints?: string[];

Named entrypoints it exports (storefront, storage, cli, …).

extraProcesses?
extraProcesses?: number | null;

Processes or threads allowed beyond the launcher's own (native guests).

jobs?
jobs?: string[];

[triggers].jobs types it may handle.

memoryMib?
memoryMib?: number | null;

Memory ceiling in MiB.

networkMode?
networkMode?: string;

deny (no egress) or outbound; anything else is treated as deny.

ownUserAgentHosts?
ownUserAgentHosts?: string[] | null;

Hosts that receive the plugin's own User-Agent instead of the host's.

ownUserAgentReason?
ownUserAgentReason?: string | null;

The plugin's reason for ownUserAgentHosts.

pluginId?
pluginId?: string;

Display alias from plugin.toml (not security authoritative).

producers?
producers?: string[];

Event types it may publish and queue bindings it may send to.

subrequests?
subrequests?: number | null;

workerd outbound fetch (subrequest) budget per request.

tcp?
tcp?: object[];

Raw TCP destinations: a host and the ports allowed on it.

host
host: string;
ports
ports: number[];

ScopeRule

One rule of a patron scope.

Properties

effect
effect: RuleEffect;

Include or exclude.

field
field: ScopeField;

The field the rule matches.

value
value: string;

One value of the field, compared without case.


SettingsResponse

Flat config map plus per-plugin setting groups.

Properties

effective?
effective?: Record<string, string>;
host_cpu_cores_max?
host_cpu_cores_max?: number;

Host max jail CPU in cores (2 d.p.; equals logical CPU count).

jail_cpu_cores?
jail_cpu_cores?: number | null;

Optional global per-jail CPU ceiling in cores.

output_revision?
output_revision?: number;

core.output document revision the output.* values were read from; send it as expected_output_revision. effective["output.revision"] is the revision this host has applied, which can lag the document. Absent when the server could not read core.output; the output.* values are then missing too and must not be edited.

plugins
plugins: PluginSettingsGroup[];
settings
settings: Record<string, string>;

SettingsUpdate

One config key/value pair for PATCH /api/settings.

Properties

key
key: string;
value
value: string;

ShelfKindInfo

Shelf kind id/label for preference toggles.

Properties

id
id: string;
label
label: string;

StatusResponse

Aggregate library counters from /api/status.

Properties

accounts
accounts: number;
acquired
acquired: number;
books
books: number;
error
error: number;
events?
events?: EventQueueStatus;
in_progress
in_progress: number;
listen
listen: string;
pending
pending: number;
storage_backend
storage_backend: string;

StorageSyncView

How a destination notices changes made outside Bookclerk: its change feed and its scheduled listings.

Properties

feed_checked_at?
feed_checked_at?: string;

RFC 3339 time the feed was last read.

feed_error?
feed_error?: string;

The last feed failure.

feed_state
feed_state: "off" | "healthy" | "gap" | "failing";

off (listings alone), healthy, gap (a listing runs at once) or failing.

listed_at?
listed_at?: string;

RFC 3339 time the last listing finished.

listing_error?
listing_error?: string;

Why the last listing failed or its removals were held back.

listing_in_progress
listing_in_progress: boolean;

True while a listing is in progress.

next_listing_at?
next_listing_at?: string;

RFC 3339 time the next scheduled listing is due.

objects
objects: number;

Files the destination held after the last listing or feed page.


StoreEdition

Storefront product identity for a catalog work.

Properties

product_id
product_id: string;
source
source: string;

TitleMeta

Public Audnexus / Audible catalog fields for detail dialogs.

Properties

asin?
asin?: string | null;
authors?
authors?: string | null;
categories?
categories?: string | null;
cover_path?
cover_path?: string | null;

Same-origin path of this cover's processed images; see coverSrc.

cover_url?
cover_url?: string | null;
description?
description?: string | null;
is_abridged?
is_abridged?: boolean | null;

true abridged / false unabridged when the storefront said so.

isbn?
isbn?: string | null;
language?
language?: string | null;
length_minutes?
length_minutes?: number | null;
narrators?
narrators?: string | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
rating_count?
rating_count?: number | null;
rating_overall?
rating_overall?: number | null;

Audible community ratings (detail fetch only).

rating_performance?
rating_performance?: number | null;
rating_story?
rating_story?: number | null;
review_count?
review_count?: number | null;
reviews?
reviews?: TitleReview[];
Deprecated

Prefer [fetchTitleReviews]. Title-meta no longer embeds reviews.

series?
series?: string | null;
series_index?
series_index?: string | null;
subtitle?
subtitle?: string | null;
title?
title?: string | null;

TitleRequest

Wishlist / title-request row from /api/wishlist.

Represents a user ask for a work (and optional acquire queue linkage via resolved_edition_id, the edition that fulfilled it).

Properties

asin
asin: string | null;
authors
authors: string | null;
cover_path?
cover_path?: string | null;

Same-origin path of this cover's processed images; see coverSrc.

cover_url?
cover_url?: string | null;
created_at
created_at: string;
description?
description?: string | null;
edition_id?
edition_id?: string | null;

Edition the wish named, when its identifiers reached exactly one.

genres?
genres?: string | null;
id
id: number;
identity_id
identity_id: number | null;
isbn
isbn: string | null;
language?
language?: string | null;
length_minutes?
length_minutes?: number | null;
narrators?
narrators?: string | null;
notes
notes: string | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
purchase_hints?
purchase_hints?: PurchaseHint[];
resolved_edition_id
resolved_edition_id: string | null;
series?
series?: string | null;
series_index?
series_index?: string | null;
status
status: string;
store_editions?
store_editions?: StoreEdition[];
subtitle?
subtitle?: string | null;
title
title: string;
updated_at
updated_at: string;
uuid
uuid: string;
work_id
work_id: string;

Library work the wish is for; every wish names one.

work_key
work_key: string;

Bibliographic key derived from the wish's identifiers, for display matching.


TitleReview

One Audible customer review for title detail.

Properties

author_name?
author_name?: string | null;
body
body: string;
id?
id?: string | null;
overall_rating?
overall_rating?: number | null;
performance_rating?
performance_rating?: number | null;
story_rating?
story_rating?: number | null;
submitted_at?
submitted_at?: string | null;
title?
title?: string | null;

UserAdminControls

An Administrator's switches as GET /api/users/{id}/admin-controls reports them.

Properties

applies
applies: boolean;

True only for an Administrator; an Owner may always do everything.

defaults
defaults: AdminControls;

The library's default for every Administrator.

effective
effective: AdminControls;

What applies to the user now (all off for anyone who isn't an Administrator or Owner).

overrides
overrides: AdminControlOverrides;

The switches set for this Administrator alone.

user_id
user_id: number;

The user.


UserControls

A patron's member controls as GET /api/users/{id}/controls reports them.

Properties

applies
applies: boolean;

False for an Owner, who may always do everything.

defaults
defaults: MemberControls;

The library's default for every patron.

effective
effective: MemberControls;

What applies to the user now.

follows_default
follows_default: boolean;

True for a Member, who follows the library default; false for an Administrator, whom only controls set for them alone limit.

overrides
overrides: ControlOverrides;

The controls set for this patron alone.

user_id
user_id: number;

The user.


UserMutationResponse

Created / patched user response from RBAC provisioning APIs.

Properties

claim_ticket?
claim_ticket?: string | null;
invite_url?
invite_url?: string | null;

Magic-link URL for /invite?ticket=… when an invite was minted.

ok
ok: boolean;
user
user: ListedUser;

UserPreferences

Per-user Discover / default-view preferences.

Properties

default_view
default_view: AppView;
disabled_shelves
disabled_shelves: string[];
discover_excluded_sources
discover_excluded_sources: string[];

Store ids hidden in Discover. Empty = all sources including future.

discover_language
discover_language: string | null;

null / omitted = browser language; __all__ = no hard filter.

discover_sort
discover_sort: CatalogSearchSort;
discover_sort_dir
discover_sort_dir: "desc" | "asc";
theme
theme: ThemePreference;

Appearance: system follows the OS (fallback light); light / dark pin it.


UserScope

A patron's scope as GET/PUT /api/users/{id}/scope report it.

Properties

applies
applies: boolean;

False for an Owner or Administrator, who always see everything.

own
own: boolean;

True when the user has their own scope.

scope
scope: PatronScope;

The scope that applies: their own, or the library default.

user_id
user_id: number;

The user.


WorkDetail

One work from GET /api/library/works/{id}.

Properties

authors
authors: string[];

Authors (or hosts).

can_edit_state?
can_edit_state?: boolean;

Whether the caller can keep their own state (false for the operator token).

description
description: string | null;

Description, when known (may contain light HTML).

editions
editions: Edition[];

Its editions.

id
id: string;

Work id.

kind
kind: WorkKind;

Book or podcast.

series
series: string | null;

Series name, when in one.

series_position
series_position: string | null;

Position within the series.

state?
state?: WorkState | null;

The caller's own state; absent when they recorded none.

title
title: string;

Display title.


WorksPage

A page of works and the cursor of the next one.

Properties

next_cursor?
next_cursor?: string | null;

Pass as cursor for the next page; absent on the last.

works
works: WorkSummary[];

The page's works.


WorksQuery

Filters and paging for fetchWorks.

Properties

account?
account?: string;

Only works held on this account id.

cursor?
cursor?: string;

The previous page's next_cursor.

facet?
facet?: WorkFacet;

Only works with WorksQuery.value under this facet.

kind?
kind?: WorkKind;

Only books or only podcasts.

limit?
limit?: number;

Page size (the daemon caps it at 200).

media_kind?
media_kind?: MediaKind;

Only works with an edition of this media kind.

q?
q?: string;

Search text; matches come best first and sort is ignored.

sort?
sort?: WorkSort;

Page order without q.

status?
status?: AcquireStatus | "all";

Only works in this acquire state (all or omitted for every state).

value?
value?: string;

The facet's value; an empty series value means works in no series.


WorkState

The caller's own state for a work.

Properties

is_finished
is_finished: boolean;

Whether they finished it.

rating_overall
rating_overall: number | null;

Overall rating (0–5).

rating_performance
rating_performance: number | null;

Performance rating (0–5).

rating_story
rating_story: number | null;

Story rating (0–5).

tags
tags: string | null;

Space-separated tags.


WorkStateEdit

A change to the caller's own state for a work. A field left out keeps its value; null clears a rating or the tags.

Properties

is_finished?
is_finished?: boolean;

Whether they finished it.

rating_overall?
rating_overall?: number | null;

Overall rating (0–5).

rating_performance?
rating_performance?: number | null;

Performance rating (0–5).

rating_story?
rating_story?: number | null;

Story rating (0–5).

tags?
tags?: string | null;

Whitespace-separated tags (at most 32, each at most 64 bytes).


WorkSummary

One work row from GET /api/library/works: a book or podcast once, however many editions and accounts hold it.

Properties

acquire_status
acquire_status: AcquireStatus;

The work's acquire state, summed over its editions.

added_at
added_at: string;

When the newest holding was added (ISO-8601).

authors
authors: string | null;

Authors (or hosts), comma-separated, when known.

cover_edition_id
cover_edition_id: string | null;

Edition whose cover the row shows.

cover_path
cover_path: string | null;

Same-origin path of that cover's processed images; see coverSrc.

edition_count
edition_count: number;

Editions of the work in the library.

holding_count
holding_count: number;

Holdings of the work's listings.

id
id: string;

Work id; opens the detail at /api/library/works/{id}.

kind
kind: WorkKind;

Book or podcast.

length_minutes?
length_minutes?: number | null;

Runtime in minutes of the longest held edition, when known.

media_kinds
media_kinds: MediaKind[];

Media kinds the work's editions come in.

purchased_at?
purchased_at?: string | null;

When the newest purchase a store reported happened (ISO-8601).

series
series: string | null;

Series name when the work is in one.

series_position
series_position: string | null;

Position within the series (text, so 1.5 keeps its spelling).

title
title: string;

Display title.


WorkTag

One library tag on a work.

Properties

source
source: WorkTagSource;

Set in Bookclerk (admin) or read from a sidecar file.

value
value: string;

The tag as written.


WorkTags

A work's library tags as GET /api/library/works/{id}/tags reports them.

Properties

tags
tags: WorkTag[];

Every tag, by key.

work_id
work_id: string;

The work.

Type Aliases

Abridgement

type Abridgement = "unknown" | "unabridged" | "abridged";

Whether an expression is abridged.


AcquireStatus

type AcquireStatus = "not_acquired" | "queued" | "downloading" | "acquired" | "error";

Pipeline acquire state for a library book row.


AdminControl

type AdminControl = 
  | "manage_members"
  | "set_patron_limits"
  | "library_scan"
  | "run_jobs"
  | "fix_catalog"
  | "invite_branches"
  | "approve_requests";

One thing an Owner may allow or refuse an Administrator.


AdminControlOverrides

type AdminControlOverrides = Partial<Record<AdminControl, boolean>>;

One Administrator's overrides; a missing switch follows the library's default.


AdminControls

type AdminControls = Record<AdminControl, boolean>;

A value for every Administrator switch (true = allowed).


AdminSwitchChoice

type AdminSwitchChoice = "on" | "off" | "default";

What a change does to one of an Administrator's switches.


AppView

type AppView = "discover" | "library" | "accounts" | "wishlist" | "status" | "settings";

Primary authenticated SPA views mirrored in the URL path.


AuthRole

type AuthRole = "operator" | "owner" | "administrator" | "member";

Session role returned by the daemon auth APIs.


BranchRelationship

type BranchRelationship = "shared_branch" | "remote_branch" | "local_branch";

How a node relates to the library.


CatalogSearchFilters

type CatalogSearchFilters = object;

Server-side include/exclude filters for catalog search.

Properties

authors?
authors?: string[];
exclude_narrators?
exclude_narrators?: string[];
exclude_sources?
exclude_sources?: string[];
genres?
genres?: string[];
languages?
languages?: string[];
max_length_minutes?
max_length_minutes?: number;
min_length_minutes?
min_length_minutes?: number;
min_rating?
min_rating?: number;
narrators?
narrators?: string[];
series?
series?: string[];
sources?
sources?: string[];

CatalogSearchSort

type CatalogSearchSort = 
  | "relevance"
  | "popularity"
  | "rating"
  | "title"
  | "author"
  | "price"
  | "length";

Server-supported Discover catalog sort keys.


CatalogSortDir

type CatalogSortDir = "asc" | "desc";

Ascending or descending catalog sort direction.


ControlOverrides

type ControlOverrides = Partial<Record<MemberControl, boolean>>;

One patron's overrides; a missing control follows the library's default.


CoverSize

type CoverSize = 128 | 360 | "full";

A processed cover size the daemon serves: thumbnail, card, or full size.


DiscoverFeedState

type DiscoverFeedState = "ready" | "refreshing" | "preparing";

How current a stored Discover feed is.


Entitlement

type Entitlement = "purchase" | "plus" | "loan" | "free";

How a holder came to hold a listing.


ExplicitContent

type ExplicitContent = "allow" | "hide";

Whether a patron sees books marked as explicit content.


ExpressionKind

type ExpressionKind = "text" | "narration" | "dramatisation" | "graphic" | "original_audio";

How an expression renders its work.


Holder

type Holder = AccountHolder | NodeHolder;

Who holds a listing: a store account, or a branch library's node.


InstanceSettingValue

type InstanceSettingValue = SettingCellValue | SettingRow[];

One value in a plugin instance document.


MediaKind

type MediaKind = "audio" | "ebook" | "print";

How an edition is consumed.


MemberControl

type MemberControl = 
  | "link_accounts"
  | "download"
  | "edit_metadata"
  | "upload"
  | "request_books"
  | "see_prices";

One thing an administrator may allow or refuse a patron.


MemberControls

type MemberControls = Record<MemberControl, boolean>;

A value for every member control (true = allowed).


OidcProvisionMode

type OidcProvisionMode = "mapped_role" | "any" | "allowlist" | "invite_only";

How an upstream IdP decides who may become a first-party User.


OidcSecretSource

type OidcSecretSource = "env" | "config" | "store" | "none";

Where a provider client secret is stored (never returned in plaintext).


PortalPaceMode

type PortalPaceMode = "default" | "custom" | "unlimited";

How a store account's pace is set.


RemoteConsentState

type RemoteConsentState = 
  | "consented"
  | "awaiting_host_consent"
  | "awaiting_host_reapproval"
  | "invalid_grant";

Where an owner plugin's request to run here stands.


RuleEffect

type RuleEffect = "include" | "exclude";

Whether a patron scope rule lets matching books in or keeps them out.


ScopeField

type ScopeField = "genre" | "series" | "author" | "narrator" | "tag" | "collection";

The book field a patron scope rule matches one value of.


SettingCellValue

type SettingCellValue = string | number | boolean;

One stored cell of a table setting row.


SettingDestinationScope

type SettingDestinationScope = "name" | "publicAddress" | "localAddress" | "restricted";

Where a setting's destination points, which decides how the grant reaches it.


SettingRow

type SettingRow = Record<string, SettingCellValue>;

One stored row of a table setting, keyed by column.


TitleMetaQuery

type TitleMetaQuery = object;

Query for public title metadata enrichment.

Properties

asin?
asin?: string | null;
authors?
authors?: string | null;
isbn?
isbn?: string | null;
length_minutes?
length_minutes?: number | null;
narrators?
narrators?: string | null;
region?
region?: string;
store_editions?
store_editions?: StoreEdition[] | null;

Store editions that listed the title. The server fills a sparse record from the stores that answer their own product ids before asking ISBN stores.

title
title: string;

TitleReviewsPage

type TitleReviewsPage = object;

One page of Audible customer reviews.

Properties

asin
asin: string;
has_more
has_more: boolean;
page
page: number;
page_size
page_size: number;
reviews
reviews: TitleReview[];
sort_by?
sort_by?: string;

TitleReviewsQuery

type TitleReviewsQuery = object;

Paginated title-reviews request body.

Properties

asin
asin: string;
page?
page?: number;
page_size?
page_size?: number;
region?
region?: string;
sort_by?
sort_by?: TitleReviewsSort;

TitleReviewsSort

type TitleReviewsSort = "MostHelpful" | "MostRecent";

Audible review sort modes for title detail.


WorkFacet

type WorkFacet = 
  | "author"
  | "narrator"
  | "series"
  | "genre"
  | "publisher"
  | "source"
  | "tag"
  | "library_tag"
  | "collection"
  | "progress";

What facet and value filter works by: a value list of the page index (library_tag is a library tag everyone sees), the caller's own tags (tag), or their progress (finished / not_finished).


WorkKind

type WorkKind = "book" | "podcast";

What a work is: a book, or a podcast (its show).


WorkSort

type WorkSort = "title" | "author" | "series" | "purchased" | "added" | "length";

How /api/library/works orders a page (ignored while searching).


WorkTagSource

type WorkTagSource = "admin" | "sidecar";

Where a library tag came from.

Variables

BEFORE_SIGN_OUT_WAIT_MS

const BEFORE_SIGN_OUT_WAIT_MS: 3000 = 3000;

How long a change of identity waits for the work registered with beforeSignOut, in milliseconds.


endElevate

const endElevate: () => Promise<void> = endElevation;

Alias used by Settings RBAC controls.

Ends an elevated operator window on a user session.

Returns

Promise<void>

Resolves when elevation is cleared.

Functions

ackEventDelivery()

function ackEventDelivery(id): Promise<ActionResponse>;

Acknowledges a dead-lettered delivery (no further retry).

Parameters

Parameter Type Description
id string Delivery id ({eventId}:{pluginId}).

Returns

Promise<ActionResponse>

Action ack from the daemon.


acquirableEditions()

function acquirableEditions(work): string[];

The editions of work an acquire should queue: those someone holds that are not acquired or on their way.

Parameters

Parameter Type Description
work WorkDetail A work's detail.

Returns

string[]

Edition ids for triggerAcquire's editions.


approveLibraryConsent()

function approveLibraryConsent(body): Promise<{
  consent: RemoteConsentView;
}>;

Approves an owner plugin's request, optionally narrowed. Only what the request asks for can be approved.

Parameters

Parameter Type Description
body RemoteApprovalBody The request reviewed and what to leave out.

Returns

Promise<{ consent: RemoteConsentView; }>

The consent row after approval.


approvePluginConsent()

function approvePluginConsent(
   id, 
   grant?, 
   pluginKey?, 
   settingDestinations?
): Promise<PluginConsentResponse>;

Approves network consent for a plugin.

Parameters

Parameter Type Description
id string Display alias from Settings.
grant? { addressCidrs?: string[]; allowUndeclaredPublicRedirects?: boolean; bindings: string[]; compatibilityFlags: string[]; cpuCores?: number; cpuMs?: number; diskMib?: number; domains: string[]; extraProcesses?: number; memoryMib?: number; networkMode: string; ownUserAgentHosts?: string[]; subrequests?: number; tcp?: object[]; } Operator-approved grant overlay; omitted fields keep defaults.
grant.addressCidrs? string[] -
grant.allowUndeclaredPublicRedirects? boolean -
grant.bindings string[] -
grant.compatibilityFlags string[] -
grant.cpuCores? number -
grant.cpuMs? number -
grant.diskMib? number -
grant.domains string[] -
grant.extraProcesses? number -
grant.memoryMib? number -
grant.networkMode string -
grant.ownUserAgentHosts? string[] -
grant.subrequests? number -
grant.tcp? object[] -
pluginKey? string Provenance-qualified PluginKey when the alias is ambiguous.
settingDestinations? PluginSettingDestinationApproval[] Setting destinations to approve; one left out stays pending, and omitting the list keeps earlier approvals that a setting still names.

Returns

Promise<PluginConsentResponse>

Updated consent response after approval.


authMe()

function authMe(): Promise<AuthSession>;

Loads the current session from GET /api/auth/me.

A 503 with Retry-After (the session could not be checked yet) is asked again a few times; only a 401 means signed out.

Returns

Promise<AuthSession>

Anonymous session when the response is 401.

Throws

When the check fails or times out, which is not a sign-out.


authMeUntilAnswered()

function authMeUntilAnswered(
   stopped, 
   check?, 
   sleep?
): Promise<AuthSession | null>;

Asks authMe until it answers, backing off between attempts.

A check that timed out, could not reach the server, or found it busy (502, 503 or 504) is not a sign-out, so the app keeps its loading screen and asks again rather than showing the sign-in page to someone whose session is fine. Waits 1 s, 2 s, 4 s … up to 10 s. Any other failure is thrown to the caller.

Parameters

Parameter Type Default value Description
stopped () => boolean undefined True once the caller no longer wants the answer.
check? () => Promise<AuthSession> authMe Performs one session check (defaults to authMe).
sleep? (ms) => Promise<void> ... Waits the given milliseconds (defaults to a timer).

Returns

Promise<AuthSession | null>

The session, or null when stopped turned true first.

Throws

When the check fails in a way asking again cannot fix.


availableThroughLabel()

function availableThroughLabel(through): string | null;

One line naming the branches a title is available through.

Parameters

Parameter Type Description
through BranchAvailability[] | undefined The title's branch availability.

Returns

string | null

For example "Available through Riley's branch", or null when no branch lists the title.


beforeSignOut()

function beforeSignOut(task, after?): () => void;

Registers work that must finish while the signed-in identity still holds, such as the player's last position report.

Parameters

Parameter Type Description
task () => Promise<void> Run twice at the start of every sign-out and before impersonation starts or stops, so it must do nothing when there is nothing left to finish, and awaited for up to BEFORE_SIGN_OUT_WAIT_MS. A task that fails, throws or takes longer does not stop the change.
after? () => void Run once the request that changes the identity has answered or failed, to take back whatever task held off meanwhile (the player starts no book in between).

Returns

Removes the task and after.

() => void


bootstrapAdministrator()

function bootstrapAdministrator(body): Promise<BootstrapAdministratorResponse>;

Creates the first Owner account when no owners (or legacy administrators) exist.

Parameters

Parameter Type Description
body { display_name?: string; email?: string; login_name?: string; password?: string; } Optional display/login/email/password fields for the new owner.
body.display_name? string -
body.email? string -
body.login_name? string -
body.password? string -

Returns

Promise<BootstrapAdministratorResponse>

Bootstrap result including the one-time invite magic link.


branchesToAsk()

function branchesToAsk(through): object[];

The distinct branches a title is available through, one entry per branch, in the order given, with the label to ask each by.

Parameters

Parameter Type Description
through BranchAvailability[] | undefined The title's branch availability.

Returns

object[]

For example [{ node_id, work_id, label: "Riley's branch" }].


cancelEventDelivery()

function cancelEventDelivery(id): Promise<ActionResponse>;

Cancels a pending delivery or flags a running one.

Parameters

Parameter Type Description
id string Delivery id ({eventId}:{pluginId}).

Returns

Promise<ActionResponse>

Action ack from the daemon.


cancelJob()

function cancelJob(id): Promise<ActionResponse>;

Requests cancel of a pending job or cooperative stop of a running job.

Parameters

Parameter Type Description
id string Durable job id from /api/jobs.

Returns

Promise<ActionResponse>

Action ack including the job id.


coverSrc()

function coverSrc(path, size): string | null;

The same-origin URL of one processed size of a remote cover.

The daemon hands out cover_path (/api/covers/<token>) for every remote https cover, so the web app never loads cover_url from another site.

Parameters

Parameter Type Description
path string | null | undefined A cover_path from an API response.
size CoverSize The size to load.

Returns

string | null

The image URL, or null when there is no usable path.


createOidcClient()

function createOidcClient(body): Promise<OidcAsClient>;

Creates an OIDC client. Confidential clients return client_secret once.

Parameters

Parameter Type Description
body OidcAsClientWrite Client id, redirects, token policy.

Returns

Promise<OidcAsClient>

Created client; confidential clients include client_secret once.


createUser()

function createUser(body): Promise<UserMutationResponse>;

Creates a first-party Bookclerk user.

Parameters

Parameter Type Description
body { display_name?: string; email?: string; login_name?: string; mint_invite?: boolean; password?: string; role?: string; } Role, profile fields, optional password, and invite choice.
body.display_name? string -
body.email? string -
body.login_name? string -
body.mint_invite? boolean -
body.password? string -
body.role? string -

Returns

Promise<UserMutationResponse>

Created user plus optional one-time claim ticket.


createWishlistItem()

function createWishlistItem(body): Promise<TitleRequest>;

Adds a title to the current user's wishlist.

Parameters

Parameter Type Description
body { asin?: string; authors?: string; cover_url?: string | null; description?: string | null; genres?: string | null; isbn?: string; language?: string | null; length_minutes?: number | null; narrators?: string | null; notes?: string; published_at?: string | null; publisher?: string | null; purchase_hints?: PurchaseHint[]; series?: string | null; series_index?: string | null; store_editions?: StoreEdition[]; subtitle?: string | null; title: string; } Title fields and optional catalog enrichment.
body.asin? string -
body.authors? string -
body.cover_url? string | null -
body.description? string | null -
body.genres? string | null -
body.isbn? string -
body.language? string | null -
body.length_minutes? number | null -
body.narrators? string | null -
body.notes? string -
body.published_at? string | null -
body.publisher? string | null -
body.purchase_hints? PurchaseHint[] -
body.series? string | null -
body.series_index? string | null -
body.store_editions? StoreEdition[] -
body.subtitle? string | null -
body.title string -

Returns

Promise<TitleRequest>

Created title-request row.


deleteDiagnosticsReport()

function deleteDiagnosticsReport(reportId): Promise<number>;

Deletes the collector's stored copy of a sent report; its summary and issue links stay (operator only).

Parameters

Parameter Type Description
reportId string The report's ID.

Returns

Promise<number>

When the copy was deleted, Unix milliseconds.


deleteOidcClient()

function deleteOidcClient(clientId): Promise<void>;

Deletes a registered OIDC client (operator or elevated Owner only).

Parameters

Parameter Type Description
clientId string Client to remove.

Returns

Promise<void>

Resolves when the client is removed.


deletePasskey()

function deletePasskey(id, currentPassword?): Promise<void>;

Delete a passkey owned by the current User.

Parameters

Parameter Type Description
id number -
currentPassword? string -

Returns

Promise<void>


deletePluginPlacement()

function deletePluginPlacement(instanceId): Promise<{
  deleted: boolean;
  plugin_instance_id: string;
}>;

Drops an instance's placement: its deployments stay as they are and the Enabled switch manages them again.

Parameters

Parameter Type Description
instanceId string Plugin instance id.

Returns

Promise<{ deleted: boolean; plugin_instance_id: string; }>

Whether a placement was removed.


deleteProfileAvatar()

function deleteProfileAvatar(): Promise<void>;

Removes the signed-in user's stored profile picture.

Returns

Promise<void>


deleteUser()

function deleteUser(id): Promise<{
  ok: boolean;
}>;

Deletes a first-party user (operator / administrator provisioner).

Parameters

Parameter Type Description
id number User id.

Returns

Promise<{ ok: boolean; }>

Ack payload.


disableTotp()

function disableTotp(currentPassword?): Promise<void>;

Disables TOTP for the current user.

Parameters

Parameter Type Description
currentPassword? string Required when the portal session is older than the reauth window.

Returns

Promise<void>

Resolves when TOTP is disabled.


editionCoverUrl()

function editionCoverUrl(editionId): string;

Builds the authenticated URL of the cover an acquire wrote beside an edition's file (404 when this node has none).

Parameters

Parameter Type Description
editionId string Edition id.

Returns

string

Relative URL under /api/library/editions/.../cover.


elevate()

function elevate(password): Promise<void>;

Temporarily elevates an Owner session after password re-authentication.

Parameters

Parameter Type Description
password string The Owner's account password.

Returns

Promise<void>

Resolves when elevation succeeds.


endElevation()

function endElevation(): Promise<void>;

Ends an elevated operator window on a user session.

Returns

Promise<void>

Resolves when elevation is cleared.


fetchCatalogListing()

function fetchCatalogListing(): Promise<CatalogListingView>;

Whether the signed-in user's books are listed to the libraries this server is a branch of (GET /api/auth/profile/catalog-listing).

Returns

Promise<CatalogListingView>

The choice, and how many libraries it applies to.


fetchDiagnosticsReport()

function fetchDiagnosticsReport(reportId): Promise<DiagnosticsReportLookup>;

Reads a sent report back from the collector with its access code (operator only).

Parameters

Parameter Type Description
reportId string The report's ID.

Returns

Promise<DiagnosticsReportLookup>

The report, its issues and its fix.


fetchDiagnosticsReports()

function fetchDiagnosticsReports(): Promise<DiagnosticsReport[]>;

Lists the diagnostics reports this install sent (operator only).

Returns

Promise<DiagnosticsReport[]>

Reports, newest first (the install keeps the last 200).


fetchDiscoverFeed()

function fetchDiscoverFeed(): Promise<DiscoverFeed>;

Loads the caller's stored Discover shelves.

Returns

Promise<DiscoverFeed>

Discover feed payload; state says whether shelves are still being prepared.


fetchEventDeliveries()

function fetchEventDeliveries(state?): Promise<EventDeliveryInfo[]>;

Lists recent event deliveries for the Library strip.

Parameters

Parameter Type Description
state? string Optional lifecycle filter (dead_letter, running, …).

Returns

Promise<EventDeliveryInfo[]>

Delivery rows from /api/events/deliveries.


fetchFacetValues()

function fetchFacetValues(facet, cursor?): Promise<FacetValuesPage>;

Fetches one page of a facet's values across the library's held works.

Parameters

Parameter Type Description
facet | "source" | "tag" | "author" | "series" | "narrator" | "genre" | "publisher" | "library_tag" | "collection" The facet (not progress, whose values are fixed).
cursor? string The previous page's next_cursor; omitted for the first.

Returns

Promise<FacetValuesPage>

The page and the next page's cursor.


fetchInbox()

function fetchInbox(options?): Promise<InboxPageView>;

Reads one page of the signed-in person's notification inbox.

Parameters

Parameter Type Description
options? { cursor?: string | null; limit?: number; } cursor from the previous page and a page size.
options.cursor? string | null -
options.limit? number -

Returns

Promise<InboxPageView>

The page, malformed entries dropped.


fetchJobs()

function fetchJobs(): Promise<JobInfo[]>;

Lists recent background jobs for the jobs strip / status polling.

Returns

Promise<JobInfo[]>

Job rows from /api/jobs (newest first as returned by the daemon).


fetchLibraryStatus()

function fetchLibraryStatus(): Promise<LibraryStatusResponse>;

Library health every node administrator may see, with detail for the caller's visible nodes.

Returns

Promise<LibraryStatusResponse>

Library summary, visible nodes, and the caller's capabilities.


fetchMfaPolicy()

function fetchMfaPolicy(): Promise<{
  require_second_factor: boolean;
}>;

Host-wide password second-factor policy (daemon.auth.require_second_factor).

Returns

Promise<{ require_second_factor: boolean; }>

Whether password login requires a second factor.


fetchOidcConfig()

function fetchOidcConfig(): Promise<OidcBrokerConfigView>;

Owner/operator identity-broker configuration (secrets redacted).

Returns

Promise<OidcBrokerConfigView>

Enabled flag, callback URL, and provider rows.


fetchPluginConsent()

function fetchPluginConsent(id, pluginKey?): Promise<PluginConsentResponse>;

Loads network/capability consent status for a plugin before enable.

Call from Settings when an operator reviews domains/bindings that still need approval; covered is false until approvePluginConsent succeeds.

Parameters

Parameter Type Description
id string Display alias from Settings.
pluginKey? string Provenance-qualified PluginKey when the alias is ambiguous.

Returns

Promise<PluginConsentResponse>

Current consent request payload and whether it already covers the ask.


fetchPluginInstanceConfig()

function fetchPluginInstanceConfig(instanceId): Promise<PluginInstanceConfig>;

Reads a plugin instance's stored document.

Parameters

Parameter Type Description
instanceId string Plugin instance id.

Returns

Promise<PluginInstanceConfig>

Stored settings, secret refs, and the document revision.


fetchPreferences()

function fetchPreferences(): Promise<UserPreferences>;

Loads the signed-in user's preferences.

Returns

Promise<UserPreferences>

Normalized UserPreferences.


fetchPurchaseHints()

function fetchPurchaseHints(body): Promise<PurchaseHintsResponse>;

Resolves purchase hints through a batch shared with every other card.

Lookups asked close together go out as one batch request, one batch at a time, after the covers on screen have loaded (see lookupBatcher.ts).

Parameters

Parameter Type Description
body PurchaseHintsQuery Title identity and optional candidate edition.

Returns

Promise<PurchaseHintsResponse>

Hints list plus optional best pick (client-cached).


fetchRequestQueue()

function fetchRequestQueue(): Promise<GlobalQueueEntry[]>;

Loads the global request queue (shared demand).

Returns

Promise<GlobalQueueEntry[]>

Aggregated queue entries.


fetchRetryingBusy()

function fetchRetryingBusy(
   input, 
   init, 
   fetcher?, 
   sleep?
): Promise<Response>;

Fetches a read, asking again while the daemon answers 503 with Retry-After.

The daemon answers that way when it could not check the session yet (a busy library, as on a small server that is still starting), which is not the same as being signed out. Only for GET requests, which are safe to repeat.

Parameters

Parameter Type Description
input string Request URL.
init RequestInit | undefined Request options; the method must be GET.
fetcher? (input, init?) => Promise<Response> Performs one request (defaults to fetch).
sleep? (ms) => Promise<void> Waits the given milliseconds (defaults to a timer).

Returns

Promise<Response>

The first response that is not such a 503, or the last 503.


fetchSettings()

function fetchSettings(): Promise<SettingsResponse>;

Loads operator settings groups and plugin option schemas for the Settings page.

Returns

Promise<SettingsResponse>

Core settings plus per-plugin option groups.


fetchSigninMethods()

function fetchSigninMethods(): Promise<{
  integrations: object[];
  oidc: OidcProvider[];
  operator_token: boolean;
  require_second_factor: boolean;
}>;

Public sign-in picker (operator-token availability, SSO, integration logins).

Returns

Promise<{ integrations: object[]; oidc: OidcProvider[]; operator_token: boolean; require_second_factor: boolean; }>

Whether SPA operator-token login is offered, plus IdP and integration buttons.


fetchStatus()

function fetchStatus(): Promise<StatusResponse>;

Loads aggregate library status counters.

Returns

Promise<StatusResponse>

Status payload for the jobs strip / library header.


fetchTitleMeta()

function fetchTitleMeta(body): Promise<TitleMeta | null>;

Fetches title metadata through a batch shared with every other card (see fetchPurchaseHints).

Parameters

Parameter Type Description
body TitleMetaQuery Title identity fields.

Returns

Promise<TitleMeta | null>

Metadata or null when none matched (client-cached).


fetchTitleMetaBatch()

function fetchTitleMetaBatch(queries): Promise<(TitleMeta | null)[]>;

Batch title-meta fetch (order preserved); shares the client TTL cache with singles.

Parameters

Parameter Type Description
queries TitleMetaQuery[] Parallel title-meta queries.

Returns

Promise<(TitleMeta | null)[]>

Metadata (or null) aligned with queries.


fetchTitleReviews()

function fetchTitleReviews(body): Promise<TitleReviewsPage>;

Loads a page of Audible customer reviews for title detail infinite scroll.

Parameters

Parameter Type Description
body TitleReviewsQuery ASIN, region, page, and sort.

Returns

Promise<TitleReviewsPage>

Reviews page payload.


fetchTotpStatus()

function fetchTotpStatus(): Promise<{
  enabled: boolean;
}>;

Whether TOTP is confirmed for the current user.

Returns

Promise<{ enabled: boolean; }>

{ enabled } for the signed-in user.


fetchWishlist()

function fetchWishlist(): Promise<TitleRequest[]>;

Loads the current user's wishlist items.

Returns

Promise<TitleRequest[]>

Title-request rows.


fetchWork()

function fetchWork(id): Promise<WorkDetail>;

Fetches one work with its editions, listings, holdings and own state.

Parameters

Parameter Type Description
id string Work id.

Returns

Promise<WorkDetail>

The work.


fetchWorks()

function fetchWorks(query): Promise<WorksPage>;

Fetches one page of the library's works.

Parameters

Parameter Type Description
query WorksQuery Filters, order and the cursor of the page to read.

Returns

Promise<WorksPage>

The page and the next page's cursor.


getCollections()

function getCollections(): Promise<LibraryCollections>;

Reads the library's collections (operator, Owner or Administrator).

Returns

Promise<LibraryCollections>

The collections.


getDefaultAdminControls()

function getDefaultAdminControls(): Promise<{
  controls: AdminControls;
}>;

Reads the library's default Administrator switches.

Returns

Promise<{ controls: AdminControls; }>

The default.


getDefaultControls()

function getDefaultControls(): Promise<{
  controls: MemberControls;
}>;

Reads the library's default member controls.

Returns

Promise<{ controls: MemberControls; }>

The default.


getDefaultScope()

function getDefaultScope(): Promise<{
  scope: PatronScope;
}>;

Reads the library's default patron scope.

Returns

Promise<{ scope: PatronScope; }>

The default.


getUserAdminControls()

function getUserAdminControls(id): Promise<UserAdminControls>;

Reads what an Administrator may do.

Parameters

Parameter Type Description
id number The user.

Returns

Promise<UserAdminControls>

The default, the Administrator's overrides and what applies.


getUserControls()

function getUserControls(id): Promise<UserControls>;

Reads what a patron may do.

Parameters

Parameter Type Description
id number The user.

Returns

Promise<UserControls>

The default, the patron's overrides and what applies.


getUserScope()

function getUserScope(id): Promise<UserScope>;

Reads which part of the library a patron sees.

Parameters

Parameter Type Description
id number The user.

Returns

Promise<UserScope>

The scope that applies and where it comes from.


getWorkTags()

function getWorkTags(id): Promise<WorkTags>;

Reads a work's library tags (operator, Owner or Administrator).

Parameters

Parameter Type Description
id string A top-level work.

Returns

Promise<WorkTags>

The tags.


isApiError()

function isApiError(error): error is ApiError;

Narrows unknown to ApiError.

Parameters

Parameter Type Description
error unknown Caught value from a failed API call.

Returns

error is ApiError

Whether error is an ApiError instance.


listConfigNodes()

function listConfigNodes(): Promise<NodesResponse>;

Lists the nodes the caller may see: every node for an operator, the owned ones for a node owner.

Returns

Promise<NodesResponse>

The serving node's id, the visible nodes, and what the caller may edit.


listLibraryConsents()

function listLibraryConsents(): Promise<LibraryConsentsResponse>;

Lists the libraries this host is enrolled in and what each asks to run here. Operator only.

Returns

Promise<LibraryConsentsResponse>

Links and consent rows.


listOidcClients()

function listOidcClients(): Promise<OidcAsClient[]>;

Lists Bookclerk-as-IdP clients (no plaintext secrets).

Returns

Promise<OidcAsClient[]>

Registered OAuth clients.


listOidcIdentities()

function listOidcIdentities(): Promise<LinkedIdentity[]>;

Linked login identities for the current User.

Returns

Promise<LinkedIdentity[]>


listOidcProviders()

function listOidcProviders(): Promise<{
  enabled: boolean;
  providers: OidcProvider[];
}>;

Public list of SSO providers for the login page.

Returns

Promise<{ enabled: boolean; providers: OidcProvider[]; }>


listPasskeys()

function listPasskeys(): Promise<ListedPasskey[]>;

Passkeys registered to the current User.

Returns

Promise<ListedPasskey[]>


listSessions()

function listSessions(): Promise<ListedSession[]>;

Lists sessions for the current principal.

Returns

Promise<ListedSession[]>

Active session rows.


listUsers()

function listUsers(): Promise<ListedUser[]>;

Lists users for administrator settings.

Returns

Promise<ListedUser[]>

User rows (empty array when none).


login()

function login(token): Promise<AuthSession>;

Signs in with the operator token via POST /api/auth/login.

Parameters

Parameter Type Description
token string Operator bearer token from bookclerk daemon token.

Returns

Promise<AuthSession>

Authenticated operator session (acquire enabled).


logout()

function logout(): Promise<void>;

Clears the operator cookie session via POST /api/auth/logout.

Returns

Promise<void>

Resolves when the library answered that the sign-out is done.

Throws

When the library answers anything else.


markInboxRead()

function markInboxRead(notificationId): Promise<number>;

Marks one inbox entry read, or the whole inbox when no id is given.

Parameters

Parameter Type Description
notificationId string | null The entry to mark, or null for all of them.

Returns

Promise<number>

How many entries changed.


mintUserClaimTicket()

function mintUserClaimTicket(id): Promise<{
  claim_ticket: string;
  invite_url?: string | null;
  ok: boolean;
}>;

Mints a fresh one-time claim ticket for an existing active user.

Parameters

Parameter Type Description
id number User id.

Returns

Promise<{ claim_ticket: string; invite_url?: string | null; ok: boolean; }>

One-time claim ticket.


passkeyElevateBegin()

function passkeyElevateBegin(): Promise<{
  challenge_id: string;
  publicKey: Record<string, unknown>;
}>;

Begin passkey Owner elevation.

Returns

Promise<{ challenge_id: string; publicKey: Record<string, unknown>; }>


passkeyElevateFinish()

function passkeyElevateFinish(body): Promise<void>;

Finish passkey Owner elevation.

Parameters

Parameter Type Description
body { challenge_id: string; credential: Record<string, unknown>; } -
body.challenge_id string -
body.credential Record<string, unknown> -

Returns

Promise<void>


passkeyLoginBegin()

function passkeyLoginBegin(login): Promise<{
  challenge_id: string;
  publicKey: Record<string, unknown>;
}>;

Begin identifier-first passkey login.

Parameters

Parameter Type Description
login string -

Returns

Promise<{ challenge_id: string; publicKey: Record<string, unknown>; }>


passkeyLoginFinish()

function passkeyLoginFinish(body): Promise<void>;

Finish passkey login (sets the portal session cookie).

Parameters

Parameter Type Description
body { challenge_id: string; credential: Record<string, unknown>; } -
body.challenge_id string -
body.credential Record<string, unknown> -

Returns

Promise<void>


passkeyRegisterBegin()

function passkeyRegisterBegin(currentPassword?): Promise<{
  challenge_id: string;
  publicKey: Record<string, unknown>;
}>;

Begin WebAuthn registration (authenticated).

Parameters

Parameter Type Description
currentPassword? string -

Returns

Promise<{ challenge_id: string; publicKey: Record<string, unknown>; }>


passkeyRegisterFinish()

function passkeyRegisterFinish(body): Promise<void>;

Finish WebAuthn registration.

Parameters

Parameter Type Description
body { challenge_id: string; credential: Record<string, unknown>; name?: string; } -
body.challenge_id string -
body.credential Record<string, unknown> -
body.name? string -

Returns

Promise<void>


passwordLogin()

function passwordLogin(login, password): Promise<{
  mfa?: {
     challenge_id: string;
     method: string;
  };
  ok: boolean;
}>;

Signs in with username/password via POST /api/auth/password.

Parameters

Parameter Type Description
login string Username or email.
password string Account password.

Returns

Promise<{ mfa?: { challenge_id: string; method: string; }; ok: boolean; }>

Session cookie on success, or an MFA challenge when TOTP is enabled.


patchDefaultAdminControls()

function patchDefaultAdminControls(changes): Promise<{
  controls: AdminControls;
}>;

Changes some of the library's default Administrator switches (Owner or operator only).

Only the named switches change, so a concurrent edit of another switch is kept.

Parameters

Parameter Type Description
changes Partial<AdminControls> The switches to change and their new values.

Returns

Promise<{ controls: AdminControls; }>

The default after the change.


patchPreferences()

function patchPreferences(body): Promise<UserPreferences>;

Partially updates the signed-in user's preferences.

Parameters

Parameter Type Description
body { default_view?: AppView; disabled_shelves?: string[]; discover_excluded_sources?: string[]; discover_language?: string | null; discover_sort?: CatalogSearchSort; discover_sort_dir?: "desc" | "asc"; theme?: ThemePreference; } Fields to patch (discover_language: null clears to browser default).
body.default_view? AppView -
body.disabled_shelves? string[] -
body.discover_excluded_sources? string[] -
body.discover_language? string | null Pass null to clear to browser default.
body.discover_sort? CatalogSearchSort -
body.discover_sort_dir? "desc" | "asc" -
body.theme? ThemePreference -

Returns

Promise<UserPreferences>

Updated preferences after save.


patchProfile()

function patchProfile(body): Promise<{
  ok: boolean;
  user: AuthMeUser;
}>;

Updates the signed-in user's display name and/or email.

Parameters

Parameter Type Description
body { avatar_source?: string; display_name?: string; email?: string; } Fields to change; omitted keys are left unchanged.
body.avatar_source? string -
body.display_name? string -
body.email? string -

Returns

Promise<{ ok: boolean; user: AuthMeUser; }>

Updated profile snapshot from the daemon.


patchSettings()

function patchSettings(body): Promise<SettingsResponse>;

Writes bootstrap settings (daemon, jail, [database] keys) through PATCH /api/settings. Plugin settings are not accepted here: they are instance documents, written with putPluginInstanceConfig.

Parameters

Parameter Type Description
body { expected_output_revision?: number; settings: SettingsUpdate[]; } Settings updates to apply.
body.expected_output_revision? number core.output revision the caller read; a stale value is rejected with 409.
body.settings SettingsUpdate[] -

Returns

Promise<SettingsResponse>

The settings view after the write.


patchUser()

function patchUser(id, body): Promise<UserMutationResponse>;

Updates a first-party user role, status, or profile fields.

Parameters

Parameter Type Description
id number User id to patch.
body { display_name?: string; email?: string; login_name?: string; role?: string; status?: string; } Partial user fields accepted by the daemon.
body.display_name? string -
body.email? string -
body.login_name? string -
body.role? string -
body.status? string -

Returns

Promise<UserMutationResponse>

Patched user row.


patchUserAdminControls()

function patchUserAdminControls(id, changes): Promise<UserAdminControls>;

Changes some switches for one Administrator (Owner or operator only).

Only the named switches change, so a concurrent edit of another switch is kept.

Parameters

Parameter Type Description
id number The user.
changes Partial<Record<AdminControl, AdminSwitchChoice>> on or off for them alone, or default to follow the library's default.

Returns

Promise<UserAdminControls>

The switches after the change.


portalConnections()

function portalConnections(): Promise<PortalConnection[]>;

Lists linked store accounts for the current portal user.

Returns

Promise<PortalConnection[]>

Connection rows.


portalLoginIntegration()

function portalLoginIntegration(body): Promise<void>;

Signs in via an integration provider username/password.

Parameters

Parameter Type Description
body { password: string; provider: string; username: string; } Provider id plus credentials.
body.password string -
body.provider string -
body.username string -

Returns

Promise<void>

Resolves when the portal session is established.


portalLogout()

function portalLogout(): Promise<void>;

Clears the portal / user session cookie.

Returns

Promise<void>

Resolves when logout finishes (best-effort).


portalMe()

function portalMe(): Promise<PortalMe>;

Loads the linked portal identity for the signed-in SPA session.

Returns

Promise<PortalMe>

Portal identity metadata used by Accounts / Settings headers.


portalRedeem()

function portalRedeem(ticket, password?): Promise<void>;

Redeems a claim ticket into a portal user session.

Parameters

Parameter Type Description
ticket string One-time claim ticket string.
password? string Optional password when claiming invite/reset tickets.

Returns

Promise<void>

Resolves when the session cookie is set.


portalRevokeConnection()

function portalRevokeConnection(source, accountId): Promise<void>;

Disconnects a storefront account from the current portal user.

Does not delete library rows; only revokes the sealed credentials / link. Accounts belong to a plugin, so the source (alias or PluginKey) is part of the address: the same account id may exist on two stores.

Parameters

Parameter Type Description
source string Source id or PluginKey from portalConnections.
accountId string Portal connection account id from portalConnections.

Returns

Promise<void>

Resolves when the revoke POST succeeds.


portalSetConnectionPace()

function portalSetConnectionPace(
   source, 
   accountId, 
   change
): Promise<PortalPace>;

Changes how fast Bookclerk downloads from one of the caller's store accounts when it starts the downloads itself.

Parameters

Parameter Type Description
source string Source id or PluginKey from portalConnections.
accountId string Store account id from portalConnections.
change PortalPaceChange The new pace, and whether to end the store's cool-down.

Returns

Promise<PortalPace>

The account's pace as it now stands.


portalSourceLogin()

function portalSourceLogin(id, body): Promise<void>;

Password-connects a storefront account.

Parameters

Parameter Type Description
id string Source plugin id.
body { email: string; password: string; } Store email and password.
body.email string -
body.password string -

Returns

Promise<void>

Resolves when the connection is stored.


portalSourceOauthStart()

function portalSourceOauthStart(id): Promise<{
  url: string;
}>;

Starts OAuth for a storefront and returns the authorize URL.

Parameters

Parameter Type Description
id string Source plugin id.

Returns

Promise<{ url: string; }>

Object with browser url to open.


portalSources()

function portalSources(): Promise<PortalSource[]>;

Lists connectable storefronts for Accounts.

Returns

Promise<PortalSource[]>

Source descriptors including brand metadata.


putCollections()

function putCollections(collections): Promise<LibraryCollections>;

Replaces the library's collections; the Library is re-indexed after.

Parameters

Parameter Type Description
collections LibraryCollections The new collections.

Returns

Promise<LibraryCollections>

The collections as saved (names trimmed, prefixes ending in /).


putDefaultControls()

function putDefaultControls(controls): Promise<{
  controls: MemberControls;
}>;

Replaces the library's default member controls.

Parameters

Parameter Type Description
controls MemberControls The new default.

Returns

Promise<{ controls: MemberControls; }>

The default after the change.


putDefaultScope()

function putDefaultScope(scope): Promise<{
  scope: PatronScope;
}>;

Replaces the library's default patron scope.

Parameters

Parameter Type Description
scope PatronScope The new default.

Returns

Promise<{ scope: PatronScope; }>

The default after the change.


putMfaPolicy()

function putMfaPolicy(requireSecondFactor): Promise<{
  require_second_factor: boolean;
}>;

Persists whether password login requires TOTP or a passkey (operator or elevated Owner only).

Parameters

Parameter Type Description
requireSecondFactor boolean When true, password-only sign-in is not enough once enrolled.

Returns

Promise<{ require_second_factor: boolean; }>

Saved { require_second_factor } flag.


putNodeLabels()

function putNodeLabels(nodeId, labels): Promise<unknown>;

Replaces a node's operator labels.

Parameters

Parameter Type Description
nodeId string Node to edit.
labels string[] The complete label set (nas, zone=eu).

Returns

Promise<unknown>

The updated node.


putNodeOwner()

function putNodeOwner(nodeId, userId): Promise<{
  node_id: string;
  owner_user_id: number | null;
}>;

Assigns a node to the user who administers it, or clears its owner.

Parameters

Parameter Type Description
nodeId string Node to assign.
userId number | null Owning user, or null to clear.

Returns

Promise<{ node_id: string; owner_user_id: number | null; }>

The node id and its owner.


putNodeRuntime()

function putNodeRuntime(nodeId, body): Promise<{
  node_id: string;
  revision: number;
  runtime: NodeRuntimeView;
}>;

Edits a node's label, budgets, or drain switch. The node applies it at its next heartbeat.

Parameters

Parameter Type Description
nodeId string Node to edit.
body Partial<NodeRuntimeView> Fields to change; omitted fields keep their value.

Returns

Promise<{ node_id: string; revision: number; runtime: NodeRuntimeView; }>

The stored runtime document.


putOidcConfig()

function putOidcConfig(body): Promise<OidcBrokerConfigView>;

Replaces [auth.oidc] providers. Omit client_secret to keep the stored value.

Parameters

Parameter Type Description
body OidcBrokerConfigUpdate Broker enablement and provider list.

Returns

Promise<OidcBrokerConfigView>

Saved configuration with redacted secrets.


putPluginDeployment()

function putPluginDeployment(
   instanceId, 
   nodeId, 
   desired, 
   expectedRevision?
): Promise<PluginDeploymentView>;

Sets whether a plugin instance should run on a host (the enable switch).

Parameters

Parameter Type Description
instanceId string Plugin instance id.
nodeId string Target node id.
desired "present" | "absent" present to run it there, absent to retire it.
expectedRevision? number Deployment revision last observed, for compare-and-swap.

Returns

Promise<PluginDeploymentView>

The deployment row after the write.


putPluginInstanceConfig()

function putPluginInstanceConfig(instanceId, body): Promise<{
  plugin_instance_id: string;
  revision: number;
}>;

Replaces a plugin instance's document (compare-and-swap on expected_revision).

Secrets in body.secrets are sealed server-side and referenced by name; the response never carries them.

Parameters

Parameter Type Description
instanceId string Plugin instance id.
body PluginInstanceConfigWrite New document plus secrets to seal.

Returns

Promise<{ plugin_instance_id: string; revision: number; }>

The committed revision.


putPluginPlacement()

function putPluginPlacement(instanceId, body): Promise<{
  placement: PluginPlacementView;
  plugin_instance_id: string;
}>;

Hands an instance's deployments to the library scheduler, or changes its placement (compare-and-swap on expected_revision; 0 creates).

Parameters

Parameter Type Description
instanceId string Plugin instance id.
body { constraints: string[]; expected_revision: number; replicas: number | "all"; } Replica count, label constraints, and the revision last seen.
body.constraints string[] -
body.expected_revision number -
body.replicas number | "all" -

Returns

Promise<{ placement: PluginPlacementView; plugin_instance_id: string; }>

The stored placement.


putUserControls()

function putUserControls(id, overrides): Promise<UserControls>;

Sets the controls that differ for one patron; the rest follow the library's default.

Parameters

Parameter Type Description
id number The user.
overrides ControlOverrides The controls set for them alone ({} for none).

Returns

Promise<UserControls>

The controls after the change.


putUserScope()

function putUserScope(id, scope): Promise<UserScope>;

Gives a patron their own scope, or with null returns them to the library's default.

Parameters

Parameter Type Description
id number The user.
scope PatronScope | null Their own scope, or null.

Returns

Promise<UserScope>

The scope after the change.


putWorkState()

function putWorkState(id, edit): Promise<WorkState>;

Changes the caller's own finished flag, ratings or tags for a work.

Parameters

Parameter Type Description
id string The work.
edit WorkStateEdit The fields to change.

Returns

Promise<WorkState>

The caller's state after the change.


putWorkTags()

function putWorkTags(id, tags): Promise<WorkTags>;

Replaces the tags set in Bookclerk on a work; sidecar tags stay.

Parameters

Parameter Type Description
id string A top-level work.
tags string[] The tags to set ([] removes them).

Returns

Promise<WorkTags>

The tags afterwards.


removeWishlistItem()

function removeWishlistItem(uuid): Promise<TitleRequest>;

Deletes a wishlist title-request owned by the current user.

Parameters

Parameter Type Description
uuid string Wishlist title-request uuid from fetchWishlist.

Returns

Promise<TitleRequest>

The removed title-request row as echoed by the API.


requestDiscoverRefresh()

function requestDiscoverRefresh(): Promise<DiscoverStatus>;

Queues a storefront fetch and ranking for the caller's shelves now, as the Refresh button asks. A fetch already waiting absorbs the request.

Returns

Promise<DiscoverStatus>

The caller's Discover status once the fetch is queued.


requestFromBranch()

function requestFromBranch(workId, nodeId): Promise<BranchRequestQueued>;

Asks a branch for a book it lists. The branch takes it automatically; the book arrives with the branch's next catalog sync.

Parameters

Parameter Type Description
workId string The title's work (BranchAvailability.work_id).
nodeId string The branch to ask.

Returns

Promise<BranchRequestQueued>

The queued request.

Throws

404 when the branch no longer lists the title.


resetUserPassword()

function resetUserPassword(id): Promise<{
  claim_ticket: string;
  invite_url?: string | null;
  ok: boolean;
  revoked_sessions: number;
}>;

Mints a password-reset claim ticket and revokes the user's portal sessions.

Parameters

Parameter Type Description
id number User id.

Returns

Promise<{ claim_ticket: string; invite_url?: string | null; ok: boolean; revoked_sessions: number; }>

Reset ticket plus count of revoked sessions.


resumeEventDelivery()

function resumeEventDelivery(id): Promise<ActionResponse>;

Wakes a suspended delivery for the next worker claim.

Parameters

Parameter Type Description
id string Delivery id ({eventId}:{pluginId}).

Returns

Promise<ActionResponse>

Action ack from the daemon.


retryEventDelivery()

function retryEventDelivery(id): Promise<ActionResponse>;

Re-queues a dead-lettered delivery.

Parameters

Parameter Type Description
id string Delivery id ({eventId}:{pluginId}).

Returns

Promise<ActionResponse>

Action ack from the daemon.


revokeLibraryConsent()

function revokeLibraryConsent(libraryId, pluginKey): Promise<{
  consent: RemoteConsentView;
}>;

Withdraws an approval: held jobs of the plugin are cancelled and given back, and nothing of it is claimed until approved again.

Parameters

Parameter Type Description
libraryId string Library.
pluginKey string Canonical plugin key.

Returns

Promise<{ consent: RemoteConsentView; }>

The consent row after revoking.


revokeSession()

function revokeSession(id): Promise<void>;

Revokes one session visible to the current principal.

Parameters

Parameter Type Description
id number Session id.

Returns

Promise<void>

Resolves when the revoke succeeds.


rotateOidcClientSecret()

function rotateOidcClientSecret(clientId): Promise<OidcAsClient>;

Rotates a confidential client's secret (operator or elevated Owner only); plaintext is returned once.

Parameters

Parameter Type Description
clientId string Confidential client to rotate.

Returns

Promise<OidcAsClient>

Client row including the new plaintext secret once.


saveDiagnosticsSharing()

function saveDiagnosticsSharing(shareReports, shareUsage): Promise<SettingsResponse>;

Saves the install's diagnostics sharing choices (diagnostics.share_reports and diagnostics.share_usage). The daemon applies them without a restart.

Parameters

Parameter Type Description
shareReports boolean Upload redacted reports after crashes and error bursts.
shareUsage boolean Send the weekly anonymous check-in and tag reports with the install ID.

Returns

Promise<SettingsResponse>

The settings view after the write.


searchCatalog()

function searchCatalog(q, opts?): Promise<CatalogSearchPage>;

Searches the Discover catalog across enabled storefronts.

Returns an empty page (without calling the network) when q trims to fewer than 2 characters. Language defaults to the browser locale unless allLanguages is set.

Parameters

Parameter Type Description
q string Free-text query (minimum 2 characters after trim).
opts? { allLanguages?: boolean; cursor?: string | null; field?: "author" | "series" | "narrator" | "genre"; filters?: CatalogSearchFilters; lang?: string; limit?: number; page_size?: number; sort?: CatalogSearchSort; sort_dir?: CatalogSortDir; } Pagination cursor, sort, language, and server-side facet filters.
opts.allLanguages? boolean When true, do not hard-filter by language.
opts.cursor? string | null -
opts.field? "author" | "series" | "narrator" | "genre" -
opts.filters? CatalogSearchFilters -
opts.lang? string -
opts.limit? number Deprecated use page_size
opts.page_size? number -
opts.sort? CatalogSearchSort -
opts.sort_dir? CatalogSortDir -

Returns

Promise<CatalogSearchPage>

Cursor-paginated search page (or an empty stub when q is too short).


setCatalogListing()

function setCatalogListing(listed): Promise<CatalogListingView>;

Sets whether the signed-in user's books are listed to the libraries this server is a branch of (PUT /api/auth/profile/catalog-listing).

Parameters

Parameter Type Description
listed boolean false keeps the user's books out of catalog answers.

Returns

Promise<CatalogListingView>

The stored choice.


setPassword()

function setPassword(body): Promise<{
  ok: boolean;
  revoked_sessions: number;
}>;

Sets a password for self or for a managed user.

Parameters

Parameter Type Description
body { current_password?: string; password: string; user_id?: number; } New password and optional target user id.
body.current_password? string -
body.password string -
body.user_id? number -

Returns

Promise<{ ok: boolean; revoked_sessions: number; }>

Count of revoked sessions.


signOut()

function signOut(role?): Promise<void>;

Signs out regardless of operator vs user/portal session, after the work registered with beforeSignOut.

Parameters

Parameter Type Description
role? AuthRole Current session role; portal roles use portal logout.

Returns

Promise<void>

Resolves when logout completes.


startImpersonate()

function startImpersonate(userId): Promise<void>;

Starts operator (or elevated Owner) impersonation of another user, after the work registered with beforeSignOut: what is playing belongs to the identity being left.

Parameters

Parameter Type Description
userId number Target user id.

Returns

Promise<void>

Resolves when impersonation is active.


stopImpersonate()

function stopImpersonate(): Promise<void>;

Stops the current operator impersonation session, after the work registered with beforeSignOut: a book the impersonated person was playing is closed as them, not reported as the restored account.

Returns

Promise<void>

Resolves when impersonation ends.


storedEditions()

function storedEditions(work): string[];

The editions of work a convert can read from: the ones already stored.

Parameters

Parameter Type Description
work WorkDetail The work's detail.

Returns

string[]

Edition ids.


totpEnrollBegin()

function totpEnrollBegin(currentPassword?): Promise<{
  otpauth_url: string;
  qr_svg: string;
  secret: string;
}>;

Starts TOTP enrollment (pending secret, otpauth URL, QR SVG).

Parameters

Parameter Type Description
currentPassword? string Required when the portal session is older than the reauth window.

Returns

Promise<{ otpauth_url: string; qr_svg: string; secret: string; }>

Pending secret, otpauth URL, and QR SVG.


totpEnrollFinish()

function totpEnrollFinish(code): Promise<void>;

Confirms the pending TOTP secret with an authenticator code.

Parameters

Parameter Type Description
code string Six-digit code from the authenticator app.

Returns

Promise<void>

Resolves when enrollment is confirmed.


totpLogin()

function totpLogin(challengeId, code): Promise<void>;

Completes password+TOTP login via POST /api/auth/totp/login.

Parameters

Parameter Type Description
challengeId string Challenge from the password-login MFA payload.
code string Six-digit authenticator code.

Returns

Promise<void>

Resolves when the session cookie is set.


triggerAcquire()

function triggerAcquire(body): Promise<ActionResponse>;

Queues an acquire: everything pending when the body names nothing, or the named editions or title.

Parameters

Parameter Type Description
body { asin?: string; editions?: string[]; uuid?: string; } editions (ids from a work's detail), or a title by uuid / asin.
body.asin? string -
body.editions? string[] -
body.uuid? string -

Returns

Promise<ActionResponse>

Action ack including job_id.


triggerConvert()

function triggerConvert(body): Promise<ActionResponse>;

Queues a convert: each named edition gets copy beside its original, made from the copy the library stores. Owners, Administrators and the operator only.

Parameters

Parameter Type Description
body { copy: OutputCopy; editions: string[]; force?: boolean; } The editions, the copy, and force to make it again.
body.copy OutputCopy -
body.editions string[] -
body.force? boolean -

Returns

Promise<ActionResponse>

Action ack including job_id.


triggerScan()

function triggerScan(): Promise<ActionResponse>;

Queues a full-library scan job for accounts with scan enabled.

Prefer CLI one-shot scans with an explicit --account in cloud testing; this SPA helper hits the authenticated daemon endpoint used by the Library UI.

Returns

Promise<ActionResponse>

Action ack including job_id when accepted.


updateOidcClient()

function updateOidcClient(clientId, body): Promise<OidcAsClient>;

Updates an OIDC client without echoing a secret unless flipping to confidential.

Parameters

Parameter Type Description
clientId string Existing client_id.
body OidcAsClientWrite Redirects and token policy.

Returns

Promise<OidcAsClient>

Updated client row (no plaintext secret unless flipping to confidential).


uploadProfileAvatar()

function uploadProfileAvatar(file): Promise<void>;

Uploads a JPEG/PNG/WebP profile picture for the signed-in user.

Parameters

Parameter Type Description
file File Image selected from the file picker.

Returns

Promise<void>


userAvatarUrl()

function userAvatarUrl(userId, cacheKey?): string;

Authenticated URL for a user's stored profile picture.

Parameters

Parameter Type Description
userId number First-party users.id.
cacheKey? number Optional cache-buster after upload.

Returns

string

Path used by <img src>.


userFacingApiError()

function userFacingApiError(error, fallback): string;

Maps API / network failures to short copy for non-technical users.

Keeps branded daemon messages when they already read as plain language.

Parameters

Parameter Type Description
error unknown Caught failure from fetch / parse helpers.
fallback string Copy used when the error has no safe user-facing text.

Returns

string

Message suitable for inline SPA error banners.

Generated from ui/src/lib at main · View as Markdown