ankka 0.10.0 → 0.12.0

package/dist/client.d.ts

@@ -1,11 +1,12 @@
 import { type Client as ConnectClient, type Transport } from "@connectrpc/connect";
 import { Client } from "./_proto/ankka/protocol/v1/client_pb.ts";
 import { jsonCodec, type Shape } from "./codec.ts";
-import { type Metadata } from "./effects/common.ts";
+import { CommandError, type Metadata } from "./effects/common.ts";
 import type { HandlerRef } from "./handlers.ts";
 import { type ComponentKind } from "./kinds.ts";
-import type { Duration } from "./time.ts";
+import { Duration } from "./time.ts";
 import { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.ts";
+import { type AgentOutcome, type DecisionInput } from "./approvals.ts";
 /** A component class as the typed client sees it: an id and, on its prototype, its kind. */
 export interface ComponentRef {
     readonly componentId: string;
@@ -18,21 +19,78 @@ interface Connection {
     transport: Transport | undefined;
     stub: ConnectClient<typeof Client> | undefined;
 }
+/** The first protocol whose runtime can wait for a workflow's end; an older one answers `UNIMPLEMENTED`. */
+export declare const AWAIT_SINCE = "1.18";
+/** One part of a wait served as a stream: the wait goes on, or how it ended. */
+export type AwaitPart<S> = {
+    readonly kind: "heartbeat";
+} | {
+    readonly kind: "ended";
+    readonly state: S;
+} | {
+    readonly kind: "failed";
+    readonly error: CommandError;
+} | {
+    readonly kind: "timed-out";
+    readonly message: string;
+};
+/** A part as one line of JSON, which is what an `sse` route yields for it. */
+export declare function awaitPartJson<S>(part: AwaitPart<S>): string;
 /** One call, ready to invoke or stream. */
 export declare class Invocation<I, R> {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined);
-    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined, state?: Shape<unknown>);
+    /**
+     * Invokes and decodes the reply; a refusal rejects with `CommandError`. An agent's turn that waits for a
+     * person rejects with `ApprovalAwaited`; `ask` answers it instead.
+     */
     invoke(input?: I): Promise<R>;
-    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    /**
+     * Sends this command to the workflow and then waits for its end, as one call: answered with the state it
+     * ended with, within `timeoutMillis` of the command being sent. A refusal of the command rejects at once and
+     * no wait begins; the command's own reply is not kept. `state` decodes it, unless the workflow class did.
+     */
+    thenAwaitEnd<S>(timeoutMillis: number, state?: Shape<S>): AwaitingInvocation<I, S>;
+    /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
+    ask(input?: I): Promise<AgentOutcome<R>>;
+    /**
+     * Decides one of the session's approval requests; this invocation names the handler whose turn waits.
+     * `by` names who decided and is required. When it was the turn's last awaited decision the turn goes on,
+     * and this answers as `ask` would have. A request already decided is a conflict.
+     */
+    decide(approvalId: string, decision: DecisionInput): Promise<AgentOutcome<R>>;
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`, a turn that waits with `ApprovalAwaited`. */
     stream(input?: I): AsyncIterable<string>;
+    /** As `stream`, ending with one awaiting part when the turn waits for a person. */
+    streamParts(input?: I): AsyncIterable<string | Extract<AgentOutcome<never>, {
+        kind: "awaiting-approval";
+    }>>;
+}
+/** A command to a workflow followed by a wait for its end, with one deadline from the send. */
+export declare class AwaitingInvocation<I, S> {
+    #private;
+    constructor(timeoutMillis: number, send: (input: I | undefined) => Promise<unknown>, wait: (leftMillis: number) => Promise<S>);
+    /** Sends the command and waits for the end; rejects as `Calls.awaitEnd` does. */
+    invoke(input?: I): Promise<S>;
 }
 /** Calls on one component instance, by wire name. */
 export declare class Calls {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string);
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, state?: Shape<unknown>);
     /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
     call<I = undefined, R = unknown>(name: string, input?: Shape<I>, reply?: Shape<R>): Invocation<I, R>;
+    /**
+     * Waits for this workflow's end, for at most `timeoutMillis`, and resolves with the state it ended with — at
+     * once when it already has. A workflow that failed or was deleted rejects with `CommandError` whose code is
+     * `WORKFLOW_FAILED` and whose `details` hold `step`, `reason` and `deleted`; a wait not answered in time
+     * rejects with `TIMEOUT` and the workflow runs on. A paused workflow has not ended. There is no default.
+     */
+    awaitEnd<S>(timeoutMillis: number, state?: Shape<S>): Promise<S>;
+    /**
+     * The same wait as a stream, for an `sse` route that must outlast the idle timeout: a heartbeat while it goes
+     * on, then exactly one `ended`, `failed` or `timed-out` part. `awaitPartJson` renders a part as a line.
+     */
+    awaitEndParts<S>(timeoutMillis: number, state?: Shape<S>): AsyncIterable<AwaitPart<S>>;
 }
 /** Calls on one component instance through its class's handler table, fully typed. */
 export declare class TypedCalls<C> {
@@ -40,14 +98,70 @@ export declare class TypedCalls<C> {
     constructor(calls: Calls);
     /** `call(ShoppingCartEntity.handlers.addItem)`: the handler's wire name and shapes come from the declaration. */
     call<I, R>(handler: HandlerRef<C, I, R, any>): Invocation<I, R>;
+    /** For a workflow: waits for its end and resolves with its state, decoded as the class declares it. */
+    awaitEnd<S = StateOf<C>>(timeoutMillis: number): Promise<S>;
+    /** For a workflow: the same wait as a stream of parts. */
+    awaitEndParts<S = StateOf<C>>(timeoutMillis: number): AsyncIterable<AwaitPart<S>>;
+}
+/** The first protocol in which a view's query can be streamed and watched. */
+export declare const VIEW_STREAMS_SINCE = "1.17";
+/** What a watch of a view gives: a row as the query sees it now, a removal of one it gave, or the caught-up marker. */
+export type WatchEvent<Row> = {
+    readonly kind: "row";
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly kind: "removed";
+    readonly key: string;
+} | {
+    readonly kind: "caughtUp";
+};
+/** What a watch does past its unread bound: none slows the view. */
+export type Overflow = "dropHead" | "dropTail" | "dropNew" | "dropAll" | "fail";
+export interface WatchOptions {
+    /** How many unread rows the watch holds, one per key; the instance's own bound when absent. */
+    readonly unread?: number;
+    /** What it does past that bound; `dropHead`, the row changed longest ago, when absent. */
+    readonly overflow?: Overflow;
+}
+/** A watch ended for `reason`: `rebuilt`, `instance-stopping`, `listener-lost` or `unread`. Watch again for the rows now. */
+export declare class WatchEnded extends Error {
+    readonly reason: string;
+    constructor(reason: string);
 }
+/** A workflow instance's state type, read from its `state` getter. */
+type StateOf<C> = C extends {
+    readonly state: infer S;
+} ? S : unknown;
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export declare class Views {
     #private;
-    constructor(connection: Connection);
+    constructor(connection: Connection, metadata?: Metadata);
     get<Row>(viewId: string, key: string, row: Shape<Row>): Promise<Row | null>;
     all<Row>(viewId: string, row: Shape<Row>): Promise<Row[]>;
     query<Row>(viewId: string, name: string, key: string | null, row: Shape<Row>): Promise<Row[]>;
+    /**
+     * The rows of one of a view's declared queries, asked by name with the values it takes. At most
+     * `limit` rows, 1000 when it is not given, in the statement's own order.
+     */
+    ask<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, limit?: number): Promise<Row[]>;
+    /**
+     * The rows of `all` or one of a view's declared queries as the database yields them: nothing
+     * collected, and no limit unless one is given. A statement the database ends, or a reader that
+     * takes nothing for its timeout, throws.
+     */
+    stream<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: {
+        readonly limit?: number;
+    }): AsyncIterable<Row>;
+    /**
+     * A watch of one of a view's declared queries, declared `{ watched: true }`: every row it matches
+     * now, then `caughtUp`, then each row as it is written and matches and a `removed` for each given row
+     * that stops matching. Throws `WatchEnded` when it ends with a reason. `unread` bounds the rows held
+     * for a reader that has not read them, and `overflow` says what happens past that bound.
+     */
+    watch<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
+    /** A watch of one row by its key: the row now, then `caughtUp`, then each version and a `removed` when it is deleted. */
+    watchRow<Row>(viewId: string, key: string, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
 }
 /** What a timer fires: a component class and one of its handlers, or the same by name. */
 export type TimerTarget = {
@@ -61,13 +175,78 @@ export type TimerTarget = {
     readonly input?: Shape<any>;
     readonly entityId?: string;
 };
+/** What a recurring timer fires: a timed action's class and one of its handlers, or the same by name. */
+export type TimedActionTarget = {
+    readonly component: ComponentRef;
+    readonly handler: HandlerRef<any, any, any, any>;
+} | {
+    readonly componentId: string;
+    readonly name: string;
+    readonly input?: Shape<any>;
+};
 export declare class Timers {
     #private;
     constructor(connection: Connection);
     /** Schedules `target` after `delay`. Scheduling twice under one id replaces the earlier schedule. */
     schedule(timerId: string, delay: Duration, target: TimerTarget, input?: unknown): Promise<void>;
+    /**
+     * Schedules `target`, a timed action's handler, first after `delay` (zero or less is due at once) and
+     * then every `period` until it is cancelled or replaced. Setting it again with the same handler and
+     * period keeps its next due time, so a service may set its recurring timers every time it starts.
+     * A period outside 1 millisecond to 36,500 days is refused with `BAD_REQUEST` before anything is sent.
+     */
+    scheduleRecurring(timerId: string, delay: Duration, period: Duration, target: TimedActionTarget, input?: unknown): Promise<void>;
+    /** Cancels the timer under `timerId`, whether it fires once or recurs. */
     cancel(timerId: string): Promise<void>;
 }
+export declare const MAX_SECRET_NAME_LENGTH = 253;
+export declare const MAX_SECRET_VALUE_BYTES = 65536;
+/** What is wrong with a secret's name, if anything: the runtime's own rule. */
+export declare function secretNameProblem(name: string): string | undefined;
+/** What is wrong with a secret's value, if anything. Never quotes the value. */
+export declare function secretValueProblem(value: string): string | undefined;
+/**
+ * The service's secret store: named text values the runtime keeps in the service's own database,
+ * encrypted with a key this process never sees. Offered to endpoints, workflow steps, consumers,
+ * timed actions and agents; an entity and a view have no `secrets` at all.
+ *
+ * Every refusal is a `CommandError` with the runtime's code: `BAD_REQUEST` for a name or a value that
+ * breaks its rule, `INTERNAL` when the service has no secret key or a value was kept with another
+ * one, `UNAVAILABLE` when the database cannot be reached.
+ */
+export declare class Secrets {
+    #private;
+    /** The store reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client?: ComponentClient);
+    /** Keeps `value` under `name`, replacing what was there. */
+    put(name: string, value: string): Promise<void>;
+    /** The value kept under `name`, or `undefined` when there is none. Never an empty string. */
+    get(name: string): Promise<string | undefined>;
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    delete(name: string): Promise<void>;
+}
+/** A secret store for unit tests: a map, applying the runtime's rules with its words. */
+export declare class InMemorySecrets extends Secrets {
+    readonly values: Map<string, string>;
+    put(name: string, value: string): Promise<void>;
+    get(name: string): Promise<string | undefined>;
+    delete(name: string): Promise<void>;
+}
+/** A store for unit tests whose every call throws: the unit kit's default, beside `noClient()`. */
+export declare function noSecrets(): Secrets;
+/**
+ * @internal What a call to another service is sent through: `client`'s sidecar, and the metadata of
+ * the handler `client` was scoped to. Not a member of the client, which an entity holds too.
+ */
+export declare function channelOf(client: ComponentClient): {
+    stub(): ConnectClient<typeof Client>;
+    metadata: Metadata;
+} | undefined;
+/**
+ * @internal The secret store reached through `client`'s sidecar. Not a member of the client, which
+ * an entity holds too: only the component kinds that may have a store call this.
+ */
+export declare function secretsFor(client: ComponentClient): Secrets;
 export declare class ComponentClient {
     #private;
     readonly views: Views;
@@ -93,6 +272,8 @@ export declare class ComponentClient {
     } | string, instanceId?: string): AutonomousAgentCalls;
     /** @internal A call with a JSON body and a JSON reply, as the platform's own components take them. */
     _raw(kind: ComponentKind, componentId: string, entityId: string, name: string, body?: unknown): Promise<unknown>;
+    /** @internal A decision on an approval request; a refusal rejects with `CommandError`. */
+    _decide(kind: ComponentKind, componentId: string, entityId: string, name: string, approvalId: string, decision: DecisionInput): Promise<void>;
     /** @internal A streaming call whose tokens are text. */
     _rawStream(kind: ComponentKind, componentId: string, entityId: string, name: string): AsyncIterable<string>;
     /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */