plugin
Host ↔ database adapter session returned by DatabaseAdapterEntrypoint.openSession.
RpcTarget
new AdapterDatabaseSession(): AdapterDatabaseSession;
RpcTarget.constructor
assertRestoreConstraints(): Promise<void>;
Re-check constraints after a unit restore; optional.
Promise<void>
Resolves when every constraint holds.
bootstrap(): Promise<DbBootstrap>;
Bootstrap-only diagnostic metadata (DbBootstrap); optional.
Promise<DbBootstrap>
Engine identity for diagnostics.
capabilities(): Promise<unknown>;
Typed SQL-contract advertisement.
Promise<unknown>
Guest DbCapabilities.
close(): Promise<void>;
Close the adapter session.
Promise<void>
Resolves when the session is closed.
dropUserRelations(_names): Promise<void>;
Drop the named user relations; optional.
| Parameter | Type | Description |
|---|---|---|
_names |
string[] |
Relation names from AdapterDatabaseSession.listUserRelations. |
Promise<void>
Resolves when the relations are gone.
execute(_request): Promise<ExecuteReply>;
Typed atomic batch (ExecuteRequest → ExecuteReply).
| Parameter | Type | Description |
|---|---|---|
_request |
ExecuteRequest |
Cap'n ExecuteRequest (structured Workers RPC object). |
Promise<ExecuteReply>
ExecuteReply.
executeStreamed(_request): Promise<Uint8Array<ArrayBufferLike>>;
The same atomic batch as AdapterDatabaseSession.execute, answered
as concatenated ExecuteStreamFrame messages counted against the
advertised maxStreamedResultBytes / maxStreamedResultRows; optional.
Adapters that advertise 0 for both leave the default, which answers
unsupported. An isolate adapter's frames travel inside one invoke
reply, so its streamed budget is clamped to MAX_SCALAR_BYTES (256 KiB)
and larger frames are a limit_exceeded (maxScalarBytes) error.
executeAdapterBatchStreamed runs the batch, stores the replay receipt
and checks that bound before it commits.
| Parameter | Type | Description |
|---|---|---|
_request |
AdapterExecuteRequest |
Proven statements plus isolation and receipt. |
Promise<Uint8Array<ArrayBufferLike>>
Every frame of the committed reply, concatenated.
exportIdentity(): Promise<IdentityHighWater[]>;
Identity high-water marks for a logical export; optional.
Promise<IdentityHighWater[]>
One row per identity column.
importIdentity(_rows): Promise<void>;
Restore identity high-water marks after a logical import; optional.
| Parameter | Type | Description |
|---|---|---|
_rows |
IdentityHighWater[] |
Rows from an earlier AdapterDatabaseSession.exportIdentity. |
Promise<void>
Resolves when the marks are applied.
listUserRelations(): Promise<string[]>;
Names of user relations the host may drop before a restore; optional.
Promise<string[]>
Relation names.
prepareUnitRestore(): Promise<void>;
Prepare the engine for a unit restore (disable constraints, …); optional.
Promise<void>
Resolves when the engine is ready for the restore.
ai entrypoint (AiModels): serves models to the host and, through the
AI binding, to every plugin with the grant. [ai].serves in
plugin.toml declares the tasks. The host checks every listing and every
reply, so a wrong vector count or length fails the run. Export it as
export class Ai extends AiEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env"></a> Env extends BookclerkEnv |
BookclerkEnv |
new AiEntrypoint<Env>(ctx, env): AiEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
AiEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<HealthOk>;
Reports whether the models can be loaded with the current settings.
Promise<HealthOk>
Health flag plus detail.
models(): Promise<AiModelList>;
Lists the models served now. Must be cheap: do not load a model here.
Change a model's revision whenever its weights, tokenizer or loaded
language packs change, because outputs are comparable only within one
revision.
Promise<AiModelList>
The served models, each modelId once.
run(_params): Promise<AiRunOk>;
Runs one model on one input. Throw not_found for a model this plugin
does not serve and invalid_params for an input of another task. For
text embeddings return one vector per text, in input order
(packEmbeddingVectors), with the model's listed dimensions and
revision.
| Parameter | Type | Description |
|---|---|---|
_params |
AiRunParams |
The plugin's own model id and the input. |
Promise<AiRunOk>
The output; leave model unset.
Default-export base. Optional trigger methods: BookclerkEntrypoint.event
and BookclerkEntrypoint.job; optional BookclerkEntrypoint.describe
(identity beyond plugin.toml), BookclerkEntrypoint.databaseMigrations,
and BookclerkEntrypoint.shutdown.
The bookclerk* methods are the adapter-facing dispatch surface; authors
neither call nor override them.
import { BookclerkEntrypoint, type EventBatch } from "@bookclerk/plugin-sdk/workerd";
import type { Env } from "./bookclerk-configuration.js";
export default class MyPlugin extends BookclerkEntrypoint<Env> {
async event(batch: EventBatch) {
for (const msg of batch.messages) {
await this.env.DB.prepare("INSERT INTO seen (id) VALUES (?)").bind(msg.id).run();
msg.ack();
}
}
}
WorkerEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-1"></a> Env extends BookclerkEnv |
BookclerkEnv |
new BookclerkEntrypoint<Env>(ctx, env): BookclerkEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
BookclerkEntrypoint<Env>
WorkerEntrypoint<Env>.constructor
readonly ctx: ExecutionContext;
WorkerEntrypoint.ctx
readonly env: Env;
WorkerEntrypoint.env
bookclerkDatabaseMigrations(binding): Promise<PluginMigration[]>;
Internal
Adapter dispatch for databaseMigrations(binding).
| Parameter | Type | Description |
|---|---|---|
binding |
string |
Binding name from [[databases]]. |
Promise<PluginMigration[]>
Bounded registration ([] when not implemented).
bookclerkDescribe(): Promise<Partial<PluginDescribe> | null>;
Internal
Adapter dispatch for describe().
Promise<Partial<PluginDescribe> | null>
Author refinement or null when not implemented.
bookclerkEvent(context, wireBatch): Promise<EventOutcome[]>;
Internal
Adapter dispatch for the event(batch) trigger.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wireBatch |
WireEventBatch |
Wire EventBatch. |
Promise<EventOutcome[]>
One outcome per event, in order.
bookclerkJob(
context,
invocation,
granted
): Promise<JobOutcomeRecord>;
Internal
Adapter dispatch for the job(controller) trigger.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
invocation |
Partial<JobInvocation> |
Durable command envelope. |
granted |
GrantedJobCapabilities |
Granted input / output / progress / cancel stubs. |
Promise<JobOutcomeRecord>
Wire job outcome.
bookclerkQueue(context, wireBatch): Promise<QueueOutcome[]>;
Internal
Adapter dispatch for the queue(batch) trigger.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wireBatch |
WireQueueBatch |
Wire QueueBatch. |
Promise<QueueOutcome[]>
One outcome per message, in order.
bookclerkScheduled(context, wire): Promise<void>;
Internal
Adapter dispatch for the scheduled(controller) trigger.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wire |
Partial<ScheduledController> |
Wire ScheduledController. |
Promise<void>
Resolves when the author's handler completes.
bookclerkShutdown(): Promise<void>;
Internal
Adapter dispatch for shutdown().
Promise<void>
Resolves when the author hook has run.
bookclerkSocketClosed(context, wire): Promise<void>;
Internal
Adapter dispatch for SocketHandler.closed. Without a
webSocketClose handler the close is acknowledged and ignored.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wire |
Partial<SocketClosed> |
Wire SocketClosed. |
Promise<void>
Resolves when the author's handler completes.
bookclerkSocketMessage(context, wire): Promise<SocketMessageOk>;
Internal
Adapter dispatch for SocketHandler.message.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wire |
Partial<SocketMessage> |
Wire SocketMessage. |
Promise<SocketMessageOk>
What the handler asks of the host (pollEvents).
bookclerkWebhookDelivered(context, wire): Promise<void>;
Internal
Adapter dispatch for WebhookHandler.delivered. Without a
webhookDelivered handler the call is acknowledged and ignored.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
wire |
Partial<WebhookDeliveredEvent> |
Wire WebhookDelivered. |
Promise<void>
Resolves when the author's handler completes.
databaseMigrations?(binding):
| PluginMigration[]
| Promise<PluginMigration[]>;
Complete ordered plugin-owned migration sequence for one named binding. The host calls this at binding initialization, before ordinary execute.
| Parameter | Type |
|---|---|
binding |
string |
| PluginMigration[]
| Promise<PluginMigration[]>
describe?():
| Partial<PluginDescribe>
| Promise<Partial<PluginDescribe>>;
Optional identity refinement merged over the manifest projection.
| Partial<PluginDescribe>
| Promise<Partial<PluginDescribe>>
event?(batch): void | Promise<void>;
[[events.consumers]] trigger: handle one delivered batch. Record an
outcome per message; untouched messages ack on return and retry on throw.
| Parameter | Type |
|---|---|
batch |
EventBatch |
void | Promise<void>
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
job?(job):
| void
| JobCompletion
| Promise<void | JobCompletion>;
[triggers] jobs trigger: run one durable job. Return to complete,
throw to reject, or call job.suspend() / job.retryLater().
| Parameter | Type |
|---|---|
job |
JobController |
| void
| JobCompletion
| Promise<void | JobCompletion>
queue?(batch): void | Promise<void>;
[[queues.consumers]] trigger: handle one delivered batch from one
queue. Record an outcome per message; untouched messages ack on return
and retry on throw.
| Parameter | Type |
|---|---|
batch |
QueueBatch |
void | Promise<void>
scheduled?(controller): void | Promise<void>;
[triggers] crons trigger, the Workers scheduled(controller): run one
cron fire. Return to complete; throw to have the host retry the same
fire (same scheduledTime and fireId) with backoff. Fires are
delivered at least once, so dedupe on controller.fireId.
| Parameter | Type |
|---|---|
controller |
Readonly<ScheduledController> |
void | Promise<void>
shutdown?(): void | Promise<void>;
Releases guest resources.
void | Promise<void>
webhookDelivered?(event): void | Promise<void>;
[[webhooks]] handler: the host stored requests for one webhook. Pull
them with env.WEBHOOKS.pull(event.name). The host coalesces calls, so
one call may stand for several requests; read until a pull comes back
empty. Without this handler the plugin reads requests on its own
schedule.
| Parameter | Type |
|---|---|
event |
WebhookDeliveredEvent |
void | Promise<void>
webSocketClose?(
ws,
code,
reason,
wasClean
): void | Promise<void>;
[sockets] handler, the Workers webSocketClose(ws, code, reason, wasClean): a host-brokered socket closed, by the server, the network,
or the host (1006 when the connection dropped or the host stopped the
socket's broker). The socket's id is never reused.
| Parameter | Type |
|---|---|
ws |
HostWebSocket |
code |
number |
reason |
string |
wasClean |
boolean |
void | Promise<void>
webSocketMessage?(ws, message):
| void
| Partial<SocketMessageOk>
| Promise<void | Partial<SocketMessageOk>>;
[sockets] handler, the Workers webSocketMessage(ws, message): one
message arrived on a host-brokered socket while the plugin may have been
asleep. ws carries the socket's id and its attachment as it was when
the message arrived. Throwing reports the failure to the host; the
socket stays open. Return { pollEvents: true } when the message
announced something pollEvents hands over (a new user), and the host
polls now instead of at its next scheduled poll.
| Parameter | Type |
|---|---|
ws |
HostWebSocket |
message |
SocketMessageData |
| void
| Partial<SocketMessageOk>
| Promise<void | Partial<SocketMessageOk>>
cli entrypoint (PluginCli): describe() → CliSchema,
invoke(params) → CliInvokeResult. Export it as
export class Cli extends CliEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-2"></a> Env extends BookclerkEnv |
BookclerkEnv |
new CliEntrypoint<Env>(ctx, env): CliEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
CliEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
describe(): Promise<CliSchema>;
Guest CLI schema.
Promise<CliSchema>
Declared commands ({ commands: [] } when the guest has no CLI).
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
invoke(_params): Promise<CliInvokeResult>;
Invokes a guest CLI command.
| Parameter | Type | Description |
|---|---|---|
_params |
CliInvokeParams |
Command name plus named argument values. |
Promise<CliInvokeResult>
Exit code, captured output, optional structured payload.
covers entrypoint (CoverFetcher): downloads cover images for the host.
The host passes a sink Destination; put the body for urls[i]
under the key String(i) and return one CoverImage per URL, in
request order. The host sniffs, decodes and re-encodes every body, so the
bytes stay untrusted. Export it as export class Covers extends CoverEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-3"></a> Env extends BookclerkEnv |
BookclerkEnv |
new CoverEntrypoint<Env>(ctx, env): CoverEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
CoverEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
fetchCovers(_params, _sink): Promise<CoverImage[]>;
Fetches each URL and streams its body into sink under its index.
| Parameter | Type | Description |
|---|---|---|
_params |
CoverFetchParams |
URLs (absolute https://) and the per-body byte cap. |
_sink |
Destination |
Host destination; accepts put for keys 0..urls.length. |
Promise<CoverImage[]>
One entry per URL, in request order.
health(): Promise<HealthOk>;
Reports whether the fetcher can answer.
Promise<HealthOk>
Health flag plus detail.
databaseAdapter entrypoint: opens typed SQL sessions for the host
library. Export it as export class DatabaseAdapter extends DatabaseAdapterEntrypoint.
The adapter isolate drives sessions through two dispatch verbs on
DatabaseAdapterEntrypoint.bookclerkInvoke: openSession returns a
fresh session id, and session(id, method, ...params) calls method on
the retained AdapterDatabaseSession; close releases the entry.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-4"></a> Env extends BookclerkEnv |
BookclerkEnv |
new DatabaseAdapterEntrypoint<Env>(ctx, env): DatabaseAdapterEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
DatabaseAdapterEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: openSession → session id; dropUnit; session → call
on a retained session (args = [id, method, ...params]).
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
openSession, dropUnit, or session. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Session id for openSession, else the session method result.
NamedEntrypoint.bookclerkInvoke
dropUnit(_unitRef): Promise<void>;
Physically drops one provisioned binding unit.
| Parameter | Type | Description |
|---|---|---|
_unitRef |
string |
Adapter-native unit identity. |
Promise<void>
Resolves when the unit is dropped.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
openSession(): Promise<AdapterDatabaseSession>;
Opens a session. Sessions cannot survive suspension.
Promise<AdapterDatabaseSession>
Adapter session capability.
Object store capability: job.output and the WORK_FS binding. The
runtime stub is the capability; abort is stream cancel.
RpcTarget
new Destination(): Destination;
RpcTarget.constructor
abortStage(_key, _commitToken): Promise<void>;
Abort a destination-side staged object.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_commitToken |
string |
Staging token to discard. |
Promise<void>
Rejects with typed unsupported unless overridden.
changes(_request): Promise<ChangesPage>;
Keys changed since a cursor (declare storage.changes).
| Parameter | Type | Description |
|---|---|---|
_request |
ChangesRequest |
Cursor and page size. |
Promise<ChangesPage>
One page of changes.
commit(_key, _commitToken): Promise<PutResult>;
Finalize a destination-side staged object.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_commitToken |
string |
Idempotency / commit token. |
Promise<PutResult>
Published object metadata.
copy(_from, _to): Promise<CopyResult>;
Server-side copy when the backend supports it.
| Parameter | Type | Description |
|---|---|---|
_from |
string |
Source key. |
_to |
string |
Destination key. |
Promise<CopyResult>
Bytes copied.
delete(_key): Promise<void>;
Delete a key (no-op if missing).
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
Promise<void>
Resolves when the delete is complete.
deleteMany(_keys): Promise<KeyOutcome[]>;
Remove up to MAX_BATCH_KEYS objects (declare storage.deleteMany).
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Object keys. |
Promise<KeyOutcome[]>
One outcome per key, in order; a missing key succeeds.
get(_key, _options?): Promise<ReadResult>;
Streamed read. The body is a transferred stream, not a scalar.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_options? |
ReadOptions |
Optional byte range. |
Promise<ReadResult>
Metadata plus a transferred body stream.
head(_key): Promise<ObjectMetadata | null>;
Metadata without a body; null when the key is missing.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
Promise<ObjectMetadata | null>
Metadata or null when the key is missing.
headMany(_keys): Promise<(ObjectMetadata | null)[]>;
Probe up to MAX_BATCH_KEYS objects (declare storage.headMany).
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Object keys. |
Promise<(ObjectMetadata | null)[]>
One entry per key, in order; null when missing.
list(_options): Promise<ListPage>;
One page of keys under options.prefix.
| Parameter | Type | Description |
|---|---|---|
_options |
ListOptions |
Prefix, cursor, and limit. |
Promise<ListPage>
One page of object keys.
move(
_from,
_to,
_options
): Promise<MoveResult>;
Move one object (declare storage.move). Repeating a finished move
resolves with alreadyMoved.
| Parameter | Type | Description |
|---|---|---|
_from |
string |
Source key. |
_to |
string |
Target key. |
_options |
MoveOptions |
Overwrite and source preconditions. |
Promise<MoveResult>
How the move was done.
moveMany(_request): Promise<MoveManyPage>;
Move a set of objects or a whole prefix, one page per call (declare
storage.moveMany). Safe to repeat.
| Parameter | Type | Description |
|---|---|---|
_request |
MoveManyRequest |
Pairs or prefix, cursor, and options. |
Promise<MoveManyPage>
Per-key outcomes and the continuation.
put(
_key,
_body,
_options?
): Promise<PutResult>;
Streamed write. body ownership is transferred to the destination.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_body |
ReadableStream<Uint8Array<ArrayBufferLike>> |
Byte stream. |
_options? |
WriteOptions |
Optional content type / length. |
Promise<PutResult>
Bytes written and optional etag / sha256.
translateKeys(_keys): Promise<string[]>;
Translate up to MAX_BATCH_KEYS host keys into the keys this
destination stores them under (declare storage.translateKeys). A host
key is /-joined segments, none empty, ., .. or holding `` or a
control character; return a relative key with the same properties. The
same host key must always translate to the same key. Without the
feature the host stores each host key as written.
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Host keys. |
Promise<string[]>
One translated key per host key, in order.
One event(batch) delivery (EventBatch struct), Workers MessageBatch-shaped.
new EventBatch(events, invocation?): EventBatch;
| Parameter | Type |
|---|---|
events |
| readonly Partial<DomainEvent>[] | undefined |
invocation? |
Invocation |
invocation: Invocation;
Invocation identity of this delivery.
readonly messages: readonly EventMessage[];
Messages in delivery order.
get type(): string;
Event type shared by the batch.
string
The shared type, or "" when mixed or empty.
ackAll(): void;
Ack every message.
void
retryAll(options?): void;
Retry every message.
| Parameter | Type | Description |
|---|---|---|
options? |
RetryOptions |
Redelivery timing and reason. |
void
One delivered domain event. Exactly one outcome is recorded per message;
the first of ack / retry / reject / deadLetter / suspend wins and
later calls are ignored (as with Workers queue messages). Messages left
untouched are acked when event() resolves and retried when it throws.
new EventMessage(event): EventMessage;
| Parameter | Type |
|---|---|
event |
Partial<DomainEvent> | undefined |
readonly accountId: string;
Account scope; empty for host-wide events.
readonly attempts: number;
Delivery counter, starting at 1.
readonly body: Uint8Array;
Encoded payload bytes.
readonly causationId: string;
Id of the command or event that caused this one.
readonly checkpoint: DeliveredCheckpoint | null;
Checkpoint from the prior suspend(), or null.
readonly correlationId: string;
Trace correlation id.
readonly deduplicationKey: string;
Consumer-side idempotency key; stable across redeliveries.
readonly id: string;
Outbox event id.
readonly invocationSequence: number;
Resume ordinal; distinct from attempts.
readonly raw: Partial<DomainEvent>;
Raw wire envelope.
readonly resumePending: boolean;
True when this delivery resumes a prior suspend().
readonly schemaVersion: number;
Schema version of EventMessage.body.
readonly source: string;
Producer plugin id; empty when unknown.
readonly timestamp: Date;
When the producer observed the fact.
readonly type: string;
Event type (book_acquired, …).
get result(): EventOutcome | null;
Recorded outcome.
EventOutcome | null
The outcome, or null while undecided.
ack(): void;
Mark handled; the host marks the event delivered.
void
deadLetter(reason?): void;
Park for operator review.
| Parameter | Type | Description |
|---|---|---|
reason? |
string |
Short operator-facing reason. |
void
json<T>(): T;
Decode EventMessage.body as JSON.
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-t"></a> T |
JsonObject |
T
Parsed payload ({} for an empty body).
reject(reason?): void;
Stop delivering; the host records reason.
| Parameter | Type | Description |
|---|---|---|
reason? |
string |
Short operator-facing reason. |
void
retry(options?): void;
Redeliver later: at retryAt, after delaySeconds, or — when both are
omitted — whenever the host's backoff chooses.
| Parameter | Type | Description |
|---|---|---|
options? |
RetryOptions |
Redelivery timing and reason. |
void
suspend(options?): void;
Release with a bounded checkpoint; the host redelivers at wakeAt or
when a wakeOnEventType event arrives.
| Parameter | Type | Description |
|---|---|---|
options? |
EventSuspendOptions |
Checkpoint and wake conditions. |
void
ingress entrypoint (Ingress): gives the library a public https
address. A relay plugin ([ingress] kind = "relay") receives requests from
its provider and hands each one to env.ORIGIN.fetch; the host starts at
most one ingress instance at a time. Export it as
export class Ingress extends IngressEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-5"></a> Env extends BookclerkEnv |
BookclerkEnv |
new IngressEntrypoint<Env>(ctx, env): IngressEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
IngressEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<IngressHealth>;
Reports whether the address is serving.
Promise<IngressHealth>
serving, plus a detail for the operator when it is not.
start(): Promise<IngressStarted>;
Brings the public address up and returns it once it serves.
Promise<IngressStarted>
The public origin: https:// and a host name, no port, path
or trailing slash.
stop(): Promise<void>;
Takes the public address down. The host stops sending requests after this returns.
Promise<void>
Resolves once the address no longer serves.
Everything one job invocation may touch: the durable envelope, input /
output streams, progress(), signal, and the terminal-outcome recorders
suspend() / retryLater(). Returning normally without a recorded outcome
completes the job; throwing rejects it (unavailable /
deadline_exceeded errors are retryable, cancelled is cancelled).
new JobController(invocation, granted?): JobController;
| Parameter | Type |
|---|---|
invocation |
Partial<JobInvocation> | undefined |
granted? |
GrantedJobCapabilities |
readonly attempt: number;
Failure retry counter, starting at 1.
readonly causationId: string;
Id of the event or command that caused this job.
readonly checkpoint: DeliveredCheckpoint | null;
Checkpoint from the prior suspend(), or null.
readonly correlationId: string;
Trace correlation id.
readonly deadlineUnixMs: number;
Deadline hint (Unix ms); the host fence is authoritative.
readonly id: string;
Unique id of this invocation attempt.
readonly idempotencyKey: string;
Caller idempotency key.
readonly input: Source | null;
Granted byte source, when the job has input.
readonly invocation: Readonly<Partial<JobInvocation>>;
Full durable envelope as delivered.
readonly invocationSequence: number;
Resume ordinal.
readonly output: Destination | null;
Granted object store, when the job has output.
readonly payloadJson: string;
Command payload JSON text.
readonly payloadSchemaVersion: number;
Schema version of JobController.payloadJson.
readonly signal: AbortSignal;
Aborts when the host cancels the invocation.
readonly stepId: string;
Step id within a multi-step command; empty when single-step.
readonly type: string;
Command type the handler dispatches on.
get result(): JobOutcomeRecord | null;
Recorded terminal outcome.
JobOutcomeRecord | null
The outcome, or null while the job is still running.
cancel(): void;
Host-side cancellation observed (adapter-internal).
void
json<T>(): T;
Decode JobController.payloadJson.
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-t-1"></a> T |
JsonObject |
T
Parsed payload ({} when empty).
progress(percent, message?): Promise<void>;
Report percent in 0..=100 with an operator-facing message.
| Parameter | Type | Description |
|---|---|---|
percent |
number |
Completion percent. |
message? |
string |
Operator-facing status. |
Promise<void>
Resolves when the host records progress.
retryLater(options?): void;
Give up this attempt and let the host retry at retryAt (or its default).
| Parameter | Type | Description |
|---|---|---|
options? |
JobRetryOptions |
Retry time and reason. |
void
suspend(options?): void;
Release with a bounded checkpoint; the host resumes at wakeAt.
| Parameter | Type | Description |
|---|---|---|
options? |
JobSuspendOptions |
Checkpoint and wake time. |
void
metadata entrypoint (MetadataProvider): bibliographic lookups against a
public catalog. Records describe editions; the host decides identity.
Export it as export class Metadata extends MetadataEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-6"></a> Env extends BookclerkEnv |
BookclerkEnv |
new MetadataEntrypoint<Env>(ctx, env): MetadataEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
MetadataEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
chapters(_params): Promise<MetadataChapters>;
Chapter layout of one edition.
| Parameter | Type | Description |
|---|---|---|
_params |
MetadataChaptersParams |
Identifiers of the edition. |
Promise<MetadataChapters>
The layout, or { found: false } when the provider has none.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<HealthOk>;
Reports whether the provider can answer.
Promise<HealthOk>
Health flag plus detail.
lookup(_params): Promise<MetadataRecord[]>;
Records for the editions the identifiers name.
| Parameter | Type | Description |
|---|---|---|
_params |
MetadataLookupParams |
Identifiers, marketplace and result cap. |
Promise<MetadataRecord[]>
Records in relevance order ([] when nothing matched).
search(_params): Promise<MetadataRecord[]>;
Records matching a title and, optionally, an author.
| Parameter | Type | Description |
|---|---|---|
_params |
MetadataSearchParams |
Title, author, language, marketplace and result cap. |
Promise<MetadataRecord[]>
Records in relevance order ([] when nothing matched).
metadataFiles entrypoint (MetadataFiles): reads and writes metadata
files (sidecars such as metadata.json, OPF, NFO or CUE) for the host. The
host reads every file, chooses every path and writes every result, so the
entrypoint only converts bytes. Each dialect is a
[[metadata_files.dialects]] row in plugin.toml; params.dialect names
the row. Export it as export class MetadataFiles extends MetadataFilesEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-7"></a> Env extends BookclerkEnv |
BookclerkEnv |
new MetadataFilesEntrypoint<Env>(ctx, env): MetadataFilesEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<HealthOk>;
Reports whether the dialects can answer.
Promise<HealthOk>
Health flag plus detail.
parse(_params): Promise<MetadataFileRecord>;
What one file says about its edition. List every field the file states
in present, including ones it states as empty; leave out fields it
does not mention. Throw invalid_params for a file the dialect cannot
read.
| Parameter | Type | Description |
|---|---|---|
_params |
MetadataFileParseParams |
Dialect id, file name and the whole file. |
Promise<MetadataFileRecord>
The parsed record.
render(_params): Promise<string | Uint8Array<ArrayBufferLike>>;
The new file: params.existing with each field in params.fields set to
the record's value (removed when the value is empty), everything else
kept as it was. existing is empty when the host creates the file.
| Parameter | Type | Description |
|---|---|---|
_params |
MetadataFileRenderParams |
Dialect id, values, fields to set and the current file. |
Promise<string | Uint8Array<ArrayBufferLike>>
The new file's bytes; a string is written as UTF-8.
Base for named entrypoints. Subclasses list their RPC surface on the static
bookclerkMethods; the adapter reaches them only through bookclerkInvoke,
which installs the granted bindings on env before dispatching.
WorkerEntrypoint<Env>
StorefrontEntrypointStorageEntrypointRemoteLibraryEntrypointDatabaseAdapterEntrypointCliEntrypointOidcEntrypointMetadataEntrypointCoverEntrypointMetadataFilesEntrypointAiEntrypointNotifierEntrypointIngressEntrypoint
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-8"></a> Env extends BookclerkEnv |
BookclerkEnv |
new NamedEntrypoint<Env>(ctx, env): NamedEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
NamedEntrypoint<Env>
WorkerEntrypoint<Env>.constructor
readonly ctx: ExecutionContext;
WorkerEntrypoint.ctx
readonly env: Env;
WorkerEntrypoint.env
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[] = [];
Methods the adapter may dispatch on this entrypoint.
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
notifier entrypoint (Notifier): delivers messages the host already
rendered to one outside service (a chat webhook, a mail relay, a paging
service). The host decides what to send and where; the entrypoint only
sends. [notifier] in plugin.toml declares the destination kinds,
formats and personal address fields. Export it as
export class Notifier extends NotifierEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-9"></a> Env extends BookclerkEnv |
BookclerkEnv |
new NotifierEntrypoint<Env>(ctx, env): NotifierEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
NotifierEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<HealthOk>;
Reports whether the service can be reached with the current settings.
Promise<HealthOk>
Health flag plus detail.
send(_params): Promise<NotifySent>;
Delivers one message to one destination. Throw rate_limited (with
details.retryAfterMs when the service says when) or unavailable for
a failure worth retrying; any other error fails this destination. Never
log params.message when sensitive is set, nor addressJson.
| Parameter | Type | Description |
|---|---|---|
_params |
NotifySendParams |
The rendered message and its destination. |
Promise<NotifySent>
The service's message id, when it gives one.
validateDestination(params): Promise<NotifyValidated>;
Checks and normalises a personal address a patron entered. Throw
invalid_params for an address the service would refuse. The default
accepts the address as given.
| Parameter | Type | Description |
|---|---|---|
params |
NotifyValidateParams |
The address document as entered. |
Promise<NotifyValidated>
The address to save and an optional label that is never a secret.
oidc entrypoint: relying-party client templates and credential
verification. Export it as export class Oidc extends OidcEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-10"></a> Env extends BookclerkEnv |
BookclerkEnv |
new OidcEntrypoint<Env>(ctx, env): OidcEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
OidcEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[];
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
authenticateUser(_params): Promise<ExternalUser>;
Verifies remote credentials on behalf of the host.
| Parameter | Type | Description |
|---|---|---|
_params |
AuthenticateUserParams |
Username / password pair. |
Promise<ExternalUser>
External user identity.
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
clients(): Promise<OidcClientTemplate[]>;
Plugin-provided OIDC authorization-server client templates. The host
materializes oidc_clients rows; plugins never mint tokens.
Promise<OidcClientTemplate[]>
Templates ([] when unused).
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
Progress reports for a job invocation (never carries media).
RpcTarget
new ProgressSink(): ProgressSink;
RpcTarget.constructor
report(_percent, _message): Promise<void>;
Reports percent in 0..=100 and an operator-facing message.
| Parameter | Type | Description |
|---|---|---|
_percent |
number |
Completion percent. |
_message |
string |
Operator-facing status. |
Promise<void>
Resolves when the host records progress.
One queue(batch) delivery (QueueBatch struct), Workers MessageBatch-shaped.
new QueueBatch(
queue,
messages,
invocation?
): QueueBatch;
| Parameter | Type |
|---|---|
queue |
string | undefined |
messages |
| readonly Partial<QueueMessage>[] | undefined |
invocation? |
Invocation |
invocation: Invocation;
Invocation identity of this delivery.
readonly messages: readonly QueueMessage[];
Messages in delivery order.
readonly queue: string;
Queue the messages were sent to.
ackAll(): void;
Ack every message.
void
retryAll(options?): void;
Retry every message.
| Parameter | Type | Description |
|---|---|---|
options? |
QueueRetryOptions |
Redelivery timing and reason. |
void
One delivered queue message (QueueMessage struct), Workers Message-shaped.
Exactly one outcome is recorded per message; the first of ack / retry
wins and later calls are ignored. Messages left untouched are acked when
queue() resolves and retried when it throws.
new QueueMessage(message): QueueMessage;
| Parameter | Type |
|---|---|
message |
Partial<QueueMessage> | undefined |
readonly attempts: number;
Delivery counter, starting at 1.
readonly body: Uint8Array;
Encoded body bytes.
readonly contentType: string;
Body encoding: json, text, or bytes.
readonly id: string;
Outbox row id; stable across redeliveries.
readonly raw: Partial<QueueMessage>;
Raw wire envelope.
readonly source: string;
Producer plugin id; empty when the host sent it.
readonly timestamp: Date;
When the producer sent the message.
get result(): QueueOutcome | null;
Recorded outcome.
QueueOutcome | null
The outcome, or null while undecided.
ack(): void;
Mark handled; the host marks the message delivered.
void
json<T>(): T;
Decode QueueMessage.body as JSON.
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-t-2"></a> T |
unknown |
T
Parsed body (null for an empty body).
retry(options?): void;
Redeliver later: after delaySeconds, or — when omitted — after the
consumer's retry_delay.
| Parameter | Type | Description |
|---|---|---|
options? |
QueueRetryOptions |
Redelivery timing and reason. |
void
text(): string;
Decode QueueMessage.body as UTF-8 text.
string
The body text.
remoteLibrary entrypoint: lifecycle, rescan, listening sync, and user
polling for a remote library server. Export it as
export class RemoteLibrary extends RemoteLibraryEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-11"></a> Env extends BookclerkEnv |
BookclerkEnv |
new RemoteLibraryEntrypoint<Env>(ctx, env): RemoteLibraryEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[] = REMOTE_LIBRARY_METHODS;
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
diagnose(): Promise<string[]>;
Operator-facing diagnostic lines.
Promise<string[]>
Probe lines.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
health(): Promise<HealthOk>;
Reports whether the remote library session is usable.
Promise<HealthOk>
Health flag plus detail.
pollEvents(): Promise<ExternalUser[]>;
Drains external users observed since the last poll.
Promise<ExternalUser[]>
Newly observed users.
scanLibrary(_params): Promise<void>;
Re-syncs the remote library.
| Parameter | Type | Description |
|---|---|---|
_params |
ScanLibraryParams |
Scan scope. |
Promise<void>
Resolves when the scan has been accepted.
start(): Promise<void>;
Starts long-running work for this invocation.
Promise<void>
Resolves when running.
stop(): Promise<void>;
Stops long-running work for this invocation.
Promise<void>
Resolves when stopped.
syncListening(): Promise<ListeningProgress[]>;
Push / pull listening progress; the host upserts the rows.
Promise<ListeningProgress[]>
Progress rows.
Byte source capability: job.input.
RpcTarget
new Source(): Source;
RpcTarget.constructor
open(_key): Promise<ReadResult>;
Opens key for streamed reading.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
Promise<ReadResult>
Metadata plus a transferred body stream.
storage entrypoint (Destination interface): an object store the host
writes acquired media into. Export it as
export class Storage extends StorageEntrypoint.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-12"></a> Env extends BookclerkEnv |
BookclerkEnv |
new StorageEntrypoint<Env>(ctx, env): StorageEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
StorageEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[] = STORAGE_METHODS;
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
abortStage(_key, _commitToken): Promise<void>;
Abort a destination-side staged object.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_commitToken |
string |
Staging token to discard. |
Promise<void>
Rejects with typed unsupported unless overridden.
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
changes(_request): Promise<ChangesPage>;
Keys changed since a cursor (declare storage.changes).
| Parameter | Type | Description |
|---|---|---|
_request |
ChangesRequest |
Cursor and page size. |
Promise<ChangesPage>
One page of changes.
commit(_key, _commitToken): Promise<PutResult>;
Finalize a destination-side staged object.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_commitToken |
string |
Idempotency / commit token. |
Promise<PutResult>
Published object metadata.
copy(_from, _to): Promise<CopyResult>;
Server-side copy when the backend supports it.
| Parameter | Type | Description |
|---|---|---|
_from |
string |
Source key. |
_to |
string |
Destination key. |
Promise<CopyResult>
Bytes copied.
delete(_key): Promise<void>;
Delete a key (no-op if missing).
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
Promise<void>
Resolves when the delete is complete.
deleteMany(_keys): Promise<KeyOutcome[]>;
Remove up to MAX_BATCH_KEYS objects (declare storage.deleteMany).
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Object keys. |
Promise<KeyOutcome[]>
One outcome per key, in order; a missing key succeeds.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
get(_key, _options?): Promise<ReadResult>;
Streamed read. The body is a transferred stream, not a scalar.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_options? |
ReadOptions |
Optional byte range. |
Promise<ReadResult>
Metadata plus a transferred body stream.
head(_key): Promise<ObjectMetadata | null>;
Metadata without a body; null when the key is missing.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
Promise<ObjectMetadata | null>
Metadata or null when the key is missing.
headMany(_keys): Promise<(ObjectMetadata | null)[]>;
Probe up to MAX_BATCH_KEYS objects (declare storage.headMany).
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Object keys. |
Promise<(ObjectMetadata | null)[]>
One entry per key, in order; null when missing.
list(_options): Promise<ListPage>;
One page of keys under options.prefix.
| Parameter | Type | Description |
|---|---|---|
_options |
ListOptions |
Prefix, cursor, and limit. |
Promise<ListPage>
One page of object keys.
move(
_from,
_to,
_options
): Promise<MoveResult>;
Move one object (declare storage.move). Repeating a finished move
resolves with alreadyMoved.
| Parameter | Type | Description |
|---|---|---|
_from |
string |
Source key. |
_to |
string |
Target key. |
_options |
MoveOptions |
Overwrite and source preconditions. |
Promise<MoveResult>
How the move was done.
moveMany(_request): Promise<MoveManyPage>;
Move a set of objects or a whole prefix, one page per call (declare
storage.moveMany). Safe to repeat.
| Parameter | Type | Description |
|---|---|---|
_request |
MoveManyRequest |
Pairs or prefix, cursor, and options. |
Promise<MoveManyPage>
Per-key outcomes and the continuation.
put(
_key,
_body,
_options?
): Promise<PutResult>;
Streamed write. body ownership is transferred to the destination.
| Parameter | Type | Description |
|---|---|---|
_key |
string |
Object key. |
_body |
ReadableStream<Uint8Array<ArrayBufferLike>> |
Byte stream. |
_options? |
WriteOptions |
Optional content type / length. |
Promise<PutResult>
Bytes written and optional etag / sha256.
translateKeys(_keys): Promise<string[]>;
Translate up to MAX_BATCH_KEYS host keys into the keys this
destination stores them under (declare storage.translateKeys). A host
key is /-joined segments, none empty, ., .. or holding `` or a
control character; return a relative key with the same properties. The
same host key must always translate to the same key. Without the
feature the host stores each host key as written.
| Parameter | Type | Description |
|---|---|---|
_keys |
string[] |
Host keys. |
Promise<string[]>
One translated key per host key, in order.
storefront entrypoint (ContentSource interface). Export it as
export class Storefront extends StorefrontEntrypoint. Every method takes
and returns the typed ABI structs generated from schema/plugin.capnp.
NamedEntrypoint<Env>
| Type Parameter | Default type |
|---|---|
<a id="type-parameter-env-13"></a> Env extends BookclerkEnv |
BookclerkEnv |
new StorefrontEntrypoint<Env>(ctx, env): StorefrontEntrypoint<Env>;
| Parameter | Type |
|---|---|
ctx |
ExecutionContext |
env |
Env |
StorefrontEntrypoint<Env>
readonly ctx: ExecutionContext;
readonly env: Env;
invocation: Invocation;
Invocation identity of the current call (set by bookclerkInvoke).
static bookclerkMethods: readonly string[] = STOREFRONT_METHODS;
Methods the adapter may dispatch on this entrypoint.
NamedEntrypoint.bookclerkMethods
bookclerkInvoke(
context,
method,
...args
): Promise<unknown>;
Internal
Adapter dispatch: install granted bindings, then call method.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext |
Granted bindings for this invocation. |
method |
string |
Method name from the static allowlist. |
...args |
unknown[] |
Method arguments. |
Promise<unknown>
Method result.
NamedEntrypoint.bookclerkInvoke
catalogDetail(_params): Promise<CatalogHit | null>;
Full catalog record for one product; null when unknown.
| Parameter | Type | Description |
|---|---|---|
_params |
CatalogDetailParams |
Product identifiers. |
Promise<CatalogHit | null>
Catalog hit or null.
diagnose(): Promise<string[]>;
Operator-facing diagnostic lines.
Promise<string[]>
Probe lines.
expandCandidates(_params): Promise<CatalogHit[]>;
Related-title expansion from a seed title.
| Parameter | Type | Description |
|---|---|---|
_params |
ExpandCandidatesParams |
Seed title plus limits. |
Promise<CatalogHit[]>
Candidate hits.
fetch(_request?): Promise<Response>;
Rejects HTTP fetch — workerd guests are Workers-RPC only.
| Parameter | Type | Description |
|---|---|---|
_request? |
Request |
Incoming HTTP request when the entrypoint is fetch-facing. |
Promise<Response>
Always a 404 empty response.
fetchTitle(_params): Promise<PlainFetch>;
Fetches one title into params.cacheDir and returns plain media paths.
| Parameter | Type | Description |
|---|---|---|
_params |
FetchTitleParams |
Title identifiers, credentials, fetch options. |
Promise<PlainFetch>
Plain media parts plus metadata.
health(): Promise<HealthOk>;
Reports whether the storefront session is usable.
Promise<HealthOk>
Health flag plus detail.
listAccounts(): Promise<SourceAccount[]>;
Accounts the guest knows about.
Promise<SourceAccount[]>
Account list.
listDeals(_params): Promise<CatalogHit[]>;
Current storefront deals.
| Parameter | Type | Description |
|---|---|---|
_params |
ListDealsParams |
Optional filters. |
Promise<CatalogHit[]>
Deal hits.
login(_params): Promise<LoginResult>;
Password or one-shot OAuth login. The host seals
LoginResult.credentials into encrypted_secrets.
| Parameter | Type | Description |
|---|---|---|
_params |
LoginParams |
Login parameters. |
Promise<LoginResult>
Account identity plus opaque credentials.
loginComplete(_params): Promise<LoginResult>;
Finishes a login started by StorefrontEntrypoint.loginStart.
| Parameter | Type | Description |
|---|---|---|
_params |
LoginCompleteParams |
Continuation plus user input. |
Promise<LoginResult>
Account identity plus opaque credentials.
loginStart(_params): Promise<LoginStartResult>;
Begins an interactive OAuth login.
| Parameter | Type | Description |
|---|---|---|
_params |
LoginParams |
Login parameters. |
Promise<LoginStartResult>
Continuation for StorefrontEntrypoint.loginComplete.
purchaseHint(_params): Promise<
| PurchaseHint
| PurchaseHintAnswer
| null>;
Purchase link / price hint; null when the title is unknown.
params.lookup says how the host names the title: "isbn" or
"asin" (sent only when describe().catalog declares priceByIsbn /
priceByAsin) want that exact edition or null, never a title match;
"product" names the store's own product; "title" asks for a search
by title and authors, answered best with a PurchaseHintAnswer
listing every priced result; "unspecified" (older hosts) leaves the
choice to the store.
| Parameter | Type | Description |
|---|---|---|
_params |
PurchaseHintParams |
Title identifiers and how to look the title up. |
Promise<
| PurchaseHint
| PurchaseHintAnswer
| null>
Hint, an answer with title-search records, or null.
purchaseHints(params): Promise<(
| PurchaseHint
| PurchaseHintAnswer
| null)[]>;
Purchase links / price hints for several titles in one call, one
answer per query in order. The default asks purchaseHint for
each query, PURCHASE_HINTS_CONCURRENCY at a time, those with a
product id first, and stops starting lookups after
PURCHASE_HINTS_BUDGET_MS; a store whose catalog prices
many products per request overrides this to make one request. Reject with a
rate_limited PluginError (its details.retryAfterMs says how
long) when the store asks to slow down, so the host leaves it alone.
| Parameter | Type | Description |
|---|---|---|
params |
PurchaseHintsParams |
The titles to price, in order. |
Promise<(
| PurchaseHint
| PurchaseHintAnswer
| null)[]>
One hint, answer with records, or null per query.
qualityOffers(_params): Promise<QualityOffersResult>;
The audio quality one account would download for each title today, one
answer per title id in order (found: false when the store cannot
say). It must not license or download anything. The host asks only a
store that declares catalog.qualityOffers in describe(); the
default rejects as unsupported.
| Parameter | Type | Description |
|---|---|---|
_params |
QualityOffersParams |
Account, its credentials, settings and title ids. |
Promise<QualityOffersResult>
One answer per title, plus any refreshed credentials.
revokeAccount(_params): Promise<void>;
Undo store-side state for one account before the host deletes its credentials, such as deregistering the device registered at login. Best effort: the host revokes the account whatever this returns. The default does nothing.
| Parameter | Type | Description |
|---|---|---|
_params |
RevokeAccountParams |
Account id and its stored credentials. |
Promise<void>
Resolves when the store sign-out finished.
scan(_params): Promise<ScanPage>;
One page of one account's library scan.
The host calls this repeatedly, passing back nextCursor as
params.cursor until a page returns an empty nextCursor, which ends
the pass. An empty params.syncToken asks for a full pass; a non-empty
one asks only for changes since that token (list gone titles in
removed). Set complete only on the last page of a full pass that
listed the whole library. Only the last page's syncToken is stored. Reject a stale cursor or token with invalid_cursor and the
host restarts as a full pass.
| Parameter | Type | Description |
|---|---|---|
_params |
ScanParams |
The account, its credential, the cursor and the sync token. |
Promise<ScanPage>
At most MAX_SCAN_PAGE_BOOKS books plus the paging fields.
searchCatalog(_params): Promise<CatalogHit[]>;
Free-text storefront catalog search.
| Parameter | Type | Description |
|---|---|---|
_params |
SearchCatalogParams |
Query parameters. |
Promise<CatalogHit[]>
Catalog hits.
Trusted adapter env. Authors never see this type on their class.
BRIDGE_TOKEN?: string;
Isolate-to-host bridge bearer.
GRANTED?: GrantedFetcher;
Per-invocation grant reverse channel.
PLUGIN?: AuthorStub;
Author default entrypoint.
PLUGIN_CLI?: NamedStub;
PLUGIN_DATABASE_ADAPTER?: NamedStub;
PLUGIN_DESCRIBE?: string | PluginDescribe;
Manifest PluginDescribe projection (JSON binding).
PLUGIN_OIDC?: NamedStub;
PLUGIN_REMOTE_LIBRARY?: NamedStub;
PLUGIN_STORAGE?: NamedStub;
PLUGIN_STOREFRONT?: NamedStub;
Named author entrypoints (PLUGIN_STOREFRONT, PLUGIN_STORAGE, …).
Context as the launcher sends it on the bridge: GrantedContext
plus the grant tokens the adapter exchanges for the author's EVENTS and
env.<BINDING> stubs. Authors never receive this shape.
Omit<GrantedContext,"databases"|"queues"|"kv"|"sockets"|"origin">
ai?: AiBinding;
AI binding, when [ai].calls is declared and granted.
aiToken?: string;
Granted-channel bearer for env.AI.run; stripped before dispatch.
config?: ExtensibleConfig;
Operator settings for this plugin as application/json.
databases?: Record<string, string>;
Named [[databases]] binding → database-only bearer for /db/execute.
events?: EventPublisherBinding;
EVENTS publisher, when [[events.producers]] is granted.
eventsToken?: string;
Granted-channel bearer for env.EVENTS.publish; stripped before dispatch.
invocation?: Partial<Invocation>;
Invocation identity (Invocation struct).
kv?: Record<string, string>;
[[kv_namespaces]] binding → kv-only bearer for /kv/*.
network?: NetworkGrant;
The network grant in effect, handed to the author as env.NETWORK.
notify?: NotifyBinding;
NOTIFY binding, when [[notifications.types]] is declared.
notifyToken?: string;
Granted-channel bearer for env.NOTIFY.raise; stripped before dispatch.
originToken?: string;
Origin-only bearer for /origin/fetch; stripped before dispatch.
queues?: Record<string, string>;
[[queues.producers]] binding → queue-only bearer for /queues/send.
secrets?: ExtensibleConfig;
Granted secret values as application/json.
sockets?: Record<string, string>;
[sockets] binding → sockets-only bearer for /sockets/*.
storage?: Destination;
WORK_FS object store, when granted.
webhooks?: WebhooksTransport;
The WEBHOOKS grant, when [[webhooks]] is declared.
webhooksToken?: string;
Webhooks-only bearer for /webhooks/*; stripped before dispatch.
Optional byte range for a streamed read.
length?: number;
offset: number;
Host cancellation watch delivered to a job controller (adapter-internal).
wait(): Promise<void>;
Resolves once the host cancels the invocation.
Promise<void>
One page of StorageEntrypoint.changes.
changes: ObjectChange[];
complete: boolean;
False when the feed may have missed changes (overflow, expired retention); the host then backs it with a full listing.
cursor: string;
Cursor for the next call; never empty.
more?: boolean;
True when more changes are ready now.
Argument of StorageEntrypoint.changes.
cursor?: string;
The previous page's cursor; absent asks for the current position.
limit?: number;
Requested changes per page (at most MAX_CHANGES_PAGE).
Result of a server-side copy.
bytesCopied: number;
A prior checkpoint delivered on resume.
json: string;
Checkpoint JSON text as recorded by the earlier suspend().
schemaVersion: number;
Schema version the author attached to the checkpoint.
Options for EventMessage.suspend.
checkpoint?: Checkpoint;
Bounded checkpoint replayed on resume (at most maxCheckpointBytes).
checkpointSchemaVersion?: number;
Schema version of checkpoint (default 1).
wakeAt?: Instant;
Earliest resume instant.
wakeOnEventType?: string;
Also wake when an event of this type arrives.
wakeOnFilter?: string | JsonObject;
Host-owned payload filter for wake events (object or JSON text).
Granted Bindings for one invocation as the bridge routes carry them:
the context body field / x-bookclerk-context header decoded from
PluginWorker.open(invocation, bindings). The adapter merges it onto the
author's env before dispatching; authors never receive it directly.
ai?: AiBinding;
AI binding, when [ai].calls is declared and granted.
config?: ExtensibleConfig;
Operator settings for this plugin as application/json.
databases?: NamedDatabase[];
Named [[databases]] bindings.
events?: EventPublisherBinding;
EVENTS publisher, when [[events.producers]] is granted.
invocation?: Partial<Invocation>;
Invocation identity (Invocation struct).
kv?: NamedKv[];
[[kv_namespaces]] bindings, when granted.
network?: NetworkGrant;
The network grant in effect, handed to the author as env.NETWORK.
notify?: NotifyBinding;
NOTIFY binding, when [[notifications.types]] is declared.
origin?: OriginTransport;
ORIGIN, the library a relay ingress plugin serves, when this
instance is the active ingress.
queues?: NamedQueue[];
[[queues.producers]] bindings, when granted.
secrets?: ExtensibleConfig;
Granted secret values as application/json.
sockets?: NamedSockets[];
The [sockets] binding, when granted (at most one entry).
storage?: Destination;
WORK_FS object store, when granted.
webhooks?: WebhooksTransport;
The WEBHOOKS grant, when [[webhooks]] is declared.
Granted-channel SQL transport the adapter hands to the author isolate for
one named [[databases]] binding. The author-side SDK wraps it as the
D1-shaped DatabaseBinding on env.<BINDING>; Python authors call
GrantedDatabaseTransport.executeBytes with Cap'n bytes instead.
The *Bytes methods report every failure inside the reply (the
ExecuteResultReply or DbCapabilitiesReply err arm, or one err
stream frame) rather than by throwing, so the error keeps its code and
details across the Workers RPC boundary between the two isolates; both
author SDKs read through them.
execute(request): Promise<ExecuteReply>;
Runs one typed atomic batch.
| Parameter | Type | Description |
|---|---|---|
request |
ExecuteRequest |
Structured Cap'n ExecuteRequest. |
Promise<ExecuteReply>
Structured ExecuteReply.
executeBytes(bytes): Promise<Uint8Array<ArrayBufferLike>>;
Same batch as AtomicTransport.execute, as Cap'n Proto bytes
(ExecuteRequest in, ExecuteResultReply out).
| Parameter | Type | Description |
|---|---|---|
bytes |
Uint8Array |
Unpacked ExecuteRequest message. |
Promise<Uint8Array<ArrayBufferLike>>
Unpacked ExecuteResultReply message.
executeStreamed?(request): Promise<
| Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>>;
Same batch as AtomicTransport.executeStreamed: the reply as
ExecuteStreamFrame bytes (POST /db/execute-streamed), read under the
session's streamed budget. A transport that predates the streamed read
leaves it out; the binding then reads inline.
| Parameter | Type | Description |
|---|---|---|
request |
ExecuteRequest |
Structured ExecuteRequest. |
Promise<
| Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>>
The frame sequence as the channel delivers it.
AtomicTransport.executeStreamed
executeStreamedBytes?(bytes): Promise<Uint8Array<ArrayBufferLike>>;
Same frames as GrantedDatabaseTransport.executeStreamed, whole, from Cap'n request bytes (Python authors decode locally). Optional like GrantedDatabaseTransport.executeStreamed.
| Parameter | Type | Description |
|---|---|---|
bytes |
Uint8Array |
Unpacked ExecuteRequest message. |
Promise<Uint8Array<ArrayBufferLike>>
Every ExecuteStreamFrame, concatenated.
limits(): Promise<DbCapabilities>;
Negotiated limits of the granted session (GuestDatabase.limits).
Promise<DbCapabilities>
The adapter's DbCapabilities for this binding.
limitsBytes(): Promise<Uint8Array<ArrayBufferLike>>;
Same answer as GrantedDatabaseTransport.limits, as Cap'n Proto
bytes (DbCapabilitiesReply) for Python authors.
Promise<Uint8Array<ArrayBufferLike>>
Unpacked DbCapabilitiesReply message.
openStreamedBytes?(bytes): Promise<
| Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>>;
Same frames as GrantedDatabaseTransport.executeStreamedBytes,
as the channel delivers them: a ReadableStream when it streams, so an
author's iterate() can decode frames as they arrive instead of holding
the reply whole. Optional like
GrantedDatabaseTransport.executeStreamed.
| Parameter | Type | Description |
|---|---|---|
bytes |
Uint8Array |
Unpacked ExecuteRequest message. |
Promise<
| Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>>
The frame sequence, streamed when the channel streams it.
Reverse-channel fetcher bound as GRANTED on the adapter isolate.
fetch(input, init?): Promise<Response>;
Call the host grant broker.
| Parameter | Type | Description |
|---|---|---|
input |
string |
Request URL. |
init? |
RequestInit |
Optional fetch init. |
Promise<Response>
Host response.
Granted capabilities for one job() invocation (adapter-internal).
cancel?: CancelWatchLike | null;
input?: Source | null;
output?: Destination | null;
progress?: ProgressSink | null;
Bounded, versioned checkpoint.
json: string;
schemaVersion: number;
Value a job() handler may return to annotate a completed outcome.
bytesCopied?: number;
Bytes copied by the job, when meaningful.
message?: string;
Operator-facing summary.
Options for JobController.retryLater.
reason?: string;
Short operator-facing reason.
retryAt?: Instant;
Earliest retry instant; omitted lets the host choose.
Job-runner bridge context: the durable job id plus GrantedContext.
ai?: AiBinding;
AI binding, when [ai].calls is declared and granted.
config?: ExtensibleConfig;
Operator settings for this plugin as application/json.
databases?: NamedDatabase[];
Named [[databases]] bindings.
events?: EventPublisherBinding;
EVENTS publisher, when [[events.producers]] is granted.
invocation?: Partial<Invocation>;
Invocation identity (Invocation struct).
jobId?: string;
Durable job id (Invocation.id of the job open).
kv?: NamedKv[];
[[kv_namespaces]] bindings, when granted.
network?: NetworkGrant;
The network grant in effect, handed to the author as env.NETWORK.
notify?: NotifyBinding;
NOTIFY binding, when [[notifications.types]] is declared.
origin?: OriginTransport;
ORIGIN, the library a relay ingress plugin serves, when this
instance is the active ingress.
queues?: NamedQueue[];
[[queues.producers]] bindings, when granted.
secrets?: ExtensibleConfig;
Granted secret values as application/json.
sockets?: NamedSockets[];
The [sockets] binding, when granted (at most one entry).
storage?: Destination;
WORK_FS object store, when granted.
webhooks?: WebhooksTransport;
The WEBHOOKS grant, when [[webhooks]] is declared.
Options for JobController.suspend.
checkpoint?: Checkpoint;
Bounded checkpoint replayed on resume (at most maxCheckpointBytes).
checkpointSchemaVersion?: number;
Schema version of checkpoint (default 1).
wakeAt?: Instant;
Earliest resume instant.
Outcome for one key of a batch call; error is absent on success.
error?: object;
code: string;
message: string;
key: string;
Paginated list request.
cursor?: string;
limit?: number;
modifiedSinceMs?: number;
Hint: only objects modified at or after this UTC unix millisecond. Say whether you filtered in ListPage.modifiedSinceApplied.
prefix?: string;
withSignatures?: boolean;
Hint: fill the signature fields of each entry. Say whether you did in ListPage.signaturesIncluded.
One page of keys.
modifiedSinceApplied?: boolean;
True when objects modified before modifiedSinceMs were left out.
nextCursor?: string;
objects: ObjectInfo[];
signaturesIncluded?: boolean;
True when every entry carries the signature fields the backend has.
One page of StorageEntrypoint.moveMany progress.
atomic?: boolean;
True when every move in this page was atomic.
nextCursor?: string;
Prefix form: cursor for the next call; absent when done.
objectsMoved?: number;
Objects moved in this page.
results: KeyOutcome[];
Outcomes in request order (one per pair for the pairs form).
Argument of StorageEntrypoint.moveMany.
cursor?: string;
Prefix form: the previous page's nextCursor; absent starts.
limit?: number;
Prefix form: objects to move in this call (at most MAX_BATCH_KEYS).
options?: MoveOptions;
Overwrite rule applied to every move.
target: MoveManyTarget;
Explicit pairs, or every object under a prefix.
Options for StorageEntrypoint.move and StorageEntrypoint.moveMany.
ifSourceMatch?: string;
move only: move only while the source's etag equals this value.
noOverwrite?: boolean;
Reject with conflict instead of replacing an object at the target.
How a single move was done.
alreadyMoved?: boolean;
True when the source was already gone and the target present.
atomic: boolean;
True when the move was atomic (a rename).
One named [[databases]] binding on the granted context: either an
in-isolate DatabaseBinding or the adapter's granted-channel
GrantedDatabaseTransport the author-side SDK wraps.
database?: DatabaseBinding;
Ready binding (same isolate).
name: string;
Binding name (env.<name>).
transport?: GrantedDatabaseTransport;
Granted transport (crosses the adapter → author RPC boundary).
One granted [[kv_namespaces]] binding on the granted context.
kv: KvNamespaceBinding;
Ready namespace (crosses the adapter → author RPC boundary).
name: string;
Binding name (env.<name>).
One granted [[queues.producers]] binding on the granted context.
name: string;
Binding name (env.<name>).
queue: QueueBinding;
Ready producer (crosses the adapter → author RPC boundary).
The granted [sockets] binding on the granted context.
name: string;
Binding name (env.<name>, SOCKETS unless renamed).
sockets: SocketsTransport;
The adapter's grant (crosses the adapter → author RPC boundary).
One entry of a change feed.
info?: ObjectInfo;
Listing fields after the change, when the feed carries them.
key: string;
kind: "changed" | "upserted" | "removed";
Object listing entry. The signature fields are set only when the listing was asked for them (ListOptions.withSignatures).
etag?: string;
Opaque backend entity tag.
key: string;
modifiedAtMs?: number;
Last modification time, UTC unix milliseconds.
signature?: string;
Opaque change signature: unchanged means the object did not change.
size: number;
versionId?: string;
Backend object version id (versioned buckets).
Metadata without a body.
contentType?: string;
etag?: string;
key: string;
modifiedAtMs?: number;
Last modification time, UTC unix milliseconds.
sha256?: Uint8Array<ArrayBufferLike>;
signature?: string;
Opaque change signature, as ObjectInfo.signature.
size: number;
versionId?: string;
Backend object version id (versioned buckets).
A purchase-hint answer that carries the priced listings a title search
matched, for a host that asked with lookup = "title".
Return it from StorefrontEntrypoint.purchaseHint (or as an entry
of StorefrontEntrypoint.purchaseHints) instead of a bare
PurchaseHint when the store's search returned more than one
listing: the host places each record in its library model by
identifiers, credits and kinds, and keeps only the recording it asked
for. hint stays the store's own pick for hosts that ignore records.
hint: PurchaseHint | null;
The store's own pick, or null when it found nothing.
records: PricedRecord[];
Every priced listing the search matched, with its full catalog record.
Result of a streamed put.
bytesWritten: number;
etag?: string;
key: string;
modifiedAtMs?: number;
Modification time of the stored object, UTC unix milliseconds.
sha256?: Uint8Array<ArrayBufferLike>;
signature?: string;
Change signature of the stored object.
versionId?: string;
Version id of the stored object.
Options for QueueMessage.retry.
delaySeconds?: number;
Seconds before redelivery; 0 applies the consumer's retry_delay.
reason?: string;
Short operator-facing reason.
Read options for StorageEntrypoint.get.
range?: ByteRange;
Streamed read result. body is a transferred ReadableStream.
body: ReadableStream<Uint8Array<ArrayBufferLike>>;
meta: ObjectMetadata;
Options for EventMessage.retry.
delaySeconds?: number;
Delay from now, in seconds; ignored when retryAt is set.
reason?: string;
Short operator-facing reason.
retryAt?: Instant;
Explicit earliest redelivery instant.
Wire EventBatch as the adapter delivers it to bookclerkEvent.
events: Partial<DomainEvent>[];
Wire QueueBatch as the adapter delivers it to bookclerkQueue.
messages: Partial<QueueMessage>[];
queue: string;
Write options for StorageEntrypoint.put.
commitToken?: string;
contentLength?: number;
contentType?: string;
ifMatch?: string;
Conditional write (storage.conditionalWrite): publish only while the
stored object's etag equals this value, else reject with conflict.
ifNoneMatch?: boolean;
Conditional write (storage.conditionalWrite): publish only when no
object exists at the key, else reject with conflict.
sha256?: Uint8Array<ArrayBufferLike>;
stageOnly?: boolean;
type AuthorStub = Pick<BookclerkEntrypoint,
| "bookclerkDescribe"
| "bookclerkEvent"
| "bookclerkQueue"
| "bookclerkScheduled"
| "bookclerkSocketMessage"
| "bookclerkSocketClosed"
| "bookclerkWebhookDelivered"
| "bookclerkJob"
| "bookclerkDatabaseMigrations"
| "bookclerkShutdown">;
Author default entrypoint as seen through the PLUGIN service binding.
type Checkpoint =
| string
| JsonObject
| unknown[]
| number
| boolean
| null;
JSON-serializable checkpoint accepted by suspend().
type EntrypointName =
| "storefront"
| "storage"
| "databaseAdapter"
| "remoteLibrary"
| "cli"
| "oidc"
| "metadata"
| "covers"
| "metadataFiles"
| "notifier"
| "ingress"
| "ai";
Wire name of each named entrypoint (plugin.toml entrypoints).
type EventOutcome =
| {
kind: "ack";
}
| {
kind: "retry";
reason: string;
retryAtUnixMs: number;
}
| {
kind: "reject";
reason: string;
}
| {
kind: "deadLetter";
reason: string;
}
| {
checkpointJson: string;
checkpointSchemaVersion: number;
kind: "suspended";
wakeAtUnixMs: number;
wakeOnEventType: string;
wakeOnFilterJson: string;
};
Recorded per-event outcome (EventResult union, bridge JSON projection).
type Instant = Date | number;
Wall-clock instant accepted by retry / suspend: a Date or Unix ms.
type JobOutcomeRecord =
| {
bytesCopied: number;
kind: "completed";
message: string;
}
| {
kind: "retryable";
message: string;
retryAfterUnixMs: number;
}
| {
kind: "rejected";
message: string;
}
| {
kind: "cancelled";
message: string;
}
| {
checkpoint: JobCheckpoint;
kind: "suspended";
wakeAtUnixMs: number;
};
Recorded terminal / suspended job outcome (JobOutcome union, bridge JSON projection).
type NamedStub = Pick<NamedEntrypoint, "bookclerkInvoke">;
Named author entrypoint as seen through a PLUGIN_<ENTRYPOINT> binding.
type PluginDescribe = Partial<PluginDescribe>;
Optional identity refinement returned by BookclerkEntrypoint.describe().
The launcher derives the full wire PluginDescribe from plugin.toml
(apiVersion, id, capabilities, configOptions, cli, …); an author
describe() may add or override presentation fields such as
displayName, brand, or rpcFeatures. Identity, capabilities, the
[media] declaration, and the [[settings]]-derived configOptions
always come from the manifest: a guest list that differs from the
manifest fails the spawn on the host.
type QueueOutcome =
| {
kind: "ack";
}
| {
delaySeconds: number;
kind: "retry";
reason: string;
};
Recorded per-message outcome of a queue() handler (bridge projection of QueueResult).
const ENTRYPOINT_BINDINGS: Readonly<Record<EntrypointName, string>>;
Adapter binding name for each named entrypoint.
const ENTRYPOINT_CLASSES: Readonly<Record<EntrypointName, string>>;
Exported class name the launcher binds for each named entrypoint.
const PURCHASE_HINTS_BUDGET_MS: 4000 = 4_000;
How long the default purchaseHints keeps starting one-title lookups
before answering with what it has, in milliseconds. Well under the
host's 10 s batch deadline, so even a slow last lookup lands before it
and a store without a bulk endpoint still returns the titles it priced.
const PURCHASE_HINTS_CONCURRENCY: 4 = 4;
How many one-title lookups the default purchaseHints keeps in flight
at once. A store without a bulk endpoint answers a page of cards in
about a quarter of the time one lookup after another takes, while
staying a polite handful of requests rather than a burst.
const TRIGGER_FAMILIES: Readonly<Record<
| "eventConsumer"
| "queueConsumer"
| "scheduledHandler"
| "jobRunner"
| "socketHandler"
| "webhookHandler", string>>;
Wire names of the trigger families the launcher may ask openInvocation about.
function allowedEntrypointFamilies(capabilities, requested): string[];
Filters requested entrypoint / trigger family names against the manifest
capabilities: named entrypoints must be declared in entrypoints,
eventConsumer needs a non-empty consumes, queueConsumer needs a
non-empty queueConsumers, scheduledHandler needs a non-empty crons,
socketHandler needs sockets ([sockets] in the manifest),
webhookHandler needs webhooks ([[webhooks]] in the manifest),
and jobRunner needs jobs or the storage
entrypoint (storage guests run the host stream_copy job). Unknown names
and a missing manifest fail closed.
| Parameter | Type | Description |
|---|---|---|
capabilities |
| Partial<PluginCapabilities> | null | undefined |
Manifest capabilities from PLUGIN_DESCRIBE. |
requested |
readonly string[] |
Family names the launcher wants to export. |
string[]
The authorized subset in request order.
function cliArgs(params): Record<string, string>;
Turns CliInvokeParams.args ([{ name, value }]) into a plain
{ name: value } object for CLI handlers.
| Parameter | Type | Description |
|---|---|---|
params |
| Pick<CliInvokeParams, "args"> | undefined |
CLI invocation params from the host. |
Record<string, string>
Argument values keyed by name.
function dataMigrationOp(sql): object;
Data DML convenience for PluginMigration operations.
| Parameter | Type | Description |
|---|---|---|
sql |
string |
Already-separated BookclerkSQL data statement. |
object
Data operation tagged for host registration.
| Name | Type |
|---|---|
data |
string |
function decodeExtensibleConfig(cfg): JsonObject;
Decode an ExtensibleConfig ({ schemaVersion, mediaType, payload }) into
the plain object authors read from env.CONFIG / env.SECRETS. Non-JSON
media types are surfaced verbatim so nothing is lost.
| Parameter | Type | Description |
|---|---|---|
cfg |
unknown |
Wire config struct, a pre-decoded object, or undefined. |
Plain JSON object ({} when empty or malformed).
function eventBatchResults(batch, failed): EventOutcome[];
Translate recorded EventMessage outcomes into the wire list.
failed is the error thrown by the author's event(); undecided messages
then retry instead of ack.
| Parameter | Type | Description |
|---|---|---|
batch |
EventBatch |
Delivered batch after the handler ran. |
failed |
unknown |
Error thrown by the handler, if any. |
One outcome per message, in order.
function fromBridgeJson(value): unknown;
Bridge JSON → typed ABI value: base64 Data fields (payload, sha256,
credentials) become Uint8Array; everything else is structurally
identical, so no per-struct codec is needed.
| Parameter | Type | Description |
|---|---|---|
value |
unknown |
Bridge JSON value. |
unknown
Typed struct value.
function invocationOf(context): Invocation;
Invocation envelope (Invocation struct) with zero values normalized.
| Parameter | Type | Description |
|---|---|---|
context |
GrantedContext | undefined |
Granted context carrying invocation. |
Frozen invocation identity.
function jobOutcomeFor(
job,
returned,
failed
): JobOutcomeRecord;
Translate a job() handler's return / throw into the wire outcome.
| Parameter | Type | Description |
|---|---|---|
job |
JobController |
Controller after the handler ran. |
returned |
void | JobCompletion | undefined |
Handler return value. |
failed |
unknown |
Error thrown by the handler, if any. |
Wire job outcome.
function jsonPayload(value): ExtensibleConfig;
Wraps a JSON-serializable value as an application/json ExtensibleConfig
(schema version 1) — the shape of CliInvokeResult.payload and every other
extensible payload on the wire.
| Parameter | Type | Description |
|---|---|---|
value |
unknown |
JSON-serializable value. |
Wire-shaped extensible payload.
function packEmbeddingVectors(vectors): Uint8Array;
Packs embedding vectors into the wire form of
AiTextEmbeddingsOutput.vectors: little-endian 32-bit floats, concatenated.
| Parameter | Type | Description |
|---|---|---|
vectors |
readonly ArrayLike<number>[] |
One vector per input text, all of one length. |
Uint8Array
The bytes.
function queueBatchResults(batch, failed): QueueOutcome[];
Translate recorded QueueMessage outcomes into the wire list.
failed is the error thrown by the author's queue(); undecided messages
then retry instead of ack.
| Parameter | Type | Description |
|---|---|---|
batch |
QueueBatch |
Delivered batch after the handler ran. |
failed |
unknown |
Error thrown by the handler, if any. |
One outcome per message, in order.
function scheduledControllerOf(wire): Readonly<ScheduledController>;
Frozen author view of one wire ScheduledController, with every field
present and typed.
| Parameter | Type | Description |
|---|---|---|
wire |
| Partial<ScheduledController> | null | undefined |
Decoded wire struct (fields may be missing). |
Readonly<ScheduledController>
The controller the author's scheduled() receives.
function schemaMigrationOp(sql): object;
Schema DDL convenience for PluginMigration operations.
| Parameter | Type | Description |
|---|---|---|
sql |
string |
Already-separated BookclerkSQL schema statement. |
object
Schema operation tagged for host registration.
| Name | Type |
|---|---|
schema |
string |
function toBridgeJson(value): unknown;
Typed ABI value → bridge JSON: Cap'n Data fields (Uint8Array) travel as
base64 text; bookclerk-workerd decodes with the same convention.
| Parameter | Type | Description |
|---|---|---|
value |
unknown |
Plain typed struct value. |
unknown
JSON-safe projection.
function unpackEmbeddingVectors(bytes, dimensions): number[][];
Splits the wire form of AiTextEmbeddingsOutput.vectors into vectors.
| Parameter | Type | Description |
|---|---|---|
bytes |
Uint8Array |
Little-endian 32-bit floats, concatenated. |
dimensions |
number |
Numbers per vector. |
number[][]
One vector per dimensions numbers.
internal when the bytes are not whole vectors.
function wrapPluginFromBinding(): typeof InvocationAdapter;
Generated adapter isolate: env.PLUGIN is the author's default entrypoint
and env.PLUGIN_<ENTRYPOINT> the named ones. Every POST /invoke call
(Cap'n Proto bytes) and every stream route becomes one bookclerk*
dispatch on the author class; authors cannot replace adapter behavior with
adapter-internal names.
typeof InvocationAdapter
Adapter entrypoint class bound to AdapterEnv.
function wrapPluginFromNative(): typeof InvocationAdapter;
Native-behind-workerd generated adapter: control plane only. The launcher
forwards every entrypoint call to the native guest as typed Cap'n Proto;
this isolate decides describe (merged against PLUGIN_DESCRIBE) and
open policy (openInvocation) and receives shutdown. There is no
author PLUGIN binding.
typeof InvocationAdapter
Adapter entrypoint class bound to AdapterEnv.
Re-exports AiEmbedText
Re-exports AiInput
Re-exports AiModel
Re-exports AiModelList
Re-exports AiOutput
Re-exports AiRunOk
Re-exports AiRunParams
Re-exports AiTask
Re-exports AiTextEmbeddingsInput
Re-exports AiTextEmbeddingsOutput
Re-exports AiTextRole
Re-exports CliInvokeParams
Re-exports CliInvokeResult
Re-exports CliSchema
Re-exports CoverFetchParams
Re-exports CoverImage
Re-exports CoverImages
Re-exports DomainEvent
Re-exports ExtensibleConfig
Re-exports FEATURE_SCALAR_LIMITS
Re-exports FEATURE_STORAGE_CHANGES
Re-exports FEATURE_STORAGE_CONDITIONAL_WRITE
Re-exports FEATURE_STORAGE_COPY
Re-exports FEATURE_STORAGE_DELETE_MANY
Re-exports FEATURE_STORAGE_HEAD_MANY
Re-exports FEATURE_STORAGE_MOVE
Re-exports FEATURE_STORAGE_MOVE_MANY
Re-exports FEATURE_STREAMS
Re-exports HealthOk
Re-exports Invocation
Re-exports JobInvocation
Re-exports MAX_BATCH_KEYS
Re-exports MAX_CHANGES_CURSOR_BYTES
Re-exports MAX_CHANGES_PAGE
Re-exports MAX_CHECKPOINT_BYTES
Re-exports MAX_EVENT_PAYLOAD_BYTES
Re-exports MAX_LIST_PAGE
Re-exports MAX_PLUGIN_MIGRATION_OPS
Re-exports MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES
Re-exports MAX_PLUGIN_MIGRATION_TOTAL_OPS
Re-exports MAX_SCALAR_BYTES
Re-exports MAX_STREAM_WINDOW_BYTES
Re-exports MetadataAudioFile
Re-exports MetadataChapter
Re-exports MetadataChapters
Re-exports MetadataChaptersParams
Re-exports MetadataField
Re-exports MetadataFileParsed
Re-exports MetadataFileParseParams
Re-exports MetadataFileRecord
Re-exports MetadataFileRendered
Re-exports MetadataFileRenderParams
Re-exports MetadataLookupParams
Re-exports MetadataRecord
Re-exports MetadataSearchParams
Re-exports NetworkGrant
Re-exports NotificationAlertAction
Re-exports NotificationAudience
Re-exports NotificationField
Re-exports NotificationMessage
Re-exports NotificationSeverity
Re-exports NotifyDestination
Re-exports NotifyDestinationKind
Re-exports NotifyRaised
Re-exports NotifyRaiseParams
Re-exports NotifySendParams
Re-exports NotifySent
Re-exports NotifyValidated
Re-exports NotifyValidateParams
Re-exports OidcClientTemplate
Re-exports PluginCapabilities
Re-exports PluginError
Re-exports PluginMigration
Re-exports PluginMigrationOp
Re-exports PRODUCT_API_VERSION
Re-exports requirePluginMigrationRegistration
Re-exports ScalarLimits
Generated from packages/plugin-sdk at main · View as Markdown