@johannc-dev/zyrk 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import { Cause, Console, Effect, Exit, FileSystem, Layer, Option, Path, Stdio, Terminal, } from "effect";
+import { Argument, CliError, Command, Flag } from "effect/cli";
+import { ChildProcessSpawner } from "effect/process";
+import { BUNDLE_PATH, writeBundleEffect } from "./build.js";
+import { ZyrkClient } from "./client.js";
+import { decode, Json } from "./contracts.js";
+import { exportHistory, exportTotals, exportVolumeSearch, } from "./export.js";
+import { LocalRunner } from "./local.js";
+import { DecodeError, messageOf, } from "./errors.js";
+export const VERSION = "0.2.0";
+const print = (value) => Console.log(JSON.stringify(value, null, 2));
+const entry = Argument.String("entry.ts").pipe(Argument.withDescription("TypeScript or JavaScript entry point of the program"));
+const program = Argument.String("program").pipe(Argument.withDescription("Program name"));
+const execution = Argument.String("execution").pipe(Argument.withDescription("Execution id"));
+const fn = Argument.String("function").pipe(Argument.withDescription("Function to invoke"));
+const args = Argument.String("json").pipe(Argument.withDescription("JSON arguments (default null)"), Argument.optional);
+const minify = Flag.Boolean("minify").pipe(Flag.withDescription("Minify the bundle (smaller, harder to read in errors)"), Flag.withDefault(false));
+const noTypecheck = Flag.Boolean("no-typecheck").pipe(Flag.withDescription("Skip type-checking (the static checks still run)"), Flag.withDefault(false));
+const timeout = Flag.Int("timeout").pipe(Flag.withDescription("Stop waiting after this many milliseconds"), Flag.optional);
+const parseArgs = (raw) => Effect.try({
+    try: () => JSON.parse(Option.getOrElse(raw, () => "null")),
+    catch: (cause) => new DecodeError({ what: "arguments", message: messageOf(cause) }),
+}).pipe(Effect.flatMap(decode(Json, "arguments")));
+const bundleWith = (input) => writeBundleEffect(input.entry, {
+    minify: input.minify,
+    typecheck: !input["no-typecheck"],
+}).pipe(Effect.tap((result) => Effect.forEach(result.warnings, (w) => Console.error(`warning: ${w}`))));
+const start = Effect.fnUntraced(function* (input) {
+    const client = yield* ZyrkClient;
+    const id = yield* client.start(input.program, {
+        function: input.function,
+        args: yield* parseArgs(input.json),
+    });
+    yield* Console.error(JSON.stringify({ executionId: id }));
+    return { client, id };
+});
+const withClient = (f) => ZyrkClient.use(f).pipe(Effect.flatMap(print), Effect.provide(ZyrkClient.layerConfig));
+const onArgument = (name, description, argument, f) => Command.make(name, { value: argument }, (input) => withClient((client) => f(client, input.value))).pipe(Command.withDescription(description));
+const timeoutOf = (value) => Option.match(value, {
+    onNone: () => ({}),
+    onSome: (timeoutMs) => ({ timeoutMs }),
+});
+export function timeOf(text) {
+    const ms = /^\d+$/.test(text) ? Number(text) : Date.parse(text);
+    if (!Number.isFinite(ms))
+        throw new Error(`Not a date: ${text}`);
+    return ms;
+}
+const local = (name, body) => Effect.promise(() => body().catch((error) => {
+    process.stderr.write(`error[${name}]: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+}));
+const optionalString = (name, description) => Flag.String(name).pipe(Flag.withDescription(description), Flag.optional);
+const flag = (name, description) => Flag.Boolean(name).pipe(Flag.withDescription(description), Flag.withDefault(false));
+const value = (o) => Option.getOrUndefined(o);
+const exportCommand = Command.make("export", {
+    token: optionalString("token", "Mint whose trades to export"),
+    wallet: optionalString("wallet", "Wallet whose trades to export"),
+    since: optionalString("since", "Start (included): 2026-11-07, ISO time or ms"),
+    until: optionalString("until", "End (excluded): 2026-11-08, ISO time or ms"),
+    side: optionalString("side", "buy or sell (default: both)"),
+    "with-signatures": flag("with-signatures", "Export batch.signatures"),
+    "with-market": flag("with-market", "Export batch.market (reserves, fees)"),
+    "with-events": flag("with-events", "Export pool events too (implies --with-market)"),
+    "with-order": flag("with-order", "Export batch.order (on-chain order)"),
+    "with-tx": flag("with-tx", "Export batch.tx (transaction of each trade, place in it)"),
+    refresh: flag("refresh", "Download every hour again (a finished export only re-downloads the hours that were open or not sealed)"),
+    totals: optionalString("totals", "Also save /v1/tokens/{mint}/totals of this mint"),
+    quote: optionalString("quote", "Quote mint of --totals"),
+    "volume-search": optionalString("volume-search", "Also save every page of ctx.data.volumeSearch(<json params>)"),
+    rpm: Flag.Int("rpm").pipe(Flag.withDescription("At most this many requests per minute"), Flag.optional),
+    out: Flag.String("out").pipe(Flag.withAlias("o"), Flag.withDescription("Data directory (created, resumed if it exists)"), Flag.withDefault("data")),
+}, (input) => local("export", async () => {
+    const url = process.env.TH_API_URL;
+    const apiKey = process.env.TH_API_KEY;
+    if (!url || !apiKey)
+        throw new Error("Set TH_API_URL and TH_API_KEY");
+    const connection = {
+        url,
+        apiKey,
+        ...(Option.isSome(input.rpm) ? { rpm: input.rpm.value } : {}),
+        onWarning: (m) => process.stderr.write(`warning: ${m}\n`),
+        onProgress: (p) => process.stderr.write(p.done
+            ? `${p.read}: done, ${p.hours} hour files, ${p.bytes} bytes\n`
+            : `${p.read}: hour ${p.hour} (${p.hours})\r`),
+    };
+    const token = value(input.token);
+    const wallet = value(input.wallet);
+    let work = false;
+    if (token || wallet) {
+        if (token && wallet)
+            throw new Error("--token or --wallet, not both");
+        const since = value(input.since);
+        const until = value(input.until);
+        if (!since || !until)
+            throw new Error("--since and --until are required");
+        const side = value(input.side);
+        if (side !== undefined && side !== "buy" && side !== "sell")
+            throw new Error("--side is buy or sell");
+        const summary = await exportHistory(connection, input.out, {
+            scope: token ? "token" : "wallet",
+            key: (token ?? wallet),
+            sinceMs: timeOf(since),
+            untilMs: timeOf(until),
+            ...(side ? { side } : {}),
+            withSignatures: input["with-signatures"],
+            withMarket: input["with-market"],
+            withEvents: input["with-events"],
+            withOrder: input["with-order"],
+            withTx: input["with-tx"],
+            refresh: input.refresh,
+        });
+        process.stderr.write(`${summary.reads.length} part(s), ${summary.requests} requests, ${summary.bytes} bytes written to ${input.out}\n`);
+        work = true;
+    }
+    const totals = value(input.totals);
+    if (totals) {
+        await exportTotals(connection, input.out, totals, value(input.quote) ?? null);
+        work = true;
+    }
+    const volume = value(input["volume-search"]);
+    if (volume) {
+        const pages = await exportVolumeSearch(connection, input.out, JSON.parse(volume));
+        process.stderr.write(`volumeSearch: ${pages} page(s)\n`);
+        work = true;
+    }
+    if (!work)
+        throw new Error("Nothing to export: --token/--wallet, --totals or --volume-search");
+})).pipe(Command.withDescription("Download history (one file per hour, as hosted programs see it) for zyrk dev. Resumes an interrupted export."));
+const devCommand = Command.make("dev", {
+    entry,
+    function: fn,
+    json: args,
+    data: optionalString("data", "Directory written by zyrk export"),
+    state: optionalString("state", "Keep the program state in this folder between runs"),
+    storage: optionalString("storage", "Keep ctx.storage in this folder (default: memory)"),
+    bundle: flag("bundle", "entry is a built bundle (.functions/program.js)"),
+    replay: optionalString("replay", "Replay this subscription over --since/--until: <function> is ignored, json is unused"),
+    since: optionalString("since", "Replay start"),
+    until: optionalString("until", "Replay end"),
+    "events-per-delivery": Flag.Int("events-per-delivery").pipe(Flag.withDescription("Events per replayed delivery (1 to 32, default 1)"), Flag.optional),
+    quiet: flag("quiet", "Do not print logs and emits as they happen"),
+    "no-typecheck": noTypecheck,
+}, (input) => local("dev", async () => {
+    const source = input.bundle
+        ? { code: (await import("node:fs")).readFileSync(input.entry, "utf8") }
+        : input.entry;
+    const runner = await LocalRunner.load(source, {
+        ...(Option.isSome(input.data) ? { data: input.data.value } : {}),
+        ...(Option.isSome(input.state) ? { state: input.state.value } : {}),
+        ...(Option.isSome(input.storage)
+            ? { storage: input.storage.value }
+            : {}),
+        console: !input.quiet,
+        typecheck: !input["no-typecheck"],
+    });
+    const replay = value(input.replay);
+    if (replay) {
+        const since = value(input.since);
+        const until = value(input.until);
+        if (!since || !until)
+            throw new Error("--replay needs --since and --until");
+        const r = await runner.replay({
+            subscription: replay,
+            sinceMs: timeOf(since),
+            untilMs: timeOf(until),
+            ...(Option.isSome(input["events-per-delivery"])
+                ? { eventsPerDelivery: input["events-per-delivery"].value }
+                : {}),
+        });
+        for (const w of [...r.warnings, ...runner.warnings])
+            process.stderr.write(`warning: ${w}\n`);
+        console.log(JSON.stringify({
+            id: r.id,
+            status: r.status,
+            ...(r.error ? { error: r.error } : {}),
+            progress: r.progress,
+            deliveries: r.runs.map((x) => ({
+                id: x.id,
+                status: x.status,
+                ...(x.error ? { error: x.error } : { result: x.result }),
+            })),
+            state: Object.fromEntries(r.state),
+        }, null, 2));
+        if (r.status !== "succeeded")
+            process.exitCode = 1;
+        return;
+    }
+    const parsed = JSON.parse(Option.getOrElse(input.json, () => "null"));
+    const run = await runner.run(input.function, parsed);
+    await runner.idle();
+    for (const w of runner.warnings)
+        process.stderr.write(`warning: ${w}\n`);
+    const last = run.executions[run.executions.length - 1];
+    if (last)
+        process.stderr.write(`usage: ${JSON.stringify(last.usage)}\n`);
+    if (run.status === "succeeded")
+        console.log(JSON.stringify(run.result, null, 2));
+    else {
+        process.stderr.write(`error[ExecutionFailed ${run.error?.kind}/${run.error?.code}]: ${run.error?.message}\n`);
+        process.exitCode = 1;
+    }
+})).pipe(Command.withDescription("Run a function on your machine with the same ctx as the service, on data from zyrk export"));
+const webhook = Command.make("webhook").pipe(Command.withDescription("Outbound webhook of the account: configuration, test, delivery log"), Command.withSubcommands([
+    Command.make("get", {}, () => withClient((c) => c.webhook())).pipe(Command.withDescription("Show the configuration (secrets masked)")),
+    Command.make("set", {
+        url: Argument.String("url").pipe(Argument.withDescription("https:// URL of your receiver")),
+        events: Flag.String("events").pipe(Flag.withDescription("Automatic alerts, comma separated: failed, limit, cpu_limit…"), Flag.withDefault("")),
+        disabled: Flag.Boolean("disabled").pipe(Flag.withDescription("Keep the configuration but deliver nothing"), Flag.withDefault(false)),
+    }, (input) => withClient((c) => c.setWebhook({
+        url: input.url,
+        events: input.events
+            .split(",")
+            .map((e) => e.trim())
+            .filter((e) => e !== ""),
+        enabled: !input.disabled,
+    }))).pipe(Command.withDescription("Set the URL and alerts; the first time prints the secret (keep it)")),
+    Command.make("rotate", {
+        force: Flag.Boolean("force").pipe(Flag.withDescription("Rotate again although the previous secret is still valid (it stops working now)"), Flag.withDefault(false)),
+    }, (input) => withClient((c) => c.rotateWebhookSecret({ force: input.force }))).pipe(Command.withDescription("New secret (printed); the previous one stays valid for 24 h")),
+    Command.make("test", {}, () => withClient((c) => c.testWebhook())).pipe(Command.withDescription("Send a test message")),
+    Command.make("deliveries", {
+        limit: Flag.Int("limit").pipe(Flag.withDescription("Attempts to show (1 to 100)"), Flag.optional),
+    }, (input) => withClient((c) => c.webhookDeliveries(Option.getOrUndefined(input.limit)))).pipe(Command.withDescription("Last delivery attempts (status, latency, error) and pending count")),
+    Command.make("delete", {}, () => withClient((c) => c.deleteWebhook())).pipe(Command.withDescription("Remove the webhook and its queued messages")),
+]));
+const zyrk = Command.make("zyrk").pipe(Command.withDescription("Zyrk hosted functions (SDK 0.2). Environment: TH_API_URL, TH_API_KEY. Install npm dependencies locally; the service receives only the bundle."), Command.withSubcommands([
+    Command.make("build", { entry, minify, "no-typecheck": noTypecheck }, (input) => bundleWith(input).pipe(Effect.flatMap((r) => Console.log(`${BUNDLE_PATH} (${r.bytes} bytes)`)))).pipe(Command.withDescription(`Check and bundle into ${BUNDLE_PATH}. Refuses Node modules, fetch and the 0.1 API.`)),
+    Command.make("deploy", {
+        program,
+        entry,
+        minify,
+        "no-typecheck": noTypecheck,
+        force: Flag.Boolean("force").pipe(Flag.withDescription("Deploy even if executions in flight are incompatible (they are cancelled)"), Flag.withDefault(false)),
+    }, (input) => Effect.gen(function* () {
+        const { code } = yield* bundleWith(input);
+        const client = yield* ZyrkClient;
+        yield* print(yield* client.deploy(input.program, code, { force: input.force }));
+    }).pipe(Effect.provide(ZyrkClient.layerConfig))).pipe(Command.withDescription("Build and deploy a program")),
+    Command.make("run", { program, function: fn, json: args, timeout }, (input) => start(input).pipe(Effect.flatMap(({ client, id }) => client.wait(id, timeoutOf(input.timeout))), Effect.flatMap(print), Effect.provide(ZyrkClient.layerConfig))).pipe(Command.withDescription("Start a function and wait for its result")),
+    Command.make("start", { program, function: fn, json: args }, (input) => start(input).pipe(Effect.flatMap(({ id }) => print({ id })), Effect.provide(ZyrkClient.layerConfig))).pipe(Command.withDescription("Start a function without waiting")),
+    Command.make("wait", { execution, timeout }, (input) => withClient((c) => c.wait(input.execution, timeoutOf(input.timeout)))).pipe(Command.withDescription("Wait for the result of an execution")),
+    onArgument("result", "Status and result of an execution (continuations followed)", execution, (c, id) => c.result(id)),
+    onArgument("execution", "Full record of one execution (logs, usage)", execution, (c, id) => c.execution(id)),
+    onArgument("ack", "Acknowledge an execution", execution, (c, id) => c.acknowledge(id)),
+    onArgument("cancel", "Cancel an execution", execution, (c, id) => c.cancel(id)),
+    Command.make("programs", {}, () => withClient((c) => c.programs())).pipe(Command.withDescription("List the programs of the account")),
+    onArgument("inspect", "Show a program", program, (c, p) => c.inspect(p)),
+    onArgument("executions", "Recent executions of a program", program, (c, p) => c.executions(p)),
+    onArgument("pause", "Pause a program", program, (c, p) => c.pause(p, true)),
+    onArgument("resume", "Resume a program", program, (c, p) => c.pause(p, false)),
+    exportCommand,
+    devCommand,
+    Command.make("measurements", {}, () => withClient((c) => c.measurements())).pipe(Command.withDescription("Daily usage of the account")),
+    webhook,
+]));
+const describe = (error) => {
+    switch (error._tag) {
+        case "ApiError":
+            return `error[ApiError ${error.status} ${error.code}]: ${error.message}`;
+        case "BuildError":
+            return `error[BuildError ${error.stage}]:\n${error.message}`;
+        case "DecodeError":
+            return `error[DecodeError ${error.what}]: ${error.message}`;
+        case "ExecutionFailed":
+            return `error[ExecutionFailed ${error.failure.kind}/${error.failure.code}]: ${error.message}`;
+        case "ExecutionEnded":
+            return `error[ExecutionEnded ${error.status}]: ${error.message}`;
+        case "WaitTimeout":
+        case "ConfigError":
+        case "NetworkError":
+            return `error[${error._tag}]: ${error.message}`;
+        default:
+            return error;
+    }
+};
+const CliEnvironment = Layer.mergeAll(FileSystem.layerNoop({}), Path.layer, Stdio.layerTest({}), Layer.succeed(Terminal.Terminal, Terminal.make({
+    columns: Effect.sync(() => process.stdout.columns ?? 80),
+    rows: Effect.sync(() => process.stdout.rows ?? 24),
+    size: Effect.die("unsupported"),
+    readInput: Effect.die("unsupported"),
+    readLine: Effect.die("unsupported"),
+    display: (text) => Effect.sync(() => void process.stdout.write(text)),
+})), Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, ChildProcessSpawner.make(() => Effect.die("unsupported"))));
+Effect.runPromiseExit(Command.runWith(zyrk, { version: VERSION })(process.argv.slice(2)).pipe(Effect.provide(CliEnvironment))).then((exit) => {
+    if (Exit.isSuccess(exit))
+        return;
+    const error = Cause.findErrorOption(exit.cause);
+    if (Option.isNone(error))
+        process.stderr.write(Cause.pretty(exit.cause) + "\n");
+    else if (!CliError.isCliError(error.value))
+        process.stderr.write(describe(error.value) + "\n");
+    process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,208 @@
+import { Context, Effect, Layer } from "effect";
+import { Job, Json, ProgramSummary, type JobResult } from "./contracts.js";
+import { ApiError, ConfigError, DecodeError, ExecutionEnded, ExecutionFailed, NetworkError, WaitTimeout } from "./errors.js";
+export * from "./errors.js";
+export type { Job, JobResult, ProgramSummary } from "./contracts.js";
+import type { ReplayFeedItem, ReplayRecord, ReplayRequest } from "./sdk.js";
+export type { ReplayFeedItem, ReplayRecord, ReplayRequest } from "./sdk.js";
+export interface ClientConfig {
+    /** Gateway URL, e.g. `https://api.example.com`. */
+    readonly url: string;
+    readonly apiKey: string;
+}
+export interface StartInput {
+    readonly function: string;
+    readonly args: Json;
+    readonly onComplete?: string;
+    /** Retry key: the same id within 24 h returns the same execution. Default: random. */
+    readonly requestId?: string;
+}
+export interface WaitOptions {
+    /** Delay between two status checks, in milliseconds (default 1000). */
+    readonly pollMs?: number;
+    /** Give up after this many milliseconds (default: never). The execution keeps running. */
+    readonly timeoutMs?: number;
+}
+export interface DeployOptions {
+    /** Deploy even if incompatible with executions in flight (they are cancelled). */
+    readonly force?: boolean;
+}
+/** Input of {@link ZyrkClientService.run}: a start without `onComplete`. */
+export type RunInput = Omit<StartInput, "onComplete">;
+export interface AbortOptions {
+    readonly signal?: AbortSignal;
+}
+/** Errors of a single HTTP call to the service. */
+export type RequestError = NetworkError | ApiError | DecodeError;
+/** Errors of waiting for one execution result. */
+export type WaitError = RequestError | ExecutionFailed | ExecutionEnded | WaitTimeout;
+export interface ZyrkClientService {
+    request(method: string, path: string, body?: unknown): Effect.Effect<Json, RequestError>;
+    deploy(program: string, code: string, options?: DeployOptions): Effect.Effect<Json, RequestError>;
+    programs(): Effect.Effect<readonly ProgramSummary[], RequestError>;
+    inspect(program: string): Effect.Effect<Json, RequestError>;
+    pause(program: string, paused?: boolean): Effect.Effect<Json, RequestError>;
+    /** Recent executions of a program (summaries). */
+    executions(program: string): Effect.Effect<Json, RequestError>;
+    /** Starts an execution and returns its id. */
+    start(program: string, input: StartInput): Effect.Effect<string, RequestError>;
+    /** The raw execution record (continuations not followed). */
+    execution(id: string): Effect.Effect<Job, RequestError>;
+    /** Where the job stands now, continuations followed (same shape as `ctx.jobs.result`). */
+    result(id: string): Effect.Effect<JobResult, RequestError>;
+    /** Polls until the job succeeds and returns its result; fails otherwise. */
+    wait(id: string, options?: WaitOptions): Effect.Effect<Json, WaitError>;
+    /**
+     * Polls until every job is final or `timeoutMs` elapses (same contract as
+     * `ctx.jobs.wait`): never fails because a job failed.
+     */
+    waitAll(ids: readonly string[], options?: WaitOptions): Effect.Effect<JobResult[], RequestError>;
+    run(program: string, input: RunInput, options?: WaitOptions): Effect.Effect<Json, WaitError>;
+    acknowledge(id: string): Effect.Effect<Json, RequestError>;
+    cancel(id: string): Effect.Effect<Json, RequestError>;
+    /** Buffered account events after `afterSeq` (the WebSocket stream is in `./stream`). */
+    events(afterSeq?: number): Effect.Effect<Json, RequestError>;
+    /** Daily usage of the account. */
+    measurements(): Effect.Effect<Json, RequestError>;
+    /** The webhook configuration (secrets masked) and its queue counts. */
+    webhook(): Effect.Effect<Json, RequestError>;
+    /** Sets the webhook; the first call returns the secret in clear (keep it). */
+    setWebhook(config: WebhookConfig): Effect.Effect<Json, RequestError>;
+    deleteWebhook(): Effect.Effect<Json, RequestError>;
+    /** New secret (returned in clear); the previous one also signs for 24 h. */
+    /** Refused (`rotation_in_progress`) while the previous secret is valid, unless `force`. */
+    rotateWebhookSecret(options?: RotateOptions): Effect.Effect<Json, RequestError>;
+    /** Queues a `test` message. */
+    testWebhook(): Effect.Effect<Json, RequestError>;
+    /** Last delivery attempts, pending count, failed messages. */
+    webhookDeliveries(limit?: number): Effect.Effect<Json, RequestError>;
+}
+export interface RotateOptions {
+    /** How long the previous secret keeps signing (default and maximum 24 h). */
+    keepPreviousMs?: number;
+    /** Rotate even though the previous secret is still valid (it ends now). */
+    force?: boolean;
+}
+export interface WebhookConfig {
+    /** `https://` only. */
+    url: string;
+    /** Automatic alerts: `failed`, `limit` or failure codes like `cpu_limit`. */
+    events?: readonly string[];
+    enabled?: boolean;
+}
+/** Builds the client service for a gateway URL and API key. */
+export declare const make: (config: ClientConfig) => ZyrkClientService;
+/** Reads `TH_API_URL` and `TH_API_KEY` from the environment. */
+export declare const clientConfig: Effect.Effect<ClientConfig, ConfigError>;
+declare const ZyrkClient_base: Context.ServiceClass<ZyrkClient, "@johannc-dev/zyrk/ZyrkClient", ZyrkClientService>;
+/** The Zyrk functions HTTP client as an Effect service. */
+export declare class ZyrkClient extends ZyrkClient_base {
+    static readonly layer: (config: ClientConfig) => Layer.Layer<ZyrkClient>;
+    /** Layer configured from `TH_API_URL` / `TH_API_KEY`. */
+    static readonly layerConfig: Layer.Layer<ZyrkClient, ConfigError>;
+}
+/**
+ * Promise façade over {@link ZyrkClient}. Methods reject with the tagged
+ * error classes of `./errors` (`ApiError`, `NetworkError`…). Every method
+ * takes an `AbortSignal`: in its options object when it has one, else as its
+ * last argument.
+ */
+export declare class FunctionsClient {
+    private readonly client;
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * What functions stored in `ctx.storage.short` / `ctx.storage.long`, over
+     * HTTP (no WebSocket needed). Same shapes as in functions.
+     */
+    storage(area: "short" | "long" | "durable"): HttpStorageArea;
+    request(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<Json>;
+    deploy(program: string, code: string, options?: DeployOptions & AbortOptions): Promise<Json>;
+    programs(signal?: AbortSignal): Promise<readonly ProgramSummary[]>;
+    inspect(program: string, signal?: AbortSignal): Promise<Json>;
+    pause(program: string, paused?: boolean, signal?: AbortSignal): Promise<Json>;
+    executions(program: string, signal?: AbortSignal): Promise<Json>;
+    start(program: string, input: StartInput, signal?: AbortSignal): Promise<string>;
+    execution(id: string, signal?: AbortSignal): Promise<Job>;
+    result(id: string, signal?: AbortSignal): Promise<JobResult>;
+    wait(id: string, options?: WaitOptions & AbortOptions): Promise<Json>;
+    waitAll(ids: readonly string[], options?: WaitOptions & AbortOptions): Promise<JobResult[]>;
+    run(program: string, input: RunInput, options?: WaitOptions & AbortOptions): Promise<Json>;
+    acknowledge(id: string, signal?: AbortSignal): Promise<Json>;
+    cancel(id: string, signal?: AbortSignal): Promise<Json>;
+    events(afterSeq?: number, signal?: AbortSignal): Promise<Json>;
+    measurements(signal?: AbortSignal): Promise<Json>;
+    webhook(signal?: AbortSignal): Promise<Json>;
+    setWebhook(config: WebhookConfig, signal?: AbortSignal): Promise<Json>;
+    deleteWebhook(signal?: AbortSignal): Promise<Json>;
+    rotateWebhookSecret(options?: RotateOptions, signal?: AbortSignal): Promise<Json>;
+    testWebhook(signal?: AbortSignal): Promise<Json>;
+    webhookDeliveries(limit?: number, signal?: AbortSignal): Promise<Json>;
+    /** Starts a history replay of a subscription (`POST programs/{p}/replay`). */
+    replay(program: string, request: ReplayRequest, signal?: AbortSignal): Promise<ReplayRecord>;
+    /** Status and progress of a replay. */
+    replayStatus(id: string, signal?: AbortSignal): Promise<ReplayRecord>;
+    cancelReplay(id: string, signal?: AbortSignal): Promise<ReplayRecord>;
+    /** Executions of a replay still queued or running (`ctx.jobs` mode); finished ones are in {@link replayEmits}. */
+    replayExecutions(id: string, after?: number, signal?: AbortSignal): Promise<Json>;
+    /**
+     * The replay's live feed (never on the account stream, never stored):
+     * its `ctx.emit` values and each execution's final record, in order,
+     * after `afterSeq` (200 at most). Reading frees everything up to
+     * `afterSeq`: pass the last `seq` received, while the replay runs (it
+     * pauses when 16 MiB wait, and fails after 2 min without a read).
+     */
+    replayEmits(id: string, afterSeq?: number, signal?: AbortSignal): Promise<ReplayFeedItem[]>;
+}
+/** Lakebed's `StorageObjectHead` as the HTTP headers describe it. */
+export interface HttpStorageHead {
+    readonly key: string;
+    readonly size: number;
+    readonly contentType: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly lastModified: string;
+    /** ISO 8601 (`x-expires-at`); `null` in `durable`. */
+    readonly expiresAt: string | null;
+    readonly etag: string;
+}
+export interface HttpStorageObject extends HttpStorageHead {
+    readonly body: Uint8Array;
+}
+/** `ctx.storage` of the account, seen from outside over HTTP. */
+export interface HttpStorageArea {
+    /** `null` when absent or expired; `range` sends `Range: bytes=…`. */
+    get(key: string, options?: {
+        offset?: number;
+        length?: number;
+        signal?: AbortSignal;
+    }): Promise<HttpStorageObject | null>;
+    head(key: string, signal?: AbortSignal): Promise<HttpStorageHead | null>;
+    /** Uploads a dataset for functions to read (`ifAbsent`: `If-None-Match: *`). */
+    put(key: string, body: Uint8Array | ArrayBuffer | string | Blob, options?: {
+        contentType?: string;
+        metadata?: Record<string, string>;
+        ifAbsent?: boolean;
+        /** `If-Match`: only if the object still has this etag (412 `precondition_failed`). */
+        ifMatch?: string;
+        signal?: AbortSignal;
+    }): Promise<Json>;
+    delete(key: string, options?: {
+        ifMatch?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    list(prefix?: string, options?: {
+        cursor?: string | null;
+        limit?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        objects: Json[];
+        cursor: string | null;
+    }>;
+    usage(signal?: AbortSignal): Promise<Json>;
+}
+/**
+ * The path of a key: each `/`-separated part percent-encoded. Empty, `.`
+ * and `..` parts cannot travel in a URL, so such keys are refused here
+ * (they stay usable from functions).
+ */
+export declare const storageKeyPath: (key: string) => string;