@opendatalabs/vana-sdk 3.20.1 → 3.22.0

package/dist/index.node.d.ts

@@ -51,7 +51,8 @@ export { ScopeSchema, parseScope, scopeToPathSegments, scopeMatchesPattern, scop
 export { SCOPE_ACTIONS, InvalidScopeEntryError, parseScopeEntry, formatScopeEntry, grantPermissions, permissionsToScopes, tryGrantPermissions, hasAction, type ScopeAction, type ParsedScopeEntry, type GrantPermission, } from "./protocol/scope-actions.js";
 export { WRITE_SESSION_PATH, WRITE_SIGNATURE_HEADER, WRITE_METADATA_HEADER, WRITE_FILENAME_HEADER, WRITE_CONTENT_DISPOSITION_HEADER, WRITER_ATTRIBUTION_KEY, LINEAGE_KEY, LINEAGE_FIELD, MAX_LINEAGE_SOURCES, RESERVED_WRITE_KEYS, openWriteSession, writeData, writePersonalServerData, sessionCoversScope, binaryWriteSignedBytes, normalizeBinaryMimeType, parseWriteMetadataHeader, encodeWriteMetadataHeader, type WriteTransportRetryOptions, type WriteSession, type OpenWriteSessionParams, type WriteBinaryPayload, type LineageSource, type WriteJsonDataParams, type WriteBinaryDataParams, type WriteDataParams, type WriteDataResult, type WritePersonalServerDataParams, type WritePersonalServerDataResult, type BinaryWriteSignedBytesInput, } from "./protocol/personal-server-write.js";
 export { resolveWriteSigner, type WriteSigner, type WriteSignerSource, type ViemWriteAccount, type ViemWriteWalletClient, type ResolveWriteSignerOptions, } from "./protocol/write-signer.js";
-export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, DERIVATIVE_ERROR_CODES, DerivativeErrorCodeSchema, type DerivativeErrorCode, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_STATUS_PATH, DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS, DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS, derivativeStatusTarget, getDerivativeStatus, waitForDerivativeStatus, isDerivativeStatusSettled, DerivativeStatusSchema, type DerivativeStatus, type GetDerivativeStatusParams, type WaitForDerivativeStatusParams, } from "./protocol/derivative-status.js";
 export { deriveDataPointId, isDataPointId, scopeNamespace, derivedScopeViolatesNaming, assertDerivedScopeNaming, isRedactedLineageNode, personalServerLineagePath, gatewayLineagePath, getLineage, getPersonalServerLineage, getGatewayLineage, LineageNodeSchema, RedactedLineageNodeSchema, LineageEntrySchema, LineageGraphSchema, type LineageNode, type RedactedLineageNode, type LineageEntry, type LineageGraph, type LineageReadResult, type PersonalServerLineageParams, type GatewayLineageParams, type GetLineageParams, } from "./protocol/lineage.js";
 export { DataFileEnvelopeSchema, createDataFileEnvelope, IngestResponseSchema, type DataFileEnvelope, type IngestResponse, } from "./protocol/data-file.js";
 export { createGatewayClient, type GatewayEnvelope, type GatewayProof, type Builder, type Schema, type ServerInfo, type OwnerServerRecord, type OwnerServersResult, type GatewayGrantFee, type GatewayGrantStatus, type GatewayGrantResponse, type GrantListItem, type DataPointRecord, type DataPointListResult, type ListDataPointsOptions, type RegisterServerParams, type RegisterServerResult, type RegisterBuilderParams, type RegisterBuilderResult, type RegisterDataPointParams, type RegisterDataPointResult, type GetDataPointOptions, type DeleteDataPointParams, type DeleteDataPointResult, type CreateGrantParams, type RevokeGrantParams, type AccessRecord, type PayForOperationParams, type PayForOperationResult, type SettleOpType, type SettleItem, type SettlePromoteResult, type SettleReconcileItem, type SettleParams, type SettleResult, type GatewayClient, } from "./protocol/gateway.js";

package/dist/index.node.js

@@ -34404,6 +34404,13 @@ var QUESTION_STATUSES = [
   "failed",
   "stale"
 ];
+var DERIVATIVE_ERROR_CODES = [
+  "inference_unavailable",
+  "source_missing",
+  "grant_invalid",
+  "internal"
+];
+var DerivativeErrorCodeSchema = z5.enum(DERIVATIVE_ERROR_CODES);
 var QuestionStatusSchema = z5.enum(QUESTION_STATUSES);
 var QuestionRegisteredBySchema = z5.union([
   z5.object({ kind: z5.literal("owner") }),
@@ -34425,6 +34432,14 @@ var DerivativeQuestionSchema = z5.object({
   status: QuestionStatusSchema,
   /** A short reason, set only while `status` is `failed`. */
   error: nullableString,
+  /**
+   * The coarse failure class behind `error`, set only while `status` is
+   * `failed`. `null` from a Personal Server that predates the class
+   * (`personal-server-ts` before the status route).
+   */
+  errorCode: DerivativeErrorCodeSchema.nullish().transform(
+    (value) => value ?? null
+  ),
   createdAt: z5.string(),
   updatedAt: nullableString,
   /** When the last compute finished, or `null` while `pending`. */
@@ -34557,6 +34572,7 @@ async function questionErrorFromResponse(response, body) {
       );
   }
 }
+var personalServerErrorFromQuestionResponse = questionErrorFromResponse;
 async function sendOnce(params, resolved, session, spec, bodyBytes) {
   return sendWithFreshProof(
     spec.label,
@@ -34836,6 +34852,166 @@ async function askPersonalServer(params) {
   return { registration, record };
 }
 
+// src/protocol/derivative-status.ts
+import { z as z6 } from "zod";
+var DERIVATIVE_STATUS_PATH = "/v1/derivatives/status";
+var DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS = 12e4;
+var DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS = 2e3;
+var nullable = (schema) => schema.nullish().transform((value) => value ?? null);
+var DerivativeStatusSchema = z6.object({
+  derivedScope: z6.string().min(1),
+  status: QuestionStatusSchema,
+  /** When the last compute finished, or `null` if none ever has. */
+  lastComputedAt: nullable(z6.string()),
+  /** Local version of the derived record the last compute wrote. */
+  derivedVersion: nullable(z6.number()),
+  derivedCollectedAt: nullable(z6.string()),
+  /** The failure class; `null` unless `status` is `failed`. */
+  errorCode: nullable(DerivativeErrorCodeSchema),
+  /**
+   * Seconds until the Personal Server's next automatic retry, or `null` when
+   * none is pending or running — the terminal signature. Poll on this cadence
+   * rather than guessing one.
+   */
+  retryAfterSeconds: nullable(z6.number())
+});
+function derivativeStatusTarget(derivedScope) {
+  return `${DERIVATIVE_STATUS_PATH}?derivedScope=${encodeURIComponent(derivedScope)}`;
+}
+function normalizeBaseUrl3(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch3(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new WriteRequestError("No fetch implementation available");
+  }
+  return resolved;
+}
+function requireDerivedScope(derivedScope) {
+  if (typeof derivedScope !== "string" || derivedScope.length === 0) {
+    throw new WriteRequestError("derivedScope is required");
+  }
+  return derivedScope;
+}
+function sleep3(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError2(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function timeoutError(latest, timeoutMs) {
+  return new DerivativeQuestionTimeoutError(
+    `Derived scope ${latest.derivedScope} was still ${latest.status} after ${timeoutMs}ms`,
+    {
+      derivedScope: latest.derivedScope,
+      status: latest.status,
+      errorCode: latest.errorCode,
+      retryAfterSeconds: latest.retryAfterSeconds,
+      timeoutMs
+    }
+  );
+}
+function abortError2(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new WriteRequestError("Derivative status wait was aborted");
+}
+function isDerivativeStatusSettled(status) {
+  if (status.status === "ready") return true;
+  return status.status === "failed" && status.retryAfterSeconds === null;
+}
+async function getDerivativeStatus(params) {
+  const derivedScope = requireDerivedScope(params.derivedScope);
+  const fetchFn = resolveFetch3(params.fetch);
+  const baseUrl = normalizeBaseUrl3(params.personalServerUrl);
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await buildWeb3SignedHeader({
+      signMessage: signer.signMessage,
+      aud: params.audience ?? baseUrl,
+      method: "GET",
+      uri: DERIVATIVE_STATUS_PATH,
+      grantId: params.grantId
+    })
+  );
+  let response;
+  try {
+    response = await fetchFn(
+      `${baseUrl}${derivativeStatusTarget(derivedScope)}`,
+      {
+        method: "GET",
+        headers,
+        ...params.signal ? { signal: params.signal } : {}
+      }
+    );
+  } catch (err) {
+    throw new WriteTransportError(
+      `Derivative status read failed: ${err instanceof Error ? err.message : String(err)}`,
+      1,
+      err
+    );
+  }
+  if (!response.ok) {
+    throw await personalServerErrorFromQuestionResponse(
+      response
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not JSON",
+      response.status,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const parsed = DerivativeStatusSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not a status view",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+async function waitForDerivativeStatus(params) {
+  const timeoutMs = Math.max(
+    0,
+    params.timeoutMs ?? DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS
+  );
+  const pollIntervalMs = Math.max(
+    0,
+    params.pollIntervalMs ?? DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS
+  );
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (params.signal?.aborted) throw abortError2(params.signal);
+    const latest = await getDerivativeStatus(params);
+    if (isDerivativeStatusSettled(latest)) return latest;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw timeoutError(latest, timeoutMs);
+    const waitMs = latest.retryAfterSeconds === null ? pollIntervalMs : latest.retryAfterSeconds * 1e3;
+    if (waitMs > remaining) {
+      throw timeoutError(latest, timeoutMs);
+    }
+    await sleep3(waitMs, params.signal);
+  }
+}
+
 // src/protocol/gateway.ts
 function withGrantPermissions(grant) {
   const stripped = { ...grant };
@@ -35916,9 +36092,13 @@ export {
   ContractNotFoundError,
   DATA_ACCESS_OP_TYPE,
   DATA_REGISTRY_STATUS_ABI,
+  DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS,
+  DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS,
   DEFAULT_QUESTION_POLL_INTERVAL_MS,
   DEFAULT_QUESTION_TIMEOUT_MS,
+  DERIVATIVE_ERROR_CODES,
   DERIVATIVE_QUESTIONS_PATH,
+  DERIVATIVE_STATUS_PATH,
   DataFileEnvelopeSchema,
   DataPointDeletedError,
   DataPointNotFoundError,
@@ -35927,6 +36107,7 @@ export {
   DerivativeComputeUnavailableError,
   DerivativeCycleError,
   DerivativeDerivedScopeRequiredError,
+  DerivativeErrorCodeSchema,
   DerivativeQuestionFailedError,
   DerivativeQuestionInvalidError,
   DerivativeQuestionNotFoundError,
@@ -35934,6 +36115,7 @@ export {
   DerivativeQuestionSchema,
   DerivativeQuestionTimeoutError,
   DerivativeSourceNotGrantedError,
+  DerivativeStatusSchema,
   DropboxStorage,
   ECIESError,
   ESCROW_DEPOSIT_ABI2 as ESCROW_DEPOSIT_ABI,
@@ -36069,6 +36251,7 @@ export {
   decryptWithPassword,
   deleteDataPoint,
   deleteQuestion,
+  derivativeStatusTarget,
   deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
@@ -36092,6 +36275,7 @@ export {
   getContractAddress,
   getContractController,
   getContractInfo,
+  getDerivativeStatus,
   getFee,
   getGatewayLineage,
   getLineage,
@@ -36107,6 +36291,7 @@ export {
   isDataPointId,
   isDataPointTombstone,
   isDataPortabilityGatewayConfig,
+  isDerivativeStatusSettled,
   isECIESEncrypted,
   isPlatformSupported,
   isRedactedLineageNode,
@@ -36154,6 +36339,7 @@ export {
   verifyGrantRegistration,
   verifyPkceChallenge,
   verifyWeb3Signed,
+  waitForDerivativeStatus,
   waitForQuestion,
   writeData,
   writePersonalServerData