plugin

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

Last updated View as Markdown

Classes

AdapterDatabaseSession

Host ↔ database adapter session returned by DatabaseAdapterEntrypoint.openSession.

Extends

  • RpcTarget

Constructors

Constructor
new AdapterDatabaseSession(): AdapterDatabaseSession;
Returns

AdapterDatabaseSession

Inherited from

RpcTarget.constructor

Methods

assertRestoreConstraints()
assertRestoreConstraints(): Promise<void>;

Re-check constraints after a unit restore; optional.

Returns

Promise<void>

Resolves when every constraint holds.

bootstrap()
bootstrap(): Promise<DbBootstrap>;

Bootstrap-only diagnostic metadata (DbBootstrap); optional.

Returns

Promise<DbBootstrap>

Engine identity for diagnostics.

capabilities()
capabilities(): Promise<unknown>;

Typed SQL-contract advertisement.

Returns

Promise<unknown>

Guest DbCapabilities.

close()
close(): Promise<void>;

Close the adapter session.

Returns

Promise<void>

Resolves when the session is closed.

dropUserRelations()
dropUserRelations(_names): Promise<void>;

Drop the named user relations; optional.

Parameters
Parameter Type Description
_names string[] Relation names from AdapterDatabaseSession.listUserRelations.
Returns

Promise<void>

Resolves when the relations are gone.

execute()
execute(_request): Promise<ExecuteReply>;

Typed atomic batch (ExecuteRequest → ExecuteReply).

Parameters
Parameter Type Description
_request ExecuteRequest Cap'n ExecuteRequest (structured Workers RPC object).
Returns

Promise<ExecuteReply>

ExecuteReply.

executeStreamed()
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.

Parameters
Parameter Type Description
_request AdapterExecuteRequest Proven statements plus isolation and receipt.
Returns

Promise<Uint8Array<ArrayBufferLike>>

Every frame of the committed reply, concatenated.

exportIdentity()
exportIdentity(): Promise<IdentityHighWater[]>;

Identity high-water marks for a logical export; optional.

Returns

Promise<IdentityHighWater[]>

One row per identity column.

importIdentity()
importIdentity(_rows): Promise<void>;

Restore identity high-water marks after a logical import; optional.

Parameters
Parameter Type Description
_rows IdentityHighWater[] Rows from an earlier AdapterDatabaseSession.exportIdentity.
Returns

Promise<void>

Resolves when the marks are applied.

listUserRelations()
listUserRelations(): Promise<string[]>;

Names of user relations the host may drop before a restore; optional.

Returns

Promise<string[]>

Relation names.

prepareUnitRestore()
prepareUnitRestore(): Promise<void>;

Prepare the engine for a unit restore (disable constraints, …); optional.

Returns

Promise<void>

Resolves when the engine is ready for the restore.


AiEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new AiEntrypoint<Env>(ctx, env): AiEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

AiEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<HealthOk>;

Reports whether the models can be loaded with the current settings.

Returns

Promise<HealthOk>

Health flag plus detail.

models()
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.

Returns

Promise<AiModelList>

The served models, each modelId once.

run()
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.

Parameters
Parameter Type Description
_params AiRunParams The plugin's own model id and the input.
Returns

Promise<AiRunOk>

The output; leave model unset.


BookclerkEntrypoint

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.

Example

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();
    }
  }
}

Extends

  • WorkerEntrypoint<Env>

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-1"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new BookclerkEntrypoint<Env>(ctx, env): BookclerkEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

BookclerkEntrypoint<Env>

Inherited from

WorkerEntrypoint<Env>.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

WorkerEntrypoint.ctx

env
readonly env: Env;
Inherited from

WorkerEntrypoint.env

Methods

bookclerkDatabaseMigrations()
bookclerkDatabaseMigrations(binding): Promise<PluginMigration[]>;

Internal

Adapter dispatch for databaseMigrations(binding).

Parameters
Parameter Type Description
binding string Binding name from [[databases]].
Returns

Promise<PluginMigration[]>

Bounded registration ([] when not implemented).

bookclerkDescribe()
bookclerkDescribe(): Promise<Partial<PluginDescribe> | null>;

Internal

Adapter dispatch for describe().

Returns

Promise<Partial<PluginDescribe> | null>

Author refinement or null when not implemented.

bookclerkEvent()
bookclerkEvent(context, wireBatch): Promise<EventOutcome[]>;

Internal

Adapter dispatch for the event(batch) trigger.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wireBatch WireEventBatch Wire EventBatch.
Returns

Promise<EventOutcome[]>

One outcome per event, in order.

bookclerkJob()
bookclerkJob(
   context, 
   invocation, 
   granted
): Promise<JobOutcomeRecord>;

Internal

Adapter dispatch for the job(controller) trigger.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
invocation Partial<JobInvocation> Durable command envelope.
granted GrantedJobCapabilities Granted input / output / progress / cancel stubs.
Returns

Promise<JobOutcomeRecord>

Wire job outcome.

bookclerkQueue()
bookclerkQueue(context, wireBatch): Promise<QueueOutcome[]>;

Internal

Adapter dispatch for the queue(batch) trigger.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wireBatch WireQueueBatch Wire QueueBatch.
Returns

Promise<QueueOutcome[]>

One outcome per message, in order.

bookclerkScheduled()
bookclerkScheduled(context, wire): Promise<void>;

Internal

Adapter dispatch for the scheduled(controller) trigger.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wire Partial<ScheduledController> Wire ScheduledController.
Returns

Promise<void>

Resolves when the author's handler completes.

bookclerkShutdown()
bookclerkShutdown(): Promise<void>;

Internal

Adapter dispatch for shutdown().

Returns

Promise<void>

Resolves when the author hook has run.

bookclerkSocketClosed()
bookclerkSocketClosed(context, wire): Promise<void>;

Internal

Adapter dispatch for SocketHandler.closed. Without a webSocketClose handler the close is acknowledged and ignored.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wire Partial<SocketClosed> Wire SocketClosed.
Returns

Promise<void>

Resolves when the author's handler completes.

bookclerkSocketMessage()
bookclerkSocketMessage(context, wire): Promise<SocketMessageOk>;

Internal

Adapter dispatch for SocketHandler.message.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wire Partial<SocketMessage> Wire SocketMessage.
Returns

Promise<SocketMessageOk>

What the handler asks of the host (pollEvents).

bookclerkWebhookDelivered()
bookclerkWebhookDelivered(context, wire): Promise<void>;

Internal

Adapter dispatch for WebhookHandler.delivered. Without a webhookDelivered handler the call is acknowledged and ignored.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
wire Partial<WebhookDeliveredEvent> Wire WebhookDelivered.
Returns

Promise<void>

Resolves when the author's handler completes.

databaseMigrations()?
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.

Parameters
Parameter Type
binding string
Returns

| PluginMigration[] | Promise<PluginMigration[]>

describe()?
describe?(): 
  | Partial<PluginDescribe>
| Promise<Partial<PluginDescribe>>;

Optional identity refinement merged over the manifest projection.

Returns

| Partial<PluginDescribe> | Promise<Partial<PluginDescribe>>

event()?
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.

Parameters
Parameter Type
batch EventBatch
Returns

void | Promise<void>

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

job()?
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().

Parameters
Parameter Type
job JobController
Returns

| void | JobCompletion | Promise<void | JobCompletion>

queue()?
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.

Parameters
Parameter Type
batch QueueBatch
Returns

void | Promise<void>

scheduled()?
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.

Parameters
Parameter Type
controller Readonly<ScheduledController>
Returns

void | Promise<void>

shutdown()?
shutdown?(): void | Promise<void>;

Releases guest resources.

Returns

void | Promise<void>

webhookDelivered()?
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.

Parameters
Parameter Type
event WebhookDeliveredEvent
Returns

void | Promise<void>

webSocketClose()?
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.

Parameters
Parameter Type
ws HostWebSocket
code number
reason string
wasClean boolean
Returns

void | Promise<void>

webSocketMessage()?
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.

Parameters
Parameter Type
ws HostWebSocket
message SocketMessageData
Returns

| void | Partial<SocketMessageOk> | Promise<void | Partial<SocketMessageOk>>


CliEntrypoint

cli entrypoint (PluginCli): describe() → CliSchema, invoke(params) → CliInvokeResult. Export it as export class Cli extends CliEntrypoint.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-2"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new CliEntrypoint<Env>(ctx, env): CliEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

CliEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

describe()
describe(): Promise<CliSchema>;

Guest CLI schema.

Returns

Promise<CliSchema>

Declared commands ({ commands: [] } when the guest has no CLI).

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

invoke()
invoke(_params): Promise<CliInvokeResult>;

Invokes a guest CLI command.

Parameters
Parameter Type Description
_params CliInvokeParams Command name plus named argument values.
Returns

Promise<CliInvokeResult>

Exit code, captured output, optional structured payload.


CoverEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-3"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new CoverEntrypoint<Env>(ctx, env): CoverEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

CoverEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

fetchCovers()
fetchCovers(_params, _sink): Promise<CoverImage[]>;

Fetches each URL and streams its body into sink under its index.

Parameters
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.
Returns

Promise<CoverImage[]>

One entry per URL, in request order.

health()
health(): Promise<HealthOk>;

Reports whether the fetcher can answer.

Returns

Promise<HealthOk>

Health flag plus detail.


DatabaseAdapterEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-4"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new DatabaseAdapterEntrypoint<Env>(ctx, env): DatabaseAdapterEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

DatabaseAdapterEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: openSession → session id; dropUnit; session → call on a retained session (args = [id, method, ...params]).

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string openSession, dropUnit, or session.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Session id for openSession, else the session method result.

Overrides

NamedEntrypoint.bookclerkInvoke

dropUnit()
dropUnit(_unitRef): Promise<void>;

Physically drops one provisioned binding unit.

Parameters
Parameter Type Description
_unitRef string Adapter-native unit identity.
Returns

Promise<void>

Resolves when the unit is dropped.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

openSession()
openSession(): Promise<AdapterDatabaseSession>;

Opens a session. Sessions cannot survive suspension.

Returns

Promise<AdapterDatabaseSession>

Adapter session capability.


Destination

Object store capability: job.output and the WORK_FS binding. The runtime stub is the capability; abort is stream cancel.

Extends

  • RpcTarget

Constructors

Constructor
new Destination(): Destination;
Returns

Destination

Inherited from

RpcTarget.constructor

Methods

abortStage()
abortStage(_key, _commitToken): Promise<void>;

Abort a destination-side staged object.

Parameters
Parameter Type Description
_key string Object key.
_commitToken string Staging token to discard.
Returns

Promise<void>

Rejects with typed unsupported unless overridden.

changes()
changes(_request): Promise<ChangesPage>;

Keys changed since a cursor (declare storage.changes).

Parameters
Parameter Type Description
_request ChangesRequest Cursor and page size.
Returns

Promise<ChangesPage>

One page of changes.

commit()
commit(_key, _commitToken): Promise<PutResult>;

Finalize a destination-side staged object.

Parameters
Parameter Type Description
_key string Object key.
_commitToken string Idempotency / commit token.
Returns

Promise<PutResult>

Published object metadata.

copy()
copy(_from, _to): Promise<CopyResult>;

Server-side copy when the backend supports it.

Parameters
Parameter Type Description
_from string Source key.
_to string Destination key.
Returns

Promise<CopyResult>

Bytes copied.

delete()
delete(_key): Promise<void>;

Delete a key (no-op if missing).

Parameters
Parameter Type Description
_key string Object key.
Returns

Promise<void>

Resolves when the delete is complete.

deleteMany()
deleteMany(_keys): Promise<KeyOutcome[]>;

Remove up to MAX_BATCH_KEYS objects (declare storage.deleteMany).

Parameters
Parameter Type Description
_keys string[] Object keys.
Returns

Promise<KeyOutcome[]>

One outcome per key, in order; a missing key succeeds.

get()
get(_key, _options?): Promise<ReadResult>;

Streamed read. The body is a transferred stream, not a scalar.

Parameters
Parameter Type Description
_key string Object key.
_options? ReadOptions Optional byte range.
Returns

Promise<ReadResult>

Metadata plus a transferred body stream.

head(_key): Promise<ObjectMetadata | null>;

Metadata without a body; null when the key is missing.

Parameters
Parameter Type Description
_key string Object key.
Returns

Promise<ObjectMetadata | null>

Metadata or null when the key is missing.

headMany()
headMany(_keys): Promise<(ObjectMetadata | null)[]>;

Probe up to MAX_BATCH_KEYS objects (declare storage.headMany).

Parameters
Parameter Type Description
_keys string[] Object keys.
Returns

Promise<(ObjectMetadata | null)[]>

One entry per key, in order; null when missing.

list()
list(_options): Promise<ListPage>;

One page of keys under options.prefix.

Parameters
Parameter Type Description
_options ListOptions Prefix, cursor, and limit.
Returns

Promise<ListPage>

One page of object keys.

move()
move(
   _from, 
   _to, 
   _options
): Promise<MoveResult>;

Move one object (declare storage.move). Repeating a finished move resolves with alreadyMoved.

Parameters
Parameter Type Description
_from string Source key.
_to string Target key.
_options MoveOptions Overwrite and source preconditions.
Returns

Promise<MoveResult>

How the move was done.

moveMany()
moveMany(_request): Promise<MoveManyPage>;

Move a set of objects or a whole prefix, one page per call (declare storage.moveMany). Safe to repeat.

Parameters
Parameter Type Description
_request MoveManyRequest Pairs or prefix, cursor, and options.
Returns

Promise<MoveManyPage>

Per-key outcomes and the continuation.

put()
put(
   _key, 
   _body, 
   _options?
): Promise<PutResult>;

Streamed write. body ownership is transferred to the destination.

Parameters
Parameter Type Description
_key string Object key.
_body ReadableStream<Uint8Array<ArrayBufferLike>> Byte stream.
_options? WriteOptions Optional content type / length.
Returns

Promise<PutResult>

Bytes written and optional etag / sha256.

translateKeys()
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.

Parameters
Parameter Type Description
_keys string[] Host keys.
Returns

Promise<string[]>

One translated key per host key, in order.


EventBatch

One event(batch) delivery (EventBatch struct), Workers MessageBatch-shaped.

Constructors

Constructor
new EventBatch(events, invocation?): EventBatch;
Parameters
Parameter Type
events | readonly Partial<DomainEvent>[] | undefined
invocation? Invocation
Returns

EventBatch

Properties

invocation
invocation: Invocation;

Invocation identity of this delivery.

messages
readonly messages: readonly EventMessage[];

Messages in delivery order.

Accessors

type
Get Signature
get type(): string;

Event type shared by the batch.

Returns

string

The shared type, or "" when mixed or empty.

Methods

ackAll()
ackAll(): void;

Ack every message.

Returns

void

retryAll()
retryAll(options?): void;

Retry every message.

Parameters
Parameter Type Description
options? RetryOptions Redelivery timing and reason.
Returns

void


EventMessage

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.

Constructors

Constructor
new EventMessage(event): EventMessage;
Parameters
Parameter Type
event Partial<DomainEvent> | undefined
Returns

EventMessage

Properties

accountId
readonly accountId: string;

Account scope; empty for host-wide events.

attempts
readonly attempts: number;

Delivery counter, starting at 1.

body
readonly body: Uint8Array;

Encoded payload bytes.

causationId
readonly causationId: string;

Id of the command or event that caused this one.

checkpoint
readonly checkpoint: DeliveredCheckpoint | null;

Checkpoint from the prior suspend(), or null.

correlationId
readonly correlationId: string;

Trace correlation id.

deduplicationKey
readonly deduplicationKey: string;

Consumer-side idempotency key; stable across redeliveries.

id
readonly id: string;

Outbox event id.

invocationSequence
readonly invocationSequence: number;

Resume ordinal; distinct from attempts.

raw
readonly raw: Partial<DomainEvent>;

Raw wire envelope.

resumePending
readonly resumePending: boolean;

True when this delivery resumes a prior suspend().

schemaVersion
readonly schemaVersion: number;

Schema version of EventMessage.body.

source
readonly source: string;

Producer plugin id; empty when unknown.

timestamp
readonly timestamp: Date;

When the producer observed the fact.

type
readonly type: string;

Event type (book_acquired, …).

Accessors

result
Get Signature
get result(): EventOutcome | null;

Recorded outcome.

Returns

EventOutcome | null

The outcome, or null while undecided.

Methods

ack()
ack(): void;

Mark handled; the host marks the event delivered.

Returns

void

deadLetter()
deadLetter(reason?): void;

Park for operator review.

Parameters
Parameter Type Description
reason? string Short operator-facing reason.
Returns

void

json()
json<T>(): T;

Decode EventMessage.body as JSON.

Type Parameters
Type Parameter Default type
<a id="type-parameter-t"></a> T JsonObject
Returns

T

Parsed payload ({} for an empty body).

reject()
reject(reason?): void;

Stop delivering; the host records reason.

Parameters
Parameter Type Description
reason? string Short operator-facing reason.
Returns

void

retry()
retry(options?): void;

Redeliver later: at retryAt, after delaySeconds, or — when both are omitted — whenever the host's backoff chooses.

Parameters
Parameter Type Description
options? RetryOptions Redelivery timing and reason.
Returns

void

suspend()
suspend(options?): void;

Release with a bounded checkpoint; the host redelivers at wakeAt or when a wakeOnEventType event arrives.

Parameters
Parameter Type Description
options? EventSuspendOptions Checkpoint and wake conditions.
Returns

void


IngressEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-5"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new IngressEntrypoint<Env>(ctx, env): IngressEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

IngressEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<IngressHealth>;

Reports whether the address is serving.

Returns

Promise<IngressHealth>

serving, plus a detail for the operator when it is not.

start()
start(): Promise<IngressStarted>;

Brings the public address up and returns it once it serves.

Returns

Promise<IngressStarted>

The public origin: https:// and a host name, no port, path or trailing slash.

stop()
stop(): Promise<void>;

Takes the public address down. The host stops sending requests after this returns.

Returns

Promise<void>

Resolves once the address no longer serves.


JobController

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).

Constructors

Constructor
new JobController(invocation, granted?): JobController;
Parameters
Parameter Type
invocation Partial<JobInvocation> | undefined
granted? GrantedJobCapabilities
Returns

JobController

Properties

attempt
readonly attempt: number;

Failure retry counter, starting at 1.

causationId
readonly causationId: string;

Id of the event or command that caused this job.

checkpoint
readonly checkpoint: DeliveredCheckpoint | null;

Checkpoint from the prior suspend(), or null.

correlationId
readonly correlationId: string;

Trace correlation id.

deadlineUnixMs
readonly deadlineUnixMs: number;

Deadline hint (Unix ms); the host fence is authoritative.

id
readonly id: string;

Unique id of this invocation attempt.

idempotencyKey
readonly idempotencyKey: string;

Caller idempotency key.

input
readonly input: Source | null;

Granted byte source, when the job has input.

invocation
readonly invocation: Readonly<Partial<JobInvocation>>;

Full durable envelope as delivered.

invocationSequence
readonly invocationSequence: number;

Resume ordinal.

output
readonly output: Destination | null;

Granted object store, when the job has output.

payloadJson
readonly payloadJson: string;

Command payload JSON text.

payloadSchemaVersion
readonly payloadSchemaVersion: number;

Schema version of JobController.payloadJson.

signal
readonly signal: AbortSignal;

Aborts when the host cancels the invocation.

stepId
readonly stepId: string;

Step id within a multi-step command; empty when single-step.

type
readonly type: string;

Command type the handler dispatches on.

Accessors

result
Get Signature
get result(): JobOutcomeRecord | null;

Recorded terminal outcome.

Returns

JobOutcomeRecord | null

The outcome, or null while the job is still running.

Methods

cancel()
cancel(): void;

Host-side cancellation observed (adapter-internal).

Returns

void

json()
json<T>(): T;

Decode JobController.payloadJson.

Type Parameters
Type Parameter Default type
<a id="type-parameter-t-1"></a> T JsonObject
Returns

T

Parsed payload ({} when empty).

progress()
progress(percent, message?): Promise<void>;

Report percent in 0..=100 with an operator-facing message.

Parameters
Parameter Type Description
percent number Completion percent.
message? string Operator-facing status.
Returns

Promise<void>

Resolves when the host records progress.

retryLater()
retryLater(options?): void;

Give up this attempt and let the host retry at retryAt (or its default).

Parameters
Parameter Type Description
options? JobRetryOptions Retry time and reason.
Returns

void

suspend()
suspend(options?): void;

Release with a bounded checkpoint; the host resumes at wakeAt.

Parameters
Parameter Type Description
options? JobSuspendOptions Checkpoint and wake time.
Returns

void


MetadataEntrypoint

metadata entrypoint (MetadataProvider): bibliographic lookups against a public catalog. Records describe editions; the host decides identity. Export it as export class Metadata extends MetadataEntrypoint.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-6"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new MetadataEntrypoint<Env>(ctx, env): MetadataEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

MetadataEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

chapters()
chapters(_params): Promise<MetadataChapters>;

Chapter layout of one edition.

Parameters
Parameter Type Description
_params MetadataChaptersParams Identifiers of the edition.
Returns

Promise<MetadataChapters>

The layout, or { found: false } when the provider has none.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<HealthOk>;

Reports whether the provider can answer.

Returns

Promise<HealthOk>

Health flag plus detail.

lookup()
lookup(_params): Promise<MetadataRecord[]>;

Records for the editions the identifiers name.

Parameters
Parameter Type Description
_params MetadataLookupParams Identifiers, marketplace and result cap.
Returns

Promise<MetadataRecord[]>

Records in relevance order ([] when nothing matched).

search(_params): Promise<MetadataRecord[]>;

Records matching a title and, optionally, an author.

Parameters
Parameter Type Description
_params MetadataSearchParams Title, author, language, marketplace and result cap.
Returns

Promise<MetadataRecord[]>

Records in relevance order ([] when nothing matched).


MetadataFilesEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-7"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new MetadataFilesEntrypoint<Env>(ctx, env): MetadataFilesEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

MetadataFilesEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<HealthOk>;

Reports whether the dialects can answer.

Returns

Promise<HealthOk>

Health flag plus detail.

parse()
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.

Parameters
Parameter Type Description
_params MetadataFileParseParams Dialect id, file name and the whole file.
Returns

Promise<MetadataFileRecord>

The parsed record.

render()
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.

Parameters
Parameter Type Description
_params MetadataFileRenderParams Dialect id, values, fields to set and the current file.
Returns

Promise<string | Uint8Array<ArrayBufferLike>>

The new file's bytes; a string is written as UTF-8.


NamedEntrypoint

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.

Extends

  • WorkerEntrypoint<Env>

Extended by

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-8"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new NamedEntrypoint<Env>(ctx, env): NamedEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

NamedEntrypoint<Env>

Inherited from

WorkerEntrypoint<Env>.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

WorkerEntrypoint.ctx

env
readonly env: Env;
Inherited from

WorkerEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

bookclerkMethods
static bookclerkMethods: readonly string[] = [];

Methods the adapter may dispatch on this entrypoint.

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.


NotifierEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-9"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new NotifierEntrypoint<Env>(ctx, env): NotifierEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

NotifierEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<HealthOk>;

Reports whether the service can be reached with the current settings.

Returns

Promise<HealthOk>

Health flag plus detail.

send()
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.

Parameters
Parameter Type Description
_params NotifySendParams The rendered message and its destination.
Returns

Promise<NotifySent>

The service's message id, when it gives one.

validateDestination()
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.

Parameters
Parameter Type Description
params NotifyValidateParams The address document as entered.
Returns

Promise<NotifyValidated>

The address to save and an optional label that is never a secret.


OidcEntrypoint

oidc entrypoint: relying-party client templates and credential verification. Export it as export class Oidc extends OidcEntrypoint.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-10"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new OidcEntrypoint<Env>(ctx, env): OidcEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

OidcEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[];

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

authenticateUser()
authenticateUser(_params): Promise<ExternalUser>;

Verifies remote credentials on behalf of the host.

Parameters
Parameter Type Description
_params AuthenticateUserParams Username / password pair.
Returns

Promise<ExternalUser>

External user identity.

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

clients()
clients(): Promise<OidcClientTemplate[]>;

Plugin-provided OIDC authorization-server client templates. The host materializes oidc_clients rows; plugins never mint tokens.

Returns

Promise<OidcClientTemplate[]>

Templates ([] when unused).

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch


ProgressSink

Progress reports for a job invocation (never carries media).

Extends

  • RpcTarget

Constructors

Constructor
new ProgressSink(): ProgressSink;
Returns

ProgressSink

Inherited from

RpcTarget.constructor

Methods

report()
report(_percent, _message): Promise<void>;

Reports percent in 0..=100 and an operator-facing message.

Parameters
Parameter Type Description
_percent number Completion percent.
_message string Operator-facing status.
Returns

Promise<void>

Resolves when the host records progress.


QueueBatch

One queue(batch) delivery (QueueBatch struct), Workers MessageBatch-shaped.

Constructors

Constructor
new QueueBatch(
   queue, 
   messages, 
   invocation?
): QueueBatch;
Parameters
Parameter Type
queue string | undefined
messages | readonly Partial<QueueMessage>[] | undefined
invocation? Invocation
Returns

QueueBatch

Properties

invocation
invocation: Invocation;

Invocation identity of this delivery.

messages
readonly messages: readonly QueueMessage[];

Messages in delivery order.

queue
readonly queue: string;

Queue the messages were sent to.

Methods

ackAll()
ackAll(): void;

Ack every message.

Returns

void

retryAll()
retryAll(options?): void;

Retry every message.

Parameters
Parameter Type Description
options? QueueRetryOptions Redelivery timing and reason.
Returns

void


QueueMessage

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.

Constructors

Constructor
new QueueMessage(message): QueueMessage;
Parameters
Parameter Type
message Partial<QueueMessage> | undefined
Returns

QueueMessage

Properties

attempts
readonly attempts: number;

Delivery counter, starting at 1.

body
readonly body: Uint8Array;

Encoded body bytes.

contentType
readonly contentType: string;

Body encoding: json, text, or bytes.

id
readonly id: string;

Outbox row id; stable across redeliveries.

raw
readonly raw: Partial<QueueMessage>;

Raw wire envelope.

source
readonly source: string;

Producer plugin id; empty when the host sent it.

timestamp
readonly timestamp: Date;

When the producer sent the message.

Accessors

result
Get Signature
get result(): QueueOutcome | null;

Recorded outcome.

Returns

QueueOutcome | null

The outcome, or null while undecided.

Methods

ack()
ack(): void;

Mark handled; the host marks the message delivered.

Returns

void

json()
json<T>(): T;

Decode QueueMessage.body as JSON.

Type Parameters
Type Parameter Default type
<a id="type-parameter-t-2"></a> T unknown
Returns

T

Parsed body (null for an empty body).

retry()
retry(options?): void;

Redeliver later: after delaySeconds, or — when omitted — after the consumer's retry_delay.

Parameters
Parameter Type Description
options? QueueRetryOptions Redelivery timing and reason.
Returns

void

text()
text(): string;

Decode QueueMessage.body as UTF-8 text.

Returns

string

The body text.


RemoteLibraryEntrypoint

remoteLibrary entrypoint: lifecycle, rescan, listening sync, and user polling for a remote library server. Export it as export class RemoteLibrary extends RemoteLibraryEntrypoint.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-11"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new RemoteLibraryEntrypoint<Env>(ctx, env): RemoteLibraryEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

RemoteLibraryEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[] = REMOTE_LIBRARY_METHODS;

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

diagnose()
diagnose(): Promise<string[]>;

Operator-facing diagnostic lines.

Returns

Promise<string[]>

Probe lines.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

health()
health(): Promise<HealthOk>;

Reports whether the remote library session is usable.

Returns

Promise<HealthOk>

Health flag plus detail.

pollEvents()
pollEvents(): Promise<ExternalUser[]>;

Drains external users observed since the last poll.

Returns

Promise<ExternalUser[]>

Newly observed users.

scanLibrary()
scanLibrary(_params): Promise<void>;

Re-syncs the remote library.

Parameters
Parameter Type Description
_params ScanLibraryParams Scan scope.
Returns

Promise<void>

Resolves when the scan has been accepted.

start()
start(): Promise<void>;

Starts long-running work for this invocation.

Returns

Promise<void>

Resolves when running.

stop()
stop(): Promise<void>;

Stops long-running work for this invocation.

Returns

Promise<void>

Resolves when stopped.

syncListening()
syncListening(): Promise<ListeningProgress[]>;

Push / pull listening progress; the host upserts the rows.

Returns

Promise<ListeningProgress[]>

Progress rows.


Source

Byte source capability: job.input.

Extends

  • RpcTarget

Constructors

Constructor
new Source(): Source;
Returns

Source

Inherited from

RpcTarget.constructor

Methods

open()
open(_key): Promise<ReadResult>;

Opens key for streamed reading.

Parameters
Parameter Type Description
_key string Object key.
Returns

Promise<ReadResult>

Metadata plus a transferred body stream.


StorageEntrypoint

storage entrypoint (Destination interface): an object store the host writes acquired media into. Export it as export class Storage extends StorageEntrypoint.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-12"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new StorageEntrypoint<Env>(ctx, env): StorageEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

StorageEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[] = STORAGE_METHODS;

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

abortStage()
abortStage(_key, _commitToken): Promise<void>;

Abort a destination-side staged object.

Parameters
Parameter Type Description
_key string Object key.
_commitToken string Staging token to discard.
Returns

Promise<void>

Rejects with typed unsupported unless overridden.

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

changes()
changes(_request): Promise<ChangesPage>;

Keys changed since a cursor (declare storage.changes).

Parameters
Parameter Type Description
_request ChangesRequest Cursor and page size.
Returns

Promise<ChangesPage>

One page of changes.

commit()
commit(_key, _commitToken): Promise<PutResult>;

Finalize a destination-side staged object.

Parameters
Parameter Type Description
_key string Object key.
_commitToken string Idempotency / commit token.
Returns

Promise<PutResult>

Published object metadata.

copy()
copy(_from, _to): Promise<CopyResult>;

Server-side copy when the backend supports it.

Parameters
Parameter Type Description
_from string Source key.
_to string Destination key.
Returns

Promise<CopyResult>

Bytes copied.

delete()
delete(_key): Promise<void>;

Delete a key (no-op if missing).

Parameters
Parameter Type Description
_key string Object key.
Returns

Promise<void>

Resolves when the delete is complete.

deleteMany()
deleteMany(_keys): Promise<KeyOutcome[]>;

Remove up to MAX_BATCH_KEYS objects (declare storage.deleteMany).

Parameters
Parameter Type Description
_keys string[] Object keys.
Returns

Promise<KeyOutcome[]>

One outcome per key, in order; a missing key succeeds.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

get()
get(_key, _options?): Promise<ReadResult>;

Streamed read. The body is a transferred stream, not a scalar.

Parameters
Parameter Type Description
_key string Object key.
_options? ReadOptions Optional byte range.
Returns

Promise<ReadResult>

Metadata plus a transferred body stream.

head()
head(_key): Promise<ObjectMetadata | null>;

Metadata without a body; null when the key is missing.

Parameters
Parameter Type Description
_key string Object key.
Returns

Promise<ObjectMetadata | null>

Metadata or null when the key is missing.

headMany()
headMany(_keys): Promise<(ObjectMetadata | null)[]>;

Probe up to MAX_BATCH_KEYS objects (declare storage.headMany).

Parameters
Parameter Type Description
_keys string[] Object keys.
Returns

Promise<(ObjectMetadata | null)[]>

One entry per key, in order; null when missing.

list()
list(_options): Promise<ListPage>;

One page of keys under options.prefix.

Parameters
Parameter Type Description
_options ListOptions Prefix, cursor, and limit.
Returns

Promise<ListPage>

One page of object keys.

move()
move(
   _from, 
   _to, 
   _options
): Promise<MoveResult>;

Move one object (declare storage.move). Repeating a finished move resolves with alreadyMoved.

Parameters
Parameter Type Description
_from string Source key.
_to string Target key.
_options MoveOptions Overwrite and source preconditions.
Returns

Promise<MoveResult>

How the move was done.

moveMany()
moveMany(_request): Promise<MoveManyPage>;

Move a set of objects or a whole prefix, one page per call (declare storage.moveMany). Safe to repeat.

Parameters
Parameter Type Description
_request MoveManyRequest Pairs or prefix, cursor, and options.
Returns

Promise<MoveManyPage>

Per-key outcomes and the continuation.

put()
put(
   _key, 
   _body, 
   _options?
): Promise<PutResult>;

Streamed write. body ownership is transferred to the destination.

Parameters
Parameter Type Description
_key string Object key.
_body ReadableStream<Uint8Array<ArrayBufferLike>> Byte stream.
_options? WriteOptions Optional content type / length.
Returns

Promise<PutResult>

Bytes written and optional etag / sha256.

translateKeys()
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.

Parameters
Parameter Type Description
_keys string[] Host keys.
Returns

Promise<string[]>

One translated key per host key, in order.


StorefrontEntrypoint

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.

Extends

Type Parameters

Type Parameter Default type
<a id="type-parameter-env-13"></a> Env extends BookclerkEnv BookclerkEnv

Constructors

Constructor
new StorefrontEntrypoint<Env>(ctx, env): StorefrontEntrypoint<Env>;
Parameters
Parameter Type
ctx ExecutionContext
env Env
Returns

StorefrontEntrypoint<Env>

Inherited from

NamedEntrypoint.constructor

Properties

ctx
readonly ctx: ExecutionContext;
Inherited from

NamedEntrypoint.ctx

env
readonly env: Env;
Inherited from

NamedEntrypoint.env

invocation
invocation: Invocation;

Invocation identity of the current call (set by bookclerkInvoke).

Inherited from

NamedEntrypoint.invocation

bookclerkMethods
static bookclerkMethods: readonly string[] = STOREFRONT_METHODS;

Methods the adapter may dispatch on this entrypoint.

Overrides

NamedEntrypoint.bookclerkMethods

Methods

bookclerkInvoke()
bookclerkInvoke(
   context, 
   method, 
   ...args
): Promise<unknown>;

Internal

Adapter dispatch: install granted bindings, then call method.

Parameters
Parameter Type Description
context GrantedContext Granted bindings for this invocation.
method string Method name from the static allowlist.
...args unknown[] Method arguments.
Returns

Promise<unknown>

Method result.

Inherited from

NamedEntrypoint.bookclerkInvoke

catalogDetail()
catalogDetail(_params): Promise<CatalogHit | null>;

Full catalog record for one product; null when unknown.

Parameters
Parameter Type Description
_params CatalogDetailParams Product identifiers.
Returns

Promise<CatalogHit | null>

Catalog hit or null.

diagnose()
diagnose(): Promise<string[]>;

Operator-facing diagnostic lines.

Returns

Promise<string[]>

Probe lines.

expandCandidates()
expandCandidates(_params): Promise<CatalogHit[]>;

Related-title expansion from a seed title.

Parameters
Parameter Type Description
_params ExpandCandidatesParams Seed title plus limits.
Returns

Promise<CatalogHit[]>

Candidate hits.

fetch()
fetch(_request?): Promise<Response>;

Rejects HTTP fetch — workerd guests are Workers-RPC only.

Parameters
Parameter Type Description
_request? Request Incoming HTTP request when the entrypoint is fetch-facing.
Returns

Promise<Response>

Always a 404 empty response.

Inherited from

NamedEntrypoint.fetch

fetchTitle()
fetchTitle(_params): Promise<PlainFetch>;

Fetches one title into params.cacheDir and returns plain media paths.

Parameters
Parameter Type Description
_params FetchTitleParams Title identifiers, credentials, fetch options.
Returns

Promise<PlainFetch>

Plain media parts plus metadata.

health()
health(): Promise<HealthOk>;

Reports whether the storefront session is usable.

Returns

Promise<HealthOk>

Health flag plus detail.

listAccounts()
listAccounts(): Promise<SourceAccount[]>;

Accounts the guest knows about.

Returns

Promise<SourceAccount[]>

Account list.

listDeals()
listDeals(_params): Promise<CatalogHit[]>;

Current storefront deals.

Parameters
Parameter Type Description
_params ListDealsParams Optional filters.
Returns

Promise<CatalogHit[]>

Deal hits.

login()
login(_params): Promise<LoginResult>;

Password or one-shot OAuth login. The host seals LoginResult.credentials into encrypted_secrets.

Parameters
Parameter Type Description
_params LoginParams Login parameters.
Returns

Promise<LoginResult>

Account identity plus opaque credentials.

loginComplete()
loginComplete(_params): Promise<LoginResult>;

Finishes a login started by StorefrontEntrypoint.loginStart.

Parameters
Parameter Type Description
_params LoginCompleteParams Continuation plus user input.
Returns

Promise<LoginResult>

Account identity plus opaque credentials.

loginStart()
loginStart(_params): Promise<LoginStartResult>;

Begins an interactive OAuth login.

Parameters
Parameter Type Description
_params LoginParams Login parameters.
Returns

Promise<LoginStartResult>

Continuation for StorefrontEntrypoint.loginComplete.

purchaseHint()
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.

Parameters
Parameter Type Description
_params PurchaseHintParams Title identifiers and how to look the title up.
Returns

Promise< | PurchaseHint | PurchaseHintAnswer | null>

Hint, an answer with title-search records, or null.

purchaseHints()
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.

Parameters
Parameter Type Description
params PurchaseHintsParams The titles to price, in order.
Returns

Promise<( | PurchaseHint | PurchaseHintAnswer | null)[]>

One hint, answer with records, or null per query.

qualityOffers()
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.

Parameters
Parameter Type Description
_params QualityOffersParams Account, its credentials, settings and title ids.
Returns

Promise<QualityOffersResult>

One answer per title, plus any refreshed credentials.

revokeAccount()
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.

Parameters
Parameter Type Description
_params RevokeAccountParams Account id and its stored credentials.
Returns

Promise<void>

Resolves when the store sign-out finished.

scan()
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.

Parameters
Parameter Type Description
_params ScanParams The account, its credential, the cursor and the sync token.
Returns

Promise<ScanPage>

At most MAX_SCAN_PAGE_BOOKS books plus the paging fields.

searchCatalog()
searchCatalog(_params): Promise<CatalogHit[]>;

Free-text storefront catalog search.

Parameters
Parameter Type Description
_params SearchCatalogParams Query parameters.
Returns

Promise<CatalogHit[]>

Catalog hits.

Interfaces

AdapterEnv

Trusted adapter env. Authors never see this type on their class.

Properties

BRIDGE_TOKEN?
BRIDGE_TOKEN?: string;

Isolate-to-host bridge bearer.

GRANTED?
GRANTED?: GrantedFetcher;

Per-invocation grant reverse channel.

PLUGIN?
PLUGIN?: AuthorStub;

Author default entrypoint.

PLUGIN_CLI?
PLUGIN_CLI?: NamedStub;
PLUGIN_DATABASE_ADAPTER?
PLUGIN_DATABASE_ADAPTER?: NamedStub;
PLUGIN_DESCRIBE?
PLUGIN_DESCRIBE?: string | PluginDescribe;

Manifest PluginDescribe projection (JSON binding).

PLUGIN_OIDC?
PLUGIN_OIDC?: NamedStub;
PLUGIN_REMOTE_LIBRARY?
PLUGIN_REMOTE_LIBRARY?: NamedStub;
PLUGIN_STORAGE?
PLUGIN_STORAGE?: NamedStub;
PLUGIN_STOREFRONT?
PLUGIN_STOREFRONT?: NamedStub;

Named author entrypoints (PLUGIN_STOREFRONT, PLUGIN_STORAGE, …).


BridgeContext

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.

Extends

  • Omit<GrantedContext, "databases" | "queues" | "kv" | "sockets" | "origin">

Properties

ai?
ai?: AiBinding;

AI binding, when [ai].calls is declared and granted.

Inherited from

GrantedContext.ai

aiToken?
aiToken?: string;

Granted-channel bearer for env.AI.run; stripped before dispatch.

config?
config?: ExtensibleConfig;

Operator settings for this plugin as application/json.

Inherited from

GrantedContext.config

databases?
databases?: Record<string, string>;

Named [[databases]] binding → database-only bearer for /db/execute.

events?
events?: EventPublisherBinding;

EVENTS publisher, when [[events.producers]] is granted.

Inherited from

GrantedContext.events

eventsToken?
eventsToken?: string;

Granted-channel bearer for env.EVENTS.publish; stripped before dispatch.

invocation?
invocation?: Partial<Invocation>;

Invocation identity (Invocation struct).

Inherited from

GrantedContext.invocation

kv?
kv?: Record<string, string>;

[[kv_namespaces]] binding → kv-only bearer for /kv/*.

network?
network?: NetworkGrant;

The network grant in effect, handed to the author as env.NETWORK.

Inherited from

GrantedContext.network

notify?
notify?: NotifyBinding;

NOTIFY binding, when [[notifications.types]] is declared.

Inherited from

GrantedContext.notify

notifyToken?
notifyToken?: string;

Granted-channel bearer for env.NOTIFY.raise; stripped before dispatch.

originToken?
originToken?: string;

Origin-only bearer for /origin/fetch; stripped before dispatch.

queues?
queues?: Record<string, string>;

[[queues.producers]] binding → queue-only bearer for /queues/send.

secrets?
secrets?: ExtensibleConfig;

Granted secret values as application/json.

Inherited from

GrantedContext.secrets

sockets?
sockets?: Record<string, string>;

[sockets] binding → sockets-only bearer for /sockets/*.

storage?
storage?: Destination;

WORK_FS object store, when granted.

Inherited from

GrantedContext.storage

webhooks?
webhooks?: WebhooksTransport;

The WEBHOOKS grant, when [[webhooks]] is declared.

Inherited from

GrantedContext.webhooks

webhooksToken?
webhooksToken?: string;

Webhooks-only bearer for /webhooks/*; stripped before dispatch.


ByteRange

Optional byte range for a streamed read.

Properties

length?
length?: number;
offset
offset: number;

CancelWatchLike

Host cancellation watch delivered to a job controller (adapter-internal).

Methods

wait()
wait(): Promise<void>;

Resolves once the host cancels the invocation.

Returns

Promise<void>


ChangesPage

One page of StorageEntrypoint.changes.

Properties

changes
changes: ObjectChange[];
complete
complete: boolean;

False when the feed may have missed changes (overflow, expired retention); the host then backs it with a full listing.

cursor
cursor: string;

Cursor for the next call; never empty.

more?
more?: boolean;

True when more changes are ready now.


ChangesRequest

Argument of StorageEntrypoint.changes.

Properties

cursor?
cursor?: string;

The previous page's cursor; absent asks for the current position.

limit?
limit?: number;

Requested changes per page (at most MAX_CHANGES_PAGE).


CopyResult

Result of a server-side copy.

Properties

bytesCopied
bytesCopied: number;

DeliveredCheckpoint

A prior checkpoint delivered on resume.

Properties

json
json: string;

Checkpoint JSON text as recorded by the earlier suspend().

schemaVersion
schemaVersion: number;

Schema version the author attached to the checkpoint.


EventSuspendOptions

Options for EventMessage.suspend.

Properties

checkpoint?
checkpoint?: Checkpoint;

Bounded checkpoint replayed on resume (at most maxCheckpointBytes).

checkpointSchemaVersion?
checkpointSchemaVersion?: number;

Schema version of checkpoint (default 1).

wakeAt?
wakeAt?: Instant;

Earliest resume instant.

wakeOnEventType?
wakeOnEventType?: string;

Also wake when an event of this type arrives.

wakeOnFilter?
wakeOnFilter?: string | JsonObject;

Host-owned payload filter for wake events (object or JSON text).


GrantedContext

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.

Extended by

Properties

ai?
ai?: AiBinding;

AI binding, when [ai].calls is declared and granted.

config?
config?: ExtensibleConfig;

Operator settings for this plugin as application/json.

databases?
databases?: NamedDatabase[];

Named [[databases]] bindings.

events?
events?: EventPublisherBinding;

EVENTS publisher, when [[events.producers]] is granted.

invocation?
invocation?: Partial<Invocation>;

Invocation identity (Invocation struct).

kv?
kv?: NamedKv[];

[[kv_namespaces]] bindings, when granted.

network?
network?: NetworkGrant;

The network grant in effect, handed to the author as env.NETWORK.

notify?
notify?: NotifyBinding;

NOTIFY binding, when [[notifications.types]] is declared.

origin?
origin?: OriginTransport;

ORIGIN, the library a relay ingress plugin serves, when this instance is the active ingress.

queues?
queues?: NamedQueue[];

[[queues.producers]] bindings, when granted.

secrets?
secrets?: ExtensibleConfig;

Granted secret values as application/json.

sockets?
sockets?: NamedSockets[];

The [sockets] binding, when granted (at most one entry).

storage?
storage?: Destination;

WORK_FS object store, when granted.

webhooks?
webhooks?: WebhooksTransport;

The WEBHOOKS grant, when [[webhooks]] is declared.


GrantedDatabaseTransport

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.

Extends

Methods

execute()
execute(request): Promise<ExecuteReply>;

Runs one typed atomic batch.

Parameters
Parameter Type Description
request ExecuteRequest Structured Cap'n ExecuteRequest.
Returns

Promise<ExecuteReply>

Structured ExecuteReply.

Inherited from

AtomicTransport.execute

executeBytes()
executeBytes(bytes): Promise<Uint8Array<ArrayBufferLike>>;

Same batch as AtomicTransport.execute, as Cap'n Proto bytes (ExecuteRequest in, ExecuteResultReply out).

Parameters
Parameter Type Description
bytes Uint8Array Unpacked ExecuteRequest message.
Returns

Promise<Uint8Array<ArrayBufferLike>>

Unpacked ExecuteResultReply message.

executeStreamed()?
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.

Parameters
Parameter Type Description
request ExecuteRequest Structured ExecuteRequest.
Returns

Promise< | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array<ArrayBufferLike>>>

The frame sequence as the channel delivers it.

Overrides

AtomicTransport.executeStreamed

executeStreamedBytes()?
executeStreamedBytes?(bytes): Promise<Uint8Array<ArrayBufferLike>>;

Same frames as GrantedDatabaseTransport.executeStreamed, whole, from Cap'n request bytes (Python authors decode locally). Optional like GrantedDatabaseTransport.executeStreamed.

Parameters
Parameter Type Description
bytes Uint8Array Unpacked ExecuteRequest message.
Returns

Promise<Uint8Array<ArrayBufferLike>>

Every ExecuteStreamFrame, concatenated.

limits()
limits(): Promise<DbCapabilities>;

Negotiated limits of the granted session (GuestDatabase.limits).

Returns

Promise<DbCapabilities>

The adapter's DbCapabilities for this binding.

Overrides

AtomicTransport.limits

limitsBytes()
limitsBytes(): Promise<Uint8Array<ArrayBufferLike>>;

Same answer as GrantedDatabaseTransport.limits, as Cap'n Proto bytes (DbCapabilitiesReply) for Python authors.

Returns

Promise<Uint8Array<ArrayBufferLike>>

Unpacked DbCapabilitiesReply message.

openStreamedBytes()?
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.

Parameters
Parameter Type Description
bytes Uint8Array Unpacked ExecuteRequest message.
Returns

Promise< | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array<ArrayBufferLike>>>

The frame sequence, streamed when the channel streams it.


GrantedFetcher

Reverse-channel fetcher bound as GRANTED on the adapter isolate.

Methods

fetch()
fetch(input, init?): Promise<Response>;

Call the host grant broker.

Parameters
Parameter Type Description
input string Request URL.
init? RequestInit Optional fetch init.
Returns

Promise<Response>

Host response.


GrantedJobCapabilities

Granted capabilities for one job() invocation (adapter-internal).

Properties

cancel?
cancel?: CancelWatchLike | null;
input?
input?: Source | null;
output?
output?: Destination | null;
progress?
progress?: ProgressSink | null;

JobCheckpoint

Bounded, versioned checkpoint.

Properties

json
json: string;
schemaVersion
schemaVersion: number;

JobCompletion

Value a job() handler may return to annotate a completed outcome.

Properties

bytesCopied?
bytesCopied?: number;

Bytes copied by the job, when meaningful.

message?
message?: string;

Operator-facing summary.


JobRetryOptions

Options for JobController.retryLater.

Properties

reason?
reason?: string;

Short operator-facing reason.

retryAt?
retryAt?: Instant;

Earliest retry instant; omitted lets the host choose.


JobRunnerContext

Job-runner bridge context: the durable job id plus GrantedContext.

Extends

Properties

ai?
ai?: AiBinding;

AI binding, when [ai].calls is declared and granted.

Inherited from

GrantedContext.ai

config?
config?: ExtensibleConfig;

Operator settings for this plugin as application/json.

Inherited from

GrantedContext.config

databases?
databases?: NamedDatabase[];

Named [[databases]] bindings.

Inherited from

GrantedContext.databases

events?
events?: EventPublisherBinding;

EVENTS publisher, when [[events.producers]] is granted.

Inherited from

GrantedContext.events

invocation?
invocation?: Partial<Invocation>;

Invocation identity (Invocation struct).

Inherited from

GrantedContext.invocation

jobId?
jobId?: string;

Durable job id (Invocation.id of the job open).

kv?
kv?: NamedKv[];

[[kv_namespaces]] bindings, when granted.

Inherited from

GrantedContext.kv

network?
network?: NetworkGrant;

The network grant in effect, handed to the author as env.NETWORK.

Inherited from

GrantedContext.network

notify?
notify?: NotifyBinding;

NOTIFY binding, when [[notifications.types]] is declared.

Inherited from

GrantedContext.notify

origin?
origin?: OriginTransport;

ORIGIN, the library a relay ingress plugin serves, when this instance is the active ingress.

Inherited from

GrantedContext.origin

queues?
queues?: NamedQueue[];

[[queues.producers]] bindings, when granted.

Inherited from

GrantedContext.queues

secrets?
secrets?: ExtensibleConfig;

Granted secret values as application/json.

Inherited from

GrantedContext.secrets

sockets?
sockets?: NamedSockets[];

The [sockets] binding, when granted (at most one entry).

Inherited from

GrantedContext.sockets

storage?
storage?: Destination;

WORK_FS object store, when granted.

Inherited from

GrantedContext.storage

webhooks?
webhooks?: WebhooksTransport;

The WEBHOOKS grant, when [[webhooks]] is declared.

Inherited from

GrantedContext.webhooks


JobSuspendOptions

Options for JobController.suspend.

Properties

checkpoint?
checkpoint?: Checkpoint;

Bounded checkpoint replayed on resume (at most maxCheckpointBytes).

checkpointSchemaVersion?
checkpointSchemaVersion?: number;

Schema version of checkpoint (default 1).

wakeAt?
wakeAt?: Instant;

Earliest resume instant.


KeyOutcome

Outcome for one key of a batch call; error is absent on success.

Properties

error?
error?: object;
code
code: string;
message
message: string;
key
key: string;

ListOptions

Paginated list request.

Properties

cursor?
cursor?: string;
limit?
limit?: number;
modifiedSinceMs?
modifiedSinceMs?: number;

Hint: only objects modified at or after this UTC unix millisecond. Say whether you filtered in ListPage.modifiedSinceApplied.

prefix?
prefix?: string;
withSignatures?
withSignatures?: boolean;

Hint: fill the signature fields of each entry. Say whether you did in ListPage.signaturesIncluded.


ListPage

One page of keys.

Properties

modifiedSinceApplied?
modifiedSinceApplied?: boolean;

True when objects modified before modifiedSinceMs were left out.

nextCursor?
nextCursor?: string;
objects
objects: ObjectInfo[];
signaturesIncluded?
signaturesIncluded?: boolean;

True when every entry carries the signature fields the backend has.


MoveManyPage

One page of StorageEntrypoint.moveMany progress.

Properties

atomic?
atomic?: boolean;

True when every move in this page was atomic.

nextCursor?
nextCursor?: string;

Prefix form: cursor for the next call; absent when done.

objectsMoved?
objectsMoved?: number;

Objects moved in this page.

results
results: KeyOutcome[];

Outcomes in request order (one per pair for the pairs form).


MoveManyRequest

Argument of StorageEntrypoint.moveMany.

Properties

cursor?
cursor?: string;

Prefix form: the previous page's nextCursor; absent starts.

limit?
limit?: number;

Prefix form: objects to move in this call (at most MAX_BATCH_KEYS).

options?
options?: MoveOptions;

Overwrite rule applied to every move.

target
target: MoveManyTarget;

Explicit pairs, or every object under a prefix.


MoveOptions

Options for StorageEntrypoint.move and StorageEntrypoint.moveMany.

Properties

ifSourceMatch?
ifSourceMatch?: string;

move only: move only while the source's etag equals this value.

noOverwrite?
noOverwrite?: boolean;

Reject with conflict instead of replacing an object at the target.


MoveResult

How a single move was done.

Properties

alreadyMoved?
alreadyMoved?: boolean;

True when the source was already gone and the target present.

atomic
atomic: boolean;

True when the move was atomic (a rename).


NamedDatabase

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.

Properties

database?
database?: DatabaseBinding;

Ready binding (same isolate).

name
name: string;

Binding name (env.<name>).

transport?
transport?: GrantedDatabaseTransport;

Granted transport (crosses the adapter → author RPC boundary).


NamedKv

One granted [[kv_namespaces]] binding on the granted context.

Properties

kv
kv: KvNamespaceBinding;

Ready namespace (crosses the adapter → author RPC boundary).

name
name: string;

Binding name (env.<name>).


NamedQueue

One granted [[queues.producers]] binding on the granted context.

Properties

name
name: string;

Binding name (env.<name>).

queue
queue: QueueBinding;

Ready producer (crosses the adapter → author RPC boundary).


NamedSockets

The granted [sockets] binding on the granted context.

Properties

name
name: string;

Binding name (env.<name>, SOCKETS unless renamed).

sockets
sockets: SocketsTransport;

The adapter's grant (crosses the adapter → author RPC boundary).


ObjectChange

One entry of a change feed.

Properties

info?
info?: ObjectInfo;

Listing fields after the change, when the feed carries them.

key
key: string;
kind
kind: "changed" | "upserted" | "removed";

ObjectInfo

Object listing entry. The signature fields are set only when the listing was asked for them (ListOptions.withSignatures).

Properties

etag?
etag?: string;

Opaque backend entity tag.

key
key: string;
modifiedAtMs?
modifiedAtMs?: number;

Last modification time, UTC unix milliseconds.

signature?
signature?: string;

Opaque change signature: unchanged means the object did not change.

size
size: number;
versionId?
versionId?: string;

Backend object version id (versioned buckets).


ObjectMetadata

Metadata without a body.

Properties

contentType?
contentType?: string;
etag?
etag?: string;
key
key: string;
modifiedAtMs?
modifiedAtMs?: number;

Last modification time, UTC unix milliseconds.

sha256?
sha256?: Uint8Array<ArrayBufferLike>;
signature?
signature?: string;

Opaque change signature, as ObjectInfo.signature.

size
size: number;
versionId?
versionId?: string;

Backend object version id (versioned buckets).


PurchaseHintAnswer

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.

Properties

hint
hint: PurchaseHint | null;

The store's own pick, or null when it found nothing.

records
records: PricedRecord[];

Every priced listing the search matched, with its full catalog record.


PutResult

Result of a streamed put.

Properties

bytesWritten
bytesWritten: number;
etag?
etag?: string;
key
key: string;
modifiedAtMs?
modifiedAtMs?: number;

Modification time of the stored object, UTC unix milliseconds.

sha256?
sha256?: Uint8Array<ArrayBufferLike>;
signature?
signature?: string;

Change signature of the stored object.

versionId?
versionId?: string;

Version id of the stored object.


QueueRetryOptions

Options for QueueMessage.retry.

Properties

delaySeconds?
delaySeconds?: number;

Seconds before redelivery; 0 applies the consumer's retry_delay.

reason?
reason?: string;

Short operator-facing reason.


ReadOptions

Read options for StorageEntrypoint.get.

Properties

range?
range?: ByteRange;

ReadResult

Streamed read result. body is a transferred ReadableStream.

Properties

body
body: ReadableStream<Uint8Array<ArrayBufferLike>>;
meta
meta: ObjectMetadata;

RetryOptions

Options for EventMessage.retry.

Properties

delaySeconds?
delaySeconds?: number;

Delay from now, in seconds; ignored when retryAt is set.

reason?
reason?: string;

Short operator-facing reason.

retryAt?
retryAt?: Instant;

Explicit earliest redelivery instant.


WireEventBatch

Wire EventBatch as the adapter delivers it to bookclerkEvent.

Properties

events
events: Partial<DomainEvent>[];

WireQueueBatch

Wire QueueBatch as the adapter delivers it to bookclerkQueue.

Properties

messages
messages: Partial<QueueMessage>[];
queue
queue: string;

WriteOptions

Write options for StorageEntrypoint.put.

Properties

commitToken?
commitToken?: string;
contentLength?
contentLength?: number;
contentType?
contentType?: string;
ifMatch?
ifMatch?: string;

Conditional write (storage.conditionalWrite): publish only while the stored object's etag equals this value, else reject with conflict.

ifNoneMatch?
ifNoneMatch?: boolean;

Conditional write (storage.conditionalWrite): publish only when no object exists at the key, else reject with conflict.

sha256?
sha256?: Uint8Array<ArrayBufferLike>;
stageOnly?
stageOnly?: boolean;

Type Aliases

AuthorStub

type AuthorStub = Pick<BookclerkEntrypoint, 
  | "bookclerkDescribe"
  | "bookclerkEvent"
  | "bookclerkQueue"
  | "bookclerkScheduled"
  | "bookclerkSocketMessage"
  | "bookclerkSocketClosed"
  | "bookclerkWebhookDelivered"
  | "bookclerkJob"
  | "bookclerkDatabaseMigrations"
| "bookclerkShutdown">;

Author default entrypoint as seen through the PLUGIN service binding.


Checkpoint

type Checkpoint = 
  | string
  | JsonObject
  | unknown[]
  | number
  | boolean
  | null;

JSON-serializable checkpoint accepted by suspend().


EntrypointName

type EntrypointName = 
  | "storefront"
  | "storage"
  | "databaseAdapter"
  | "remoteLibrary"
  | "cli"
  | "oidc"
  | "metadata"
  | "covers"
  | "metadataFiles"
  | "notifier"
  | "ingress"
  | "ai";

Wire name of each named entrypoint (plugin.toml entrypoints).


EventOutcome

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).


Instant

type Instant = Date | number;

Wall-clock instant accepted by retry / suspend: a Date or Unix ms.


JobOutcomeRecord

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).


NamedStub

type NamedStub = Pick<NamedEntrypoint, "bookclerkInvoke">;

Named author entrypoint as seen through a PLUGIN_<ENTRYPOINT> binding.


PluginDescribe

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.


QueueOutcome

type QueueOutcome = 
  | {
  kind: "ack";
}
  | {
  delaySeconds: number;
  kind: "retry";
  reason: string;
};

Recorded per-message outcome of a queue() handler (bridge projection of QueueResult).

Variables

ENTRYPOINT_BINDINGS

const ENTRYPOINT_BINDINGS: Readonly<Record<EntrypointName, string>>;

Adapter binding name for each named entrypoint.


ENTRYPOINT_CLASSES

const ENTRYPOINT_CLASSES: Readonly<Record<EntrypointName, string>>;

Exported class name the launcher binds for each named entrypoint.


PURCHASE_HINTS_BUDGET_MS

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.


PURCHASE_HINTS_CONCURRENCY

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.


TRIGGER_FAMILIES

const TRIGGER_FAMILIES: Readonly<Record<
  | "eventConsumer"
  | "queueConsumer"
  | "scheduledHandler"
  | "jobRunner"
  | "socketHandler"
| "webhookHandler", string>>;

Wire names of the trigger families the launcher may ask openInvocation about.

Functions

allowedEntrypointFamilies()

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.

Parameters

Parameter Type Description
capabilities | Partial<PluginCapabilities> | null | undefined Manifest capabilities from PLUGIN_DESCRIBE.
requested readonly string[] Family names the launcher wants to export.

Returns

string[]

The authorized subset in request order.


cliArgs()

function cliArgs(params): Record<string, string>;

Turns CliInvokeParams.args ([{ name, value }]) into a plain { name: value } object for CLI handlers.

Parameters

Parameter Type Description
params | Pick<CliInvokeParams, "args"> | undefined CLI invocation params from the host.

Returns

Record<string, string>

Argument values keyed by name.


dataMigrationOp()

function dataMigrationOp(sql): object;

Data DML convenience for PluginMigration operations.

Parameters

Parameter Type Description
sql string Already-separated BookclerkSQL data statement.

Returns

object

Data operation tagged for host registration.

Name Type
data string

decodeExtensibleConfig()

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.

Parameters

Parameter Type Description
cfg unknown Wire config struct, a pre-decoded object, or undefined.

Returns

JsonObject

Plain JSON object ({} when empty or malformed).


eventBatchResults()

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.

Parameters

Parameter Type Description
batch EventBatch Delivered batch after the handler ran.
failed unknown Error thrown by the handler, if any.

Returns

EventOutcome[]

One outcome per message, in order.


fromBridgeJson()

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.

Parameters

Parameter Type Description
value unknown Bridge JSON value.

Returns

unknown

Typed struct value.


invocationOf()

function invocationOf(context): Invocation;

Invocation envelope (Invocation struct) with zero values normalized.

Parameters

Parameter Type Description
context GrantedContext | undefined Granted context carrying invocation.

Returns

Invocation

Frozen invocation identity.


jobOutcomeFor()

function jobOutcomeFor(
   job, 
   returned, 
   failed
): JobOutcomeRecord;

Translate a job() handler's return / throw into the wire outcome.

Parameters

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.

Returns

JobOutcomeRecord

Wire job outcome.


jsonPayload()

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.

Parameters

Parameter Type Description
value unknown JSON-serializable value.

Returns

ExtensibleConfig

Wire-shaped extensible payload.


packEmbeddingVectors()

function packEmbeddingVectors(vectors): Uint8Array;

Packs embedding vectors into the wire form of AiTextEmbeddingsOutput.vectors: little-endian 32-bit floats, concatenated.

Parameters

Parameter Type Description
vectors readonly ArrayLike<number>[] One vector per input text, all of one length.

Returns

Uint8Array

The bytes.


queueBatchResults()

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.

Parameters

Parameter Type Description
batch QueueBatch Delivered batch after the handler ran.
failed unknown Error thrown by the handler, if any.

Returns

QueueOutcome[]

One outcome per message, in order.


scheduledControllerOf()

function scheduledControllerOf(wire): Readonly<ScheduledController>;

Frozen author view of one wire ScheduledController, with every field present and typed.

Parameters

Parameter Type Description
wire | Partial<ScheduledController> | null | undefined Decoded wire struct (fields may be missing).

Returns

Readonly<ScheduledController>

The controller the author's scheduled() receives.


schemaMigrationOp()

function schemaMigrationOp(sql): object;

Schema DDL convenience for PluginMigration operations.

Parameters

Parameter Type Description
sql string Already-separated BookclerkSQL schema statement.

Returns

object

Schema operation tagged for host registration.

Name Type
schema string

toBridgeJson()

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.

Parameters

Parameter Type Description
value unknown Plain typed struct value.

Returns

unknown

JSON-safe projection.


unpackEmbeddingVectors()

function unpackEmbeddingVectors(bytes, dimensions): number[][];

Splits the wire form of AiTextEmbeddingsOutput.vectors into vectors.

Parameters

Parameter Type Description
bytes Uint8Array Little-endian 32-bit floats, concatenated.
dimensions number Numbers per vector.

Returns

number[][]

One vector per dimensions numbers.

Throws

internal when the bytes are not whole vectors.


wrapPluginFromBinding()

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.

Returns

typeof InvocationAdapter

Adapter entrypoint class bound to AdapterEnv.


wrapPluginFromNative()

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.

Returns

typeof InvocationAdapter

Adapter entrypoint class bound to AdapterEnv.

References

AiEmbedText

Re-exports AiEmbedText


AiInput

Re-exports AiInput


AiModel

Re-exports AiModel


AiModelList

Re-exports AiModelList


AiOutput

Re-exports AiOutput


AiRunOk

Re-exports AiRunOk


AiRunParams

Re-exports AiRunParams


AiTask

Re-exports AiTask


AiTextEmbeddingsInput

Re-exports AiTextEmbeddingsInput


AiTextEmbeddingsOutput

Re-exports AiTextEmbeddingsOutput


AiTextRole

Re-exports AiTextRole


CliInvokeParams

Re-exports CliInvokeParams


CliInvokeResult

Re-exports CliInvokeResult


CliSchema

Re-exports CliSchema


CoverFetchParams

Re-exports CoverFetchParams


CoverImage

Re-exports CoverImage


CoverImages

Re-exports CoverImages


DomainEvent

Re-exports DomainEvent


ExtensibleConfig

Re-exports ExtensibleConfig


FEATURE_SCALAR_LIMITS

Re-exports FEATURE_SCALAR_LIMITS


FEATURE_STORAGE_CHANGES

Re-exports FEATURE_STORAGE_CHANGES


FEATURE_STORAGE_CONDITIONAL_WRITE

Re-exports FEATURE_STORAGE_CONDITIONAL_WRITE


FEATURE_STORAGE_COPY

Re-exports FEATURE_STORAGE_COPY


FEATURE_STORAGE_DELETE_MANY

Re-exports FEATURE_STORAGE_DELETE_MANY


FEATURE_STORAGE_HEAD_MANY

Re-exports FEATURE_STORAGE_HEAD_MANY


FEATURE_STORAGE_MOVE

Re-exports FEATURE_STORAGE_MOVE


FEATURE_STORAGE_MOVE_MANY

Re-exports FEATURE_STORAGE_MOVE_MANY


FEATURE_STREAMS

Re-exports FEATURE_STREAMS


HealthOk

Re-exports HealthOk


Invocation

Re-exports Invocation


JobInvocation

Re-exports JobInvocation


MAX_BATCH_KEYS

Re-exports MAX_BATCH_KEYS


MAX_CHANGES_CURSOR_BYTES

Re-exports MAX_CHANGES_CURSOR_BYTES


MAX_CHANGES_PAGE

Re-exports MAX_CHANGES_PAGE


MAX_CHECKPOINT_BYTES

Re-exports MAX_CHECKPOINT_BYTES


MAX_EVENT_PAYLOAD_BYTES

Re-exports MAX_EVENT_PAYLOAD_BYTES


MAX_LIST_PAGE

Re-exports MAX_LIST_PAGE


MAX_PLUGIN_MIGRATION_OPS

Re-exports MAX_PLUGIN_MIGRATION_OPS


MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES

Re-exports MAX_PLUGIN_MIGRATION_REGISTRATION_BYTES


MAX_PLUGIN_MIGRATION_TOTAL_OPS

Re-exports MAX_PLUGIN_MIGRATION_TOTAL_OPS


MAX_SCALAR_BYTES

Re-exports MAX_SCALAR_BYTES


MAX_STREAM_WINDOW_BYTES

Re-exports MAX_STREAM_WINDOW_BYTES


MetadataAudioFile

Re-exports MetadataAudioFile


MetadataChapter

Re-exports MetadataChapter


MetadataChapters

Re-exports MetadataChapters


MetadataChaptersParams

Re-exports MetadataChaptersParams


MetadataField

Re-exports MetadataField


MetadataFileParsed

Re-exports MetadataFileParsed


MetadataFileParseParams

Re-exports MetadataFileParseParams


MetadataFileRecord

Re-exports MetadataFileRecord


MetadataFileRendered

Re-exports MetadataFileRendered


MetadataFileRenderParams

Re-exports MetadataFileRenderParams


MetadataLookupParams

Re-exports MetadataLookupParams


MetadataRecord

Re-exports MetadataRecord


MetadataSearchParams

Re-exports MetadataSearchParams


NetworkGrant

Re-exports NetworkGrant


NotificationAlertAction

Re-exports NotificationAlertAction


NotificationAudience

Re-exports NotificationAudience


NotificationField

Re-exports NotificationField


NotificationMessage

Re-exports NotificationMessage


NotificationSeverity

Re-exports NotificationSeverity


NotifyDestination

Re-exports NotifyDestination


NotifyDestinationKind

Re-exports NotifyDestinationKind


NotifyRaised

Re-exports NotifyRaised


NotifyRaiseParams

Re-exports NotifyRaiseParams


NotifySendParams

Re-exports NotifySendParams


NotifySent

Re-exports NotifySent


NotifyValidated

Re-exports NotifyValidated


NotifyValidateParams

Re-exports NotifyValidateParams


OidcClientTemplate

Re-exports OidcClientTemplate


PluginCapabilities

Re-exports PluginCapabilities


PluginError

Re-exports PluginError


PluginMigration

Re-exports PluginMigration


PluginMigrationOp

Re-exports PluginMigrationOp


PRODUCT_API_VERSION

Re-exports PRODUCT_API_VERSION


requirePluginMigrationRegistration

Re-exports requirePluginMigrationRegistration


ScalarLimits

Re-exports ScalarLimits

Generated from packages/plugin-sdk at main · View as Markdown