api
HTTP failure from Bookclerk JSON APIs, including optional machine code.
Error
new ApiError(
status,
message,
extras?
): ApiError;
| Parameter | Type |
|---|---|
status |
number |
message |
string |
extras? |
{ code?: string; pluginId?: string; summary?: string[]; } |
extras.code? |
string |
extras.pluginId? |
string |
extras.summary? |
string[] |
Error.constructor
code?: string;
Machine slug from JSON error bodies when present.
pluginId?: string;
status: number;
summary?: string[];
A listing held by a store account.
account_id: string;
The account's id on that storefront.
kind: "account";
Discriminant.
plugin_key: string;
The account's storefront plugin (audible, libro, ...).
Ack payload for scan / acquire job triggers.
error?: string | null;
job_id: string;
message: string;
ok: boolean;
Active impersonation target when an administrator is viewing as another user.
display_name: string | null;
user_id: number;
Signed-in administrator or member profile from /api/auth/me.
avatar_source?: string | null;
auto, monogram, gravatar, upload, or sso:{id}.
display_name: string | null;
email?: string | null;
gravatar_hash?: string | null;
SHA-256 hex of the contact email for Gravatar.
has_avatar?: boolean;
True when a profile picture file is stored for this user.
has_password?: boolean;
id: number;
login_name?: string | null;
role: string;
sso_pictures?: object[];
IdP-supplied pictures the user can pick.
identity_id: number;
last_used_at?: string | null;
picture_path?: string | null;
Same-origin 128 px copy of picture_url, when the server signed one.
picture_url: string;
provider: string;
status?: string;
Host MFA policy plus this user's TOTP / passkey enrollment.
enrolled: boolean;
passkey_count: number;
required: boolean;
totp: boolean;
Normalized client session used to gate SPA views and actions.
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: boolean;
can_acquire: boolean;
default_view: AppView;
elevated?: boolean;
impersonating?: AuthMeImpersonating;
portal?: PortalInfo;
role?: AuthRole;
second_factor?: AuthSecondFactor;
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?: AuthMeUser;
Bootstrap response for the first owner.
claim_ticket: string;
has_password: boolean;
invite_url?: string | null;
login_name: string | null;
ok: boolean;
user_id: number;
One branch of this library that can supply a title (it answered a catalog lookup for the title's work).
node_id: string;
The branch node id.
owner_name?: string | null;
The branch owner's display name, when the owner has one.
product_id: string;
The store's product id of the branch's copy.
store: string;
The store the branch has the book from (audible).
work_id: string;
This library's work the branch supplies; what requestFromBranch asks for.
POST /api/branch-requests answer.
already_queued: boolean;
true when a request for this work to this branch was already waiting.
job_id: string;
The request's job, as /api/jobs lists it.
node_id: string;
The branch the request went to.
The signed-in user's catalog listing choice.
always_listed: boolean;
true for an Owner, whose books are always listed; listed then has no effect.
libraries: number;
Libraries this server is currently a branch of; the choice matters only above zero.
listed: boolean;
true (the default) unless the user keeps their books out of catalog answers.
One hit from /api/discover/search.
asin: string | null;
authors: string | null;
available_through?: BranchAvailability[];
Branches of this library that currently list this title.
cover_path?: string | null;
Same-origin path of this cover's processed images; see coverSrc.
cover_url?: string | null;
description?: string | null;
genres?: string | null;
is_abridged?: boolean | null;
isbn: string | null;
language?: string | null;
length_minutes?: number | null;
narrators: string | null;
price_cents?: number | null;
published_at?: string | null;
publisher?: string | null;
purchase_hints?: PurchaseHint[];
rating_count?: number | null;
rating_overall?: number | null;
series: string | null;
series_index?: string | null;
sources: string[];
store_editions: StoreEdition[];
subtitle?: string | null;
title: string;
work_key: string;
Cursor-paginated catalog search page.
has_more: boolean;
items: CatalogSearchHit[];
next_cursor?: string | null;
page_size: number;
sort: string;
sort_dir?: string;
One library node as GET /api/config/nodes returns it.
implicit_labels: string[];
Labels every node carries (node=<id>, target=<target>).
kind: "shared" | "branch";
shared (shares the database) or branch (its own database, enrolled to contribute).
labels: string[];
Operator labels.
live: boolean;
True while the node's daemon heartbeats.
node_id: string;
owner:
| {
display_name: string | null;
role: string;
user_id: number;
}
| null;
User who administers this node, when one is assigned.
relationship: BranchRelationship;
shared_branch (shares the database), remote_branch (a branch that
reports a public address) or local_branch (a branch with none).
runtime: NodeRuntimeView;
software_version?: string;
status: NodeStatusView | null;
Latest heartbeat; null when the node's daemon never ran.
target: string;
this_node: boolean;
True for the node serving this request.
One diagnostics report this install sent (GET /api/diagnostics/reports).
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: number | null;
When this install deleted the collector's stored copy, Unix milliseconds, or null.
report_id: string;
The collector's ID for the report; the GitHub issue filed for it mentions this ID.
sent_at_unix_ms: number;
When the collector accepted it, Unix milliseconds.
trigger: string;
Why it was sent: crash, error_burst, slow_burst, job_failed, cli_error, ….
version: string;
The Bookclerk version that sent it.
One logged event in a stored report.
fields: object[];
Redacted fields recorded with it.
name: string;
value: string;
level: "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE";
Severity.
message: string;
The redacted message.
target: string;
Where it was logged.
ts_unix_ms: number;
When it happened, Unix milliseconds, or 0 when unknown.
A report read back from the collector (GET /api/diagnostics/reports/{id}).
deleted_at_unix_ms: number | null;
When its stored copy was deleted, Unix milliseconds, or null.
fix:
| {
fixed_in: string | null;
pr_number: number | null;
pr_url: string | null;
}
| null;
The tracking issue's fix, or null.
issues: object[];
GitHub issues tracking it, the tracking issue first.
number: number;
state: "open" | "closed";
title: string;
url: string;
received_at_unix_ms: number;
When the collector received it, Unix milliseconds.
report:
| {
arch: string;
distro: string;
events: DiagnosticsReportEvent[];
os: string;
trigger: string;
version: string;
}
| null;
The stored report, or null once deleted.
{
arch: string;
distro: string;
events: DiagnosticsReportEvent[];
os: string;
trigger: string;
version: string;
}
arch: string;
CPU architecture.
distro: string;
Linux distribution, or empty.
events: DiagnosticsReportEvent[];
Events, oldest first.
os: string;
Operating system.
trigger: string;
Why it was sent.
version: string;
Version that sent it.
null
report_id: string;
The report's ID.
Discover recommendations feed payload.
computed_at?: string;
RFC 3339 time the stored shelves were ranked.
shelf_kinds?: ShelfKindInfo[];
shelves: DiscoverShelf[];
state?: DiscoverFeedState;
How current the stored shelves are: preparing (none stored yet),
refreshing (newer ones queued) or ready.
One Discover feed shelf (id, copy, items).
id: string;
items: Recommendation[];
subtitle: string | null;
title: string;
Stored state of the caller's Discover shelves (GET /api/discover/status).
candidates_fetched_at?: string | null;
feed_computed_at?: string | null;
ready: boolean;
scope?: string | null;
subject: string;
updating: boolean;
True while a fetch or ranking for the caller is waiting or running.
One edition of a work, with its listings.
abridgement: Abridgement;
Whether it is abridged.
acquire_status: AcquireStatus;
Its acquire state.
cover_path: string | null;
Same-origin path of its processed cover; see coverSrc.
duration_minutes: number | null;
Runtime in minutes, when known.
expression_id: string;
Its expression.
expression_kind: ExpressionKind;
How the expression renders the work.
id: string;
Edition id; acquire takes it in editions.
language: string | null;
Language code, when known.
listings: Listing[];
Store listings that sell it.
media_kind: MediaKind;
How it is consumed.
published_at: string | null;
Publication date (ISO-8601), when known.
subtitle: string | null;
Subtitle, when known.
title: string;
Edition title.
work_id: string;
The work it belongs to (an episode for a podcast's editions).
Operator delivery row from /api/events/deliveries.
attemptCount: number;
cancelRequested: boolean;
errorMessage: string | null;
eventId: string;
hasCheckpoint: boolean;
id: string;
invocationSequence: number;
leaseGeneration: number;
outcome: string | null;
pluginId: string;
resourceClass: string;
resumePending: boolean;
runAfter: string;
state: string;
updatedAt: string;
Durable domain-event delivery-queue counters from /api/status.
acked: number;
dead_letter: number;
dead_letters_total?: number;
dispatch_latency_ms_avg?: number | null;
handler_latency_ms_avg?: number | null;
oldest_pending_age_secs: number | null;
pending: number;
retries_total?: number;
running: number;
suspended: number;
suspensions_total?: number;
One value of a facet, from GET /api/library/works/facets/{facet}.
value: string;
The value, as WorksQuery.value takes it.
works: number;
How many held works have it.
A page of a facet's values and the cursor of the next one.
next_cursor?: string | null;
Pass as cursor for the next page; absent on the last.
values: FacetValue[];
The page's values, by their lower-cased spelling.
Aggregated global request-queue entry (shared wishlist demand).
asin: string | null;
authors: string | null;
cover_path?: string | null;
Same-origin path of this cover's processed images; see coverSrc.
cover_url?: string | null;
description?: string | null;
first_requested_at: string;
genres?: string | null;
isbn: string | null;
language?: string | null;
last_requested_at: string;
length_minutes?: number | null;
narrators?: string | null;
published_at?: string | null;
publisher?: string | null;
purchase_hints?: PurchaseHint[];
reasons?: string[];
sample_uuids: string[];
score?: number;
Final rank (taste_score + wish_count boost).
series?: string | null;
series_index?: string | null;
store_editions?: StoreEdition[];
subtitle?: string | null;
taste_score?: number;
title: string;
wish_count: number;
wishers?: QueueWisher[];
Distinct people who have this title on an open wishlist.
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: string;
One holding of a store listing.
added_at: string;
When the library first saw it (ISO-8601).
entitlement: Entitlement;
How it is held.
holder: Holder;
Who holds it.
id: string;
Holding id.
purchased_at: string | null;
When the store says it was bought (ISO-8601), when known.
Background job row from /api/jobs.
attempt_count?: number;
created_at?: string | null;
detail: string | null;
error_kind?: string | null;
finished_at?: string | null;
id: string;
kind: string;
max_attempts?: number;
progress?: string | null;
status: string;
One collection: a name and the storage key prefixes whose files belong to it.
name: string;
The name people see and scope rules match.
prefixes: string[];
Folders relative to a destination's root, each ending in /.
The library's collections.
collections: LibraryCollection[];
The collections, in the order shown.
GET /api/config/library-consents.
consents: RemoteConsentView[];
Every recorded owner plugin request, approved or not.
libraries: LibraryLinkView[];
Every library link this install holds, in any state.
A library this install is enrolled in as a host (no key material).
enrolled_at: string;
RFC 3339 time of the latest enrollment (a re-enrollment resets it).
include_branches?: boolean;
"Include books from my own branches" (on by default).
job_share?: number;
Jobs the library may have running here now; absent while its link is not running.
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?: boolean;
"Keep copies of other members' books" (off by default).
library_id: string;
Id of the library; one link per library.
list_members_books?: boolean;
"List my members' books" when the library asks (on by default).
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: string;
Node id the owner minted for this install.
owner_origin: string;
Canonical origin (https://host[:port]) this host dials the owner at.
pinned: boolean;
True when the link pins the owner's self-signed certificate.
share_books?: boolean;
"Share this branch's books with <library>" (on by default).
state: string;
active, revoked (by the owner), or left (by this host).
work_for_members?: boolean;
"Download for other members of <library>" (off by default).
GET /api/library-status: library health plus the nodes the caller may see.
capabilities: NodeCapabilities;
library: LibrarySummary;
node_id: string;
nodes: ConfigNodeView[];
Library-wide health from GET /api/library-status.
active_jobs: number;
branch_nodes: number;
cpu_budget_millicores: number;
cpu_reserved_millicores: number;
deliveries: object;
dead_letter: number;
oldest_pending_age_secs: number | null;
pending: number;
running: number;
drained: number;
live: number;
memory_budget_bytes: number;
memory_reserved_bytes: number;
nodes: number;
running_guests: number;
Linked portal identity (local or oidc:{id}).
external_user_id: string;
label: string | null;
provider: string;
Registered passkey row.
credential_id: string;
id: number;
name?: string | null;
Active auth session row visible to the current principal.
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?: string | null;
created_at: string;
device_type?: string | null;
elevated?: boolean;
expires_at: string;
id: number;
impersonating_user_id?: number | null;
is_current?: boolean;
kind: string;
last_used_at?: string | null;
user_agent?: string | null;
User row from GET /api/users (administrator settings).
avatar_source?: string | null;
auto, monogram, gravatar, upload, or sso:{id}.
controls?: MemberControls;
What the user may do here: the member controls that apply to them.
display_name: string | null;
email?: string | null;
gravatar_hash?: string | null;
SHA-256 hex of the contact email for Gravatar.
has_avatar?: boolean;
True when a profile picture file is stored for this user.
has_password: boolean;
id: number;
identities?: object[];
Linked login identities (local + OIDC).
external_user_id: string;
label: string | null;
provider: string;
integrations?: object[];
Linked storefront / integration accounts.
account_id: string;
label: string | null;
source: string;
last_active_at?: string | null;
Most recent unexpired portal session activity (RFC 3339). Active vs idle is ~5 minutes.
last_seen_at?: string | null;
Durable last portal use (RFC 3339); survives logout. Null means never signed in.
listening?:
| {
last_listened_at: string;
provider: string;
title: string | null;
}
| null;
Unfinished listen within ~30 minutes (waveform uses the last ~5 minutes).
login_name: string | null;
online?: boolean;
Non-expired portal session present (true even when idle).
role: string;
sso_pictures?: object[];
IdP-supplied pictures the user can pick.
identity_id: number;
last_used_at?: string | null;
picture_path?: string | null;
Same-origin 128 px copy of picture_url, when the server signed one.
picture_url: string;
provider: string;
status: string;
One store listing of an edition.
holdings: Holding[];
Who holds it.
id: string;
Listing id.
marketplace: string;
Marketplace code (us, uk, …).
plugin_key: string;
Storefront plugin (audible, libro, …).
product_id: string;
The store's product id (ASIN, ISBN, …).
url: string | null;
The listing's store page, when known.
What the caller may do on the nodes it was sent.
can_assign_owner: boolean;
can_edit_labels: boolean;
can_edit_runtime: boolean;
scope: "all" | "owned";
all for an operator; owned for a user who owns nodes.
A listing held by a branch library's node.
kind: "node";
Discriminant.
node_id: string;
The holding node's id.
A node's runtime document (node.runtime): its label, the share of its
detected capacity the scheduler may commit, and the drain switch.
cpu_budget_percent: number;
Share of detected CPU the scheduler may commit (1..=100).
label: string;
memory_budget_percent: number;
Share of detected memory the scheduler may commit (1..=100).
schedulable: boolean;
False drains the node: nothing new is placed there.
GET /api/config/nodes.
capabilities: NodeCapabilities;
node_id: string;
nodes: ConfigNodeView[];
A node's latest heartbeat (every 15 s while its daemon runs).
availability_ppm: number;
Recent online fraction in parts per million (decays over about a day).
cpu_budget_millicores: number;
cpu_millicores: number;
Detected CPU capacity in millicores.
cpu_used_millicores: number | null;
Measured CPU in use since the previous heartbeat.
files_dir_free_bytes: number | null;
heartbeat_at: string;
interval_ms: number;
memory_available_bytes: number | null;
Measured memory available to new work.
memory_budget_bytes: number | null;
memory_bytes: number | null;
Detected memory in bytes, when the node could read it.
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: object;
Sum of the running guests' jail ceilings.
cpu_millicores: number;
memory_bytes: number;
running_guests: number;
schedulable: boolean;
started_at: string;
Bookclerk-as-IdP OAuth client (secrets never listed after create/rotate).
allowed_scopes: string[];
client_id: string;
client_secret?: string | null;
Plaintext secret, returned only on create or rotate.
confidential: boolean;
enabled: boolean;
has_secret: boolean;
issue_refresh_token: boolean;
name?: string | null;
plugin_id?: string | null;
Set when a plugin owns this client (redirects are read-only).
redirect_uris: string[];
Body for creating or updating a Bookclerk-as-IdP client.
allowed_scopes: string[];
client_id?: string;
confidential: boolean;
enabled: boolean;
issue_refresh_token: boolean;
name?: string | null;
redirect_uris: string[];
Body for PUT /api/auth/oidc/config.
allowed_email_domains: string[];
enabled: boolean;
providers: OidcProviderConfigUpdate[];
public_origin?: string | null;
Omit to leave unchanged; empty string clears integrations.public_origin.
Owner/operator identity-broker settings payload.
allowed_email_domains: string[];
authorization_endpoint?: string;
callback_url?: string | null;
detected_origin?: string;
Origin detected from this request when it is a bound loopback listen address.
discovery_url?: string;
Absolute OpenID discovery URL.
enabled: boolean;
issuer_url?: string;
Effective issuer origin (public_origin, else bound loopback, else localhost).
providers: OidcProviderConfigView[];
public_origin?: string | null;
Configured integrations.public_origin (issuer / callback / invite base).
revocation_endpoint?: string;
token_endpoint?: string;
userinfo_endpoint?: string;
Enabled upstream OIDC/OAuth login providers.
id: string;
name: string;
preset?: string | null;
Built-in social preset (google, github, apple, discord) when set.
Provider fields accepted by PUT /api/auth/oidc/config.
allowed_email_domains: string[];
allowed_emails: string[];
allowed_subjects: string[];
apple_key_id?: string | null;
apple_private_key?: string;
apple_team_id?: string | null;
client_id: string;
client_secret?: string;
Omit to keep; empty string to clear; non-empty to store.
default_role: string;
id: string;
issuer?: string | null;
link_by_email: boolean;
name: string;
preset?: string | null;
provision: OidcProvisionMode;
role_claim: string;
role_map: Record<string, string>;
scopes: string[];
Owner/operator view of one [auth.oidc] provider (secrets redacted).
allowed_email_domains: string[];
allowed_emails: string[];
allowed_subjects: string[];
apple_key_id?: string | null;
apple_team_id?: string | null;
client_id: string;
default_role: string;
has_apple_private_key?: boolean;
has_client_secret: boolean;
id: string;
issuer?: string | null;
link_by_email: boolean;
name: string;
preset?: string | null;
provision: OidcProvisionMode;
role_claim: string;
role_map: Record<string, string>;
scopes: string[];
secret_source: OidcSecretSource;
One copy of a book: a format at a quality, as output.copies names it.
format: string;
m4b, mp3, mp3_chapters, opus (or original, which a convert refuses).
quality: string;
original, a bitrate such as 64k or 64k-mono, or an MP3 VBR level such as v2.
Which part of the library a patron sees.
explicit?: ExplicitContent;
Whether books a store or metadata file marks explicit are visible;
left out means allow.
rules: ScopeRule[];
Visibility rules; empty means every book is visible.
Branded display metadata for a plugin consent dialog.
accent?: string | null;
bg?: string | null;
fg?: string | null;
logo?: string | null;
name: string;
Host-capped consent limit defaults (workerd budgets + shared jail/disk).
Jail CPU fields are cores (2 d.p.) from the daemon — no percent conversion.
cpu_cores: number;
Manifest / default jail CPU in cores.
cpu_ms: number;
disk_mib: number;
extra_processes: number;
Default extra process/thread budget (native).
jail_cpu_cores?: number | null;
Optional Settings global jail CPU ceiling in cores.
known_bindings: string[];
max_cpu_cores: number;
Host max jail CPU in cores.
max_cpu_ms: number;
max_disk_mib: number;
max_extra_processes: number;
Host hard cap for extra process budget.
max_memory_mib: number;
max_subrequests: number;
memory_mib: number;
subrequests: number;
The difference between a plugin's request and its stored grant.
addressCidrs: string[];
CIDRs the request adds.
allowUndeclaredPublicRedirects: boolean;
Whether the request newly asks to follow undeclared public redirects.
domains: string[];
Fetch host patterns the request adds (* is any public host).
lines: string[];
Operator-facing lines naming every capability awaiting consent (the CLI prints the same).
tcp: object[];
TCP host:ports the request adds, narrowed to the new ports.
host: string;
ports: number[];
Network/capability consent status for a plugin.
brand?: PluginConsentBrand;
covered: boolean;
existing?: PluginGrant;
host_user_agent?: string;
The User-Agent the host sends, except to the request's ownUserAgentHosts.
limits: PluginConsentLimits;
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: string;
plugin_key?: string;
provenance?: string;
request: PluginGrant;
runtime: string;
Guest runtime: native or workerd.
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: string[];
This node's deployment of a plugin instance, with its latest observation.
applied_config_revision?: number;
deployment_id: string;
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?: string;
node_id: string;
observed_at?: string;
revision: number;
status?: string;
materialized, running, healthy, error, or retired when observed.
Plugin consent grant shape serialized by the daemon.
addressCidrs?: string[];
allowUndeclaredPublicRedirects?: boolean;
approvedAt: string;
authorityRevision?: string;
bindings: string[];
compatibilityFlags: string[];
consumers?: object[];
Approved event-consumer subscriptions (type + schemas + suspend + filter).
eventType: string;
filter?: string | null;
schemaVersions: number[];
supportsSuspend: boolean;
cpuCores?: number;
Jail CPU in cores (2 d.p.) from the daemon.
cpuMs?: number;
diskMib?: number;
domains: string[];
entrypoints: string[];
Exported entrypoints the operator approved (storefront, cli, …).
extraProcesses?: number;
Extra process/thread budget beyond launcher overhead (native).
jobs?: string[];
Approved [triggers].jobs types.
manifestDomains?: string[];
memoryMib?: number;
networkMode: string;
operatorAddedCidrs?: string[];
operatorAddedDomains?: string[];
operatorAddedTcp?: object[];
host: string;
ports: number[];
operatorDeniedCidrs?: string[];
operatorDeniedDomains?: string[];
operatorDeniedTcp?: object[];
host: string;
ports: number[];
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?: string;
The plugin's reason for ownUserAgentHosts, from plugin.toml.
pluginId: string;
pluginKey?: string;
producers: string[];
Event types the operator approved the plugin to publish.
subrequests?: number;
tcp?: object[];
host: string;
ports: number[];
Instance document as GET /api/config/plugin-instances/{id}/config returns it.
effective: Record<string, unknown>;
Schema defaults under the stored settings.
plugin_instance_id: string;
plugin_key: string;
revision: number;
secret_refs: object[];
Secret refs (names only).
key: string;
name: string;
settings: Record<string, InstanceSettingValue>;
Stored settings (operator writes only; defaults are not stored).
Body for PUT /api/config/plugin-instances/{id}/config.
expected_revision: number;
secret_refs: object[];
key: string;
name: string;
secrets?: Record<string, string>;
Secret values to seal; never echoed back.
settings: Record<string, InstanceSettingValue>;
Scheduler placement of a plugin instance: the operator's intent and the last scheduler pass's result.
constraints: string[];
Label constraints (nas, zone=eu, !slow, host=<id>).
detail: string;
Why fewer than requested are placed; empty when satisfied.
placed: number;
Replicas the last scheduler pass placed.
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: number;
Compare-and-swap revision of the intent.
scheduled_at: string;
updated_at: string;
Select option for a plugin setting.
label: string;
value: string;
One column of a table setting: the record field each row fills.
choices?: PluginSettingChoice[];
Dropdown values of an enum column.
default?: string;
String form of the value a new row starts with.
key: string;
Field name in each row object.
label: string;
Column heading.
required?: boolean;
True when every row must have a value in this column.
value_type: "string" | "number" | "boolean";
One network setting's destination on one plugin instance.
destination?: string;
scheme://host:port for a fetch, host:port for TCP; absent when unset or invalid.
error?: string;
Why the value names no destination, when state is invalid.
instanceId?: string;
The instance whose settings name it; absent while the plugin has no instance.
label: string;
The setting's label.
network: "fetch" | "tcp";
fetch (HTTP requests) or tcp (a raw socket).
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: string;
The setting key the grant is stored under.
state: "approved" | "pending" | "unset" | "invalid";
Approval state of the destination.
tls?: boolean;
True for an https fetch; false trusts the network's DNS answer.
A setting destination the operator approves, as the consent response shows it.
destination: string;
The destination exactly as PluginSettingDestination.destination shows it.
setting: string;
The setting key.
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.
choices?: PluginSettingChoice[];
columns?: PluginSettingColumn[];
Columns of a table setting, in display order.
key: string;
label: string;
secret?: boolean;
True for a secret setting; value is always empty.
secret_set?: boolean;
For a secret setting, whether a sealed value is stored for the instance.
value: string;
String form of the value; for a table setting, the rows as JSON text.
value_type: "string" | "number" | "boolean" | "table" | "secret";
Settings group for one plugin instance, or for a bootstrap database adapter.
config_revision?: number;
Instance document revision for compare-and-swap writes.
deployment?: PluginDeploymentView;
This node's deployment of the instance, when one exists.
display_name?: string;
Operator-facing instance name, when set.
family: string;
Handler family (source, integration, output, database).
id: string;
is_default?: boolean;
True when a bare plugin key or alias routes to this instance.
logo?: string;
Same-origin logo for Settings list rows (embedded, or a copy of the remote logo).
placement?: PluginPlacementView;
Scheduler placement; absent when the instance is managed by hand.
plugin_instance_id?: string;
Instance this group edits; absent for a config.toml-backed database adapter.
plugin_key?: string;
Provenance-qualified PluginKey when this row came from a discovered install.
present_on?: string[];
Nodes whose deployment of the instance is present.
provenance?: string;
Host-evaluated provenance (platform_bundled, verified_staged, installed, …).
settings: PluginSettingOption[];
storage_sync?: StorageSyncView;
How a storage destination follows outside changes; absent until its first sync pass.
Storefront brand colors and logo URL for Accounts UI.
accent: string;
bg: string;
fg: string;
logo: string;
Linked store account for the current portal user.
account_id: string;
brand?: PortalBrand;
connection_status: string;
label: string | null;
pace: PortalPace;
How fast Bookclerk downloads from this account when it starts the downloads itself.
plugin_key: string;
Provenance-qualified PluginKey that owns the account.
source: string;
source_enabled: boolean;
Linked portal identity attached to a user session.
external_user_id: string;
identity_id: number;
label: string | null;
provider: string;
Portal identity from /api/portal/me.
external_user_id: string;
label: string | null;
provider: string;
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.
cooldown_until: string | null;
End of the store's cool-down (RFC 3339), when one is running.
custom_downloads_per_day: number | null;
The custom daily budget, when mode is custom.
custom_min_gap_seconds: number | null;
The custom gap, when mode is custom.
downloads_last_day: number;
Downloads from this account in the last 24 hours.
downloads_per_day: number | null;
Downloads allowed in any rolling 24 hours; null for no daily budget.
min_gap_seconds: number;
Seconds between two downloads.
mode: PortalPaceMode;
default (the store's pace), custom or unlimited.
next_automatic_at: string | null;
When the next automatic download may start (RFC 3339); null for now.
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: number | null;
The store's declared gap; null when its plugin isn't deployed here.
Body of portalSetConnectionPace.
clear_cooldown?: boolean;
Also end a cool-down the store asked for.
downloads_per_day?: number;
Custom downloads per rolling 24 hours (1 to 10000); custom only.
min_gap_seconds?: number;
Custom seconds between downloads (0 to 86400); custom only.
mode?: PortalPaceMode;
default, custom or unlimited. Leave it out to only end the
cool-down (with clear_cooldown: true) and keep the stored pace.
Connectable storefront advertised by /api/portal/sources.
auth: string;
brand: PortalBrand;
id: string;
name: string;
Live or seeded storefront price / buy URL for a title.
currency?: string | null;
list_price_cents?: number | null;
list_price_label?: string | null;
member_price_cents?: number | null;
member_price_label?: string | null;
price_cents?: number | null;
price_label?: string | null;
product_id: string;
source: string;
title: string | null;
url: string | null;
Query used to resolve purchase hints for a title.
asin?: string | null;
authors?: string | null;
candidate_product_id?: string | null;
candidate_source?: string | null;
isbn?: string | null;
region?: string;
store_editions?: StoreEdition[];
title: string;
Purchase hint list plus optional best pick.
best: PurchaseHint | null;
hints: PurchaseHint[];
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.
Person who has a title on an open wishlist (global queue avatars).
avatar_source?: string | null;
Explicit picture choice (auto / monogram / gravatar / upload / sso:{id}).
display_name?: string | null;
Display name, identity label, or Operator.
gravatar_hash?: string | null;
SHA-256 hex of the contact email for Gravatar.
has_avatar?: boolean;
True when an uploaded avatar file exists.
identity_id?: number | null;
Portal identity that created the wish.
login_name?: string | null;
Local login name when set.
operator?: boolean;
True when the wish came from the operator token.
picture_path?: string | null;
Same-origin 128 px copy of picture_url, when the server signed one.
picture_url?: string | null;
HTTPS picture from the wishing identity, when any; never loaded directly.
user_id?: number | null;
First-party user id when the portal identity is linked.
Discover shelf recommendation item.
asin: string | null;
authors: string | null;
available_through?: BranchAvailability[];
Branches of this library that currently list this title.
candidate_product_id: string | null;
candidate_source: string | null;
categories?: string[];
Stable shelf-kind tags (finish_series, author, requests, …).
cover_path?: string | null;
Same-origin path of this cover's processed images; see coverSrc.
cover_url?: string | null;
description?: string | null;
from_request: boolean;
genres?: string | null;
isbn: string | null;
language?: string | null;
length_minutes?: number | null;
narrators: string | null;
published_at?: string | null;
publisher?: string | null;
purchase_hints: PurchaseHint[];
reasons: string[];
request_uuid: string | null;
score: number;
seed_categories?: string | null;
seed_title?: string | null;
Title of the book or wish the storefront was asked about to find this card.
series: string | null;
series_index: string | null;
starter_genre?: string | null;
Starter genre this card was browsed from while the taste was thin.
store_editions?: StoreEdition[];
subtitle?: string | null;
title: string;
wish_count?: number;
Distinct wisher count (may exceed wishers.length).
wishers?: QueueWisher[];
People who have this title on an open wishlist.
work_id: string | null;
work_key?: string;
Stable bibliographic key (isbn: / asin: / soft:…).
Body of an approval: the reviewed request and what of it to leave out. An approval can only narrow the request, never widen it.
deny_bindings?: string[];
Host bindings to remove (secrets, oauth, kv, …).
deny_domains?: string[];
Outbound domain patterns to remove from the grant.
deny_network?: boolean;
True turns outbound network off altogether (no domains, TCP or CIDRs).
deny_own_user_agent_hosts?: string[];
Requested hosts refused the plugin's own User-Agent; they get Bookclerk's agent.
library_id: string;
Library of the request.
plugin_key: string;
Plugin key of the request.
request_digest: string;
The request_digest reviewed; refused when the recorded request is another one.
One owner plugin's request to run on this host, and this host's answer.
approved_at: string | null;
RFC 3339 time of the approval, if approved.
approved_by: string | null;
Who approved: the operator's audit identity, or platform for an automatic approval.
approved_version: string | null;
Version this host approved, if any.
grant: RemoteGrantView | null;
What this host granted (the request, narrowed), if approved.
library_id: string;
Library that asks; matches a LibraryLinkView.library_id.
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: string;
Canonical plugin key the request is for.
request_digest: string;
Digest of the whole request (version, grant, archive); approve by it.
requested_artifact?: object;
The archive this host would fetch for that version (hex SHA-256 digests).
archive_sha256: string;
Digest of the archive file.
payload_root_sha256: string;
Digest of the unpacked payload tree.
url: string;
blob: (served by the owner) or https: archive URL.
requested_grant: RemoteGrantView | null;
What that version asks for; null when the stored request does not parse.
requested_version: string;
Version the owner now asks to run.
revoked_at?: string | null;
RFC 3339 time this host's operator revoked it; a revoke holds until approved again.
state: RemoteConsentState;
Whether the guest may run here now, or what it waits on.
updated_at?: string;
RFC 3339 time the row last changed.
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.
addressCidrs?: string[];
CIDR ranges beyond the public Internet (private or local addresses).
allowUndeclaredPublicRedirects?: boolean;
Follow a redirect to a public host it did not declare.
bindings?: string[];
Host bindings (config, secrets, kv, …).
compatibilityFlags?: string[];
workerd compatibility flags the isolate runs with.
consumers?: unknown[];
Events and queues it consumes (shape owned by the host).
cpuMs?: number | null;
workerd CPU budget per request, in milliseconds.
cpuRatePercent?: number | null;
CPU rate as a percent of one logical CPU (above 100 asks for more than one core).
diskMib?: number | null;
Disk budget in MiB for each of its data/ and tmp/ directories.
domains?: string[];
Outbound domain patterns the guest may dial first (redirect hops aside).
entrypoints?: string[];
Named entrypoints it exports (storefront, storage, cli, …).
extraProcesses?: number | null;
Processes or threads allowed beyond the launcher's own (native guests).
jobs?: string[];
[triggers].jobs types it may handle.
memoryMib?: number | null;
Memory ceiling in MiB.
networkMode?: string;
deny (no egress) or outbound; anything else is treated as deny.
ownUserAgentHosts?: string[] | null;
Hosts that receive the plugin's own User-Agent instead of the host's.
ownUserAgentReason?: string | null;
The plugin's reason for ownUserAgentHosts.
pluginId?: string;
Display alias from plugin.toml (not security authoritative).
producers?: string[];
Event types it may publish and queue bindings it may send to.
subrequests?: number | null;
workerd outbound fetch (subrequest) budget per request.
tcp?: object[];
Raw TCP destinations: a host and the ports allowed on it.
host: string;
ports: number[];
One rule of a patron scope.
effect: RuleEffect;
Include or exclude.
field: ScopeField;
The field the rule matches.
value: string;
One value of the field, compared without case.
Flat config map plus per-plugin setting groups.
effective?: Record<string, string>;
host_cpu_cores_max?: number;
Host max jail CPU in cores (2 d.p.; equals logical CPU count).
jail_cpu_cores?: number | null;
Optional global per-jail CPU ceiling in cores.
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: PluginSettingsGroup[];
settings: Record<string, string>;
One config key/value pair for PATCH /api/settings.
key: string;
value: string;
Shelf kind id/label for preference toggles.
id: string;
label: string;
Aggregate library counters from /api/status.
accounts: number;
acquired: number;
books: number;
error: number;
events?: EventQueueStatus;
in_progress: number;
listen: string;
pending: number;
storage_backend: string;
How a destination notices changes made outside Bookclerk: its change feed and its scheduled listings.
feed_checked_at?: string;
RFC 3339 time the feed was last read.
feed_error?: string;
The last feed failure.
feed_state: "off" | "healthy" | "gap" | "failing";
off (listings alone), healthy, gap (a listing runs at once) or failing.
listed_at?: string;
RFC 3339 time the last listing finished.
listing_error?: string;
Why the last listing failed or its removals were held back.
listing_in_progress: boolean;
True while a listing is in progress.
next_listing_at?: string;
RFC 3339 time the next scheduled listing is due.
objects: number;
Files the destination held after the last listing or feed page.
Storefront product identity for a catalog work.
product_id: string;
source: string;
Public Audnexus / Audible catalog fields for detail dialogs.
asin?: string | null;
authors?: string | null;
categories?: string | null;
cover_path?: string | null;
Same-origin path of this cover's processed images; see coverSrc.
cover_url?: string | null;
description?: string | null;
is_abridged?: boolean | null;
true abridged / false unabridged when the storefront said so.
isbn?: string | null;
language?: string | null;
length_minutes?: number | null;
narrators?: string | null;
published_at?: string | null;
publisher?: string | null;
rating_count?: number | null;
rating_overall?: number | null;
Audible community ratings (detail fetch only).
rating_performance?: number | null;
rating_story?: number | null;
review_count?: number | null;
reviews?: TitleReview[];
Prefer [fetchTitleReviews]. Title-meta no longer embeds reviews.
series?: string | null;
series_index?: string | null;
subtitle?: string | null;
title?: string | null;
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).
asin: string | null;
authors: string | null;
cover_path?: string | null;
Same-origin path of this cover's processed images; see coverSrc.
cover_url?: string | null;
created_at: string;
description?: string | null;
edition_id?: string | null;
Edition the wish named, when its identifiers reached exactly one.
genres?: string | null;
id: number;
identity_id: number | null;
isbn: string | null;
language?: string | null;
length_minutes?: number | null;
narrators?: string | null;
notes: string | null;
published_at?: string | null;
publisher?: string | null;
purchase_hints?: PurchaseHint[];
resolved_edition_id: string | null;
series?: string | null;
series_index?: string | null;
status: string;
store_editions?: StoreEdition[];
subtitle?: string | null;
title: string;
updated_at: string;
uuid: string;
work_id: string;
Library work the wish is for; every wish names one.
work_key: string;
Bibliographic key derived from the wish's identifiers, for display matching.
One Audible customer review for title detail.
author_name?: string | null;
body: string;
id?: string | null;
overall_rating?: number | null;
performance_rating?: number | null;
story_rating?: number | null;
submitted_at?: string | null;
title?: string | null;
An Administrator's switches as GET /api/users/{id}/admin-controls reports them.
applies: boolean;
True only for an Administrator; an Owner may always do everything.
defaults: AdminControls;
The library's default for every Administrator.
effective: AdminControls;
What applies to the user now (all off for anyone who isn't an Administrator or Owner).
overrides: AdminControlOverrides;
The switches set for this Administrator alone.
user_id: number;
The user.
A patron's member controls as GET /api/users/{id}/controls reports them.
applies: boolean;
False for an Owner, who may always do everything.
defaults: MemberControls;
The library's default for every patron.
effective: MemberControls;
What applies to the user now.
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: ControlOverrides;
The controls set for this patron alone.
user_id: number;
The user.
Created / patched user response from RBAC provisioning APIs.
claim_ticket?: string | null;
invite_url?: string | null;
Magic-link URL for /invite?ticket=… when an invite was minted.
ok: boolean;
user: ListedUser;
Per-user Discover / default-view preferences.
default_view: AppView;
disabled_shelves: string[];
discover_excluded_sources: string[];
Store ids hidden in Discover. Empty = all sources including future.
discover_language: string | null;
null / omitted = browser language; __all__ = no hard filter.
discover_sort: CatalogSearchSort;
discover_sort_dir: "desc" | "asc";
theme: ThemePreference;
Appearance: system follows the OS (fallback light); light / dark pin it.
A patron's scope as GET/PUT /api/users/{id}/scope report it.
applies: boolean;
False for an Owner or Administrator, who always see everything.
own: boolean;
True when the user has their own scope.
scope: PatronScope;
The scope that applies: their own, or the library default.
user_id: number;
The user.
One work from GET /api/library/works/{id}.
authors: string[];
Authors (or hosts).
can_edit_state?: boolean;
Whether the caller can keep their own state (false for the operator token).
description: string | null;
Description, when known (may contain light HTML).
editions: Edition[];
Its editions.
id: string;
Work id.
kind: WorkKind;
Book or podcast.
series: string | null;
Series name, when in one.
series_position: string | null;
Position within the series.
state?: WorkState | null;
The caller's own state; absent when they recorded none.
title: string;
Display title.
A page of works and the cursor of the next one.
next_cursor?: string | null;
Pass as cursor for the next page; absent on the last.
works: WorkSummary[];
The page's works.
Filters and paging for fetchWorks.
account?: string;
Only works held on this account id.
cursor?: string;
The previous page's next_cursor.
facet?: WorkFacet;
Only works with WorksQuery.value under this facet.
kind?: WorkKind;
Only books or only podcasts.
limit?: number;
Page size (the daemon caps it at 200).
media_kind?: MediaKind;
Only works with an edition of this media kind.
q?: string;
Search text; matches come best first and sort is ignored.
sort?: WorkSort;
Page order without q.
status?: AcquireStatus | "all";
Only works in this acquire state (all or omitted for every state).
value?: string;
The facet's value; an empty series value means works in no series.
The caller's own state for a work.
is_finished: boolean;
Whether they finished it.
rating_overall: number | null;
Overall rating (0–5).
rating_performance: number | null;
Performance rating (0–5).
rating_story: number | null;
Story rating (0–5).
tags: string | null;
Space-separated tags.
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.
is_finished?: boolean;
Whether they finished it.
rating_overall?: number | null;
Overall rating (0–5).
rating_performance?: number | null;
Performance rating (0–5).
rating_story?: number | null;
Story rating (0–5).
tags?: string | null;
Whitespace-separated tags (at most 32, each at most 64 bytes).
One work row from GET /api/library/works: a book or podcast once,
however many editions and accounts hold it.
acquire_status: AcquireStatus;
The work's acquire state, summed over its editions.
added_at: string;
When the newest holding was added (ISO-8601).
authors: string | null;
Authors (or hosts), comma-separated, when known.
cover_edition_id: string | null;
Edition whose cover the row shows.
cover_path: string | null;
Same-origin path of that cover's processed images; see coverSrc.
edition_count: number;
Editions of the work in the library.
holding_count: number;
Holdings of the work's listings.
id: string;
Work id; opens the detail at /api/library/works/{id}.
kind: WorkKind;
Book or podcast.
length_minutes?: number | null;
Runtime in minutes of the longest held edition, when known.
media_kinds: MediaKind[];
Media kinds the work's editions come in.
purchased_at?: string | null;
When the newest purchase a store reported happened (ISO-8601).
series: string | null;
Series name when the work is in one.
series_position: string | null;
Position within the series (text, so 1.5 keeps its spelling).
title: string;
Display title.
One library tag on a work.
source: WorkTagSource;
Set in Bookclerk (admin) or read from a sidecar file.
value: string;
The tag as written.
A work's library tags as GET /api/library/works/{id}/tags reports them.
tags: WorkTag[];
Every tag, by key.
work_id: string;
The work.
type Abridgement = "unknown" | "unabridged" | "abridged";
Whether an expression is abridged.
type AcquireStatus = "not_acquired" | "queued" | "downloading" | "acquired" | "error";
Pipeline acquire state for a library book row.
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.
type AdminControlOverrides = Partial<Record<AdminControl, boolean>>;
One Administrator's overrides; a missing switch follows the library's default.
type AdminControls = Record<AdminControl, boolean>;
A value for every Administrator switch (true = allowed).
type AdminSwitchChoice = "on" | "off" | "default";
What a change does to one of an Administrator's switches.
type AppView = "discover" | "library" | "accounts" | "wishlist" | "status" | "settings";
Primary authenticated SPA views mirrored in the URL path.
type AuthRole = "operator" | "owner" | "administrator" | "member";
Session role returned by the daemon auth APIs.
type BranchRelationship = "shared_branch" | "remote_branch" | "local_branch";
How a node relates to the library.
type CatalogSearchFilters = object;
Server-side include/exclude filters for catalog search.
authors?: string[];
exclude_narrators?: string[];
exclude_sources?: string[];
genres?: string[];
languages?: string[];
max_length_minutes?: number;
min_length_minutes?: number;
min_rating?: number;
narrators?: string[];
series?: string[];
sources?: string[];
type CatalogSearchSort =
| "relevance"
| "popularity"
| "rating"
| "title"
| "author"
| "price"
| "length";
Server-supported Discover catalog sort keys.
type CatalogSortDir = "asc" | "desc";
Ascending or descending catalog sort direction.
type ControlOverrides = Partial<Record<MemberControl, boolean>>;
One patron's overrides; a missing control follows the library's default.
type CoverSize = 128 | 360 | "full";
A processed cover size the daemon serves: thumbnail, card, or full size.
type DiscoverFeedState = "ready" | "refreshing" | "preparing";
How current a stored Discover feed is.
type Entitlement = "purchase" | "plus" | "loan" | "free";
How a holder came to hold a listing.
type ExplicitContent = "allow" | "hide";
Whether a patron sees books marked as explicit content.
type ExpressionKind = "text" | "narration" | "dramatisation" | "graphic" | "original_audio";
How an expression renders its work.
type Holder = AccountHolder | NodeHolder;
Who holds a listing: a store account, or a branch library's node.
type InstanceSettingValue = SettingCellValue | SettingRow[];
One value in a plugin instance document.
type MediaKind = "audio" | "ebook" | "print";
How an edition is consumed.
type MemberControl =
| "link_accounts"
| "download"
| "edit_metadata"
| "upload"
| "request_books"
| "see_prices";
One thing an administrator may allow or refuse a patron.
type MemberControls = Record<MemberControl, boolean>;
A value for every member control (true = allowed).
type OidcProvisionMode = "mapped_role" | "any" | "allowlist" | "invite_only";
How an upstream IdP decides who may become a first-party User.
type OidcSecretSource = "env" | "config" | "store" | "none";
Where a provider client secret is stored (never returned in plaintext).
type PortalPaceMode = "default" | "custom" | "unlimited";
How a store account's pace is set.
type RemoteConsentState =
| "consented"
| "awaiting_host_consent"
| "awaiting_host_reapproval"
| "invalid_grant";
Where an owner plugin's request to run here stands.
type RuleEffect = "include" | "exclude";
Whether a patron scope rule lets matching books in or keeps them out.
type ScopeField = "genre" | "series" | "author" | "narrator" | "tag" | "collection";
The book field a patron scope rule matches one value of.
type SettingCellValue = string | number | boolean;
One stored cell of a table setting row.
type SettingDestinationScope = "name" | "publicAddress" | "localAddress" | "restricted";
Where a setting's destination points, which decides how the grant reaches it.
type SettingRow = Record<string, SettingCellValue>;
One stored row of a table setting, keyed by column.
type TitleMetaQuery = object;
Query for public title metadata enrichment.
asin?: string | null;
authors?: string | null;
isbn?: string | null;
length_minutes?: number | null;
narrators?: string | null;
region?: string;
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: string;
type TitleReviewsPage = object;
One page of Audible customer reviews.
asin: string;
has_more: boolean;
page: number;
page_size: number;
reviews: TitleReview[];
sort_by?: string;
type TitleReviewsQuery = object;
Paginated title-reviews request body.
asin: string;
page?: number;
page_size?: number;
region?: string;
sort_by?: TitleReviewsSort;
type TitleReviewsSort = "MostHelpful" | "MostRecent";
Audible review sort modes for title detail.
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).
type WorkKind = "book" | "podcast";
What a work is: a book, or a podcast (its show).
type WorkSort = "title" | "author" | "series" | "purchased" | "added" | "length";
How /api/library/works orders a page (ignored while searching).
type WorkTagSource = "admin" | "sidecar";
Where a library tag came from.
const BEFORE_SIGN_OUT_WAIT_MS: 3000 = 3000;
How long a change of identity waits for the work registered with beforeSignOut, in milliseconds.
const endElevate: () => Promise<void> = endElevation;
Alias used by Settings RBAC controls.
Ends an elevated operator window on a user session.
Promise<void>
Resolves when elevation is cleared.
function ackEventDelivery(id): Promise<ActionResponse>;
Acknowledges a dead-lettered delivery (no further retry).
| Parameter | Type | Description |
|---|---|---|
id |
string |
Delivery id ({eventId}:{pluginId}). |
Promise<ActionResponse>
Action ack from the daemon.
function acquirableEditions(work): string[];
The editions of work an acquire should queue: those someone holds
that are not acquired or on their way.
| Parameter | Type | Description |
|---|---|---|
work |
WorkDetail |
A work's detail. |
string[]
Edition ids for triggerAcquire's editions.
function approveLibraryConsent(body): Promise<{
consent: RemoteConsentView;
}>;
Approves an owner plugin's request, optionally narrowed. Only what the request asks for can be approved.
| Parameter | Type | Description |
|---|---|---|
body |
RemoteApprovalBody |
The request reviewed and what to leave out. |
Promise<{
consent: RemoteConsentView;
}>
The consent row after approval.
function approvePluginConsent(
id,
grant?,
pluginKey?,
settingDestinations?
): Promise<PluginConsentResponse>;
Approves network consent for a plugin.
| 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. |
Promise<PluginConsentResponse>
Updated consent response after approval.
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.
Promise<AuthSession>
Anonymous session when the response is 401.
When the check fails or times out, which is not a sign-out.
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.
| 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). |
Promise<AuthSession | null>
The session, or null when stopped turned true first.
When the check fails in a way asking again cannot fix.
function availableThroughLabel(through): string | null;
One line naming the branches a title is available through.
| Parameter | Type | Description |
|---|---|---|
through |
BranchAvailability[] | undefined |
The title's branch availability. |
string | null
For example "Available through Riley's branch", or null when
no branch lists the title.
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.
| 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). |
Removes the task and after.
() => void
function bootstrapAdministrator(body): Promise<BootstrapAdministratorResponse>;
Creates the first Owner account when no owners (or legacy administrators) exist.
| 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 |
- |
Promise<BootstrapAdministratorResponse>
Bootstrap result including the one-time invite magic link.
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.
| Parameter | Type | Description |
|---|---|---|
through |
BranchAvailability[] | undefined |
The title's branch availability. |
object[]
For example [{ node_id, work_id, label: "Riley's branch" }].
function cancelEventDelivery(id): Promise<ActionResponse>;
Cancels a pending delivery or flags a running one.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Delivery id ({eventId}:{pluginId}). |
Promise<ActionResponse>
Action ack from the daemon.
function cancelJob(id): Promise<ActionResponse>;
Requests cancel of a pending job or cooperative stop of a running job.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Durable job id from /api/jobs. |
Promise<ActionResponse>
Action ack including the job id.
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.
| Parameter | Type | Description |
|---|---|---|
path |
string | null | undefined |
A cover_path from an API response. |
size |
CoverSize |
The size to load. |
string | null
The image URL, or null when there is no usable path.
function createOidcClient(body): Promise<OidcAsClient>;
Creates an OIDC client. Confidential clients return client_secret once.
| Parameter | Type | Description |
|---|---|---|
body |
OidcAsClientWrite |
Client id, redirects, token policy. |
Promise<OidcAsClient>
Created client; confidential clients include client_secret once.
function createUser(body): Promise<UserMutationResponse>;
Creates a first-party Bookclerk user.
| 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 |
- |
Promise<UserMutationResponse>
Created user plus optional one-time claim ticket.
function createWishlistItem(body): Promise<TitleRequest>;
Adds a title to the current user's wishlist.
| 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 |
- |
Promise<TitleRequest>
Created title-request row.
function deleteDiagnosticsReport(reportId): Promise<number>;
Deletes the collector's stored copy of a sent report; its summary and issue links stay (operator only).
| Parameter | Type | Description |
|---|---|---|
reportId |
string |
The report's ID. |
Promise<number>
When the copy was deleted, Unix milliseconds.
function deleteOidcClient(clientId): Promise<void>;
Deletes a registered OIDC client (operator or elevated Owner only).
| Parameter | Type | Description |
|---|---|---|
clientId |
string |
Client to remove. |
Promise<void>
Resolves when the client is removed.
function deletePasskey(id, currentPassword?): Promise<void>;
Delete a passkey owned by the current User.
| Parameter | Type | Description |
|---|---|---|
id |
number |
- |
currentPassword? |
string |
- |
Promise<void>
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.
| Parameter | Type | Description |
|---|---|---|
instanceId |
string |
Plugin instance id. |
Promise<{
deleted: boolean;
plugin_instance_id: string;
}>
Whether a placement was removed.
function deleteProfileAvatar(): Promise<void>;
Removes the signed-in user's stored profile picture.
Promise<void>
function deleteUser(id): Promise<{
ok: boolean;
}>;
Deletes a first-party user (operator / administrator provisioner).
| Parameter | Type | Description |
|---|---|---|
id |
number |
User id. |
Promise<{
ok: boolean;
}>
Ack payload.
function disableTotp(currentPassword?): Promise<void>;
Disables TOTP for the current user.
| Parameter | Type | Description |
|---|---|---|
currentPassword? |
string |
Required when the portal session is older than the reauth window. |
Promise<void>
Resolves when TOTP is disabled.
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).
| Parameter | Type | Description |
|---|---|---|
editionId |
string |
Edition id. |
string
Relative URL under /api/library/editions/.../cover.
function elevate(password): Promise<void>;
Temporarily elevates an Owner session after password re-authentication.
| Parameter | Type | Description |
|---|---|---|
password |
string |
The Owner's account password. |
Promise<void>
Resolves when elevation succeeds.
function endElevation(): Promise<void>;
Ends an elevated operator window on a user session.
Promise<void>
Resolves when elevation is cleared.
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).
Promise<CatalogListingView>
The choice, and how many libraries it applies to.
function fetchDiagnosticsReport(reportId): Promise<DiagnosticsReportLookup>;
Reads a sent report back from the collector with its access code (operator only).
| Parameter | Type | Description |
|---|---|---|
reportId |
string |
The report's ID. |
Promise<DiagnosticsReportLookup>
The report, its issues and its fix.
function fetchDiagnosticsReports(): Promise<DiagnosticsReport[]>;
Lists the diagnostics reports this install sent (operator only).
Promise<DiagnosticsReport[]>
Reports, newest first (the install keeps the last 200).
function fetchDiscoverFeed(): Promise<DiscoverFeed>;
Loads the caller's stored Discover shelves.
Promise<DiscoverFeed>
Discover feed payload; state says whether shelves are still being prepared.
function fetchEventDeliveries(state?): Promise<EventDeliveryInfo[]>;
Lists recent event deliveries for the Library strip.
| Parameter | Type | Description |
|---|---|---|
state? |
string |
Optional lifecycle filter (dead_letter, running, …). |
Promise<EventDeliveryInfo[]>
Delivery rows from /api/events/deliveries.
function fetchFacetValues(facet, cursor?): Promise<FacetValuesPage>;
Fetches one page of a facet's values across the library's held works.
| 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. |
Promise<FacetValuesPage>
The page and the next page's cursor.
function fetchInbox(options?): Promise<InboxPageView>;
Reads one page of the signed-in person's notification inbox.
| 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 |
- |
Promise<InboxPageView>
The page, malformed entries dropped.
function fetchJobs(): Promise<JobInfo[]>;
Lists recent background jobs for the jobs strip / status polling.
Promise<JobInfo[]>
Job rows from /api/jobs (newest first as returned by the daemon).
function fetchLibraryStatus(): Promise<LibraryStatusResponse>;
Library health every node administrator may see, with detail for the caller's visible nodes.
Promise<LibraryStatusResponse>
Library summary, visible nodes, and the caller's capabilities.
function fetchMfaPolicy(): Promise<{
require_second_factor: boolean;
}>;
Host-wide password second-factor policy (daemon.auth.require_second_factor).
Promise<{
require_second_factor: boolean;
}>
Whether password login requires a second factor.
function fetchOidcConfig(): Promise<OidcBrokerConfigView>;
Owner/operator identity-broker configuration (secrets redacted).
Promise<OidcBrokerConfigView>
Enabled flag, callback URL, and provider rows.
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.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Display alias from Settings. |
pluginKey? |
string |
Provenance-qualified PluginKey when the alias is ambiguous. |
Promise<PluginConsentResponse>
Current consent request payload and whether it already covers the ask.
function fetchPluginInstanceConfig(instanceId): Promise<PluginInstanceConfig>;
Reads a plugin instance's stored document.
| Parameter | Type | Description |
|---|---|---|
instanceId |
string |
Plugin instance id. |
Promise<PluginInstanceConfig>
Stored settings, secret refs, and the document revision.
function fetchPreferences(): Promise<UserPreferences>;
Loads the signed-in user's preferences.
Promise<UserPreferences>
Normalized UserPreferences.
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).
| Parameter | Type | Description |
|---|---|---|
body |
PurchaseHintsQuery |
Title identity and optional candidate edition. |
Promise<PurchaseHintsResponse>
Hints list plus optional best pick (client-cached).
function fetchRequestQueue(): Promise<GlobalQueueEntry[]>;
Loads the global request queue (shared demand).
Promise<GlobalQueueEntry[]>
Aggregated queue entries.
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.
| 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). |
Promise<Response>
The first response that is not such a 503, or the last 503.
function fetchSettings(): Promise<SettingsResponse>;
Loads operator settings groups and plugin option schemas for the Settings page.
Promise<SettingsResponse>
Core settings plus per-plugin option groups.
function fetchSigninMethods(): Promise<{
integrations: object[];
oidc: OidcProvider[];
operator_token: boolean;
require_second_factor: boolean;
}>;
Public sign-in picker (operator-token availability, SSO, integration logins).
Promise<{
integrations: object[];
oidc: OidcProvider[];
operator_token: boolean;
require_second_factor: boolean;
}>
Whether SPA operator-token login is offered, plus IdP and integration buttons.
function fetchStatus(): Promise<StatusResponse>;
Loads aggregate library status counters.
Promise<StatusResponse>
Status payload for the jobs strip / library header.
function fetchTitleMeta(body): Promise<TitleMeta | null>;
Fetches title metadata through a batch shared with every other card (see fetchPurchaseHints).
| Parameter | Type | Description |
|---|---|---|
body |
TitleMetaQuery |
Title identity fields. |
Promise<TitleMeta | null>
Metadata or null when none matched (client-cached).
function fetchTitleMetaBatch(queries): Promise<(TitleMeta | null)[]>;
Batch title-meta fetch (order preserved); shares the client TTL cache with singles.
| Parameter | Type | Description |
|---|---|---|
queries |
TitleMetaQuery[] |
Parallel title-meta queries. |
Promise<(TitleMeta | null)[]>
Metadata (or null) aligned with queries.
function fetchTitleReviews(body): Promise<TitleReviewsPage>;
Loads a page of Audible customer reviews for title detail infinite scroll.
| Parameter | Type | Description |
|---|---|---|
body |
TitleReviewsQuery |
ASIN, region, page, and sort. |
Promise<TitleReviewsPage>
Reviews page payload.
function fetchTotpStatus(): Promise<{
enabled: boolean;
}>;
Whether TOTP is confirmed for the current user.
Promise<{
enabled: boolean;
}>
{ enabled } for the signed-in user.
function fetchWishlist(): Promise<TitleRequest[]>;
Loads the current user's wishlist items.
Promise<TitleRequest[]>
Title-request rows.
function fetchWork(id): Promise<WorkDetail>;
Fetches one work with its editions, listings, holdings and own state.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Work id. |
Promise<WorkDetail>
The work.
function fetchWorks(query): Promise<WorksPage>;
Fetches one page of the library's works.
| Parameter | Type | Description |
|---|---|---|
query |
WorksQuery |
Filters, order and the cursor of the page to read. |
Promise<WorksPage>
The page and the next page's cursor.
function getCollections(): Promise<LibraryCollections>;
Reads the library's collections (operator, Owner or Administrator).
Promise<LibraryCollections>
The collections.
function getDefaultAdminControls(): Promise<{
controls: AdminControls;
}>;
Reads the library's default Administrator switches.
Promise<{
controls: AdminControls;
}>
The default.
function getDefaultControls(): Promise<{
controls: MemberControls;
}>;
Reads the library's default member controls.
Promise<{
controls: MemberControls;
}>
The default.
function getDefaultScope(): Promise<{
scope: PatronScope;
}>;
Reads the library's default patron scope.
Promise<{
scope: PatronScope;
}>
The default.
function getUserAdminControls(id): Promise<UserAdminControls>;
Reads what an Administrator may do.
| Parameter | Type | Description |
|---|---|---|
id |
number |
The user. |
Promise<UserAdminControls>
The default, the Administrator's overrides and what applies.
function getUserControls(id): Promise<UserControls>;
Reads what a patron may do.
| Parameter | Type | Description |
|---|---|---|
id |
number |
The user. |
Promise<UserControls>
The default, the patron's overrides and what applies.
function getUserScope(id): Promise<UserScope>;
Reads which part of the library a patron sees.
| Parameter | Type | Description |
|---|---|---|
id |
number |
The user. |
Promise<UserScope>
The scope that applies and where it comes from.
function getWorkTags(id): Promise<WorkTags>;
Reads a work's library tags (operator, Owner or Administrator).
| Parameter | Type | Description |
|---|---|---|
id |
string |
A top-level work. |
Promise<WorkTags>
The tags.
function isApiError(error): error is ApiError;
Narrows unknown to ApiError.
| Parameter | Type | Description |
|---|---|---|
error |
unknown |
Caught value from a failed API call. |
error is ApiError
Whether error is an ApiError instance.
function listConfigNodes(): Promise<NodesResponse>;
Lists the nodes the caller may see: every node for an operator, the owned ones for a node owner.
Promise<NodesResponse>
The serving node's id, the visible nodes, and what the caller may edit.
function listLibraryConsents(): Promise<LibraryConsentsResponse>;
Lists the libraries this host is enrolled in and what each asks to run here. Operator only.
Promise<LibraryConsentsResponse>
Links and consent rows.
function listOidcClients(): Promise<OidcAsClient[]>;
Lists Bookclerk-as-IdP clients (no plaintext secrets).
Promise<OidcAsClient[]>
Registered OAuth clients.
function listOidcIdentities(): Promise<LinkedIdentity[]>;
Linked login identities for the current User.
Promise<LinkedIdentity[]>
function listOidcProviders(): Promise<{
enabled: boolean;
providers: OidcProvider[];
}>;
Public list of SSO providers for the login page.
Promise<{
enabled: boolean;
providers: OidcProvider[];
}>
function listPasskeys(): Promise<ListedPasskey[]>;
Passkeys registered to the current User.
Promise<ListedPasskey[]>
function listSessions(): Promise<ListedSession[]>;
Lists sessions for the current principal.
Promise<ListedSession[]>
Active session rows.
function listUsers(): Promise<ListedUser[]>;
Lists users for administrator settings.
Promise<ListedUser[]>
User rows (empty array when none).
function login(token): Promise<AuthSession>;
Signs in with the operator token via POST /api/auth/login.
| Parameter | Type | Description |
|---|---|---|
token |
string |
Operator bearer token from bookclerk daemon token. |
Promise<AuthSession>
Authenticated operator session (acquire enabled).
function logout(): Promise<void>;
Clears the operator cookie session via POST /api/auth/logout.
Promise<void>
Resolves when the library answered that the sign-out is done.
When the library answers anything else.
function markInboxRead(notificationId): Promise<number>;
Marks one inbox entry read, or the whole inbox when no id is given.
| Parameter | Type | Description |
|---|---|---|
notificationId |
string | null |
The entry to mark, or null for all of them. |
Promise<number>
How many entries changed.
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.
| Parameter | Type | Description |
|---|---|---|
id |
number |
User id. |
Promise<{
claim_ticket: string;
invite_url?: string | null;
ok: boolean;
}>
One-time claim ticket.
function passkeyElevateBegin(): Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>;
Begin passkey Owner elevation.
Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>
function passkeyElevateFinish(body): Promise<void>;
Finish passkey Owner elevation.
| Parameter | Type | Description |
|---|---|---|
body |
{ challenge_id: string; credential: Record<string, unknown>; } |
- |
body.challenge_id |
string |
- |
body.credential |
Record<string, unknown> |
- |
Promise<void>
function passkeyLoginBegin(login): Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>;
Begin identifier-first passkey login.
| Parameter | Type | Description |
|---|---|---|
login |
string |
- |
Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>
function passkeyLoginFinish(body): Promise<void>;
Finish passkey login (sets the portal session cookie).
| Parameter | Type | Description |
|---|---|---|
body |
{ challenge_id: string; credential: Record<string, unknown>; } |
- |
body.challenge_id |
string |
- |
body.credential |
Record<string, unknown> |
- |
Promise<void>
function passkeyRegisterBegin(currentPassword?): Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>;
Begin WebAuthn registration (authenticated).
| Parameter | Type | Description |
|---|---|---|
currentPassword? |
string |
- |
Promise<{
challenge_id: string;
publicKey: Record<string, unknown>;
}>
function passkeyRegisterFinish(body): Promise<void>;
Finish WebAuthn registration.
| 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 |
- |
Promise<void>
function passwordLogin(login, password): Promise<{
mfa?: {
challenge_id: string;
method: string;
};
ok: boolean;
}>;
Signs in with username/password via POST /api/auth/password.
| Parameter | Type | Description |
|---|---|---|
login |
string |
Username or email. |
password |
string |
Account password. |
Promise<{
mfa?: {
challenge_id: string;
method: string;
};
ok: boolean;
}>
Session cookie on success, or an MFA challenge when TOTP is enabled.
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.
| Parameter | Type | Description |
|---|---|---|
changes |
Partial<AdminControls> |
The switches to change and their new values. |
Promise<{
controls: AdminControls;
}>
The default after the change.
function patchPreferences(body): Promise<UserPreferences>;
Partially updates the signed-in user's preferences.
| 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 |
- |
Promise<UserPreferences>
Updated preferences after save.
function patchProfile(body): Promise<{
ok: boolean;
user: AuthMeUser;
}>;
Updates the signed-in user's display name and/or email.
| 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 |
- |
Promise<{
ok: boolean;
user: AuthMeUser;
}>
Updated profile snapshot from the daemon.
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.
| 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[] |
- |
Promise<SettingsResponse>
The settings view after the write.
function patchUser(id, body): Promise<UserMutationResponse>;
Updates a first-party user role, status, or profile fields.
| 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 |
- |
Promise<UserMutationResponse>
Patched user row.
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.
| 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. |
Promise<UserAdminControls>
The switches after the change.
function portalConnections(): Promise<PortalConnection[]>;
Lists linked store accounts for the current portal user.
Promise<PortalConnection[]>
Connection rows.
function portalLoginIntegration(body): Promise<void>;
Signs in via an integration provider username/password.
| Parameter | Type | Description |
|---|---|---|
body |
{ password: string; provider: string; username: string; } |
Provider id plus credentials. |
body.password |
string |
- |
body.provider |
string |
- |
body.username |
string |
- |
Promise<void>
Resolves when the portal session is established.
function portalLogout(): Promise<void>;
Clears the portal / user session cookie.
Promise<void>
Resolves when logout finishes (best-effort).
function portalMe(): Promise<PortalMe>;
Loads the linked portal identity for the signed-in SPA session.
Promise<PortalMe>
Portal identity metadata used by Accounts / Settings headers.
function portalRedeem(ticket, password?): Promise<void>;
Redeems a claim ticket into a portal user session.
| Parameter | Type | Description |
|---|---|---|
ticket |
string |
One-time claim ticket string. |
password? |
string |
Optional password when claiming invite/reset tickets. |
Promise<void>
Resolves when the session cookie is set.
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.
| Parameter | Type | Description |
|---|---|---|
source |
string |
Source id or PluginKey from portalConnections. |
accountId |
string |
Portal connection account id from portalConnections. |
Promise<void>
Resolves when the revoke POST succeeds.
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.
| 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. |
Promise<PortalPace>
The account's pace as it now stands.
function portalSourceLogin(id, body): Promise<void>;
Password-connects a storefront account.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Source plugin id. |
body |
{ email: string; password: string; } |
Store email and password. |
body.email |
string |
- |
body.password |
string |
- |
Promise<void>
Resolves when the connection is stored.
function portalSourceOauthStart(id): Promise<{
url: string;
}>;
Starts OAuth for a storefront and returns the authorize URL.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Source plugin id. |
Promise<{
url: string;
}>
Object with browser url to open.
function portalSources(): Promise<PortalSource[]>;
Lists connectable storefronts for Accounts.
Promise<PortalSource[]>
Source descriptors including brand metadata.
function putCollections(collections): Promise<LibraryCollections>;
Replaces the library's collections; the Library is re-indexed after.
| Parameter | Type | Description |
|---|---|---|
collections |
LibraryCollections |
The new collections. |
Promise<LibraryCollections>
The collections as saved (names trimmed, prefixes ending in /).
function putDefaultControls(controls): Promise<{
controls: MemberControls;
}>;
Replaces the library's default member controls.
| Parameter | Type | Description |
|---|---|---|
controls |
MemberControls |
The new default. |
Promise<{
controls: MemberControls;
}>
The default after the change.
function putDefaultScope(scope): Promise<{
scope: PatronScope;
}>;
Replaces the library's default patron scope.
| Parameter | Type | Description |
|---|---|---|
scope |
PatronScope |
The new default. |
Promise<{
scope: PatronScope;
}>
The default after the change.
function putMfaPolicy(requireSecondFactor): Promise<{
require_second_factor: boolean;
}>;
Persists whether password login requires TOTP or a passkey (operator or elevated Owner only).
| Parameter | Type | Description |
|---|---|---|
requireSecondFactor |
boolean |
When true, password-only sign-in is not enough once enrolled. |
Promise<{
require_second_factor: boolean;
}>
Saved { require_second_factor } flag.
function putNodeLabels(nodeId, labels): Promise<unknown>;
Replaces a node's operator labels.
| Parameter | Type | Description |
|---|---|---|
nodeId |
string |
Node to edit. |
labels |
string[] |
The complete label set (nas, zone=eu). |
Promise<unknown>
The updated node.
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.
| Parameter | Type | Description |
|---|---|---|
nodeId |
string |
Node to assign. |
userId |
number | null |
Owning user, or null to clear. |
Promise<{
node_id: string;
owner_user_id: number | null;
}>
The node id and its owner.
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.
| Parameter | Type | Description |
|---|---|---|
nodeId |
string |
Node to edit. |
body |
Partial<NodeRuntimeView> |
Fields to change; omitted fields keep their value. |
Promise<{
node_id: string;
revision: number;
runtime: NodeRuntimeView;
}>
The stored runtime document.
function putOidcConfig(body): Promise<OidcBrokerConfigView>;
Replaces [auth.oidc] providers. Omit client_secret to keep the stored value.
| Parameter | Type | Description |
|---|---|---|
body |
OidcBrokerConfigUpdate |
Broker enablement and provider list. |
Promise<OidcBrokerConfigView>
Saved configuration with redacted secrets.
function putPluginDeployment(
instanceId,
nodeId,
desired,
expectedRevision?
): Promise<PluginDeploymentView>;
Sets whether a plugin instance should run on a host (the enable switch).
| 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. |
Promise<PluginDeploymentView>
The deployment row after the write.
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.
| Parameter | Type | Description |
|---|---|---|
instanceId |
string |
Plugin instance id. |
body |
PluginInstanceConfigWrite |
New document plus secrets to seal. |
Promise<{
plugin_instance_id: string;
revision: number;
}>
The committed revision.
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).
| 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" |
- |
Promise<{
placement: PluginPlacementView;
plugin_instance_id: string;
}>
The stored placement.
function putUserControls(id, overrides): Promise<UserControls>;
Sets the controls that differ for one patron; the rest follow the library's default.
| Parameter | Type | Description |
|---|---|---|
id |
number |
The user. |
overrides |
ControlOverrides |
The controls set for them alone ({} for none). |
Promise<UserControls>
The controls after the change.
function putUserScope(id, scope): Promise<UserScope>;
Gives a patron their own scope, or with null returns them to the
library's default.
| Parameter | Type | Description |
|---|---|---|
id |
number |
The user. |
scope |
PatronScope | null |
Their own scope, or null. |
Promise<UserScope>
The scope after the change.
function putWorkState(id, edit): Promise<WorkState>;
Changes the caller's own finished flag, ratings or tags for a work.
| Parameter | Type | Description |
|---|---|---|
id |
string |
The work. |
edit |
WorkStateEdit |
The fields to change. |
Promise<WorkState>
The caller's state after the change.
function putWorkTags(id, tags): Promise<WorkTags>;
Replaces the tags set in Bookclerk on a work; sidecar tags stay.
| Parameter | Type | Description |
|---|---|---|
id |
string |
A top-level work. |
tags |
string[] |
The tags to set ([] removes them). |
Promise<WorkTags>
The tags afterwards.
function removeWishlistItem(uuid): Promise<TitleRequest>;
Deletes a wishlist title-request owned by the current user.
| Parameter | Type | Description |
|---|---|---|
uuid |
string |
Wishlist title-request uuid from fetchWishlist. |
Promise<TitleRequest>
The removed title-request row as echoed by the API.
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.
Promise<DiscoverStatus>
The caller's Discover status once the fetch is queued.
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.
| Parameter | Type | Description |
|---|---|---|
workId |
string |
The title's work (BranchAvailability.work_id). |
nodeId |
string |
The branch to ask. |
Promise<BranchRequestQueued>
The queued request.
404 when the branch no longer lists the title.
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.
| Parameter | Type | Description |
|---|---|---|
id |
number |
User id. |
Promise<{
claim_ticket: string;
invite_url?: string | null;
ok: boolean;
revoked_sessions: number;
}>
Reset ticket plus count of revoked sessions.
function resumeEventDelivery(id): Promise<ActionResponse>;
Wakes a suspended delivery for the next worker claim.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Delivery id ({eventId}:{pluginId}). |
Promise<ActionResponse>
Action ack from the daemon.
function retryEventDelivery(id): Promise<ActionResponse>;
Re-queues a dead-lettered delivery.
| Parameter | Type | Description |
|---|---|---|
id |
string |
Delivery id ({eventId}:{pluginId}). |
Promise<ActionResponse>
Action ack from the daemon.
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.
| Parameter | Type | Description |
|---|---|---|
libraryId |
string |
Library. |
pluginKey |
string |
Canonical plugin key. |
Promise<{
consent: RemoteConsentView;
}>
The consent row after revoking.
function revokeSession(id): Promise<void>;
Revokes one session visible to the current principal.
| Parameter | Type | Description |
|---|---|---|
id |
number |
Session id. |
Promise<void>
Resolves when the revoke succeeds.
function rotateOidcClientSecret(clientId): Promise<OidcAsClient>;
Rotates a confidential client's secret (operator or elevated Owner only); plaintext is returned once.
| Parameter | Type | Description |
|---|---|---|
clientId |
string |
Confidential client to rotate. |
Promise<OidcAsClient>
Client row including the new plaintext secret once.
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.
| 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. |
Promise<SettingsResponse>
The settings view after the write.
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.
| 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 |
- |
Promise<CatalogSearchPage>
Cursor-paginated search page (or an empty stub when q is too short).
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).
| Parameter | Type | Description |
|---|---|---|
listed |
boolean |
false keeps the user's books out of catalog answers. |
Promise<CatalogListingView>
The stored choice.
function setPassword(body): Promise<{
ok: boolean;
revoked_sessions: number;
}>;
Sets a password for self or for a managed user.
| 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 |
- |
Promise<{
ok: boolean;
revoked_sessions: number;
}>
Count of revoked sessions.
function signOut(role?): Promise<void>;
Signs out regardless of operator vs user/portal session, after the work registered with beforeSignOut.
| Parameter | Type | Description |
|---|---|---|
role? |
AuthRole |
Current session role; portal roles use portal logout. |
Promise<void>
Resolves when logout completes.
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.
| Parameter | Type | Description |
|---|---|---|
userId |
number |
Target user id. |
Promise<void>
Resolves when impersonation is active.
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.
Promise<void>
Resolves when impersonation ends.
function storedEditions(work): string[];
The editions of work a convert can read from: the ones already stored.
| Parameter | Type | Description |
|---|---|---|
work |
WorkDetail |
The work's detail. |
string[]
Edition ids.
function totpEnrollBegin(currentPassword?): Promise<{
otpauth_url: string;
qr_svg: string;
secret: string;
}>;
Starts TOTP enrollment (pending secret, otpauth URL, QR SVG).
| Parameter | Type | Description |
|---|---|---|
currentPassword? |
string |
Required when the portal session is older than the reauth window. |
Promise<{
otpauth_url: string;
qr_svg: string;
secret: string;
}>
Pending secret, otpauth URL, and QR SVG.
function totpEnrollFinish(code): Promise<void>;
Confirms the pending TOTP secret with an authenticator code.
| Parameter | Type | Description |
|---|---|---|
code |
string |
Six-digit code from the authenticator app. |
Promise<void>
Resolves when enrollment is confirmed.
function totpLogin(challengeId, code): Promise<void>;
Completes password+TOTP login via POST /api/auth/totp/login.
| Parameter | Type | Description |
|---|---|---|
challengeId |
string |
Challenge from the password-login MFA payload. |
code |
string |
Six-digit authenticator code. |
Promise<void>
Resolves when the session cookie is set.
function triggerAcquire(body): Promise<ActionResponse>;
Queues an acquire: everything pending when the body names nothing, or the named editions or title.
| 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 |
- |
Promise<ActionResponse>
Action ack including job_id.
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.
| 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 |
- |
Promise<ActionResponse>
Action ack including job_id.
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.
Promise<ActionResponse>
Action ack including job_id when accepted.
function updateOidcClient(clientId, body): Promise<OidcAsClient>;
Updates an OIDC client without echoing a secret unless flipping to confidential.
| Parameter | Type | Description |
|---|---|---|
clientId |
string |
Existing client_id. |
body |
OidcAsClientWrite |
Redirects and token policy. |
Promise<OidcAsClient>
Updated client row (no plaintext secret unless flipping to confidential).
function uploadProfileAvatar(file): Promise<void>;
Uploads a JPEG/PNG/WebP profile picture for the signed-in user.
| Parameter | Type | Description |
|---|---|---|
file |
File |
Image selected from the file picker. |
Promise<void>
function userAvatarUrl(userId, cacheKey?): string;
Authenticated URL for a user's stored profile picture.
| Parameter | Type | Description |
|---|---|---|
userId |
number |
First-party users.id. |
cacheKey? |
number |
Optional cache-buster after upload. |
string
Path used by <img src>.
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.
| Parameter | Type | Description |
|---|---|---|
error |
unknown |
Caught failure from fetch / parse helpers. |
fallback |
string |
Copy used when the error has no safe user-facing text. |
string
Message suitable for inline SPA error banners.
Generated from ui/src/lib at main · View as Markdown