@opendatalabs/vana-sdk 3.18.1 → 3.19.1

package/dist/protocol/derivative-questions.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Builder-side client for the Personal Server derivative question API.
+ *
+ * @remarks
+ * A question is a standing prompt over the owner's source scopes. The
+ * Personal Server answers it locally (the raw sources never leave the
+ * machine except through its inference call) and writes the answer into the
+ * derived scope as an ordinary derivative record, with lineage pointing at
+ * the sources. The builder then reads the derived scope with its normal read
+ * grant. Every source change re-runs the question, so a builder registers it
+ * once and keeps reading a scope that stays up to date.
+ *
+ * One grant carries the whole pipeline, and it needs all three of:
+ *
+ * - a bare read entry for every source scope (the answer exposes them, so
+ *   the server refuses the registration otherwise:
+ *   `DERIVATIVE_SOURCE_NOT_GRANTED`),
+ * - a bare read entry for the derived scope (to read the answer back),
+ * - `write:<derivedScope>` (the credential the question routes authorize
+ *   against).
+ *
+ * Authentication is the Write API's, with no new credential: the write
+ * session bearer from {@link openWriteSession} plus a fresh, single-use
+ * `X-Vana-Write-Signature` Web3Signed proof over every request, carrying the
+ * grant id as a signed claim. These helpers own that: they open one session
+ * per `{ signer, Personal Server, grant }`, reuse it across calls, sign a new
+ * proof per request, and re-open the session once when a call comes back a
+ * 401 the session is responsible for (the Personal Server keeps sessions in
+ * memory and forgets them when it restarts; a 401 about the PROOF is
+ * surfaced as it is, since a new session would not change it).
+ *
+ * Two rules govern the proof on these routes, and both are the server's
+ * (`personal-server-ts` d91124d and later):
+ *
+ * - the signed `uri` claim covers the query string, not just the path,
+ *   because `?derivedScope=` is what the list route authorizes against;
+ * - every call carries a fresh `nonce` claim, which becomes the server's
+ *   replay key. Without one the whole proof is the key, so two identical
+ *   polls signed inside the same second are refused as a replay.
+ *
+ * @category Protocol
+ */
+import { z } from "zod";
+import type { DataFileEnvelope } from "./data-file.js";
+import { type WriteTransportRetryOptions } from "./write-request.js";
+import { type ResolveWriteSignerOptions, type WriteSignerSource } from "./write-signer.js";
+/** Path the question routes are mounted at. */
+export declare const DERIVATIVE_QUESTIONS_PATH = "/v1/derivatives/questions";
+/** The most source scopes one question may read. */
+export declare const MAX_QUESTION_SOURCE_SCOPES = 16;
+/** The longest question text the Personal Server accepts. */
+export declare const MAX_QUESTION_CHARS = 8000;
+/** The longest model id the Personal Server accepts. */
+export declare const MAX_QUESTION_MODEL_CHARS = 128;
+/** How long {@link waitForQuestion} polls before giving up. */
+export declare const DEFAULT_QUESTION_TIMEOUT_MS = 120000;
+/** How long {@link waitForQuestion} waits between polls. */
+export declare const DEFAULT_QUESTION_POLL_INTERVAL_MS = 2000;
+/** Every state a question can be in. */
+export declare const QUESTION_STATUSES: readonly ["pending", "ready", "failed", "stale"];
+/**
+ * `pending` (never computed) -> `ready` | `failed`; a source change or an
+ * explicit recompute puts a computed question back to `stale`, which
+ * settles as `ready` or `failed` again.
+ */
+export declare const QuestionStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    ready: "ready";
+    failed: "failed";
+    stale: "stale";
+}>;
+/** @see {@link QuestionStatusSchema} */
+export type QuestionStatus = z.infer<typeof QuestionStatusSchema>;
+/** Who registered the question: the owner, or a builder under a grant. */
+export declare const QuestionRegisteredBySchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"owner">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"builder">;
+    builder: z.ZodString;
+    grantId: z.ZodString;
+}, z.core.$strip>]>;
+/** @see {@link QuestionRegisteredBySchema} */
+export type QuestionRegisteredBy = z.infer<typeof QuestionRegisteredBySchema>;
+/**
+ * A question registration as the Personal Server reports it (the answer of
+ * register, get and list).
+ */
+export declare const DerivativeQuestionSchema: z.ZodObject<{
+    questionId: z.ZodString;
+    derivedScope: z.ZodString;
+    sourceScopes: z.ZodArray<z.ZodString>;
+    question: z.ZodString;
+    model: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    registeredBy: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"owner">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"builder">;
+        builder: z.ZodString;
+        grantId: z.ZodString;
+    }, z.core.$strip>]>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        ready: "ready";
+        failed: "failed";
+        stale: "stale";
+    }>;
+    error: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    lastComputedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    derivedVersion: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, z.ZodTransform<number | null, number | null | undefined>>;
+    derivedCollectedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$strip>;
+/** @see {@link DerivativeQuestionSchema} */
+export type DerivativeQuestion = z.infer<typeof DerivativeQuestionSchema>;
+/**
+ * The 202 answer of a recompute request: the same registration view every
+ * other question route answers, so a client needs one schema.
+ *
+ * @remarks
+ * Older Personal Servers answered only
+ * `{ questionId, derivedScope, status }` here. The full view is a superset
+ * of those three fields, so code reading them is unaffected, but the answer
+ * of a server before `personal-server-ts` d91124d no longer parses.
+ */
+export declare const QuestionRecomputeResultSchema: z.ZodObject<{
+    questionId: z.ZodString;
+    derivedScope: z.ZodString;
+    sourceScopes: z.ZodArray<z.ZodString>;
+    question: z.ZodString;
+    model: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    registeredBy: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"owner">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"builder">;
+        builder: z.ZodString;
+        grantId: z.ZodString;
+    }, z.core.$strip>]>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        ready: "ready";
+        failed: "failed";
+        stale: "stale";
+    }>;
+    error: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    lastComputedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+    derivedVersion: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodNumber>>, z.ZodTransform<number | null, number | null | undefined>>;
+    derivedCollectedAt: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$strip>;
+/** @see {@link QuestionRecomputeResultSchema} */
+export type QuestionRecomputeResult = DerivativeQuestion;
+/** The answer of a delete request. */
+export declare const QuestionDeleteResultSchema: z.ZodObject<{
+    questionId: z.ZodString;
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** @see {@link QuestionDeleteResultSchema} */
+export type QuestionDeleteResult = z.infer<typeof QuestionDeleteResultSchema>;
+/**
+ * Connection, credential and transport shared by every question call.
+ *
+ * @remarks
+ * The write session is opened on demand and reused for every later call
+ * made with the same `signer` object, Personal Server, audience, grant and
+ * `fetch`; a 401 re-opens it once and replays the call.
+ */
+export interface DerivativeQuestionAuthParams extends ResolveWriteSignerOptions {
+    /** Personal Server origin, e.g. `https://ps.example.com`. */
+    personalServerUrl: string;
+    /** Builder key: a viem `LocalAccount`, `WalletClient`, or `{ signMessage }`. */
+    signer: WriteSignerSource;
+    /**
+     * The grant the call runs under. It must carry `write:<derivedScope>`, a
+     * bare read entry for the derived scope, and a bare read entry for every
+     * source scope.
+     */
+    grantId: string;
+    /** Web3Signed audience; defaults to `personalServerUrl`. */
+    audience?: string;
+    /** `fetch` to use; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Extra request headers. */
+    headers?: HeadersInit;
+    retry?: WriteTransportRetryOptions;
+    /** Aborts the request (and, for {@link waitForQuestion}, the polling). */
+    signal?: AbortSignal;
+}
+export interface RegisterQuestionParams extends DerivativeQuestionAuthParams {
+    /**
+     * The scope the answer is written into. Must not share its first
+     * dot-segment with any source scope, so put derivatives in the app's own
+     * namespace.
+     */
+    derivedScope: string;
+    /**
+     * The scopes the question reads: 1 to
+     * {@link MAX_QUESTION_SOURCE_SCOPES} distinct scopes, none of them the
+     * derived scope. They do not have to hold data yet: the question computes
+     * once they do.
+     */
+    sourceScopes: readonly string[];
+    /** The prompt, 1 to {@link MAX_QUESTION_CHARS} characters. */
+    question: string;
+    /** Model id override; omitted = the Personal Server's default model. */
+    model?: string;
+}
+export interface GetQuestionParams extends DerivativeQuestionAuthParams {
+    questionId: string;
+}
+export interface ListQuestionsParams extends DerivativeQuestionAuthParams {
+    /**
+     * The derived scope to list. A builder must name one (it may only see its
+     * own questions on a scope it may write); the unfiltered list is the
+     * owner's.
+     */
+    derivedScope: string;
+}
+export interface RecomputeQuestionParams extends DerivativeQuestionAuthParams {
+    questionId: string;
+}
+export interface DeleteQuestionParams extends DerivativeQuestionAuthParams {
+    questionId: string;
+}
+export interface WaitForQuestionParams extends DerivativeQuestionAuthParams {
+    questionId: string;
+    /** Give up after this long (default {@link DEFAULT_QUESTION_TIMEOUT_MS}). */
+    timeoutMs?: number;
+    /** Wait between polls (default {@link DEFAULT_QUESTION_POLL_INTERVAL_MS}). */
+    pollIntervalMs?: number;
+}
+export interface AskPersonalServerParams extends RegisterQuestionParams {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/** {@link askPersonalServer}'s answer. */
+export interface AskPersonalServerResult {
+    /** The settled registration (`status` is `ready`). */
+    registration: DerivativeQuestion;
+    /** The derived record the Personal Server wrote and the builder just read. */
+    record: DataFileEnvelope;
+}
+/**
+ * Register a standing question over the owner's source scopes.
+ *
+ * @remarks
+ * Sends `POST /v1/derivatives/questions`. The registration comes back
+ * `pending` and the first compute is scheduled immediately; poll it with
+ * {@link waitForQuestion}, then read `derivedScope`.
+ *
+ * @example
+ * ```typescript
+ * const registered = await registerQuestion({
+ *   personalServerUrl: "https://ps.example.com",
+ *   signer,
+ *   grantId,
+ *   derivedScope: "coach.weekly",
+ *   sourceScopes: ["oura.sleep", "chatgpt.conversations"],
+ *   question: "How did my sleep relate to my mood this week?",
+ * });
+ * ```
+ * @returns The registration, `status: "pending"`.
+ * @throws {WriteRequestError} Before sending: a missing grant, a bad scope
+ *   list, an over-long question, a derived scope under a source's namespace.
+ * @throws {DerivativeSourceNotGrantedError} 403: a source scope is not
+ *   read-granted to the builder (`details.scopes`).
+ * @throws {DerivativeCycleError} 409: the question would make the derived
+ *   scope a transitive source of itself.
+ * @throws {DerivativeQuestionInvalidError} 400 from the server.
+ * @throws {DerivativeComputeUnavailableError} 503: no compute layer.
+ * @throws {WriteForbiddenError} 403: the grant does not authorize writing
+ *   the derived scope.
+ */
+export declare function registerQuestion(params: RegisterQuestionParams): Promise<DerivativeQuestion>;
+/**
+ * Read one question's current state.
+ *
+ * @remarks
+ * Sends `GET /v1/derivatives/questions/:id`. A builder only sees questions
+ * it registered itself; anything else is a 404.
+ *
+ * @returns The registration, including `status`, `lastComputedAt`,
+ *   `derivedVersion` and (when it failed) `error`.
+ * @throws {DerivativeQuestionNotFoundError} 404: unknown id, or not this
+ *   builder's question.
+ */
+export declare function getQuestion(params: GetQuestionParams): Promise<DerivativeQuestion>;
+/**
+ * List the questions this builder registered on a derived scope.
+ *
+ * @remarks
+ * Sends `GET /v1/derivatives/questions?derivedScope=...`. The scope is
+ * required for a builder: it is what the call is authorized against, which
+ * is exactly why the signed proof commits to the query string as well as the
+ * path. The target is built once and used for both, so the signature and the
+ * request can never name different scopes.
+ *
+ * @returns The registrations, newest state included.
+ * @throws {DerivativeDerivedScopeRequiredError} 400
+ *   `DERIVATIVE_DERIVED_SCOPE_REQUIRED` when the server saw no
+ *   `?derivedScope=` (the SDK refuses an empty one before sending).
+ */
+export declare function listQuestions(params: ListQuestionsParams): Promise<DerivativeQuestion[]>;
+/**
+ * Ask the Personal Server to recompute a question now.
+ *
+ * @remarks
+ * Sends `POST /v1/derivatives/questions/:id/recompute`, which answers 202
+ * and schedules the compute immediately instead of after the usual quiet
+ * period. Use it to retry a `failed` question; a source change recomputes on
+ * its own.
+ *
+ * @returns The full registration view, with the status the question was put
+ *   into (`pending` when it had never computed, else `stale`). Servers
+ *   before `personal-server-ts` d91124d answered only
+ *   `{ questionId, derivedScope, status }` here, which no longer parses.
+ */
+export declare function recomputeQuestion(params: RecomputeQuestionParams): Promise<QuestionRecomputeResult>;
+/**
+ * Delete a question registration.
+ *
+ * @remarks
+ * Sends `DELETE /v1/derivatives/questions/:id`. The question stops
+ * recomputing; the derived records it already wrote are left alone (delete
+ * those through the data-point deletion path).
+ *
+ * @returns `{ questionId, deleted: true }`.
+ */
+export declare function deleteQuestion(params: DeleteQuestionParams): Promise<QuestionDeleteResult>;
+/**
+ * Poll a question until it settles.
+ *
+ * @remarks
+ * Calls {@link getQuestion} every `pollIntervalMs` until `status` is `ready`
+ * or `failed` and returns that state; a `failed` question is returned, not
+ * thrown, so the caller can read `error` and decide whether to
+ * {@link recomputeQuestion}. All polls share the one write session and each
+ * signs its own proof.
+ *
+ * @example
+ * ```typescript
+ * const settled = await waitForQuestion({
+ *   personalServerUrl,
+ *   signer,
+ *   grantId,
+ *   questionId: registered.questionId,
+ *   timeoutMs: 60_000,
+ * });
+ * if (settled.status === "ready") {
+ *   // read derivedScope
+ * }
+ * ```
+ * @returns The settled registration (`ready` or `failed`).
+ * @throws {DerivativeQuestionTimeoutError} The question had not settled
+ *   within `timeoutMs`; it keeps computing on the server.
+ * @throws Whatever {@link getQuestion} throws, and the `signal`'s abort
+ *   reason when the caller aborts.
+ */
+export declare function waitForQuestion(params: WaitForQuestionParams): Promise<DerivativeQuestion>;
+/**
+ * Register a question, wait for it, and read the answer: the whole builder
+ * loop in one call.
+ *
+ * @remarks
+ * {@link registerQuestion} + {@link waitForQuestion} +
+ * {@link readPersonalServerData} on the derived scope, which is why the
+ * grant needs a bare read entry for `derivedScope` on top of
+ * `write:<derivedScope>` and the source reads. The read is the plain
+ * Web3Signed one; when the grant is priced, settle the 402 yourself with the
+ * escrow-aware read from `@opendatalabs/vana-sdk/server` and use
+ * {@link registerQuestion} and {@link waitForQuestion} directly.
+ *
+ * A question registered this way keeps recomputing after the call returns:
+ * every later change to a source scope refreshes the derived record, and the
+ * builder can read it again without registering anything.
+ *
+ * @example
+ * ```typescript
+ * const { registration, record } = await askPersonalServer({
+ *   personalServerUrl: "https://ps.example.com",
+ *   signer,
+ *   grantId,
+ *   derivedScope: "coach.weekly",
+ *   sourceScopes: ["oura.sleep"],
+ *   question: "How did my sleep trend this week?",
+ * });
+ * console.log(record.data.answer, registration.questionId);
+ * ```
+ * @returns The settled registration and the derived record.
+ * @throws {DerivativeQuestionFailedError} The question settled as `failed`
+ *   (`details.error` is the server's reason).
+ * @throws Everything {@link registerQuestion}, {@link waitForQuestion} and
+ *   the read path throw.
+ */
+export declare function askPersonalServer(params: AskPersonalServerParams): Promise<AskPersonalServerResult>;