@opendatalabs/vana-sdk 3.20.1 → 3.22.0

package/dist/index.node.cjs

@@ -1186,9 +1186,13 @@ __export(index_node_exports, {
   ContractNotFoundError: () => ContractNotFoundError,
   DATA_ACCESS_OP_TYPE: () => DATA_ACCESS_OP_TYPE,
   DATA_REGISTRY_STATUS_ABI: () => DATA_REGISTRY_STATUS_ABI,
+  DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS: () => DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS,
+  DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS: () => DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS,
   DEFAULT_QUESTION_POLL_INTERVAL_MS: () => DEFAULT_QUESTION_POLL_INTERVAL_MS,
   DEFAULT_QUESTION_TIMEOUT_MS: () => DEFAULT_QUESTION_TIMEOUT_MS,
+  DERIVATIVE_ERROR_CODES: () => DERIVATIVE_ERROR_CODES,
   DERIVATIVE_QUESTIONS_PATH: () => DERIVATIVE_QUESTIONS_PATH,
+  DERIVATIVE_STATUS_PATH: () => DERIVATIVE_STATUS_PATH,
   DataFileEnvelopeSchema: () => DataFileEnvelopeSchema,
   DataPointDeletedError: () => DataPointDeletedError,
   DataPointNotFoundError: () => DataPointNotFoundError,
@@ -1197,6 +1201,7 @@ __export(index_node_exports, {
   DerivativeComputeUnavailableError: () => DerivativeComputeUnavailableError,
   DerivativeCycleError: () => DerivativeCycleError,
   DerivativeDerivedScopeRequiredError: () => DerivativeDerivedScopeRequiredError,
+  DerivativeErrorCodeSchema: () => DerivativeErrorCodeSchema,
   DerivativeQuestionFailedError: () => DerivativeQuestionFailedError,
   DerivativeQuestionInvalidError: () => DerivativeQuestionInvalidError,
   DerivativeQuestionNotFoundError: () => DerivativeQuestionNotFoundError,
@@ -1204,6 +1209,7 @@ __export(index_node_exports, {
   DerivativeQuestionSchema: () => DerivativeQuestionSchema,
   DerivativeQuestionTimeoutError: () => DerivativeQuestionTimeoutError,
   DerivativeSourceNotGrantedError: () => DerivativeSourceNotGrantedError,
+  DerivativeStatusSchema: () => DerivativeStatusSchema,
   DropboxStorage: () => DropboxStorage,
   ECIESError: () => ECIESError,
   ESCROW_DEPOSIT_ABI: () => ESCROW_DEPOSIT_ABI2,
@@ -1339,6 +1345,7 @@ __export(index_node_exports, {
   decryptWithPassword: () => decryptWithPassword,
   deleteDataPoint: () => deleteDataPoint,
   deleteQuestion: () => deleteQuestion,
+  derivativeStatusTarget: () => derivativeStatusTarget,
   deriveDataPointId: () => deriveDataPointId,
   deriveMasterKey: () => deriveMasterKey,
   deriveScopeKey: () => deriveScopeKey,
@@ -1362,6 +1369,7 @@ __export(index_node_exports, {
   getContractAddress: () => getContractAddress,
   getContractController: () => getContractController,
   getContractInfo: () => getContractInfo,
+  getDerivativeStatus: () => getDerivativeStatus,
   getFee: () => getFee,
   getGatewayLineage: () => getGatewayLineage,
   getLineage: () => getLineage,
@@ -1377,6 +1385,7 @@ __export(index_node_exports, {
   isDataPointId: () => isDataPointId,
   isDataPointTombstone: () => isDataPointTombstone,
   isDataPortabilityGatewayConfig: () => isDataPortabilityGatewayConfig,
+  isDerivativeStatusSettled: () => isDerivativeStatusSettled,
   isECIESEncrypted: () => isECIESEncrypted,
   isPlatformSupported: () => isPlatformSupported,
   isRedactedLineageNode: () => isRedactedLineageNode,
@@ -1424,6 +1433,7 @@ __export(index_node_exports, {
   verifyGrantRegistration: () => verifyGrantRegistration,
   verifyPkceChallenge: () => verifyPkceChallenge,
   verifyWeb3Signed: () => verifyWeb3Signed,
+  waitForDerivativeStatus: () => waitForDerivativeStatus,
   waitForQuestion: () => waitForQuestion,
   writeData: () => writeData,
   writePersonalServerData: () => writePersonalServerData
@@ -34662,6 +34672,13 @@ var QUESTION_STATUSES = [
   "failed",
   "stale"
 ];
+var DERIVATIVE_ERROR_CODES = [
+  "inference_unavailable",
+  "source_missing",
+  "grant_invalid",
+  "internal"
+];
+var DerivativeErrorCodeSchema = import_zod5.z.enum(DERIVATIVE_ERROR_CODES);
 var QuestionStatusSchema = import_zod5.z.enum(QUESTION_STATUSES);
 var QuestionRegisteredBySchema = import_zod5.z.union([
   import_zod5.z.object({ kind: import_zod5.z.literal("owner") }),
@@ -34683,6 +34700,14 @@ var DerivativeQuestionSchema = import_zod5.z.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: import_zod5.z.string(),
   updatedAt: nullableString,
   /** When the last compute finished, or `null` while `pending`. */
@@ -34815,6 +34840,7 @@ async function questionErrorFromResponse(response, body) {
       );
   }
 }
+var personalServerErrorFromQuestionResponse = questionErrorFromResponse;
 async function sendOnce(params, resolved, session, spec, bodyBytes) {
   return sendWithFreshProof(
     spec.label,
@@ -35094,6 +35120,166 @@ async function askPersonalServer(params) {
   return { registration, record };
 }
 
+// src/protocol/derivative-status.ts
+var import_zod6 = require("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 = import_zod6.z.object({
+  derivedScope: import_zod6.z.string().min(1),
+  status: QuestionStatusSchema,
+  /** When the last compute finished, or `null` if none ever has. */
+  lastComputedAt: nullable(import_zod6.z.string()),
+  /** Local version of the derived record the last compute wrote. */
+  derivedVersion: nullable(import_zod6.z.number()),
+  derivedCollectedAt: nullable(import_zod6.z.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(import_zod6.z.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 };
@@ -36175,9 +36361,13 @@ async function parsePSError(response) {
   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,
@@ -36186,6 +36376,7 @@ async function parsePSError(response) {
   DerivativeComputeUnavailableError,
   DerivativeCycleError,
   DerivativeDerivedScopeRequiredError,
+  DerivativeErrorCodeSchema,
   DerivativeQuestionFailedError,
   DerivativeQuestionInvalidError,
   DerivativeQuestionNotFoundError,
@@ -36193,6 +36384,7 @@ async function parsePSError(response) {
   DerivativeQuestionSchema,
   DerivativeQuestionTimeoutError,
   DerivativeSourceNotGrantedError,
+  DerivativeStatusSchema,
   DropboxStorage,
   ECIESError,
   ESCROW_DEPOSIT_ABI,
@@ -36328,6 +36520,7 @@ async function parsePSError(response) {
   decryptWithPassword,
   deleteDataPoint,
   deleteQuestion,
+  derivativeStatusTarget,
   deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
@@ -36351,6 +36544,7 @@ async function parsePSError(response) {
   getContractAddress,
   getContractController,
   getContractInfo,
+  getDerivativeStatus,
   getFee,
   getGatewayLineage,
   getLineage,
@@ -36366,6 +36560,7 @@ async function parsePSError(response) {
   isDataPointId,
   isDataPointTombstone,
   isDataPortabilityGatewayConfig,
+  isDerivativeStatusSettled,
   isECIESEncrypted,
   isPlatformSupported,
   isRedactedLineageNode,
@@ -36413,6 +36608,7 @@ async function parsePSError(response) {
   verifyGrantRegistration,
   verifyPkceChallenge,
   verifyWeb3Signed,
+  waitForDerivativeStatus,
   waitForQuestion,
   writeData,
   writePersonalServerData