ocel 0.0.1-alpha.0 → 0.0.1

package/dist/realtime/realtime.js

@@ -0,0 +1,205 @@
+import { randomBytes } from "node:crypto";
+import { createClient } from "@connectrpc/connect";
+import { getConfig, refuseUnbound } from "../binding/binding.js";
+import { unprovisioned, unprovisionedPhase } from "../binding/unprovisioned.js";
+import { declarationSite } from "../declaration/callsite.js";
+import { defer } from "../declaration/defer.js";
+import { encodeDuration, parseDurationMilliseconds } from "../delivery/duration.js";
+import { encodeJsonSchema, validatePayload } from "../delivery/schema.js";
+import { RealtimeService } from "../gen/proto/app/realtime/v1/realtime_pb.js";
+import { RealtimePublish, RealtimeSubscribe, ResourceType, } from "../gen/proto/app/resources/v1/resources_pb.js";
+import { rpc } from "../runtime/rpc.js";
+import { createRuntimeTransport } from "../runtime/transport.js";
+import { encodeWireChannel, isChannelNamespace, parseChannelPattern, } from "./wire.js";
+/** Thrown by `publish` when the pattern, params or body cannot be published, naming why. */
+export class RealtimePublishError extends Error {
+    name = "RealtimePublishError";
+    /**
+     * The reason: `unknown-pattern`, `invalid-params`, `missing-param`, `unknown-param`,
+     * `empty-value`, `value-too-long`, `invalid-body` or `body-too-large`.
+     */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const runtimes = new WeakMap();
+/** Reads what the realtime handler serves of `rt`, throwing for one `realtime()` did not declare. */
+export function readRuntime(rt) {
+    const runtime = runtimes.get(rt);
+    if (!runtime)
+        throw new Error("the realtime handler takes a resource declared by realtime()");
+    return runtime;
+}
+const minTtlSeconds = 10;
+const maxTtlSeconds = 300;
+const defaultTtl = "60s";
+/** A declared realtime resource, and the handle its channels are published through. */
+export class Realtime {
+    /** The name this resource was declared under, which begins every channel. */
+    name;
+    constructor(name, options) {
+        this.name = name;
+        const what = `realtime("${name}")`;
+        if (!isChannelNamespace(name)) {
+            throw new Error(`${what}: the name begins every channel, so it is letters, digits and -, at most 50 characters, starting and ending with a letter or digit`);
+        }
+        const ttl = options.tokenTtl ?? defaultTtl;
+        const ttlSeconds = parseDurationMilliseconds(ttl) / 1_000;
+        if (!Number.isInteger(ttlSeconds) || ttlSeconds < minTtlSeconds || ttlSeconds > maxTtlSeconds) {
+            throw new Error(`${what}: token ttl ${ttlSeconds}s is outside ${minTtlSeconds}s to ${maxTtlSeconds}s in whole seconds: a token lives long enough to open a socket and no longer`);
+        }
+        const channels = new Map();
+        for (const [written, declared] of Object.entries(options.channels)) {
+            let pattern;
+            try {
+                pattern = parseChannelPattern(written);
+            }
+            catch (cause) {
+                throw new Error(`${what}: ${cause.message}`);
+            }
+            if (!declared.schema?.["~standard"]) {
+                throw new Error(`${what}: channel "${written}" takes a Standard Schema as its schema, and was given none`);
+            }
+            if (!options.authorize && (declared.subscribe !== "public" || declared.publish)) {
+                throw new Error(`${what}: channel "${written}" declares a rule, which decides from the caller's auth, and the resource declares no authorize to say who calls`);
+            }
+            channels.set(written, {
+                pattern,
+                schema: declared.schema,
+                wildcard: declared.wildcard ?? false,
+                subscribe: declared.subscribe,
+                publish: declared.publish,
+            });
+        }
+        if (process.env.OCEL_PHASE === "discovery") {
+            const source = declarationSite();
+            defer(rpc.resource.declare({
+                resource: { name, type: ResourceType.REALTIME },
+                config: {
+                    case: "realtime",
+                    value: {
+                        tokenTtl: encodeDuration(ttl),
+                        channels: [...channels].map(([written, channel]) => ({
+                            pattern: written,
+                            wildcard: channel.wildcard,
+                            schema: encodeJsonSchema(channel.schema),
+                            subscribe: channel.subscribe === "public"
+                                ? RealtimeSubscribe.PUBLIC
+                                : RealtimeSubscribe.RULE,
+                            publish: channel.publish ? RealtimePublish.RULE : RealtimePublish.SERVER,
+                            source,
+                        })),
+                    },
+                },
+                source,
+            }));
+        }
+        let client;
+        runtimes.set(this, {
+            name,
+            ttlSeconds,
+            channels,
+            authorize: options.authorize,
+            properties: (access) => {
+                if (unprovisionedPhase())
+                    throw unprovisioned(what, access);
+                return getConfig(name, "realtime");
+            },
+            publish: async (access, channel, envelope) => {
+                if (unprovisionedPhase())
+                    throw unprovisioned(what, access);
+                const refusal = refuseUnbound(name, "realtime");
+                if (refusal)
+                    throw refusal;
+                client ??= createClient(RealtimeService, createRuntimeTransport());
+                try {
+                    await client.publish({ realtime: name, channel, event: envelope });
+                }
+                catch (cause) {
+                    throw new Error(`${what}: publish on ${channel}: ${cause.message}`, { cause });
+                }
+            },
+        });
+    }
+    /**
+     * Publishes `body` on the channel `params` fill in `pattern`, to every subscriber, after
+     * validating it against the pattern's schema. Every param is required. Throws a
+     * {@link RealtimePublishError} for a pattern, params or body that cannot be published.
+     */
+    async publish(pattern, message) {
+        const runtime = readRuntime(this);
+        const prepared = await prepareEvent(runtime, pattern, message.params ?? {}, message.body);
+        if ("refused" in prepared) {
+            throw new RealtimePublishError(prepared.refused, `realtime("${this.name}") cannot publish on "${pattern}": ${prepared.reason}`);
+        }
+        await runtime.publish("publish", prepared.channel, prepared.envelope);
+    }
+}
+const maxEventBytes = 240 * 1024;
+/** Whether `params` is an object mapping each name to a string. */
+export function isParams(params) {
+    return (params !== null &&
+        typeof params === "object" &&
+        !Array.isArray(params) &&
+        Object.values(params).every((value) => typeof value === "string"));
+}
+/**
+ * Validates `body` against `channel`'s schema and encodes the envelope it is published in
+ * on `wire`, refusing a body the schema rejects or an event over 240 KiB.
+ */
+export async function encodeEvent(channel, wire, body) {
+    const validation = await validatePayload(channel.schema, body);
+    if (!validation.ok)
+        return { refused: "invalid-body", reason: `the body fails its schema: ${validation.message}` };
+    const envelope = JSON.stringify({
+        v: 1,
+        id: randomBytes(16).toString("hex"),
+        ch: wire,
+        ts: Date.now(),
+        kind: "live",
+        data: validation.value,
+    });
+    if (new TextEncoder().encode(envelope).byteLength > maxEventBytes) {
+        return { refused: "body-too-large", reason: `an event is at most ${maxEventBytes} bytes` };
+    }
+    return { channel: wire, body: validation.value, envelope };
+}
+/** Prepares the event the server publishes on `pattern`, or says why it cannot. */
+export async function prepareEvent(runtime, pattern, params, body) {
+    const channel = runtime.channels.get(pattern);
+    if (!channel)
+        return { refused: "unknown-pattern", reason: "no channel of that pattern is declared" };
+    if (!isParams(params))
+        return { refused: "invalid-params", reason: "params map each name to a string" };
+    const wire = encodeWireChannel(runtime.name, channel.pattern, params, false);
+    if ("refused" in wire)
+        return { refused: wire.refused, reason: `the params are refused: ${wire.refused}` };
+    return encodeEvent(channel, wire.channel, body);
+}
+/**
+ * Declares a realtime resource named `name`: typed channels that browsers subscribe to
+ * and the server publishes on, each pattern with the rules that decide who may.
+ *
+ * ```ts
+ * export const rt = realtime("app", {
+ *   authorize: async (req) => (await getSession(req)) ?? null,
+ *   channels: {
+ *     "orders/:orderId": {
+ *       schema: OrderEvent,
+ *       subscribe: async ({ auth, params }) => ownsOrder(auth, params.orderId),
+ *     },
+ *     status: { schema: Status, subscribe: "public" },
+ *   },
+ * });
+ *
+ * await rt.publish("orders/:orderId", { params: { orderId }, body: { status: "shipped" } });
+ * ```
+ *
+ * Serve it to browsers with `createRealtimeHandler` from `ocel/realtime/next`,
+ * `ocel/realtime/express` or `ocel/realtime/hono`.
+ */
+export function realtime(name, options) {
+    return new Realtime(name, options);
+}

package/dist/realtime/token.d.ts

@@ -0,0 +1,20 @@
+import type { RealtimeProperties } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+/** The operation a token admits its holder to on its channel. */
+export type TokenOperation = "connect" | "subscribe" | "publish";
+/** The realtime resource a token is minted for: its name and how long its tokens live. */
+export interface TokenIssuer {
+    name: string;
+    ttlSeconds: number;
+}
+/** A signed token and the Unix second it expires at. */
+export interface Token {
+    token: string;
+    expiresAt: number;
+}
+/** Signs `header` and `claims` as an EdDSA JWT with an Ed25519 signing key. */
+export declare function signToken(signingKey: Uint8Array, header: Record<string, unknown>, claims: Record<string, unknown>): string;
+/**
+ * Mints the token admitting `subject` to `operation` on `channel` of `issuer`, signed with
+ * the binding's key for the binding's host. Throws when the binding's key cannot sign.
+ */
+export declare function mintToken(properties: RealtimeProperties, issuer: TokenIssuer, subject: string, operation: TokenOperation, channel: string): Token;

package/dist/realtime/token.js

@@ -0,0 +1,45 @@
+import { createPrivateKey, randomBytes, sign } from "node:crypto";
+const tokenHeader = { alg: "EdDSA", typ: "JWT" };
+const pkcs8Ed25519Prefix = Buffer.from("302e020100300506032b657004220420", "hex");
+function encodeCanonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(encodeCanonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const members = Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${encodeCanonicalJson(value[key])}`);
+        return `{${members.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function encodeBase64url(text) {
+    return Buffer.from(text).toString("base64url");
+}
+/** Signs `header` and `claims` as an EdDSA JWT with an Ed25519 signing key. */
+export function signToken(signingKey, header, claims) {
+    const key = createPrivateKey({
+        key: Buffer.concat([pkcs8Ed25519Prefix, Buffer.from(signingKey)]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const input = `${encodeBase64url(encodeCanonicalJson(header))}.${encodeBase64url(encodeCanonicalJson(claims))}`;
+    return `${input}.${encodeBase64url(sign(null, Buffer.from(input), key))}`;
+}
+/**
+ * Mints the token admitting `subject` to `operation` on `channel` of `issuer`, signed with
+ * the binding's key for the binding's host. Throws when the binding's key cannot sign.
+ */
+export function mintToken(properties, issuer, subject, operation, channel) {
+    const issuedAt = Math.floor(Date.now() / 1_000);
+    const expiresAt = issuedAt + issuer.ttlSeconds;
+    const token = signToken(properties.signingKey, tokenHeader, {
+        iss: `ocel:rt:${issuer.name}`,
+        aud: properties.host,
+        sub: subject,
+        iat: issuedAt,
+        exp: expiresAt,
+        jti: randomBytes(16).toString("base64url"),
+        ocel: { op: operation, ch: channel, ns: issuer.name },
+    });
+    return { token, expiresAt };
+}

package/dist/realtime/transport.d.ts

@@ -0,0 +1,11 @@
+import { type RealtimeProperties } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+/** The transport a realtime binding names, as the handler names it to a browser. */
+export interface Transport {
+    name: "appsync-events" | "ocel-gateway";
+    host?: string;
+}
+/**
+ * Resolves the transport `properties` names for the resource `name`. Throws for a
+ * transport this SDK does not speak.
+ */
+export declare function resolveTransport(properties: RealtimeProperties, name: string): Transport;

package/dist/realtime/transport.js

@@ -0,0 +1,15 @@
+import { RealtimeTransport, } from "../gen/proto/common/bindings/v1/bindings_pb.js";
+/**
+ * Resolves the transport `properties` names for the resource `name`. Throws for a
+ * transport this SDK does not speak.
+ */
+export function resolveTransport(properties, name) {
+    switch (properties.transport) {
+        case RealtimeTransport.OCEL_GATEWAY:
+            return { name: "ocel-gateway" };
+        case RealtimeTransport.APPSYNC_EVENTS:
+            return { name: "appsync-events", host: properties.host };
+        default:
+            throw new Error(`realtime("${name}"): the binding names transport ${properties.transport}, which this SDK does not speak`);
+    }
+}

package/dist/realtime/wire.d.ts

@@ -0,0 +1,30 @@
+type Segment = {
+    literal: string;
+} | {
+    parameter: string;
+};
+/** A channel pattern as written, split into its literal and `:parameter` segments. */
+export interface ChannelPattern {
+    readonly written: string;
+    readonly segments: readonly Segment[];
+}
+/** Why params cannot fill a pattern into a wire channel. */
+export type WireRefusal = "missing-param" | "unknown-param" | "empty-value" | "value-too-long";
+/** The wire channel params fill a pattern into, or why they cannot. */
+export type WireChannel = {
+    channel: string;
+} | {
+    refused: WireRefusal;
+};
+/** Parses a written channel pattern, throwing for one its grammar does not allow. */
+export declare function parseChannelPattern(written: string): ChannelPattern;
+/** Whether `name` can begin every channel of a realtime resource. */
+export declare function isChannelNamespace(name: string): boolean;
+/** The names of the `:parameter` segments of `pattern`, in order. */
+export declare function listPatternParameters(pattern: ChannelPattern): string[];
+/**
+ * Encodes the wire channel `params` fill `pattern` into under `namespace`; a `wildcard`
+ * pattern may leave off trailing params and ends in `*`.
+ */
+export declare function encodeWireChannel(namespace: string, pattern: ChannelPattern, params: Record<string, string>, wildcard: boolean): WireChannel;
+export {};

package/dist/realtime/wire.js

@@ -0,0 +1,104 @@
+const maxSegments = 4;
+const maxValueBytes = 30;
+const channelSegment = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?$/;
+const parameterSegment = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+const segmentRule = "letters, digits and -, at most 50 characters, starting and ending with a letter or digit";
+/** Parses a written channel pattern, throwing for one its grammar does not allow. */
+export function parseChannelPattern(written) {
+    if (written === "") {
+        throw new Error(`the pattern is empty: write one to ${maxSegments} segments joined by /, each a literal or a :parameter`);
+    }
+    const parts = written.split("/");
+    if (parts.length > maxSegments) {
+        throw new Error(`pattern "${written}" has ${parts.length} segments, and a channel pattern has at most ${maxSegments}`);
+    }
+    const segments = [];
+    const named = new Set();
+    for (const part of parts) {
+        if (part === "") {
+            throw new Error(`pattern "${written}" has an empty segment: it neither starts nor ends with /, and no two / are adjacent`);
+        }
+        if (part.startsWith(":")) {
+            if (!parameterSegment.test(part)) {
+                throw new Error(`pattern "${written}" has segment "${part}", which is no parameter: a parameter is : and a name of letters, digits and _ that starts with a letter or _`);
+            }
+            const name = part.slice(1);
+            if (named.has(name)) {
+                throw new Error(`pattern "${written}" names parameter "${name}" twice, so a channel could not say which value is which`);
+            }
+            named.add(name);
+            segments.push({ parameter: name });
+        }
+        else if (!channelSegment.test(part)) {
+            throw new Error(`pattern "${written}" has segment "${part}", which is no literal: a literal is ${segmentRule}`);
+        }
+        else {
+            segments.push({ literal: part });
+        }
+    }
+    return { written, segments };
+}
+/** Whether `name` can begin every channel of a realtime resource. */
+export function isChannelNamespace(name) {
+    return channelSegment.test(name);
+}
+/** The names of the `:parameter` segments of `pattern`, in order. */
+export function listPatternParameters(pattern) {
+    return pattern.segments.flatMap((s) => ("parameter" in s ? [s.parameter] : []));
+}
+const base32Alphabet = "abcdefghijklmnopqrstuvwxyz234567";
+function encodeLowerBase32(bytes) {
+    let out = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += base32Alphabet[(buffer >> bits) & 31];
+        }
+    }
+    if (bits > 0)
+        out += base32Alphabet[(buffer << (5 - bits)) & 31];
+    return out;
+}
+function encodeValue(value, bytes) {
+    if (channelSegment.test(value) && !value.startsWith("0z"))
+        return value;
+    return `0z${encodeLowerBase32(bytes)}`;
+}
+/**
+ * Encodes the wire channel `params` fill `pattern` into under `namespace`; a `wildcard`
+ * pattern may leave off trailing params and ends in `*`.
+ */
+export function encodeWireChannel(namespace, pattern, params, wildcard) {
+    const names = listPatternParameters(pattern);
+    for (const name of Object.keys(params)) {
+        if (!names.includes(name))
+            return { refused: "unknown-param" };
+    }
+    const channel = ["", namespace];
+    for (const [i, segment] of pattern.segments.entries()) {
+        if ("literal" in segment) {
+            channel.push(segment.literal);
+            continue;
+        }
+        const value = Object.hasOwn(params, segment.parameter) ? params[segment.parameter] : undefined;
+        if (value === undefined) {
+            const later = pattern.segments
+                .slice(i)
+                .some((s) => "parameter" in s && Object.hasOwn(params, s.parameter));
+            if (!wildcard || later)
+                return { refused: "missing-param" };
+            return { channel: [...channel, "*"].join("/") };
+        }
+        if (value === "")
+            return { refused: "empty-value" };
+        const bytes = new TextEncoder().encode(value);
+        if (bytes.byteLength > maxValueBytes)
+            return { refused: "value-too-long" };
+        channel.push(encodeValue(value, bytes));
+    }
+    return { channel: channel.join("/") };
+}

package/dist/runtime/dev-server.d.ts

@@ -0,0 +1,8 @@
+/** The address of the running `ocel dev` server; undefined outside it. */
+export declare const OCEL_DEV_SERVER: string | undefined;
+/** The env key the token every call to the dev server presents is delivered under. */
+export declare const DEV_SERVER_TOKEN = "OCEL_DEV_SERVER_TOKEN";
+/** The delivered dev-server token; empty when none was delivered. */
+export declare const getDevServerToken: () => string;
+/** The header every call to the dev server names this SDK's version in. */
+export declare const SDK_VERSION_HEADER = "Ocel-Sdk-Version";

package/dist/runtime/dev-server.js

@@ -0,0 +1,8 @@
+/** The address of the running `ocel dev` server; undefined outside it. */
+export const OCEL_DEV_SERVER = process.env.OCEL_DEV_SERVER;
+/** The env key the token every call to the dev server presents is delivered under. */
+export const DEV_SERVER_TOKEN = "OCEL_DEV_SERVER_TOKEN";
+/** The delivered dev-server token; empty when none was delivered. */
+export const getDevServerToken = () => process.env[DEV_SERVER_TOKEN] ?? "";
+/** The header every call to the dev server names this SDK's version in. */
+export const SDK_VERSION_HEADER = "Ocel-Sdk-Version";

package/dist/runtime/rpc.d.ts

@@ -0,0 +1,23 @@
+import { type Interceptor } from "@connectrpc/connect";
+/** Presents the dev-server token and this SDK's version on every call. */
+export declare const authorized: Interceptor;
+/** Clients for the services the dev server serves. */
+export declare const rpc: {
+    resource: import("@connectrpc/connect").Client<import("@bufbuild/protobuf/codegenv2").GenService<{
+        declare: {
+            methodKind: "unary";
+            input: typeof import("../gen/proto/app/resources/v1/resources_pb.js").DeclareRequestSchema;
+            output: typeof import("../gen/proto/app/resources/v1/resources_pb.js").DeclareResponseSchema;
+        };
+        declareEnv: {
+            methodKind: "unary";
+            input: typeof import("../gen/proto/app/resources/v1/variables_pb.js").DeclareEnvRequestSchema;
+            output: typeof import("../gen/proto/app/resources/v1/variables_pb.js").DeclareEnvResponseSchema;
+        };
+        reportEnvProblems: {
+            methodKind: "unary";
+            input: typeof import("../gen/proto/app/resources/v1/variables_pb.js").ReportEnvProblemsRequestSchema;
+            output: typeof import("../gen/proto/app/resources/v1/variables_pb.js").ReportEnvProblemsResponseSchema;
+        };
+    }>>;
+};

package/dist/runtime/rpc.js

@@ -0,0 +1,24 @@
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-node";
+import { ResourceService } from "../gen/proto/app/resources/v1/resources_pb.js";
+import { SDK_VERSION } from "../version.js";
+import { getDevServerToken, OCEL_DEV_SERVER, SDK_VERSION_HEADER } from "./dev-server.js";
+/** Presents the dev-server token and this SDK's version on every call. */
+export const authorized = (next) => (req) => {
+    req.header.set("Authorization", `Bearer ${getDevServerToken()}`);
+    req.header.set(SDK_VERSION_HEADER, `js/${SDK_VERSION}`);
+    return next(req);
+};
+const _rpc = () => {
+    const transport = createConnectTransport({
+        httpVersion: "1.1",
+        baseUrl: OCEL_DEV_SERVER,
+        interceptors: [authorized],
+    });
+    const resourceClient = createClient(ResourceService, transport);
+    return {
+        resource: resourceClient,
+    };
+};
+/** Clients for the services the dev server serves. */
+export const rpc = _rpc();

package/dist/runtime/transport.d.ts

@@ -0,0 +1,11 @@
+import type { Transport } from "@connectrpc/connect";
+/** The env key the ocel runtime's address is delivered under. */
+export declare const RUNTIME_ADDRESS = "OCEL_RUNTIME_ADDRESS";
+/** The env key the token every call to the ocel runtime presents is delivered under. */
+export declare const SESSION_TOKEN = "OCEL_SESSION_TOKEN";
+/** The delivered address of the ocel runtime. Throws when none was delivered. */
+export declare const getRuntimeAddress: () => string;
+/** The delivered session token for the ocel runtime. Throws when none was delivered. */
+export declare const getSessionToken: () => string;
+/** A transport to the ocel runtime that presents the session token on every call. Throws when the address or token was not delivered. */
+export declare function createRuntimeTransport(): Transport;

package/dist/runtime/transport.js

@@ -0,0 +1,35 @@
+import { createConnectTransport } from "@connectrpc/connect-node";
+/** The env key the ocel runtime's address is delivered under. */
+export const RUNTIME_ADDRESS = "OCEL_RUNTIME_ADDRESS";
+/** The env key the token every call to the ocel runtime presents is delivered under. */
+export const SESSION_TOKEN = "OCEL_SESSION_TOKEN";
+/** The delivered address of the ocel runtime. Throws when none was delivered. */
+export const getRuntimeAddress = () => {
+    const address = process.env[RUNTIME_ADDRESS];
+    if (!address) {
+        throw new Error(`${RUNTIME_ADDRESS} is not defined, so no resource the ocel runtime serves can be reached. Run \`ocel dev\` to serve it locally, or \`ocel deploy\` to have the deployed runtime's address delivered.`);
+    }
+    return address;
+};
+/** The delivered session token for the ocel runtime. Throws when none was delivered. */
+export const getSessionToken = () => {
+    const token = process.env[SESSION_TOKEN];
+    if (!token) {
+        throw new Error(`${SESSION_TOKEN} is not defined, so the ocel runtime at ${RUNTIME_ADDRESS} would refuse every call. It is delivered beside ${RUNTIME_ADDRESS} by \`ocel dev\` and by the deployed runtime, never set by hand.`);
+    }
+    return token;
+};
+function createAuthorizationInterceptor(token) {
+    return (next) => (req) => {
+        req.header.set("Authorization", `Bearer ${token}`);
+        return next(req);
+    };
+}
+/** A transport to the ocel runtime that presents the session token on every call. Throws when the address or token was not delivered. */
+export function createRuntimeTransport() {
+    return createConnectTransport({
+        httpVersion: "1.1",
+        baseUrl: getRuntimeAddress(),
+        interceptors: [createAuthorizationInterceptor(getSessionToken())],
+    });
+}

package/dist/task/errors.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown from a task's `run` or a topic consumer to fail the run or the message now, without
+ * another attempt. Its message is recorded as the reason.
+ */
+export declare class AbortTaskRunError extends Error {
+    name: string;
+}

package/dist/task/errors.js

@@ -0,0 +1,7 @@
+/**
+ * Thrown from a task's `run` or a topic consumer to fail the run or the message now, without
+ * another attempt. Its message is recorded as the reason.
+ */
+export class AbortTaskRunError extends Error {
+    name = "AbortTaskRunError";
+}

package/dist/task/hooks.d.ts

@@ -0,0 +1,57 @@
+import type { RunContext } from "../worker/context.js";
+/** How a run ended: with the output its `run` returned, or with the error that failed it. */
+export type TaskResult<TOutput> = {
+    ok: true;
+    output: TOutput;
+} | {
+    ok: false;
+    error: unknown;
+};
+/** What `catchError` answers to fail the run now instead of retrying it. */
+export interface CatchErrorResult {
+    /** Fails the run without another attempt. */
+    skipRetrying?: boolean;
+}
+/** The hooks a task runs around its attempts. */
+export interface TaskHooks<TPayload, TOutput> {
+    /** Runs once the run succeeds. An error it throws is reported, and changes nothing. */
+    onSuccess?: (args: {
+        payload: TPayload;
+        output: TOutput;
+        ctx: RunContext;
+    }) => unknown;
+    /** Runs once the run fails for good. An error it throws is reported, and changes nothing. */
+    onFailure?: (args: {
+        payload: TPayload;
+        error: unknown;
+        ctx: RunContext;
+    }) => unknown;
+    /** Runs after `onSuccess` or `onFailure`. An error it throws is reported, and changes nothing. */
+    onComplete?: (args: {
+        payload: TPayload;
+        ctx: RunContext;
+        result: TaskResult<TOutput>;
+    }) => unknown;
+    /** Runs when the run is canceled during an attempt, best-effort. */
+    onCancel?: (args: {
+        payload: TPayload;
+        ctx: RunContext;
+    }) => unknown;
+    /** Sees every error an attempt throws; answering a {@link CatchErrorResult} of `{ skipRetrying: true }` fails the run now. */
+    catchError?: (args: {
+        payload: TPayload;
+        error: unknown;
+        ctx: RunContext;
+    }) => unknown;
+    /** Wraps every attempt; `next` runs the attempt, and an error it throws fails the attempt. */
+    middleware?: (args: {
+        payload: TPayload;
+        ctx: RunContext;
+        next: () => Promise<void>;
+    }) => unknown;
+    /** Runs before every attempt; an error it throws fails the attempt. */
+    onStartAttempt?: (args: {
+        payload: TPayload;
+        ctx: RunContext;
+    }) => unknown;
+}

package/dist/task/hooks.js

@@ -0,0 +1 @@
+export {};

package/dist/task/index.d.ts

@@ -0,0 +1,9 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export type { Duration } from "../delivery/duration.js";
+export type { Lane } from "../delivery/lane.js";
+export type { RetryOptions } from "../delivery/retry.js";
+export type { RunContext, RunOptions } from "../worker/context.js";
+export { AbortTaskRunError } from "./errors.js";
+export type { CatchErrorResult, TaskHooks, TaskResult } from "./hooks.js";
+export { type ListRunsOptions, type RescheduleOptions, type Run, type RunPage, type RunStatus, runs, } from "./runs.js";
+export { type BatchOptions, type BatchTriggerItem, type RunFunction, type RunHandle, Task, type TaskOptions, type TriggerOptions, task, } from "./task.js";

package/dist/task/index.js

@@ -0,0 +1,4 @@
+export { UnprovisionedResourceError } from "../binding/unprovisioned.js";
+export { AbortTaskRunError } from "./errors.js";
+export { runs, } from "./runs.js";
+export { Task, task, } from "./task.js";