@opendatalabs/vana-sdk 3.17.0 → 3.18.0

package/dist/direct/personal-server-read.cjs

@@ -28,6 +28,9 @@ var import_web3_signed_builder = require("../auth/web3-signed-builder");
 var import_escrow = require("../protocol/escrow");
 var import_escrow_payment = require("./escrow-payment");
 var import_errors = require("./errors");
+var import_errors2 = require("../errors");
+var import_data_point_deletion = require("../protocol/data-point-deletion");
+var import_response_body = require("../utils/response-body");
 const TRANSPORT_RETRY_DEFAULTS = {
   attempts: 3,
   initialDelayMs: 1e3,
@@ -392,6 +395,15 @@ async function readPersonalServerData(params) {
       );
     }
   }
+  if (res.status === 410) {
+    throw new import_errors2.DataPointDeletedError(
+      `Personal Server scope '${params.scope}' has been deleted`,
+      {
+        scope: params.scope,
+        deletedAt: (0, import_data_point_deletion.tombstoneDeletedAt)(await (0, import_response_body.readJsonValue)(res))
+      }
+    );
+  }
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
     throw new import_errors.PersonalServerReadError(
@@ -403,7 +415,14 @@ async function readPersonalServerData(params) {
   payment = (0, import_escrow_payment.paymentResponseMetadataFromHeader)(
     res.headers.get("X-PAYMENT-RESPONSE")
   );
-  return { data: await res.json(), payment };
+  const data = await res.json();
+  if ((0, import_data_point_deletion.isDataPointTombstone)(data)) {
+    throw new import_errors2.DataPointDeletedError(
+      `Personal Server scope '${params.scope}' has been deleted`,
+      { scope: params.scope, deletedAt: (0, import_data_point_deletion.tombstoneDeletedAt)(data) }
+    );
+  }
+  return { data, payment };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/direct/personal-server-read.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — signs the challenged escrow operation and\n * retries once.\n *\n * The 402 body is parsed into a validated grant or receipt-bound data-access\n * operation, which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildEscrowPaymentHeader,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  paymentResponseMetadataFromHeader,\n  type EscrowPaymentHeaderConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentResponseMetadata,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerPaymentOperation,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/**\n * Transport-level retry knobs for {@link readPersonalServerData}.\n *\n * @remarks\n * Applies only when the underlying `fetch` **throws** (connection reset, DNS,\n * socket died mid-handshake — the browser-PS relay drop window). A received\n * HTTP response is never retried here: 402 has its own payment loop and other\n * statuses are surfaced to the caller unchanged.\n */\nexport interface PersonalServerTransportRetryOptions {\n  /** Total attempts including the first (default 3). `1` disables retries. */\n  attempts?: number;\n  /** Delay before the first retry (ms); doubles per retry (default 1_000). */\n  initialDelayMs?: number;\n  /** Cap on the between-retry delay (ms, default 5_000). */\n  maxDelayMs?: number;\n}\n\nconst TRANSPORT_RETRY_DEFAULTS: Required<PersonalServerTransportRetryOptions> =\n  {\n    attempts: 3,\n    initialDelayMs: 1_000,\n    maxDelayMs: 5_000,\n  };\n\n/** Clamp a caller-supplied attempt count to a finite integer >= 1. */\nfunction resolveAttempts(attempts: number): number {\n  return Number.isFinite(attempts) ? Math.max(1, Math.floor(attempts)) : 1;\n}\n\n/** An aborted request is the caller's intent to stop — never retry it. */\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === \"AbortError\";\n}\n\nconst sleep = (ms: number) =>\n  new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Run a fetch with bounded transport retries.\n *\n * Each attempt rebuilds the request via `buildRequest` so the Web3Signed\n * header is freshly signed (local app-key signature — cheap), while letting\n * the caller pin anything that must NOT be regenerated across attempts\n * (an already-signed `X-PAYMENT` header keeps its paymentNonce, so a retry\n * can never mint a second escrow payment for the same read).\n */\nasync function fetchWithTransportRetry(\n  fetchFn: PersonalServerFetch,\n  buildRequest: () => Promise<{\n    url: string;\n    method: string;\n    headers: Record<string, string>;\n  }>,\n  retry: Required<PersonalServerTransportRetryOptions>,\n): Promise<FetchResponseLike> {\n  const attempts = resolveAttempts(retry.attempts);\n  let lastError: unknown;\n  for (let attempt = 0; attempt < attempts; attempt += 1) {\n    if (attempt > 0) {\n      await sleep(\n        Math.min(retry.maxDelayMs, retry.initialDelayMs * 2 ** (attempt - 1)),\n      );\n    }\n    const request = await buildRequest();\n    try {\n      return await fetchFn(request.url, {\n        method: request.method,\n        headers: request.headers,\n      });\n    } catch (error) {\n      // An abort is a deliberate cancellation, not a flaky tunnel — surface it\n      // immediately instead of burning attempts (and backoff) on it.\n      if (isAbortError(error)) {\n        throw error;\n      }\n      lastError = error;\n    }\n  }\n  throw lastError;\n}\n\n/** Outcome of {@link readPersonalServerData}. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /**\n   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Never treat this field as accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nconst UINT256_MAX = (1n << 256n) - 1n;\n\nfunction isAddressHex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{40}$/.test(value);\n}\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidDataAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    isBytes32Hex(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    isAddressHex(record.accessor) &&\n    isBytes32Hex(record.recordId) &&\n    /^0x[0-9a-fA-F]{130}$/.test(record.signature)\n  );\n}\n\nfunction parseLegacyGrantOperation(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): { opType: typeof GRANT_OP_TYPE; opId: string } {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  const opType = challengeOpType ?? GRANT_OP_TYPE;\n  if (opType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const opId = challengeOpId ?? challengeGrantId ?? grantId;\n\n  if (!opId || !isBytes32Hex(opId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId },\n    );\n  }\n\n  if (opId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId, grantId },\n    );\n  }\n\n  return { opType: GRANT_OP_TYPE, opId };\n}\n\nfunction hasDataAccessMarker(body: Record<string, unknown>): boolean {\n  if (stringField(body, \"opType\") === DATA_ACCESS_OP_TYPE) return true;\n  return (\n    Array.isArray(body.accepts) &&\n    body.accepts.some((value) => {\n      const accept = asRecord(value);\n      return (\n        stringField(asRecord(accept?.message), \"opType\") === DATA_ACCESS_OP_TYPE\n      );\n    })\n  );\n}\n\nfunction parseCanonicalDataAccessAccept(\n  value: unknown,\n): Omit<PersonalServerDataAccessPaymentOperation, \"grantId\" | \"raw\"> | null {\n  const accept = asRecord(value);\n  const message = asRecord(accept?.message);\n  if (\n    stringField(accept, \"scheme\") !== \"vana-escrow-grant\" ||\n    stringField(message, \"opType\") !== DATA_ACCESS_OP_TYPE\n  ) {\n    return null;\n  }\n\n  const network = stringField(accept, \"network\");\n  const payerAddress = stringField(message, \"payerAddress\");\n  const opId = stringField(message, \"opId\");\n  const asset = stringField(message, \"asset\");\n  const amount = stringField(message, \"amount\");\n  const paymentNonce = stringField(message, \"paymentNonce\");\n  const accessRecord = parseAccessRecord(accept?.accessRecord);\n  const acceptAsset = stringField(accept, \"asset\");\n  const acceptAmount = stringField(accept, \"amount\");\n\n  if (\n    !network ||\n    !payerAddress ||\n    !isAddressHex(payerAddress) ||\n    !opId ||\n    !isBytes32Hex(opId) ||\n    !asset ||\n    !isAddressHex(asset) ||\n    !amount ||\n    !isUint256Decimal(amount, true) ||\n    !paymentNonce ||\n    !isUint256Decimal(paymentNonce, false) ||\n    !accessRecord ||\n    !isValidDataAccessRecord(accessRecord) ||\n    payerAddress.toLowerCase() !== accessRecord.accessor.toLowerCase() ||\n    opId.toLowerCase() !== accessRecord.recordId.toLowerCase() ||\n    !acceptAsset ||\n    acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n    acceptAmount !== amount\n  ) {\n    return null;\n  }\n\n  return {\n    opType: DATA_ACCESS_OP_TYPE,\n    opId,\n    network,\n    paymentNonce,\n    accessRecord,\n    asset,\n    amount,\n  };\n}\n\nfunction parseCanonicalDataAccessPayment(params: {\n  body: Record<string, unknown>;\n  grantId: string;\n  raw: unknown;\n}): PersonalServerDataAccessPaymentOperation | undefined {\n  const { body, grantId, raw } = params;\n  if (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\") {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n\n  const operation = Array.isArray(body.accepts)\n    ? body.accepts\n        .map(parseCanonicalDataAccessAccept)\n        .find((candidate) => candidate !== null)\n    : undefined;\n  if (!operation) {\n    return undefined;\n  }\n\n  return { grantId, raw, ...operation };\n}\n\nfunction preferredLegacyAccept(body: Record<string, unknown>) {\n  if (!Array.isArray(body.accepts)) return undefined;\n  return body.accepts.map(asRecord).find((accept) => {\n    const message = asRecord(accept?.message);\n    return (\n      stringField(accept, \"scheme\") === \"vana-escrow-grant\" &&\n      stringField(message, \"opType\") === GRANT_OP_TYPE\n    );\n  });\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a validated payment operation.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent from a legacy grant challenge.\n *\n * Receipt-bound `data_access` uses a fail-closed canonical path: one compatible\n * `accepts` entry must contain the scheme, network, message, and complete\n * receipt. Its positive uint256 `paymentNonce` is mandatory because the\n * Personal Server encodes challenge freshness in that nonce and checks it on\n * retry. This parser shape-validates the receipt and binds `opId` to `recordId`;\n * it does not recover or verify the server signature.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default legacy grant `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentOperation> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  if (hasDataAccessMarker(body)) {\n    const dataAccessOperation = parseCanonicalDataAccessPayment({\n      body,\n      grantId,\n      raw,\n    });\n    if (dataAccessOperation) return dataAccessOperation;\n  }\n\n  // Legacy grant challenges predate the canonical x402 envelope. Retain their\n  // field fallbacks only for truly flat bodies. Once an accepts envelope is\n  // present, validate its canonical framing and select only a compatible offer.\n  const hasAcceptsEnvelope = Object.prototype.hasOwnProperty.call(\n    body,\n    \"accepts\",\n  );\n  if (\n    hasAcceptsEnvelope &&\n    (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\")\n  ) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n  const accept = preferredLegacyAccept(body);\n  if (hasDataAccessMarker(body) && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment challenge was untrusted or incomplete\",\n      402,\n    );\n  }\n  if (hasAcceptsEnvelope && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment challenge had no compatible escrow offer\",\n      402,\n    );\n  }\n\n  if (accept) {\n    const message = asRecord(accept.message);\n    const network = stringField(accept, \"network\");\n    const payerAddress = stringField(message, \"payerAddress\");\n    const opId = stringField(message, \"opId\");\n    const asset = stringField(message, \"asset\");\n    const amount = stringField(message, \"amount\");\n    const paymentNonce = stringField(message, \"paymentNonce\");\n    const acceptAsset = stringField(accept, \"asset\");\n    const acceptAmount = stringField(accept, \"amount\");\n    const accessRecord = parseAccessRecord(accept.accessRecord);\n    const hasAccessRecord = accept.accessRecord !== undefined;\n    if (\n      !network ||\n      !payerAddress ||\n      !isAddressHex(payerAddress) ||\n      !opId ||\n      !isBytes32Hex(opId) ||\n      !asset ||\n      !isAddressHex(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !acceptAsset ||\n      acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n      acceptAmount !== amount ||\n      (hasAccessRecord &&\n        (!accessRecord ||\n          !isValidDataAccessRecord(accessRecord) ||\n          accessRecord.accessor.toLowerCase() !==\n            payerAddress.toLowerCase())) ||\n      (amount === \"0\" && !accessRecord)\n    ) {\n      throw new PersonalServerReadError(\n        \"Personal Server grant payment challenge was untrusted or incomplete\",\n        402,\n      );\n    }\n    const operation = parseLegacyGrantOperation({\n      challengeOpId: opId,\n      challengeOpType: stringField(message, \"opType\"),\n      grantId,\n    });\n    return {\n      grantId,\n      ...operation,\n      network,\n      paymentNonce,\n      asset,\n      amount,\n      raw,\n      ...(accessRecord ? { accessRecord } : {}),\n    };\n  }\n\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId = stringField(body, \"opId\");\n  const challengeOpType = stringField(body, \"opType\");\n\n  const accessRecord = parseAccessRecord(body.accessRecord);\n  const operation = parseLegacyGrantOperation({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  const payment = {\n    grantId,\n    network: stringField(body, \"network\"),\n    paymentNonce: stringField(body, \"paymentNonce\"),\n    asset: stringField(body, \"asset\") ?? NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n  return {\n    ...payment,\n    ...operation,\n    ...(accessRecord ? { accessRecord } : {}),\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\nfunction isReceiptOnlyGrantAcknowledgment(\n  required: PersonalServerPaymentOperation,\n  payerAddress: string,\n): boolean {\n  return (\n    required.opType === GRANT_OP_TYPE &&\n    required.amount === \"0\" &&\n    required.accessRecord !== undefined &&\n    isValidDataAccessRecord(required.accessRecord) &&\n    required.accessRecord.accessor.toLowerCase() === payerAddress.toLowerCase()\n  );\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes the challenged escrow operation, and retries once. If\n * escrow is not configured, throws {@link PaymentRequiredError} carrying the\n * parsed requirement so callers can debug amount/asset.\n *\n * Transport failures (fetch throwing — the browser-PS relay reconnect window)\n * are retried with backoff per `transportRetry` (default 3 attempts). The paid\n * retry reuses the already-signed `X-PAYMENT` header, so transport retries can\n * never double-pay.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentHeaderConfig;\n  fetchFn?: PersonalServerFetch;\n  transportRetry?: PersonalServerTransportRetryOptions;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n  const transportRetry = {\n    ...TRANSPORT_RETRY_DEFAULTS,\n    ...params.transportRetry,\n  };\n\n  const buildRequest = () =>\n    buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n\n  let res = await fetchWithTransportRetry(\n    fetchFn,\n    buildRequest,\n    transportRetry,\n  );\n\n  let payment: DirectPaymentResponseMetadata | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (\n      required.opType === GRANT_OP_TYPE &&\n      !hasPositiveAmount(required.amount) &&\n      !isReceiptOnlyGrantAcknowledgment(required, params.payerAddress)\n    ) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge included neither a positive amount nor a valid access receipt\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildEscrowPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to\n    // validate. The payment header is built exactly once: transport retries\n    // below re-sign only the Web3Signed auth and resend the SAME X-PAYMENT\n    // (same paymentNonce), so a dropped tunnel cannot mint a second payment.\n    res = await fetchWithTransportRetry(\n      fetchFn,\n      async () => {\n        const retry = await buildRequest();\n        return {\n          ...retry,\n          headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n        };\n      },\n      transportRetry,\n    );\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentResponseMetadataFromHeader(\n    res.headers.get(\"X-PAYMENT-RESPONSE\"),\n  );\n  return { data: await res.json(), payment };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,iCAAsC;AAEtC,oBAGO;AACP,4BAMO;AACP,oBAA8D;AAwD9D,MAAM,2BACJ;AAAA,EACE,UAAU;AAAA,EACV,gBAAgB;AAAA,EAChB,YAAY;AACd;AAGF,SAAS,gBAAgB,UAA0B;AACjD,SAAO,OAAO,SAAS,QAAQ,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,CAAC,IAAI;AACzE;AAGA,SAAS,aAAa,OAAyB;AAC7C,SAAO,iBAAiB,SAAS,MAAM,SAAS;AAClD;AAEA,MAAM,QAAQ,CAAC,OACb,IAAI,QAAc,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAWxD,eAAe,wBACb,SACA,cAKA,OAC4B;AAC5B,QAAM,WAAW,gBAAgB,MAAM,QAAQ;AAC/C,MAAI;AACJ,WAAS,UAAU,GAAG,UAAU,UAAU,WAAW,GAAG;AACtD,QAAI,UAAU,GAAG;AACf,YAAM;AAAA,QACJ,KAAK,IAAI,MAAM,YAAY,MAAM,iBAAiB,MAAM,UAAU,EAAE;AAAA,MACtE;AAAA,IACF;AACA,UAAM,UAAU,MAAM,aAAa;AACnC,QAAI;AACF,aAAO,MAAM,QAAQ,QAAQ,KAAK;AAAA,QAChC,QAAQ,QAAQ;AAAA,QAChB,SAAS,QAAQ;AAAA,MACnB,CAAC;AAAA,IACH,SAAS,OAAO;AAGd,UAAI,aAAa,KAAK,GAAG;AACvB,cAAM;AAAA,MACR;AACA,kBAAY;AAAA,IACd;AAAA,EACF;AACA,QAAM;AACR;AAaA,SAAS,mBAAmB,KAAqB;AAC/C,SAAO,IAAI,QAAQ,QAAQ,EAAE;AAC/B;AAGO,SAAS,iBAAiB,OAAuB;AACtD,SAAO,YAAY,mBAAmB,KAAK,CAAC;AAC9C;AAEA,SAAS,SAAS,OAAqD;AACrE,SAAO,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAC5D,QACD;AACN;AAEA,SAAS,YACP,QACA,OACoB;AACpB,QAAM,QAAQ,SAAS,KAAK;AAC5B,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEA,SAAS,kBAAkB,OAAgD;AACzE,QAAM,SAAS,SAAS,KAAK;AAC7B,QAAM,cAAc,YAAY,QAAQ,aAAa;AACrD,QAAM,UAAU,YAAY,QAAQ,SAAS;AAC7C,QAAM,WAAW,YAAY,QAAQ,UAAU;AAC/C,QAAM,WAAW,YAAY,QAAQ,UAAU;AAC/C,QAAM,YAAY,YAAY,QAAQ,WAAW;AAEjD,MAAI,CAAC,eAAe,CAAC,WAAW,CAAC,YAAY,CAAC,YAAY,CAAC,WAAW;AACpE,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEA,SAAS,aAAa,OAAwB;AAC5C,SAAO,sBAAsB,KAAK,KAAK;AACzC;AAEA,MAAM,eAAe,MAAM,QAAQ;AAEnC,SAAS,aAAa,OAAwB;AAC5C,SAAO,sBAAsB,KAAK,KAAK;AACzC;AAEA,SAAS,iBAAiB,OAAe,WAA6B;AACpE,QAAM,UAAU,YAAY,mBAAmB;AAC/C,SACE,MAAM,UAAU,YAAY,SAAS,EAAE,UACvC,QAAQ,KAAK,KAAK,KAClB,OAAO,KAAK,KAAK;AAErB;AAEA,SAAS,wBAAwB,QAAqC;AACpE,SACE,aAAa,OAAO,WAAW,KAC/B,iBAAiB,OAAO,SAAS,KAAK,KACtC,aAAa,OAAO,QAAQ,KAC5B,aAAa,OAAO,QAAQ,KAC5B,uBAAuB,KAAK,OAAO,SAAS;AAEhD;AAEA,SAAS,0BAA0B,QAKgB;AACjD,QAAM,EAAE,kBAAkB,eAAe,iBAAiB,QAAQ,IAAI;AAEtE,QAAM,SAAS,mBAAmB;AAClC,MAAI,WAAW,qCAAe;AAC5B,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA,EAAE,QAAQ,gBAAgB;AAAA,IAC5B;AAAA,EACF;AAEA,QAAM,OAAO,iBAAiB,oBAAoB;AAElD,MAAI,CAAC,QAAQ,CAAC,aAAa,IAAI,GAAG;AAChC,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA,EAAE,KAAK;AAAA,IACT;AAAA,EACF;AAEA,MAAI,KAAK,YAAY,MAAM,QAAQ,YAAY,GAAG;AAChD,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,MACA,EAAE,MAAM,QAAQ;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,QAAQ,qCAAe,KAAK;AACvC;AAEA,SAAS,oBAAoB,MAAwC;AACnE,MAAI,YAAY,MAAM,QAAQ,MAAM,0CAAqB,QAAO;AAChE,SACE,MAAM,QAAQ,KAAK,OAAO,KAC1B,KAAK,QAAQ,KAAK,CAAC,UAAU;AAC3B,UAAM,SAAS,SAAS,KAAK;AAC7B,WACE,YAAY,SAAS,QAAQ,OAAO,GAAG,QAAQ,MAAM;AAAA,EAEzD,CAAC;AAEL;AAEA,SAAS,+BACP,OAC0E;AAC1E,QAAM,SAAS,SAAS,KAAK;AAC7B,QAAM,UAAU,SAAS,QAAQ,OAAO;AACxC,MACE,YAAY,QAAQ,QAAQ,MAAM,uBAClC,YAAY,SAAS,QAAQ,MAAM,2CACnC;AACA,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,YAAY,QAAQ,SAAS;AAC7C,QAAM,eAAe,YAAY,SAAS,cAAc;AACxD,QAAM,OAAO,YAAY,SAAS,MAAM;AACxC,QAAM,QAAQ,YAAY,SAAS,OAAO;AAC1C,QAAM,SAAS,YAAY,SAAS,QAAQ;AAC5C,QAAM,eAAe,YAAY,SAAS,cAAc;AACxD,QAAM,eAAe,kBAAkB,QAAQ,YAAY;AAC3D,QAAM,cAAc,YAAY,QAAQ,OAAO;AAC/C,QAAM,eAAe,YAAY,QAAQ,QAAQ;AAEjD,MACE,CAAC,WACD,CAAC,gBACD,CAAC,aAAa,YAAY,KAC1B,CAAC,QACD,CAAC,aAAa,IAAI,KAClB,CAAC,SACD,CAAC,aAAa,KAAK,KACnB,CAAC,UACD,CAAC,iBAAiB,QAAQ,IAAI,KAC9B,CAAC,gBACD,CAAC,iBAAiB,cAAc,KAAK,KACrC,CAAC,gBACD,CAAC,wBAAwB,YAAY,KACrC,aAAa,YAAY,MAAM,aAAa,SAAS,YAAY,KACjE,KAAK,YAAY,MAAM,aAAa,SAAS,YAAY,KACzD,CAAC,eACD,YAAY,YAAY,MAAM,MAAM,YAAY,KAChD,iBAAiB,QACjB;AACA,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAEA,SAAS,gCAAgC,QAIgB;AACvD,QAAM,EAAE,MAAM,SAAS,IAAI,IAAI;AAC/B,MAAI,KAAK,gBAAgB,KAAK,KAAK,UAAU,oBAAoB;AAC/D,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,QAAM,YAAY,MAAM,QAAQ,KAAK,OAAO,IACxC,KAAK,QACF,IAAI,8BAA8B,EAClC,KAAK,CAAC,cAAc,cAAc,IAAI,IACzC;AACJ,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,EACT;AAEA,SAAO,EAAE,SAAS,KAAK,GAAG,UAAU;AACtC;AAEA,SAAS,sBAAsB,MAA+B;AAC5D,MAAI,CAAC,MAAM,QAAQ,KAAK,OAAO,EAAG,QAAO;AACzC,SAAO,KAAK,QAAQ,IAAI,QAAQ,EAAE,KAAK,CAAC,WAAW;AACjD,UAAM,UAAU,SAAS,QAAQ,OAAO;AACxC,WACE,YAAY,QAAQ,QAAQ,MAAM,uBAClC,YAAY,SAAS,QAAQ,MAAM;AAAA,EAEvC,CAAC;AACH;AAQA,eAAsB,mCAAmC,QASd;AACzC,QAAM,OAAO,mBAAmB,OAAO,iBAAiB;AACxD,QAAM,OAAO,iBAAiB,OAAO,KAAK;AAC1C,QAAM,gBAAgB,UAAM,kDAAsB;AAAA,IAChD,aAAa,OAAO;AAAA,IACpB,KAAK;AAAA,IACL,QAAQ;AAAA,IACR,KAAK;AAAA,IACL,SAAS,OAAO;AAAA,EAClB,CAAC;AACD,QAAM,UAAkC;AAAA,IACtC,eAAe;AAAA,IACf,QAAQ;AAAA,EACV;AACA,SAAO,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,IAAI,QAAQ,OAAO,MAAM,QAAQ;AAC/D;AAoBA,eAAsB,mCACpB,KACA,SACyC;AACzC,MAAI,MAAe;AACnB,MAAI;AACF,UAAM,MAAM,IAAI,KAAK;AAAA,EACvB,QAAQ;AACN,UAAM;AAAA,EACR;AACA,QAAM,OAAO,SAAS,GAAG,KAAK,CAAC;AAC/B,MAAI,oBAAoB,IAAI,GAAG;AAC7B,UAAM,sBAAsB,gCAAgC;AAAA,MAC1D;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AACD,QAAI,oBAAqB,QAAO;AAAA,EAClC;AAKA,QAAM,qBAAqB,OAAO,UAAU,eAAe;AAAA,IACzD;AAAA,IACA;AAAA,EACF;AACA,MACE,uBACC,KAAK,gBAAgB,KAAK,KAAK,UAAU,qBAC1C;AACA,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,QAAM,SAAS,sBAAsB,IAAI;AACzC,MAAI,oBAAoB,IAAI,KAAK,CAAC,QAAQ;AACxC,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,sBAAsB,CAAC,QAAQ;AACjC,UAAM,IAAI;AAAA,MACR;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,MAAI,QAAQ;AACV,UAAM,UAAU,SAAS,OAAO,OAAO;AACvC,UAAM,UAAU,YAAY,QAAQ,SAAS;AAC7C,UAAM,eAAe,YAAY,SAAS,cAAc;AACxD,UAAM,OAAO,YAAY,SAAS,MAAM;AACxC,UAAM,QAAQ,YAAY,SAAS,OAAO;AAC1C,UAAM,SAAS,YAAY,SAAS,QAAQ;AAC5C,UAAM,eAAe,YAAY,SAAS,cAAc;AACxD,UAAM,cAAc,YAAY,QAAQ,OAAO;AAC/C,UAAM,eAAe,YAAY,QAAQ,QAAQ;AACjD,UAAMA,gBAAe,kBAAkB,OAAO,YAAY;AAC1D,UAAM,kBAAkB,OAAO,iBAAiB;AAChD,QACE,CAAC,WACD,CAAC,gBACD,CAAC,aAAa,YAAY,KAC1B,CAAC,QACD,CAAC,aAAa,IAAI,KAClB,CAAC,SACD,CAAC,aAAa,KAAK,KACnB,CAAC,UACD,CAAC,iBAAiB,QAAQ,IAAI,KAC9B,CAAC,gBACD,CAAC,iBAAiB,cAAc,KAAK,KACrC,CAAC,eACD,YAAY,YAAY,MAAM,MAAM,YAAY,KAChD,iBAAiB,UAChB,oBACE,CAACA,iBACA,CAAC,wBAAwBA,aAAY,KACrCA,cAAa,SAAS,YAAY,MAChC,aAAa,YAAY,MAC9B,WAAW,OAAO,CAACA,eACpB;AACA,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,UAAMC,aAAY,0BAA0B;AAAA,MAC1C,eAAe;AAAA,MACf,iBAAiB,YAAY,SAAS,QAAQ;AAAA,MAC9C;AAAA,IACF,CAAC;AACD,WAAO;AAAA,MACL;AAAA,MACA,GAAGA;AAAA,MACH;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAID,gBAAe,EAAE,cAAAA,cAAa,IAAI,CAAC;AAAA,IACzC;AAAA,EACF;AAEA,QAAM,mBAAmB,YAAY,MAAM,SAAS;AACpD,QAAM,gBAAgB,YAAY,MAAM,MAAM;AAC9C,QAAM,kBAAkB,YAAY,MAAM,QAAQ;AAElD,QAAM,eAAe,kBAAkB,KAAK,YAAY;AACxD,QAAM,YAAY,0BAA0B;AAAA,IAC1C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,QAAM,cACJ,YAAY,MAAM,QAAQ,KAC1B,YAAY,MAAM,mBAAmB,KACrC;AACF,QAAM,UAAU;AAAA,IACd;AAAA,IACA,SAAS,YAAY,MAAM,SAAS;AAAA,IACpC,cAAc,YAAY,MAAM,cAAc;AAAA,IAC9C,OAAO,YAAY,MAAM,OAAO,KAAK;AAAA,IACrC,QAAQ;AAAA,IACR;AAAA,EACF;AACA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,IACH,GAAI,eAAe,EAAE,aAAa,IAAI,CAAC;AAAA,EACzC;AACF;AAEA,SAAS,kBAAkB,QAAyB;AAClD,MAAI,CAAC,QAAQ,KAAK,MAAM,EAAG,QAAO;AAClC,SAAO,OAAO,MAAM,IAAI;AAC1B;AAEA,SAAS,iCACP,UACA,cACS;AACT,SACE,SAAS,WAAW,uCACpB,SAAS,WAAW,OACpB,SAAS,iBAAiB,UAC1B,wBAAwB,SAAS,YAAY,KAC7C,SAAS,aAAa,SAAS,YAAY,MAAM,aAAa,YAAY;AAE9E;AAmBA,eAAsB,uBAAuB,QASP;AACpC,QAAM,UACJ,OAAO,WAAY,WAAW;AAChC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,QAAM,iBAAiB;AAAA,IACrB,GAAG;AAAA,IACH,GAAG,OAAO;AAAA,EACZ;AAEA,QAAM,eAAe,MACnB,mCAAmC;AAAA,IACjC,mBAAmB,OAAO;AAAA,IAC1B,OAAO,OAAO;AAAA,IACd,SAAS,OAAO;AAAA,IAChB,aAAa,OAAO;AAAA,EACtB,CAAC;AAEH,MAAI,MAAM,MAAM;AAAA,IACd;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,MAAI;AAEJ,MAAI,IAAI,WAAW,KAAK;AACtB,UAAM,WAAW,MAAM;AAAA,MACrB;AAAA,MACA,OAAO;AAAA,IACT;AACA,QAAI,CAAC,OAAO,QAAQ;AAClB,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,UACE,OAAO,OAAO;AAAA,UACd,SAAS,SAAS;AAAA,UAClB,OAAO,SAAS;AAAA,UAChB,QAAQ,SAAS;AAAA,QACnB;AAAA,MACF;AAAA,IACF;AAEA,QACE,SAAS,WAAW,uCACpB,CAAC,kBAAkB,SAAS,MAAM,KAClC,CAAC,iCAAiC,UAAU,OAAO,YAAY,GAC/D;AACA,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,UACE,OAAO,OAAO;AAAA,UACd,SAAS,SAAS;AAAA,UAClB,OAAO,SAAS;AAAA,UAChB,QAAQ,SAAS;AAAA,QACnB;AAAA,MACF;AAAA,IACF;AAEA,UAAM,gBAAgB,UAAM,gDAAyB;AAAA,MACnD,cAAc,OAAO;AAAA,MACrB;AAAA,MACA,QAAQ,OAAO;AAAA,IACjB,CAAC;AAMD,UAAM,MAAM;AAAA,MACV;AAAA,MACA,YAAY;AACV,cAAM,QAAQ,MAAM,aAAa;AACjC,eAAO;AAAA,UACL,GAAG;AAAA,UACH,SAAS,EAAE,GAAG,MAAM,SAAS,aAAa,cAAc;AAAA,QAC1D;AAAA,MACF;AAAA,MACA;AAAA,IACF;AAEA,QAAI,IAAI,WAAW,KAAK;AACtB,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,UACE,OAAO,OAAO;AAAA,UACd,SAAS,SAAS;AAAA,UAClB,OAAO,SAAS;AAAA,UAChB,QAAQ,SAAS;AAAA,UACjB;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,SAAS,MAAM,IAAI,KAAK,EAAE,MAAM,MAAM,EAAE;AAC9C,UAAM,IAAI;AAAA,MACR,gCAAgC,IAAI,MAAM,IAAI,IAAI,UAAU;AAAA,MAC5D,IAAI;AAAA,MACJ,EAAE,OAAO,OAAO,OAAO,MAAM,OAAO,MAAM,GAAG,GAAG,EAAE;AAAA,IACpD;AAAA,EACF;AAEA,gBAAU;AAAA,IACR,IAAI,QAAQ,IAAI,oBAAoB;AAAA,EACtC;AACA,SAAO,EAAE,MAAM,MAAM,IAAI,KAAK,GAAG,QAAQ;AAC3C;","names":["accessRecord","operation"]}
+{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — signs the challenged escrow operation and\n * retries once.\n *\n * The 402 body is parsed into a validated grant or receipt-bound data-access\n * operation, which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildEscrowPaymentHeader,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  paymentResponseMetadataFromHeader,\n  type EscrowPaymentHeaderConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport { DataPointDeletedError } from \"../errors\";\nimport {\n  isDataPointTombstone,\n  tombstoneDeletedAt,\n} from \"../protocol/data-point-deletion\";\nimport { readJsonValue } from \"../utils/response-body\";\nimport type {\n  DirectPaymentResponseMetadata,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerPaymentOperation,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/**\n * Transport-level retry knobs for {@link readPersonalServerData}.\n *\n * @remarks\n * Applies only when the underlying `fetch` **throws** (connection reset, DNS,\n * socket died mid-handshake — the browser-PS relay drop window). A received\n * HTTP response is never retried here: 402 has its own payment loop and other\n * statuses are surfaced to the caller unchanged.\n */\nexport interface PersonalServerTransportRetryOptions {\n  /** Total attempts including the first (default 3). `1` disables retries. */\n  attempts?: number;\n  /** Delay before the first retry (ms); doubles per retry (default 1_000). */\n  initialDelayMs?: number;\n  /** Cap on the between-retry delay (ms, default 5_000). */\n  maxDelayMs?: number;\n}\n\nconst TRANSPORT_RETRY_DEFAULTS: Required<PersonalServerTransportRetryOptions> =\n  {\n    attempts: 3,\n    initialDelayMs: 1_000,\n    maxDelayMs: 5_000,\n  };\n\n/** Clamp a caller-supplied attempt count to a finite integer >= 1. */\nfunction resolveAttempts(attempts: number): number {\n  return Number.isFinite(attempts) ? Math.max(1, Math.floor(attempts)) : 1;\n}\n\n/** An aborted request is the caller's intent to stop — never retry it. */\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === \"AbortError\";\n}\n\nconst sleep = (ms: number) =>\n  new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Run a fetch with bounded transport retries.\n *\n * Each attempt rebuilds the request via `buildRequest` so the Web3Signed\n * header is freshly signed (local app-key signature — cheap), while letting\n * the caller pin anything that must NOT be regenerated across attempts\n * (an already-signed `X-PAYMENT` header keeps its paymentNonce, so a retry\n * can never mint a second escrow payment for the same read).\n */\nasync function fetchWithTransportRetry(\n  fetchFn: PersonalServerFetch,\n  buildRequest: () => Promise<{\n    url: string;\n    method: string;\n    headers: Record<string, string>;\n  }>,\n  retry: Required<PersonalServerTransportRetryOptions>,\n): Promise<FetchResponseLike> {\n  const attempts = resolveAttempts(retry.attempts);\n  let lastError: unknown;\n  for (let attempt = 0; attempt < attempts; attempt += 1) {\n    if (attempt > 0) {\n      await sleep(\n        Math.min(retry.maxDelayMs, retry.initialDelayMs * 2 ** (attempt - 1)),\n      );\n    }\n    const request = await buildRequest();\n    try {\n      return await fetchFn(request.url, {\n        method: request.method,\n        headers: request.headers,\n      });\n    } catch (error) {\n      // An abort is a deliberate cancellation, not a flaky tunnel — surface it\n      // immediately instead of burning attempts (and backoff) on it.\n      if (isAbortError(error)) {\n        throw error;\n      }\n      lastError = error;\n    }\n  }\n  throw lastError;\n}\n\n/** Outcome of {@link readPersonalServerData}. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /**\n   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Never treat this field as accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nconst UINT256_MAX = (1n << 256n) - 1n;\n\nfunction isAddressHex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{40}$/.test(value);\n}\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidDataAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    isBytes32Hex(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    isAddressHex(record.accessor) &&\n    isBytes32Hex(record.recordId) &&\n    /^0x[0-9a-fA-F]{130}$/.test(record.signature)\n  );\n}\n\nfunction parseLegacyGrantOperation(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): { opType: typeof GRANT_OP_TYPE; opId: string } {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  const opType = challengeOpType ?? GRANT_OP_TYPE;\n  if (opType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const opId = challengeOpId ?? challengeGrantId ?? grantId;\n\n  if (!opId || !isBytes32Hex(opId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId },\n    );\n  }\n\n  if (opId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId, grantId },\n    );\n  }\n\n  return { opType: GRANT_OP_TYPE, opId };\n}\n\nfunction hasDataAccessMarker(body: Record<string, unknown>): boolean {\n  if (stringField(body, \"opType\") === DATA_ACCESS_OP_TYPE) return true;\n  return (\n    Array.isArray(body.accepts) &&\n    body.accepts.some((value) => {\n      const accept = asRecord(value);\n      return (\n        stringField(asRecord(accept?.message), \"opType\") === DATA_ACCESS_OP_TYPE\n      );\n    })\n  );\n}\n\nfunction parseCanonicalDataAccessAccept(\n  value: unknown,\n): Omit<PersonalServerDataAccessPaymentOperation, \"grantId\" | \"raw\"> | null {\n  const accept = asRecord(value);\n  const message = asRecord(accept?.message);\n  if (\n    stringField(accept, \"scheme\") !== \"vana-escrow-grant\" ||\n    stringField(message, \"opType\") !== DATA_ACCESS_OP_TYPE\n  ) {\n    return null;\n  }\n\n  const network = stringField(accept, \"network\");\n  const payerAddress = stringField(message, \"payerAddress\");\n  const opId = stringField(message, \"opId\");\n  const asset = stringField(message, \"asset\");\n  const amount = stringField(message, \"amount\");\n  const paymentNonce = stringField(message, \"paymentNonce\");\n  const accessRecord = parseAccessRecord(accept?.accessRecord);\n  const acceptAsset = stringField(accept, \"asset\");\n  const acceptAmount = stringField(accept, \"amount\");\n\n  if (\n    !network ||\n    !payerAddress ||\n    !isAddressHex(payerAddress) ||\n    !opId ||\n    !isBytes32Hex(opId) ||\n    !asset ||\n    !isAddressHex(asset) ||\n    !amount ||\n    !isUint256Decimal(amount, true) ||\n    !paymentNonce ||\n    !isUint256Decimal(paymentNonce, false) ||\n    !accessRecord ||\n    !isValidDataAccessRecord(accessRecord) ||\n    payerAddress.toLowerCase() !== accessRecord.accessor.toLowerCase() ||\n    opId.toLowerCase() !== accessRecord.recordId.toLowerCase() ||\n    !acceptAsset ||\n    acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n    acceptAmount !== amount\n  ) {\n    return null;\n  }\n\n  return {\n    opType: DATA_ACCESS_OP_TYPE,\n    opId,\n    network,\n    paymentNonce,\n    accessRecord,\n    asset,\n    amount,\n  };\n}\n\nfunction parseCanonicalDataAccessPayment(params: {\n  body: Record<string, unknown>;\n  grantId: string;\n  raw: unknown;\n}): PersonalServerDataAccessPaymentOperation | undefined {\n  const { body, grantId, raw } = params;\n  if (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\") {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n\n  const operation = Array.isArray(body.accepts)\n    ? body.accepts\n        .map(parseCanonicalDataAccessAccept)\n        .find((candidate) => candidate !== null)\n    : undefined;\n  if (!operation) {\n    return undefined;\n  }\n\n  return { grantId, raw, ...operation };\n}\n\nfunction preferredLegacyAccept(body: Record<string, unknown>) {\n  if (!Array.isArray(body.accepts)) return undefined;\n  return body.accepts.map(asRecord).find((accept) => {\n    const message = asRecord(accept?.message);\n    return (\n      stringField(accept, \"scheme\") === \"vana-escrow-grant\" &&\n      stringField(message, \"opType\") === GRANT_OP_TYPE\n    );\n  });\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a validated payment operation.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent from a legacy grant challenge.\n *\n * Receipt-bound `data_access` uses a fail-closed canonical path: one compatible\n * `accepts` entry must contain the scheme, network, message, and complete\n * receipt. Its positive uint256 `paymentNonce` is mandatory because the\n * Personal Server encodes challenge freshness in that nonce and checks it on\n * retry. This parser shape-validates the receipt and binds `opId` to `recordId`;\n * it does not recover or verify the server signature.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default legacy grant `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentOperation> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  if (hasDataAccessMarker(body)) {\n    const dataAccessOperation = parseCanonicalDataAccessPayment({\n      body,\n      grantId,\n      raw,\n    });\n    if (dataAccessOperation) return dataAccessOperation;\n  }\n\n  // Legacy grant challenges predate the canonical x402 envelope. Retain their\n  // field fallbacks only for truly flat bodies. Once an accepts envelope is\n  // present, validate its canonical framing and select only a compatible offer.\n  const hasAcceptsEnvelope = Object.prototype.hasOwnProperty.call(\n    body,\n    \"accepts\",\n  );\n  if (\n    hasAcceptsEnvelope &&\n    (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\")\n  ) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n  const accept = preferredLegacyAccept(body);\n  if (hasDataAccessMarker(body) && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment challenge was untrusted or incomplete\",\n      402,\n    );\n  }\n  if (hasAcceptsEnvelope && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment challenge had no compatible escrow offer\",\n      402,\n    );\n  }\n\n  if (accept) {\n    const message = asRecord(accept.message);\n    const network = stringField(accept, \"network\");\n    const payerAddress = stringField(message, \"payerAddress\");\n    const opId = stringField(message, \"opId\");\n    const asset = stringField(message, \"asset\");\n    const amount = stringField(message, \"amount\");\n    const paymentNonce = stringField(message, \"paymentNonce\");\n    const acceptAsset = stringField(accept, \"asset\");\n    const acceptAmount = stringField(accept, \"amount\");\n    const accessRecord = parseAccessRecord(accept.accessRecord);\n    const hasAccessRecord = accept.accessRecord !== undefined;\n    if (\n      !network ||\n      !payerAddress ||\n      !isAddressHex(payerAddress) ||\n      !opId ||\n      !isBytes32Hex(opId) ||\n      !asset ||\n      !isAddressHex(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !acceptAsset ||\n      acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n      acceptAmount !== amount ||\n      (hasAccessRecord &&\n        (!accessRecord ||\n          !isValidDataAccessRecord(accessRecord) ||\n          accessRecord.accessor.toLowerCase() !==\n            payerAddress.toLowerCase())) ||\n      (amount === \"0\" && !accessRecord)\n    ) {\n      throw new PersonalServerReadError(\n        \"Personal Server grant payment challenge was untrusted or incomplete\",\n        402,\n      );\n    }\n    const operation = parseLegacyGrantOperation({\n      challengeOpId: opId,\n      challengeOpType: stringField(message, \"opType\"),\n      grantId,\n    });\n    return {\n      grantId,\n      ...operation,\n      network,\n      paymentNonce,\n      asset,\n      amount,\n      raw,\n      ...(accessRecord ? { accessRecord } : {}),\n    };\n  }\n\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId = stringField(body, \"opId\");\n  const challengeOpType = stringField(body, \"opType\");\n\n  const accessRecord = parseAccessRecord(body.accessRecord);\n  const operation = parseLegacyGrantOperation({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  const payment = {\n    grantId,\n    network: stringField(body, \"network\"),\n    paymentNonce: stringField(body, \"paymentNonce\"),\n    asset: stringField(body, \"asset\") ?? NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n  return {\n    ...payment,\n    ...operation,\n    ...(accessRecord ? { accessRecord } : {}),\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\nfunction isReceiptOnlyGrantAcknowledgment(\n  required: PersonalServerPaymentOperation,\n  payerAddress: string,\n): boolean {\n  return (\n    required.opType === GRANT_OP_TYPE &&\n    required.amount === \"0\" &&\n    required.accessRecord !== undefined &&\n    isValidDataAccessRecord(required.accessRecord) &&\n    required.accessRecord.accessor.toLowerCase() === payerAddress.toLowerCase()\n  );\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes the challenged escrow operation, and retries once. If\n * escrow is not configured, throws {@link PaymentRequiredError} carrying the\n * parsed requirement so callers can debug amount/asset.\n *\n * Transport failures (fetch throwing — the browser-PS relay reconnect window)\n * are retried with backoff per `transportRetry` (default 3 attempts). The paid\n * retry reuses the already-signed `X-PAYMENT` header, so transport retries can\n * never double-pay.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentHeaderConfig;\n  fetchFn?: PersonalServerFetch;\n  transportRetry?: PersonalServerTransportRetryOptions;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n  const transportRetry = {\n    ...TRANSPORT_RETRY_DEFAULTS,\n    ...params.transportRetry,\n  };\n\n  const buildRequest = () =>\n    buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n\n  let res = await fetchWithTransportRetry(\n    fetchFn,\n    buildRequest,\n    transportRetry,\n  );\n\n  let payment: DirectPaymentResponseMetadata | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (\n      required.opType === GRANT_OP_TYPE &&\n      !hasPositiveAmount(required.amount) &&\n      !isReceiptOnlyGrantAcknowledgment(required, params.payerAddress)\n    ) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge included neither a positive amount nor a valid access receipt\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildEscrowPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to\n    // validate. The payment header is built exactly once: transport retries\n    // below re-sign only the Web3Signed auth and resend the SAME X-PAYMENT\n    // (same paymentNonce), so a dropped tunnel cannot mint a second payment.\n    res = await fetchWithTransportRetry(\n      fetchFn,\n      async () => {\n        const retry = await buildRequest();\n        return {\n          ...retry,\n          headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n        };\n      },\n      transportRetry,\n    );\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  // 410 = the scope was tombstoned by its owner. Typed so builders can\n  // branch on \"gone\" without parsing a generic read failure.\n  if (res.status === 410) {\n    throw new DataPointDeletedError(\n      `Personal Server scope '${params.scope}' has been deleted`,\n      {\n        scope: params.scope,\n        deletedAt: tombstoneDeletedAt(await readJsonValue(res)),\n      },\n    );\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentResponseMetadataFromHeader(\n    res.headers.get(\"X-PAYMENT-RESPONSE\"),\n  );\n  const data: unknown = await res.json();\n  // Never return a tombstone as data, even on a 200 that carries the deleted\n  // row (deletedAt / tombstone hash pair).\n  if (isDataPointTombstone(data)) {\n    throw new DataPointDeletedError(\n      `Personal Server scope '${params.scope}' has been deleted`,\n      { scope: params.scope, deletedAt: tombstoneDeletedAt(data) },\n    );\n  }\n  return { data, payment };\n}\n"],"mappings":"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","names":["import_errors","accessRecord","operation"]}

package/dist/direct/personal-server-read.js

@@ -9,6 +9,12 @@ import {
   paymentResponseMetadataFromHeader
 } from "./escrow-payment.js";
 import { PaymentRequiredError, PersonalServerReadError } from "./errors.js";
+import { DataPointDeletedError } from "../errors.js";
+import {
+  isDataPointTombstone,
+  tombstoneDeletedAt
+} from "../protocol/data-point-deletion.js";
+import { readJsonValue } from "../utils/response-body.js";
 const TRANSPORT_RETRY_DEFAULTS = {
   attempts: 3,
   initialDelayMs: 1e3,
@@ -373,6 +379,15 @@ async function readPersonalServerData(params) {
       );
     }
   }
+  if (res.status === 410) {
+    throw new DataPointDeletedError(
+      `Personal Server scope '${params.scope}' has been deleted`,
+      {
+        scope: params.scope,
+        deletedAt: tombstoneDeletedAt(await readJsonValue(res))
+      }
+    );
+  }
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
     throw new PersonalServerReadError(
@@ -384,7 +399,14 @@ async function readPersonalServerData(params) {
   payment = paymentResponseMetadataFromHeader(
     res.headers.get("X-PAYMENT-RESPONSE")
   );
-  return { data: await res.json(), payment };
+  const data = await res.json();
+  if (isDataPointTombstone(data)) {
+    throw new DataPointDeletedError(
+      `Personal Server scope '${params.scope}' has been deleted`,
+      { scope: params.scope, deletedAt: tombstoneDeletedAt(data) }
+    );
+  }
+  return { data, payment };
 }
 export {
   buildPersonalServerDataReadRequest,

package/dist/direct/personal-server-read.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — signs the challenged escrow operation and\n * retries once.\n *\n * The 402 body is parsed into a validated grant or receipt-bound data-access\n * operation, which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildEscrowPaymentHeader,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  paymentResponseMetadataFromHeader,\n  type EscrowPaymentHeaderConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport type {\n  DirectPaymentResponseMetadata,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerPaymentOperation,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/**\n * Transport-level retry knobs for {@link readPersonalServerData}.\n *\n * @remarks\n * Applies only when the underlying `fetch` **throws** (connection reset, DNS,\n * socket died mid-handshake — the browser-PS relay drop window). A received\n * HTTP response is never retried here: 402 has its own payment loop and other\n * statuses are surfaced to the caller unchanged.\n */\nexport interface PersonalServerTransportRetryOptions {\n  /** Total attempts including the first (default 3). `1` disables retries. */\n  attempts?: number;\n  /** Delay before the first retry (ms); doubles per retry (default 1_000). */\n  initialDelayMs?: number;\n  /** Cap on the between-retry delay (ms, default 5_000). */\n  maxDelayMs?: number;\n}\n\nconst TRANSPORT_RETRY_DEFAULTS: Required<PersonalServerTransportRetryOptions> =\n  {\n    attempts: 3,\n    initialDelayMs: 1_000,\n    maxDelayMs: 5_000,\n  };\n\n/** Clamp a caller-supplied attempt count to a finite integer >= 1. */\nfunction resolveAttempts(attempts: number): number {\n  return Number.isFinite(attempts) ? Math.max(1, Math.floor(attempts)) : 1;\n}\n\n/** An aborted request is the caller's intent to stop — never retry it. */\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === \"AbortError\";\n}\n\nconst sleep = (ms: number) =>\n  new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Run a fetch with bounded transport retries.\n *\n * Each attempt rebuilds the request via `buildRequest` so the Web3Signed\n * header is freshly signed (local app-key signature — cheap), while letting\n * the caller pin anything that must NOT be regenerated across attempts\n * (an already-signed `X-PAYMENT` header keeps its paymentNonce, so a retry\n * can never mint a second escrow payment for the same read).\n */\nasync function fetchWithTransportRetry(\n  fetchFn: PersonalServerFetch,\n  buildRequest: () => Promise<{\n    url: string;\n    method: string;\n    headers: Record<string, string>;\n  }>,\n  retry: Required<PersonalServerTransportRetryOptions>,\n): Promise<FetchResponseLike> {\n  const attempts = resolveAttempts(retry.attempts);\n  let lastError: unknown;\n  for (let attempt = 0; attempt < attempts; attempt += 1) {\n    if (attempt > 0) {\n      await sleep(\n        Math.min(retry.maxDelayMs, retry.initialDelayMs * 2 ** (attempt - 1)),\n      );\n    }\n    const request = await buildRequest();\n    try {\n      return await fetchFn(request.url, {\n        method: request.method,\n        headers: request.headers,\n      });\n    } catch (error) {\n      // An abort is a deliberate cancellation, not a flaky tunnel — surface it\n      // immediately instead of burning attempts (and backoff) on it.\n      if (isAbortError(error)) {\n        throw error;\n      }\n      lastError = error;\n    }\n  }\n  throw lastError;\n}\n\n/** Outcome of {@link readPersonalServerData}. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /**\n   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Never treat this field as accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nconst UINT256_MAX = (1n << 256n) - 1n;\n\nfunction isAddressHex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{40}$/.test(value);\n}\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidDataAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    isBytes32Hex(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    isAddressHex(record.accessor) &&\n    isBytes32Hex(record.recordId) &&\n    /^0x[0-9a-fA-F]{130}$/.test(record.signature)\n  );\n}\n\nfunction parseLegacyGrantOperation(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): { opType: typeof GRANT_OP_TYPE; opId: string } {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  const opType = challengeOpType ?? GRANT_OP_TYPE;\n  if (opType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const opId = challengeOpId ?? challengeGrantId ?? grantId;\n\n  if (!opId || !isBytes32Hex(opId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId },\n    );\n  }\n\n  if (opId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId, grantId },\n    );\n  }\n\n  return { opType: GRANT_OP_TYPE, opId };\n}\n\nfunction hasDataAccessMarker(body: Record<string, unknown>): boolean {\n  if (stringField(body, \"opType\") === DATA_ACCESS_OP_TYPE) return true;\n  return (\n    Array.isArray(body.accepts) &&\n    body.accepts.some((value) => {\n      const accept = asRecord(value);\n      return (\n        stringField(asRecord(accept?.message), \"opType\") === DATA_ACCESS_OP_TYPE\n      );\n    })\n  );\n}\n\nfunction parseCanonicalDataAccessAccept(\n  value: unknown,\n): Omit<PersonalServerDataAccessPaymentOperation, \"grantId\" | \"raw\"> | null {\n  const accept = asRecord(value);\n  const message = asRecord(accept?.message);\n  if (\n    stringField(accept, \"scheme\") !== \"vana-escrow-grant\" ||\n    stringField(message, \"opType\") !== DATA_ACCESS_OP_TYPE\n  ) {\n    return null;\n  }\n\n  const network = stringField(accept, \"network\");\n  const payerAddress = stringField(message, \"payerAddress\");\n  const opId = stringField(message, \"opId\");\n  const asset = stringField(message, \"asset\");\n  const amount = stringField(message, \"amount\");\n  const paymentNonce = stringField(message, \"paymentNonce\");\n  const accessRecord = parseAccessRecord(accept?.accessRecord);\n  const acceptAsset = stringField(accept, \"asset\");\n  const acceptAmount = stringField(accept, \"amount\");\n\n  if (\n    !network ||\n    !payerAddress ||\n    !isAddressHex(payerAddress) ||\n    !opId ||\n    !isBytes32Hex(opId) ||\n    !asset ||\n    !isAddressHex(asset) ||\n    !amount ||\n    !isUint256Decimal(amount, true) ||\n    !paymentNonce ||\n    !isUint256Decimal(paymentNonce, false) ||\n    !accessRecord ||\n    !isValidDataAccessRecord(accessRecord) ||\n    payerAddress.toLowerCase() !== accessRecord.accessor.toLowerCase() ||\n    opId.toLowerCase() !== accessRecord.recordId.toLowerCase() ||\n    !acceptAsset ||\n    acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n    acceptAmount !== amount\n  ) {\n    return null;\n  }\n\n  return {\n    opType: DATA_ACCESS_OP_TYPE,\n    opId,\n    network,\n    paymentNonce,\n    accessRecord,\n    asset,\n    amount,\n  };\n}\n\nfunction parseCanonicalDataAccessPayment(params: {\n  body: Record<string, unknown>;\n  grantId: string;\n  raw: unknown;\n}): PersonalServerDataAccessPaymentOperation | undefined {\n  const { body, grantId, raw } = params;\n  if (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\") {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n\n  const operation = Array.isArray(body.accepts)\n    ? body.accepts\n        .map(parseCanonicalDataAccessAccept)\n        .find((candidate) => candidate !== null)\n    : undefined;\n  if (!operation) {\n    return undefined;\n  }\n\n  return { grantId, raw, ...operation };\n}\n\nfunction preferredLegacyAccept(body: Record<string, unknown>) {\n  if (!Array.isArray(body.accepts)) return undefined;\n  return body.accepts.map(asRecord).find((accept) => {\n    const message = asRecord(accept?.message);\n    return (\n      stringField(accept, \"scheme\") === \"vana-escrow-grant\" &&\n      stringField(message, \"opType\") === GRANT_OP_TYPE\n    );\n  });\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a validated payment operation.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent from a legacy grant challenge.\n *\n * Receipt-bound `data_access` uses a fail-closed canonical path: one compatible\n * `accepts` entry must contain the scheme, network, message, and complete\n * receipt. Its positive uint256 `paymentNonce` is mandatory because the\n * Personal Server encodes challenge freshness in that nonce and checks it on\n * retry. This parser shape-validates the receipt and binds `opId` to `recordId`;\n * it does not recover or verify the server signature.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default legacy grant `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentOperation> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  if (hasDataAccessMarker(body)) {\n    const dataAccessOperation = parseCanonicalDataAccessPayment({\n      body,\n      grantId,\n      raw,\n    });\n    if (dataAccessOperation) return dataAccessOperation;\n  }\n\n  // Legacy grant challenges predate the canonical x402 envelope. Retain their\n  // field fallbacks only for truly flat bodies. Once an accepts envelope is\n  // present, validate its canonical framing and select only a compatible offer.\n  const hasAcceptsEnvelope = Object.prototype.hasOwnProperty.call(\n    body,\n    \"accepts\",\n  );\n  if (\n    hasAcceptsEnvelope &&\n    (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\")\n  ) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n  const accept = preferredLegacyAccept(body);\n  if (hasDataAccessMarker(body) && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment challenge was untrusted or incomplete\",\n      402,\n    );\n  }\n  if (hasAcceptsEnvelope && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment challenge had no compatible escrow offer\",\n      402,\n    );\n  }\n\n  if (accept) {\n    const message = asRecord(accept.message);\n    const network = stringField(accept, \"network\");\n    const payerAddress = stringField(message, \"payerAddress\");\n    const opId = stringField(message, \"opId\");\n    const asset = stringField(message, \"asset\");\n    const amount = stringField(message, \"amount\");\n    const paymentNonce = stringField(message, \"paymentNonce\");\n    const acceptAsset = stringField(accept, \"asset\");\n    const acceptAmount = stringField(accept, \"amount\");\n    const accessRecord = parseAccessRecord(accept.accessRecord);\n    const hasAccessRecord = accept.accessRecord !== undefined;\n    if (\n      !network ||\n      !payerAddress ||\n      !isAddressHex(payerAddress) ||\n      !opId ||\n      !isBytes32Hex(opId) ||\n      !asset ||\n      !isAddressHex(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !acceptAsset ||\n      acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n      acceptAmount !== amount ||\n      (hasAccessRecord &&\n        (!accessRecord ||\n          !isValidDataAccessRecord(accessRecord) ||\n          accessRecord.accessor.toLowerCase() !==\n            payerAddress.toLowerCase())) ||\n      (amount === \"0\" && !accessRecord)\n    ) {\n      throw new PersonalServerReadError(\n        \"Personal Server grant payment challenge was untrusted or incomplete\",\n        402,\n      );\n    }\n    const operation = parseLegacyGrantOperation({\n      challengeOpId: opId,\n      challengeOpType: stringField(message, \"opType\"),\n      grantId,\n    });\n    return {\n      grantId,\n      ...operation,\n      network,\n      paymentNonce,\n      asset,\n      amount,\n      raw,\n      ...(accessRecord ? { accessRecord } : {}),\n    };\n  }\n\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId = stringField(body, \"opId\");\n  const challengeOpType = stringField(body, \"opType\");\n\n  const accessRecord = parseAccessRecord(body.accessRecord);\n  const operation = parseLegacyGrantOperation({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  const payment = {\n    grantId,\n    network: stringField(body, \"network\"),\n    paymentNonce: stringField(body, \"paymentNonce\"),\n    asset: stringField(body, \"asset\") ?? NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n  return {\n    ...payment,\n    ...operation,\n    ...(accessRecord ? { accessRecord } : {}),\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\nfunction isReceiptOnlyGrantAcknowledgment(\n  required: PersonalServerPaymentOperation,\n  payerAddress: string,\n): boolean {\n  return (\n    required.opType === GRANT_OP_TYPE &&\n    required.amount === \"0\" &&\n    required.accessRecord !== undefined &&\n    isValidDataAccessRecord(required.accessRecord) &&\n    required.accessRecord.accessor.toLowerCase() === payerAddress.toLowerCase()\n  );\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes the challenged escrow operation, and retries once. If\n * escrow is not configured, throws {@link PaymentRequiredError} carrying the\n * parsed requirement so callers can debug amount/asset.\n *\n * Transport failures (fetch throwing — the browser-PS relay reconnect window)\n * are retried with backoff per `transportRetry` (default 3 attempts). The paid\n * retry reuses the already-signed `X-PAYMENT` header, so transport retries can\n * never double-pay.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentHeaderConfig;\n  fetchFn?: PersonalServerFetch;\n  transportRetry?: PersonalServerTransportRetryOptions;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n  const transportRetry = {\n    ...TRANSPORT_RETRY_DEFAULTS,\n    ...params.transportRetry,\n  };\n\n  const buildRequest = () =>\n    buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n\n  let res = await fetchWithTransportRetry(\n    fetchFn,\n    buildRequest,\n    transportRetry,\n  );\n\n  let payment: DirectPaymentResponseMetadata | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (\n      required.opType === GRANT_OP_TYPE &&\n      !hasPositiveAmount(required.amount) &&\n      !isReceiptOnlyGrantAcknowledgment(required, params.payerAddress)\n    ) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge included neither a positive amount nor a valid access receipt\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildEscrowPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to\n    // validate. The payment header is built exactly once: transport retries\n    // below re-sign only the Web3Signed auth and resend the SAME X-PAYMENT\n    // (same paymentNonce), so a dropped tunnel cannot mint a second payment.\n    res = await fetchWithTransportRetry(\n      fetchFn,\n      async () => {\n        const retry = await buildRequest();\n        return {\n          ...retry,\n          headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n        };\n      },\n      transportRetry,\n    );\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentResponseMetadataFromHeader(\n    res.headers.get(\"X-PAYMENT-RESPONSE\"),\n  );\n  return { data: await res.json(), payment };\n}\n"],"mappings":"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","names":["accessRecord","operation"]}
+{"version":3,"sources":["../../src/direct/personal-server-read.ts"],"sourcesContent":["/**\n * Personal Server data-read request builder and the 402 -> escrow-pay -> retry loop.\n *\n * @remarks\n * The read targets the Personal Server data path (`/v1/data/{scope}`),\n * authenticates with a Web3Signed header (built on {@link buildWeb3SignedHeader}),\n * and — on `402 Payment Required` — signs the challenged escrow operation and\n * retries once.\n *\n * The 402 body is parsed into a validated grant or receipt-bound data-access\n * operation, which drives the escrow settlement.\n *\n * @category Direct\n * @module direct/personal-server-read\n */\n\nimport { buildWeb3SignedHeader } from \"../auth/web3-signed-builder\";\nimport type { Web3SignedSignFn } from \"../auth/web3-signed-builder\";\nimport {\n  NATIVE_ASSET_ADDRESS,\n  type EscrowAccessRecord,\n} from \"../protocol/escrow\";\nimport {\n  buildEscrowPaymentHeader,\n  DATA_ACCESS_OP_TYPE,\n  GRANT_OP_TYPE,\n  paymentResponseMetadataFromHeader,\n  type EscrowPaymentHeaderConfig,\n} from \"./escrow-payment\";\nimport { PaymentRequiredError, PersonalServerReadError } from \"./errors\";\nimport { DataPointDeletedError } from \"../errors\";\nimport {\n  isDataPointTombstone,\n  tombstoneDeletedAt,\n} from \"../protocol/data-point-deletion\";\nimport { readJsonValue } from \"../utils/response-body\";\nimport type {\n  DirectPaymentResponseMetadata,\n  PersonalServerDataAccessPaymentOperation,\n  PersonalServerPaymentOperation,\n} from \"./types\";\n\n/** Minimal `Response`-like shape so the read loop is testable without a DOM. */\nexport interface FetchResponseLike {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: { get(name: string): string | null };\n  json(): Promise<unknown>;\n  text(): Promise<string>;\n}\n\n/** Minimal `fetch` signature accepted by {@link readPersonalServerData}. */\nexport type PersonalServerFetch = (\n  input: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n  },\n) => Promise<FetchResponseLike>;\n\n/** A built, ready-to-send Personal Server data read request. */\nexport interface PersonalServerDataReadRequest {\n  /** Absolute URL of the read endpoint. */\n  url: string;\n  /** HTTP method (always `\"GET\"`). */\n  method: \"GET\";\n  /** Request path used in the Web3Signed `uri` claim (e.g. `/v1/data/{scope}`). */\n  path: string;\n  /** Headers including the Web3Signed `Authorization` value. */\n  headers: Record<string, string>;\n}\n\n/**\n * Transport-level retry knobs for {@link readPersonalServerData}.\n *\n * @remarks\n * Applies only when the underlying `fetch` **throws** (connection reset, DNS,\n * socket died mid-handshake — the browser-PS relay drop window). A received\n * HTTP response is never retried here: 402 has its own payment loop and other\n * statuses are surfaced to the caller unchanged.\n */\nexport interface PersonalServerTransportRetryOptions {\n  /** Total attempts including the first (default 3). `1` disables retries. */\n  attempts?: number;\n  /** Delay before the first retry (ms); doubles per retry (default 1_000). */\n  initialDelayMs?: number;\n  /** Cap on the between-retry delay (ms, default 5_000). */\n  maxDelayMs?: number;\n}\n\nconst TRANSPORT_RETRY_DEFAULTS: Required<PersonalServerTransportRetryOptions> =\n  {\n    attempts: 3,\n    initialDelayMs: 1_000,\n    maxDelayMs: 5_000,\n  };\n\n/** Clamp a caller-supplied attempt count to a finite integer >= 1. */\nfunction resolveAttempts(attempts: number): number {\n  return Number.isFinite(attempts) ? Math.max(1, Math.floor(attempts)) : 1;\n}\n\n/** An aborted request is the caller's intent to stop — never retry it. */\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === \"AbortError\";\n}\n\nconst sleep = (ms: number) =>\n  new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Run a fetch with bounded transport retries.\n *\n * Each attempt rebuilds the request via `buildRequest` so the Web3Signed\n * header is freshly signed (local app-key signature — cheap), while letting\n * the caller pin anything that must NOT be regenerated across attempts\n * (an already-signed `X-PAYMENT` header keeps its paymentNonce, so a retry\n * can never mint a second escrow payment for the same read).\n */\nasync function fetchWithTransportRetry(\n  fetchFn: PersonalServerFetch,\n  buildRequest: () => Promise<{\n    url: string;\n    method: string;\n    headers: Record<string, string>;\n  }>,\n  retry: Required<PersonalServerTransportRetryOptions>,\n): Promise<FetchResponseLike> {\n  const attempts = resolveAttempts(retry.attempts);\n  let lastError: unknown;\n  for (let attempt = 0; attempt < attempts; attempt += 1) {\n    if (attempt > 0) {\n      await sleep(\n        Math.min(retry.maxDelayMs, retry.initialDelayMs * 2 ** (attempt - 1)),\n      );\n    }\n    const request = await buildRequest();\n    try {\n      return await fetchFn(request.url, {\n        method: request.method,\n        headers: request.headers,\n      });\n    } catch (error) {\n      // An abort is a deliberate cancellation, not a flaky tunnel — surface it\n      // immediately instead of burning attempts (and backoff) on it.\n      if (isAbortError(error)) {\n        throw error;\n      }\n      lastError = error;\n    }\n  }\n  throw lastError;\n}\n\n/** Outcome of {@link readPersonalServerData}. */\nexport interface PersonalServerReadResult {\n  /** The decoded JSON payload returned by the Personal Server. */\n  data: unknown;\n  /**\n   * Shape-validated but unauthenticated payment metadata echoed by the\n   * Personal Server. Never treat this field as accounting proof.\n   */\n  payment?: DirectPaymentResponseMetadata;\n}\n\nfunction stripTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/** Compute the data path for a scope (`/v1/data/{scope}`). */\nexport function dataPathForScope(scope: string): string {\n  return `/v1/data/${encodeURIComponent(scope)}`;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  record: Record<string, unknown> | undefined,\n  field: string,\n): string | undefined {\n  const value = record?.[field];\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction parseAccessRecord(value: unknown): EscrowAccessRecord | undefined {\n  const record = asRecord(value);\n  const dataPointId = stringField(record, \"dataPointId\");\n  const version = stringField(record, \"version\");\n  const accessor = stringField(record, \"accessor\");\n  const recordId = stringField(record, \"recordId\");\n  const signature = stringField(record, \"signature\");\n\n  if (!dataPointId || !version || !accessor || !recordId || !signature) {\n    return undefined;\n  }\n\n  return {\n    dataPointId: dataPointId as `0x${string}`,\n    version,\n    accessor: accessor as `0x${string}`,\n    recordId: recordId as `0x${string}`,\n    signature: signature as `0x${string}`,\n  };\n}\n\nfunction isBytes32Hex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{64}$/.test(value);\n}\n\nconst UINT256_MAX = (1n << 256n) - 1n;\n\nfunction isAddressHex(value: string): boolean {\n  return /^0x[0-9a-fA-F]{40}$/.test(value);\n}\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidDataAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    isBytes32Hex(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    isAddressHex(record.accessor) &&\n    isBytes32Hex(record.recordId) &&\n    /^0x[0-9a-fA-F]{130}$/.test(record.signature)\n  );\n}\n\nfunction parseLegacyGrantOperation(params: {\n  challengeGrantId?: string;\n  challengeOpId?: string;\n  challengeOpType?: string;\n  grantId: string;\n}): { opType: typeof GRANT_OP_TYPE; opId: string } {\n  const { challengeGrantId, challengeOpId, challengeOpType, grantId } = params;\n\n  const opType = challengeOpType ?? GRANT_OP_TYPE;\n  if (opType !== GRANT_OP_TYPE) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an unsupported escrow op type\",\n      402,\n      { opType: challengeOpType },\n    );\n  }\n\n  const opId = challengeOpId ?? challengeGrantId ?? grantId;\n\n  if (!opId || !isBytes32Hex(opId)) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge used an invalid escrow op id\",\n      402,\n      { opId },\n    );\n  }\n\n  if (opId.toLowerCase() !== grantId.toLowerCase()) {\n    throw new PersonalServerReadError(\n      \"Personal Server payment challenge did not match the requested grant\",\n      402,\n      { opId, grantId },\n    );\n  }\n\n  return { opType: GRANT_OP_TYPE, opId };\n}\n\nfunction hasDataAccessMarker(body: Record<string, unknown>): boolean {\n  if (stringField(body, \"opType\") === DATA_ACCESS_OP_TYPE) return true;\n  return (\n    Array.isArray(body.accepts) &&\n    body.accepts.some((value) => {\n      const accept = asRecord(value);\n      return (\n        stringField(asRecord(accept?.message), \"opType\") === DATA_ACCESS_OP_TYPE\n      );\n    })\n  );\n}\n\nfunction parseCanonicalDataAccessAccept(\n  value: unknown,\n): Omit<PersonalServerDataAccessPaymentOperation, \"grantId\" | \"raw\"> | null {\n  const accept = asRecord(value);\n  const message = asRecord(accept?.message);\n  if (\n    stringField(accept, \"scheme\") !== \"vana-escrow-grant\" ||\n    stringField(message, \"opType\") !== DATA_ACCESS_OP_TYPE\n  ) {\n    return null;\n  }\n\n  const network = stringField(accept, \"network\");\n  const payerAddress = stringField(message, \"payerAddress\");\n  const opId = stringField(message, \"opId\");\n  const asset = stringField(message, \"asset\");\n  const amount = stringField(message, \"amount\");\n  const paymentNonce = stringField(message, \"paymentNonce\");\n  const accessRecord = parseAccessRecord(accept?.accessRecord);\n  const acceptAsset = stringField(accept, \"asset\");\n  const acceptAmount = stringField(accept, \"amount\");\n\n  if (\n    !network ||\n    !payerAddress ||\n    !isAddressHex(payerAddress) ||\n    !opId ||\n    !isBytes32Hex(opId) ||\n    !asset ||\n    !isAddressHex(asset) ||\n    !amount ||\n    !isUint256Decimal(amount, true) ||\n    !paymentNonce ||\n    !isUint256Decimal(paymentNonce, false) ||\n    !accessRecord ||\n    !isValidDataAccessRecord(accessRecord) ||\n    payerAddress.toLowerCase() !== accessRecord.accessor.toLowerCase() ||\n    opId.toLowerCase() !== accessRecord.recordId.toLowerCase() ||\n    !acceptAsset ||\n    acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n    acceptAmount !== amount\n  ) {\n    return null;\n  }\n\n  return {\n    opType: DATA_ACCESS_OP_TYPE,\n    opId,\n    network,\n    paymentNonce,\n    accessRecord,\n    asset,\n    amount,\n  };\n}\n\nfunction parseCanonicalDataAccessPayment(params: {\n  body: Record<string, unknown>;\n  grantId: string;\n  raw: unknown;\n}): PersonalServerDataAccessPaymentOperation | undefined {\n  const { body, grantId, raw } = params;\n  if (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\") {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n\n  const operation = Array.isArray(body.accepts)\n    ? body.accepts\n        .map(parseCanonicalDataAccessAccept)\n        .find((candidate) => candidate !== null)\n    : undefined;\n  if (!operation) {\n    return undefined;\n  }\n\n  return { grantId, raw, ...operation };\n}\n\nfunction preferredLegacyAccept(body: Record<string, unknown>) {\n  if (!Array.isArray(body.accepts)) return undefined;\n  return body.accepts.map(asRecord).find((accept) => {\n    const message = asRecord(accept?.message);\n    return (\n      stringField(accept, \"scheme\") === \"vana-escrow-grant\" &&\n      stringField(message, \"opType\") === GRANT_OP_TYPE\n    );\n  });\n}\n\n/**\n * Build a Web3Signed-authenticated Personal Server data read request.\n *\n * @param params - Personal Server URL, scope, grant id, and an EIP-191 signer.\n * @returns The request URL, method, path, and headers (including `Authorization`).\n */\nexport async function buildPersonalServerDataReadRequest(params: {\n  /** Base URL of the user's Personal Server. */\n  personalServerUrl: string;\n  /** Scope to read (e.g. `\"icloud_notes.notes\"`). */\n  scope: string;\n  /** Grant id authorizing the read. */\n  grantId: string;\n  /** EIP-191 signer for the Web3Signed header (the app key). */\n  signMessage: Web3SignedSignFn;\n}): Promise<PersonalServerDataReadRequest> {\n  const base = stripTrailingSlash(params.personalServerUrl);\n  const path = dataPathForScope(params.scope);\n  const authorization = await buildWeb3SignedHeader({\n    signMessage: params.signMessage,\n    aud: base,\n    method: \"GET\",\n    uri: path,\n    grantId: params.grantId,\n  });\n  const headers: Record<string, string> = {\n    Authorization: authorization,\n    Accept: \"application/json\",\n  };\n  return { url: `${base}${path}`, method: \"GET\", path, headers };\n}\n\n/**\n * Parse a `402 Payment Required` body into a validated payment operation.\n *\n * @remarks\n * Accepts a few field spellings and falls back to the read's own grantId and the\n * native asset when a field is absent from a legacy grant challenge.\n *\n * Receipt-bound `data_access` uses a fail-closed canonical path: one compatible\n * `accepts` entry must contain the scheme, network, message, and complete\n * receipt. Its positive uint256 `paymentNonce` is mandatory because the\n * Personal Server encodes challenge freshness in that nonce and checks it on\n * retry. This parser shape-validates the receipt and binds `opId` to `recordId`;\n * it does not recover or verify the server signature.\n *\n * @param res - The 402 response.\n * @param grantId - The grant id of the read (default legacy grant `opId`).\n * @returns The parsed payment requirement.\n */\nexport async function parsePersonalServerPaymentRequired(\n  res: FetchResponseLike,\n  grantId: string,\n): Promise<PersonalServerPaymentOperation> {\n  let raw: unknown = undefined;\n  try {\n    raw = await res.json();\n  } catch {\n    raw = undefined;\n  }\n  const body = asRecord(raw) ?? {};\n  if (hasDataAccessMarker(body)) {\n    const dataAccessOperation = parseCanonicalDataAccessPayment({\n      body,\n      grantId,\n      raw,\n    });\n    if (dataAccessOperation) return dataAccessOperation;\n  }\n\n  // Legacy grant challenges predate the canonical x402 envelope. Retain their\n  // field fallbacks only for truly flat bodies. Once an accepts envelope is\n  // present, validate its canonical framing and select only a compatible offer.\n  const hasAcceptsEnvelope = Object.prototype.hasOwnProperty.call(\n    body,\n    \"accepts\",\n  );\n  if (\n    hasAcceptsEnvelope &&\n    (body.x402Version !== 1 || body.error !== \"PAYMENT_REQUIRED\")\n  ) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment response was not a canonical x402 challenge\",\n      402,\n    );\n  }\n  const accept = preferredLegacyAccept(body);\n  if (hasDataAccessMarker(body) && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server data-access payment challenge was untrusted or incomplete\",\n      402,\n    );\n  }\n  if (hasAcceptsEnvelope && !accept) {\n    throw new PersonalServerReadError(\n      \"Personal Server grant payment challenge had no compatible escrow offer\",\n      402,\n    );\n  }\n\n  if (accept) {\n    const message = asRecord(accept.message);\n    const network = stringField(accept, \"network\");\n    const payerAddress = stringField(message, \"payerAddress\");\n    const opId = stringField(message, \"opId\");\n    const asset = stringField(message, \"asset\");\n    const amount = stringField(message, \"amount\");\n    const paymentNonce = stringField(message, \"paymentNonce\");\n    const acceptAsset = stringField(accept, \"asset\");\n    const acceptAmount = stringField(accept, \"amount\");\n    const accessRecord = parseAccessRecord(accept.accessRecord);\n    const hasAccessRecord = accept.accessRecord !== undefined;\n    if (\n      !network ||\n      !payerAddress ||\n      !isAddressHex(payerAddress) ||\n      !opId ||\n      !isBytes32Hex(opId) ||\n      !asset ||\n      !isAddressHex(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !acceptAsset ||\n      acceptAsset.toLowerCase() !== asset.toLowerCase() ||\n      acceptAmount !== amount ||\n      (hasAccessRecord &&\n        (!accessRecord ||\n          !isValidDataAccessRecord(accessRecord) ||\n          accessRecord.accessor.toLowerCase() !==\n            payerAddress.toLowerCase())) ||\n      (amount === \"0\" && !accessRecord)\n    ) {\n      throw new PersonalServerReadError(\n        \"Personal Server grant payment challenge was untrusted or incomplete\",\n        402,\n      );\n    }\n    const operation = parseLegacyGrantOperation({\n      challengeOpId: opId,\n      challengeOpType: stringField(message, \"opType\"),\n      grantId,\n    });\n    return {\n      grantId,\n      ...operation,\n      network,\n      paymentNonce,\n      asset,\n      amount,\n      raw,\n      ...(accessRecord ? { accessRecord } : {}),\n    };\n  }\n\n  const challengeGrantId = stringField(body, \"grantId\");\n  const challengeOpId = stringField(body, \"opId\");\n  const challengeOpType = stringField(body, \"opType\");\n\n  const accessRecord = parseAccessRecord(body.accessRecord);\n  const operation = parseLegacyGrantOperation({\n    challengeGrantId,\n    challengeOpId,\n    challengeOpType,\n    grantId,\n  });\n\n  const amountValue =\n    stringField(body, \"amount\") ??\n    stringField(body, \"maxAmountRequired\") ??\n    \"0\";\n  const payment = {\n    grantId,\n    network: stringField(body, \"network\"),\n    paymentNonce: stringField(body, \"paymentNonce\"),\n    asset: stringField(body, \"asset\") ?? NATIVE_ASSET_ADDRESS,\n    amount: amountValue,\n    raw,\n  };\n  return {\n    ...payment,\n    ...operation,\n    ...(accessRecord ? { accessRecord } : {}),\n  };\n}\n\nfunction hasPositiveAmount(amount: string): boolean {\n  if (!/^\\d+$/.test(amount)) return false;\n  return BigInt(amount) > 0n;\n}\n\nfunction isReceiptOnlyGrantAcknowledgment(\n  required: PersonalServerPaymentOperation,\n  payerAddress: string,\n): boolean {\n  return (\n    required.opType === GRANT_OP_TYPE &&\n    required.amount === \"0\" &&\n    required.accessRecord !== undefined &&\n    isValidDataAccessRecord(required.accessRecord) &&\n    required.accessRecord.accessor.toLowerCase() === payerAddress.toLowerCase()\n  );\n}\n\n/**\n * Read approved data from a Personal Server, settling a 402 via escrow.\n *\n * @remarks\n * Sends a Web3Signed-authenticated `GET /v1/data/{scope}`. On `402`, parses what\n * is owed, authorizes the challenged escrow operation, and retries once. If\n * escrow is not configured, throws {@link PaymentRequiredError} carrying the\n * parsed requirement so callers can debug amount/asset.\n *\n * Transport failures (fetch throwing — the browser-PS relay reconnect window)\n * are retried with backoff per `transportRetry` (default 3 attempts). The paid\n * retry reuses the already-signed `X-PAYMENT` header, so transport retries can\n * never double-pay.\n *\n * @param params - Connection details, app signer, optional escrow config and fetch.\n * @returns `{ data, payment? }`.\n */\nexport async function readPersonalServerData(params: {\n  personalServerUrl: string;\n  scope: string;\n  grantId: string;\n  payerAddress: `0x${string}`;\n  signMessage: Web3SignedSignFn;\n  escrow?: EscrowPaymentHeaderConfig;\n  fetchFn?: PersonalServerFetch;\n  transportRetry?: PersonalServerTransportRetryOptions;\n}): Promise<PersonalServerReadResult> {\n  const fetchFn =\n    params.fetchFn ?? (globalThis.fetch as unknown as PersonalServerFetch);\n  if (!fetchFn) {\n    throw new PersonalServerReadError(\n      \"No fetch implementation available for Personal Server read\",\n    );\n  }\n  const transportRetry = {\n    ...TRANSPORT_RETRY_DEFAULTS,\n    ...params.transportRetry,\n  };\n\n  const buildRequest = () =>\n    buildPersonalServerDataReadRequest({\n      personalServerUrl: params.personalServerUrl,\n      scope: params.scope,\n      grantId: params.grantId,\n      signMessage: params.signMessage,\n    });\n\n  let res = await fetchWithTransportRetry(\n    fetchFn,\n    buildRequest,\n    transportRetry,\n  );\n\n  let payment: DirectPaymentResponseMetadata | undefined;\n\n  if (res.status === 402) {\n    const required = await parsePersonalServerPaymentRequired(\n      res,\n      params.grantId,\n    );\n    if (!params.escrow) {\n      throw new PaymentRequiredError(\n        \"Personal Server requires payment but no escrow config is set\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    if (\n      required.opType === GRANT_OP_TYPE &&\n      !hasPositiveAmount(required.amount) &&\n      !isReceiptOnlyGrantAcknowledgment(required, params.payerAddress)\n    ) {\n      throw new PaymentRequiredError(\n        \"Personal Server payment challenge included neither a positive amount nor a valid access receipt\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n        },\n      );\n    }\n\n    const paymentHeader = await buildEscrowPaymentHeader({\n      payerAddress: params.payerAddress,\n      required,\n      config: params.escrow,\n    });\n\n    // Re-sign and retry with x402 payment proof for the Personal Server to\n    // validate. The payment header is built exactly once: transport retries\n    // below re-sign only the Web3Signed auth and resend the SAME X-PAYMENT\n    // (same paymentNonce), so a dropped tunnel cannot mint a second payment.\n    res = await fetchWithTransportRetry(\n      fetchFn,\n      async () => {\n        const retry = await buildRequest();\n        return {\n          ...retry,\n          headers: { ...retry.headers, \"X-PAYMENT\": paymentHeader },\n        };\n      },\n      transportRetry,\n    );\n\n    if (res.status === 402) {\n      throw new PaymentRequiredError(\n        \"Personal Server still requires payment after escrow settlement\",\n        {\n          scope: params.scope,\n          grantId: required.grantId,\n          asset: required.asset,\n          amount: required.amount,\n          payment,\n        },\n      );\n    }\n  }\n\n  // 410 = the scope was tombstoned by its owner. Typed so builders can\n  // branch on \"gone\" without parsing a generic read failure.\n  if (res.status === 410) {\n    throw new DataPointDeletedError(\n      `Personal Server scope '${params.scope}' has been deleted`,\n      {\n        scope: params.scope,\n        deletedAt: tombstoneDeletedAt(await readJsonValue(res)),\n      },\n    );\n  }\n\n  if (!res.ok) {\n    const detail = await res.text().catch(() => \"\");\n    throw new PersonalServerReadError(\n      `Personal Server read failed: ${res.status} ${res.statusText}`,\n      res.status,\n      { scope: params.scope, body: detail.slice(0, 500) },\n    );\n  }\n\n  payment = paymentResponseMetadataFromHeader(\n    res.headers.get(\"X-PAYMENT-RESPONSE\"),\n  );\n  const data: unknown = await res.json();\n  // Never return a tombstone as data, even on a 200 that carries the deleted\n  // row (deletedAt / tombstone hash pair).\n  if (isDataPointTombstone(data)) {\n    throw new DataPointDeletedError(\n      `Personal Server scope '${params.scope}' has been deleted`,\n      { scope: params.scope, deletedAt: tombstoneDeletedAt(data) },\n    );\n  }\n  return { data, payment };\n}\n"],"mappings":"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","names":["accessRecord","operation"]}

package/dist/errors.cjs

@@ -20,6 +20,9 @@ var errors_exports = {};
 __export(errors_exports, {
   BlockchainError: () => BlockchainError,
   ContractNotFoundError: () => ContractNotFoundError,
+  DataPointDeletedError: () => DataPointDeletedError,
+  DataPointNotFoundError: () => DataPointNotFoundError,
+  DataPointVersionConflictError: () => DataPointVersionConflictError,
   InvalidConfigurationError: () => InvalidConfigurationError,
   LineageReadError: () => LineageReadError,
   NetworkError: () => NetworkError,
@@ -256,10 +259,34 @@ class LineageReadError extends VanaError {
   errorCode;
   details;
 }
+class DataPointDeletedError extends VanaError {
+  constructor(message, details = {}) {
+    super(message, "DATA_POINT_DELETED");
+    this.details = details;
+  }
+  details;
+}
+class DataPointNotFoundError extends VanaError {
+  constructor(message, details = {}) {
+    super(message, "DATA_POINT_NOT_FOUND");
+    this.details = details;
+  }
+  details;
+}
+class DataPointVersionConflictError extends VanaError {
+  constructor(message, details = {}) {
+    super(message, "DATA_POINT_VERSION_CONFLICT");
+    this.details = details;
+  }
+  details;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BlockchainError,
   ContractNotFoundError,
+  DataPointDeletedError,
+  DataPointNotFoundError,
+  DataPointVersionConflictError,
   InvalidConfigurationError,
   LineageReadError,
   NetworkError,

package/dist/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Base error class for all Vana SDK errors with structured error codes.\n *\n * @remarks\n * This abstract base class provides a foundation for all SDK-specific errors with\n * consistent error codes and stack trace handling. All Vana SDK errors extend this\n * class to provide structured error information that applications can handle\n * programmatically. The error code enables differentiation between error types\n * without relying on string matching.\n * @category Error Handling\n */\nexport class VanaError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: string,\n  ) {\n    super(message);\n    this.name = this.constructor.name;\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n}\n\n/**\n * Thrown when gasless transaction submission via relayer fails.\n *\n * @remarks\n * This error occurs when the relayer service is unavailable, returns an error,\n * or fails to process a gasless transaction. It includes the HTTP status code\n * and response details when available to help with debugging relayer issues.\n * @category Error Handling\n */\nexport class RelayerError extends VanaError {\n  constructor(\n    message: string,\n    public readonly statusCode?: number,\n    public readonly response?: unknown,\n  ) {\n    super(message, \"RELAYER_ERROR\");\n  }\n}\n\n/**\n * Thrown when the user rejects a wallet signature request.\n *\n * @remarks\n * This error occurs when users decline to sign transactions or typed data through\n * their wallet interface. It's a normal part of user interaction and should be\n * handled gracefully by applications without treating it as a system error.\n * @category Error Handling\n */\nexport class UserRejectedRequestError extends VanaError {\n  constructor(message: string = \"User rejected the signature request\") {\n    super(message, \"USER_REJECTED_REQUEST\");\n  }\n}\n\n/**\n * Thrown when the SDK configuration contains invalid or missing parameters.\n *\n * @remarks\n * This error occurs during SDK initialization when required configuration\n * parameters are missing, invalid, or incompatible. Common causes include\n * missing wallet clients, invalid chain IDs, malformed storage provider\n * configurations, or incompatible parameter combinations.\n *\n * Applications should catch this error during initialization and provide\n * clear feedback to users about configuration requirements.\n *\n * @example\n * ```typescript\n * try {\n *   const vana = Vana({\n *     chainId: 999999, // Invalid chain ID\n *     account: null // Missing account\n *   });\n * } catch (error) {\n *   if (error instanceof InvalidConfigurationError) {\n *     console.error('Configuration error:', error.message);\n *     // Show user-friendly configuration help\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class InvalidConfigurationError extends VanaError {\n  constructor(message: string) {\n    super(message, \"INVALID_CONFIGURATION\");\n  }\n}\n\n/**\n * Thrown when a required Vana protocol contract is not deployed on the current chain.\n *\n * @remarks\n * This error occurs when attempting to interact with contracts that are not\n * available on the connected blockchain network. It includes the contract name\n * and chain ID to help identify deployment issues or incorrect network configuration.\n * @category Error Handling\n */\nexport class ContractNotFoundError extends VanaError {\n  constructor(contractName: string, chainId: number) {\n    super(\n      `Contract ${contractName} not found on chain ${chainId}`,\n      \"CONTRACT_NOT_FOUND\",\n    );\n  }\n}\n\n/**\n * Thrown when blockchain operations fail due to network, contract, or transaction issues.\n *\n * @remarks\n * This error encompasses various blockchain-related failures including network\n * connectivity issues, contract execution failures, insufficient gas, invalid\n * transaction parameters, or smart contract reverts. The original error is\n * preserved to provide detailed debugging information while maintaining a\n * consistent SDK error interface.\n *\n * Common causes:\n * - Network connectivity problems\n * - Insufficient gas or gas price too low\n * - Contract function reverts\n * - Invalid transaction parameters\n * - Blockchain congestion or downtime\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({\n *     grantee: '0x742d35...',\n *     operation: 'read'\n *   });\n * } catch (error) {\n *   if (error instanceof BlockchainError) {\n *     console.error('Blockchain operation failed:', error.message);\n *\n *     // Check if it's a network issue\n *     if (error.originalError?.message.includes('network')) {\n *       // Retry with exponential backoff\n *       await retryOperation();\n *     }\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class BlockchainError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"BLOCKCHAIN_ERROR\");\n  }\n}\n\n/**\n * Thrown when data serialization or deserialization operations fail.\n *\n * @remarks\n * This error occurs when the SDK cannot properly serialize parameters for\n * blockchain transactions, IPFS storage, or API calls. Common causes include\n * circular references in objects, unsupported data types, or malformed JSON.\n * It's typically encountered during grant file creation, storage operations,\n * or when preparing transaction data.\n *\n * @example\n * ```typescript\n * try {\n *   // Object with circular reference causes serialization error\n *   const obj = { name: 'test' };\n *   obj.self = obj; // Circular reference\n *\n *   await vana.data.upload({\n *     content: obj,\n *     filename: 'data.json'\n *   });\n * } catch (error) {\n *   if (error instanceof SerializationError) {\n *     console.error('Data serialization failed:', error.message);\n *     // Clean data before retry\n *     const cleanedData = removeCircularReferences(obj);\n *     await vana.data.upload({\n *       content: cleanedData,\n *       filename: 'data.json'\n *     });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class SerializationError extends VanaError {\n  constructor(message: string) {\n    super(message, \"SERIALIZATION_ERROR\");\n  }\n}\n\n/**\n * Thrown when a signature operation fails or cannot be completed.\n *\n * @remarks\n * This error occurs when wallet signature operations fail due to disconnection,\n * locked accounts, or other wallet-related issues. It preserves the original\n * error for debugging while providing consistent error handling across the SDK.\n *\n * Recovery strategies:\n * - Check wallet connection and account unlock status\n * - Retry operation with explicit user interaction\n * - For gasless operations, consider switching to direct transactions\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({ grantee: '0x...' });\n * } catch (error) {\n *   if (error instanceof SignatureError) {\n *     // Prompt user to unlock wallet\n *     await promptWalletUnlock();\n *     // Retry operation\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class SignatureError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"SIGNATURE_ERROR\");\n  }\n}\n\n/**\n * Thrown when network communication fails during API calls or blockchain interactions.\n *\n * @remarks\n * This error encompasses network connectivity issues, API unavailability,\n * timeout errors, and CORS restrictions. It's commonly encountered during\n * IPFS operations, subgraph queries, or RPC calls.\n *\n * Recovery strategies:\n * - Check network connectivity\n * - Retry with exponential backoff\n * - Verify API endpoints are accessible\n * - Switch to alternative network providers or gateways\n *\n * @example\n * ```typescript\n * try {\n *   const files = await vana.data.getUserFiles({ owner: '0x...' });\n * } catch (error) {\n *   if (error instanceof NetworkError) {\n *     // Implement retry with exponential backoff\n *     await retryWithBackoff(() => vana.data.getUserFiles({ owner: '0x...' }));\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class NetworkError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"NETWORK_ERROR\");\n  }\n}\n\n/**\n * Thrown when transaction nonce retrieval fails during gasless operations.\n *\n * @remarks\n * This error occurs when the SDK cannot retrieve the user's current nonce from\n * smart contracts, preventing gasless transaction submission. Nonces are critical\n * for preventing replay attacks in signed transactions.\n *\n * Recovery strategies:\n * - Retry nonce retrieval after brief delay\n * - Check wallet connection and account status\n * - Use manual nonce specification if supported by the operation\n * - Switch to direct transactions as fallback\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({ grantee: '0x...' });\n * } catch (error) {\n *   if (error instanceof NonceError) {\n *     // Wait and retry\n *     await delay(1000);\n *     await vana.permissions.grant({ grantee: '0x...' });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class NonceError extends VanaError {\n  constructor(message: string) {\n    super(message, \"NONCE_ERROR\");\n  }\n}\n\n/**\n * Thrown when personal server operations fail or cannot be completed.\n *\n * @remarks\n * This error occurs during interactions with personal servers for computation\n * requests, identity retrieval, or operation status checks. Common causes include\n * server unavailability, untrusted server status, or invalid permission grants.\n *\n * Recovery strategies:\n * - Verify server URL accessibility\n * - Check server trust status via `vana.permissions.getTrustedServers()`\n * - Ensure valid permissions exist for the operation\n * - Retry after server becomes available\n *\n * @example\n * ```typescript\n * try {\n *   const result = await vana.server.createOperation({ permissionId: 123 });\n * } catch (error) {\n *   if (error instanceof PersonalServerError) {\n *     // Check if server is trusted\n *     const trustedServers = await vana.permissions.getTrustedServers();\n *     if (!trustedServers.includes(serverId)) {\n *       await vana.permissions.trustServer({ serverId });\n *     }\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class PersonalServerError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"PERSONAL_SERVER_ERROR\");\n  }\n}\n\n/**\n * Thrown when attempting to register a server with a URL different from its existing registration.\n *\n * @remarks\n * This error occurs when trying to add or trust a server that's already registered\n * on-chain with a different URL. Server URLs are immutable once registered to\n * maintain consistency and security. Applications should use the existing URL\n * or register a new server with a different ID.\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.addAndTrustServer({\n *     serverId: 1,\n *     serverUrl: 'https://new-url.com',\n *     publicKey: '0x...'\n *   });\n * } catch (error) {\n *   if (error instanceof ServerUrlMismatchError) {\n *     console.log(`Server already registered with: ${error.existingUrl}`);\n *     // Use existing URL or register new server\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class ServerUrlMismatchError extends VanaError {\n  constructor(existingUrl: string, providedUrl: string, serverId: string) {\n    super(\n      `Server ${serverId} is already registered with URL \"${existingUrl}\". Cannot change to \"${providedUrl}\".`,\n      \"SERVER_URL_MISMATCH\",\n    );\n    this.existingUrl = existingUrl;\n    this.providedUrl = providedUrl;\n    this.serverId = serverId;\n  }\n\n  public readonly existingUrl: string;\n  public readonly providedUrl: string;\n  public readonly serverId: string;\n}\n\n/**\n * Thrown when permission grant, revoke, or validation operations fail.\n *\n * @remarks\n * This error occurs during permission management operations including grants,\n * revocations, and permission validation checks. Common causes include invalid\n * grantee addresses, expired permissions, or insufficient privileges.\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.revoke({ permissionId: 999999 });\n * } catch (error) {\n *   if (error instanceof PermissionError) {\n *     console.error('Permission operation failed:', error.message);\n *     // Permission may not exist or user may not be owner\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class PermissionError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"PERMISSION_ERROR\");\n  }\n}\n\n/**\n * Thrown when attempting to perform write operations without a wallet client.\n *\n * @remarks\n * This error occurs when trying to execute operations that require wallet\n * interaction (signing, encrypting, or submitting transactions) while the SDK\n * is initialized in read-only mode without a wallet client. To perform write\n * operations, the SDK must be initialized with a wallet client.\n *\n * Common operations that require a wallet:\n * - Signing transactions or typed data\n * - Encrypting or decrypting files\n * - Granting or revoking permissions\n * - Uploading data to IPFS\n * - Submitting blockchain transactions\n *\n * @example\n * ```typescript\n * try {\n *   // This will throw if no wallet client is provided\n *   await vana.data.decryptFile({ fileId: 'abc123' });\n * } catch (error) {\n *   if (error instanceof ReadOnlyError) {\n *     console.error(`Cannot ${error.operation}: ${error.message}`);\n *     // Initialize with wallet client to enable write operations\n *     const vanaWithWallet = Vana({\n *       walletClient: createWalletClient(...)\n *     });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class ReadOnlyError extends VanaError {\n  constructor(\n    operation: string,\n    suggestion: string = \"Initialize the SDK with a walletClient to perform this operation\",\n  ) {\n    super(\n      `Operation '${operation}' requires a wallet client. ${suggestion}`,\n      \"READ_ONLY_ERROR\",\n    );\n    this.operation = operation;\n    this.suggestion = suggestion;\n  }\n\n  /** The operation that was attempted */\n  public readonly operation: string;\n  /** Suggested solution for fixing the error */\n  public readonly suggestion: string;\n}\n\n/**\n * Thrown when a long-running transaction operation times out or fails during polling.\n *\n * @remarks\n * This error occurs when asynchronous relayer operations exceed the configured timeout\n * or encounter non-recoverable errors during status polling. It preserves the operation ID\n * to allow recovery and status checking at a later time.\n *\n * The error includes:\n * - Operation ID for recovery and status checking\n * - Last known status before failure\n * - Original error details\n *\n * Recovery strategies:\n * - Save the operation ID for later status checking\n * - Implement manual recovery flow using the operation ID\n * - Check transaction status through alternative means\n * - Contact support if operation remains stuck\n *\n * @example\n * ```typescript\n * try {\n *   const result = await vana.permissions.grant({\n *     grantee: '0x...',\n *     files: [1, 2, 3]\n *   });\n * } catch (error) {\n *   if (error instanceof TransactionPendingError) {\n *     // Save operation ID for recovery\n *     localStorage.setItem('pending_operation', error.operationId);\n *\n *     // Show recovery UI\n *     showRecoveryDialog({\n *       operationId: error.operationId,\n *       lastStatus: error.lastKnownStatus\n *     });\n *\n *     // Attempt recovery later\n *     const status = await vana.checkOperationStatus(error.operationId);\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class TransactionPendingError extends VanaError {\n  constructor(\n    /** The operation ID that can be used for status checking */\n    public readonly operationId: string,\n    message: string,\n    /** The last known status of the operation before failure */\n    public readonly lastKnownStatus?: unknown,\n  ) {\n    super(\n      `Transaction operation pending: ${message} (operationId: ${operationId})`,\n      \"TRANSACTION_PENDING\",\n    );\n  }\n\n  /**\n   * Converts the error to a JSON-serializable format.\n   *\n   * @remarks\n   * Useful for logging, storage, or transmission of error details.\n   *\n   * @returns JSON representation of the error\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      operationId: this.operationId,\n      lastKnownStatus: this.lastKnownStatus,\n    };\n  }\n}\n\n/**\n * Personal Server error codes a Write API call can surface in\n * {@link PersonalServerWriteError.errorCode}.\n *\n * @remarks\n * The `WRITE_*` and `LINEAGE_*` codes are specific to the Write API; the\n * rest are the shared protocol codes the write policy reuses. The string\n * escape hatch keeps codes introduced by a newer Personal Server readable.\n * @category Error Handling\n */\nexport type PersonalServerWriteErrorCode =\n  | \"WRITE_SESSION_AUTH_FAILED\"\n  | \"WRITE_SESSION_PROOF_REQUIRED\"\n  | \"WRITE_SESSION_PROOF_REPLAY\"\n  | \"GRANT_ID_REQUIRED\"\n  | \"WRITE_ATTRIBUTION_REQUIRED\"\n  | \"WRITE_ATTRIBUTION_INVALID\"\n  | \"WRITE_ATTRIBUTION_SIGNER_MISMATCH\"\n  | \"WRITE_ATTRIBUTION_GRANT_MISMATCH\"\n  | \"WRITE_ATTRIBUTION_REPLAY\"\n  | \"WRITE_BODY_NOT_CANONICAL\"\n  | \"LINEAGE_INVALID\"\n  | \"LINEAGE_SCOPE_UNDER_SOURCE_PREFIX\"\n  | \"LINEAGE_SOURCE_UNKNOWN\"\n  | \"LINEAGE_SOURCE_LOOKUP_FAILED\"\n  | \"LINEAGE_FORBIDDEN\"\n  | \"LINEAGE_GATEWAY_ERROR\"\n  | \"LINEAGE_UNAVAILABLE\"\n  | \"LINEAGE_CASCADE_UNAVAILABLE\"\n  | \"LINEAGE_SIGNATURE_REQUIRED\"\n  | \"LINEAGE_SIGNATURE_INVALID\"\n  | \"INVALID_CASCADE\"\n  | \"INVALID_VERSION\"\n  | \"NOT_FOUND\"\n  | \"MISSING_AUTH\"\n  | \"INVALID_SIGNATURE\"\n  | \"UNREGISTERED_BUILDER\"\n  | \"GRANT_REQUIRED\"\n  | \"GRANT_REVOKED\"\n  | \"GRANT_EXPIRED\"\n  | \"GRANT_OWNER_MISMATCH\"\n  | \"SCOPE_MISMATCH\"\n  | \"INVALID_BODY\"\n  | \"CONTENT_TOO_LARGE\"\n  | \"PS_UNAVAILABLE\"\n  | \"SERVER_NOT_CONFIGURED\"\n  | \"INTERNAL_ERROR\"\n  | (string & {});\n\n/**\n * Base class for every Personal Server Write API failure.\n *\n * @remarks\n * `status` is the HTTP status the Personal Server answered with (absent for\n * failures raised before a request was sent or when no response arrived),\n * `errorCode` is the Personal Server's protocol error code when the body\n * carried one, and `details` is the server-supplied detail object.\n * @category Error Handling\n */\nexport class PersonalServerWriteError extends VanaError {\n  constructor(\n    message: string,\n    code: string,\n    public readonly status?: number,\n    public readonly errorCode: PersonalServerWriteErrorCode | null = null,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, code);\n  }\n}\n\n/**\n * Thrown before any request is sent when the write input is invalid: no\n * payload, a payload that is not a JSON object, a reserved `$writtenBy` /\n * `$lineage` key, a malformed lineage source id, or an unusable signer.\n * @category Error Handling\n */\nexport class WriteRequestError extends PersonalServerWriteError {\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message, \"WRITE_INVALID_REQUEST\", undefined, null, details);\n  }\n}\n\n/**\n * Thrown when the transport failed (fetch threw) on every attempt.\n *\n * @remarks\n * A write whose response was lost may still have been stored: the Personal\n * Server commits before answering. Check the scope before re-sending the\n * same record.\n * @category Error Handling\n */\nexport class WriteTransportError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    public readonly attempts: number,\n    cause?: unknown,\n  ) {\n    super(message, \"WRITE_TRANSPORT_ERROR\", undefined, null, { attempts });\n    this.cause = cause;\n  }\n}\n\n/**\n * Thrown when `POST /v1/write/session` refused the handshake (any non-2xx),\n * or answered with a body the SDK cannot read.\n * @category Error Handling\n */\nexport class WriteSessionError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status?: number,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_SESSION_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown by {@link writeData} when the session's bearer token has passed its\n * `expires_in` lifetime. Open a new session; nothing was sent.\n * @category Error Handling\n */\nexport class WriteSessionExpiredError extends PersonalServerWriteError {\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message, \"WRITE_SESSION_EXPIRED\", undefined, null, details);\n  }\n}\n\n/**\n * Thrown when a write answered 401.\n *\n * @remarks\n * `WRITE_ATTRIBUTION_*` codes describe the per-write proof. A plain\n * `INVALID_SIGNATURE` or `MISSING_AUTH` on a write usually means the session\n * token is no longer known to the Personal Server (expired, or the server\n * restarted and dropped its in-memory sessions): open a new session.\n * @category Error Handling\n */\nexport class WriteUnauthorizedError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_UNAUTHORIZED\", 401, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered 403: the live grant no longer authorizes it\n * (revoked, expired, wrong owner) or the scope is outside its write patterns.\n * @category Error Handling\n */\nexport class WriteForbiddenError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_FORBIDDEN\", 403, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered 409 (the record conflicts with server state).\n * @category Error Handling\n */\nexport class WriteConflictError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_CONFLICT\", 409, errorCode, details);\n  }\n}\n\n/**\n * Thrown when the Personal Server rejected the write's lineage: 422\n * `LINEAGE_SOURCE_UNKNOWN` (`details.unknown` lists the offending ids), 400\n * `LINEAGE_INVALID` / `LINEAGE_SCOPE_UNDER_SOURCE_PREFIX`, or 502\n * `LINEAGE_SOURCE_LOOKUP_FAILED`.\n * @category Error Handling\n */\nexport class WriteLineageError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status = 422,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_LINEAGE_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered any other non-2xx status (400 for a body the\n * server cannot store, 413 for an oversized payload, 5xx).\n * @category Error Handling\n */\nexport class WriteRejectedError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status: number,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a lineage read (Personal Server or gateway) fails: a non-2xx\n * answer, a body that is not a lineage graph, a malformed data point id, or\n * a transport failure.\n * @category Error Handling\n */\nexport class LineageReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly errorCode: PersonalServerWriteErrorCode | null = null,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"LINEAGE_READ_ERROR\");\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Base error class for all Vana SDK errors with structured error codes.\n *\n * @remarks\n * This abstract base class provides a foundation for all SDK-specific errors with\n * consistent error codes and stack trace handling. All Vana SDK errors extend this\n * class to provide structured error information that applications can handle\n * programmatically. The error code enables differentiation between error types\n * without relying on string matching.\n * @category Error Handling\n */\nexport class VanaError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: string,\n  ) {\n    super(message);\n    this.name = this.constructor.name;\n\n    // Maintains proper stack trace for where our error was thrown (only available on V8)\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n}\n\n/**\n * Thrown when gasless transaction submission via relayer fails.\n *\n * @remarks\n * This error occurs when the relayer service is unavailable, returns an error,\n * or fails to process a gasless transaction. It includes the HTTP status code\n * and response details when available to help with debugging relayer issues.\n * @category Error Handling\n */\nexport class RelayerError extends VanaError {\n  constructor(\n    message: string,\n    public readonly statusCode?: number,\n    public readonly response?: unknown,\n  ) {\n    super(message, \"RELAYER_ERROR\");\n  }\n}\n\n/**\n * Thrown when the user rejects a wallet signature request.\n *\n * @remarks\n * This error occurs when users decline to sign transactions or typed data through\n * their wallet interface. It's a normal part of user interaction and should be\n * handled gracefully by applications without treating it as a system error.\n * @category Error Handling\n */\nexport class UserRejectedRequestError extends VanaError {\n  constructor(message: string = \"User rejected the signature request\") {\n    super(message, \"USER_REJECTED_REQUEST\");\n  }\n}\n\n/**\n * Thrown when the SDK configuration contains invalid or missing parameters.\n *\n * @remarks\n * This error occurs during SDK initialization when required configuration\n * parameters are missing, invalid, or incompatible. Common causes include\n * missing wallet clients, invalid chain IDs, malformed storage provider\n * configurations, or incompatible parameter combinations.\n *\n * Applications should catch this error during initialization and provide\n * clear feedback to users about configuration requirements.\n *\n * @example\n * ```typescript\n * try {\n *   const vana = Vana({\n *     chainId: 999999, // Invalid chain ID\n *     account: null // Missing account\n *   });\n * } catch (error) {\n *   if (error instanceof InvalidConfigurationError) {\n *     console.error('Configuration error:', error.message);\n *     // Show user-friendly configuration help\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class InvalidConfigurationError extends VanaError {\n  constructor(message: string) {\n    super(message, \"INVALID_CONFIGURATION\");\n  }\n}\n\n/**\n * Thrown when a required Vana protocol contract is not deployed on the current chain.\n *\n * @remarks\n * This error occurs when attempting to interact with contracts that are not\n * available on the connected blockchain network. It includes the contract name\n * and chain ID to help identify deployment issues or incorrect network configuration.\n * @category Error Handling\n */\nexport class ContractNotFoundError extends VanaError {\n  constructor(contractName: string, chainId: number) {\n    super(\n      `Contract ${contractName} not found on chain ${chainId}`,\n      \"CONTRACT_NOT_FOUND\",\n    );\n  }\n}\n\n/**\n * Thrown when blockchain operations fail due to network, contract, or transaction issues.\n *\n * @remarks\n * This error encompasses various blockchain-related failures including network\n * connectivity issues, contract execution failures, insufficient gas, invalid\n * transaction parameters, or smart contract reverts. The original error is\n * preserved to provide detailed debugging information while maintaining a\n * consistent SDK error interface.\n *\n * Common causes:\n * - Network connectivity problems\n * - Insufficient gas or gas price too low\n * - Contract function reverts\n * - Invalid transaction parameters\n * - Blockchain congestion or downtime\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({\n *     grantee: '0x742d35...',\n *     operation: 'read'\n *   });\n * } catch (error) {\n *   if (error instanceof BlockchainError) {\n *     console.error('Blockchain operation failed:', error.message);\n *\n *     // Check if it's a network issue\n *     if (error.originalError?.message.includes('network')) {\n *       // Retry with exponential backoff\n *       await retryOperation();\n *     }\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class BlockchainError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"BLOCKCHAIN_ERROR\");\n  }\n}\n\n/**\n * Thrown when data serialization or deserialization operations fail.\n *\n * @remarks\n * This error occurs when the SDK cannot properly serialize parameters for\n * blockchain transactions, IPFS storage, or API calls. Common causes include\n * circular references in objects, unsupported data types, or malformed JSON.\n * It's typically encountered during grant file creation, storage operations,\n * or when preparing transaction data.\n *\n * @example\n * ```typescript\n * try {\n *   // Object with circular reference causes serialization error\n *   const obj = { name: 'test' };\n *   obj.self = obj; // Circular reference\n *\n *   await vana.data.upload({\n *     content: obj,\n *     filename: 'data.json'\n *   });\n * } catch (error) {\n *   if (error instanceof SerializationError) {\n *     console.error('Data serialization failed:', error.message);\n *     // Clean data before retry\n *     const cleanedData = removeCircularReferences(obj);\n *     await vana.data.upload({\n *       content: cleanedData,\n *       filename: 'data.json'\n *     });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class SerializationError extends VanaError {\n  constructor(message: string) {\n    super(message, \"SERIALIZATION_ERROR\");\n  }\n}\n\n/**\n * Thrown when a signature operation fails or cannot be completed.\n *\n * @remarks\n * This error occurs when wallet signature operations fail due to disconnection,\n * locked accounts, or other wallet-related issues. It preserves the original\n * error for debugging while providing consistent error handling across the SDK.\n *\n * Recovery strategies:\n * - Check wallet connection and account unlock status\n * - Retry operation with explicit user interaction\n * - For gasless operations, consider switching to direct transactions\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({ grantee: '0x...' });\n * } catch (error) {\n *   if (error instanceof SignatureError) {\n *     // Prompt user to unlock wallet\n *     await promptWalletUnlock();\n *     // Retry operation\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class SignatureError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"SIGNATURE_ERROR\");\n  }\n}\n\n/**\n * Thrown when network communication fails during API calls or blockchain interactions.\n *\n * @remarks\n * This error encompasses network connectivity issues, API unavailability,\n * timeout errors, and CORS restrictions. It's commonly encountered during\n * IPFS operations, subgraph queries, or RPC calls.\n *\n * Recovery strategies:\n * - Check network connectivity\n * - Retry with exponential backoff\n * - Verify API endpoints are accessible\n * - Switch to alternative network providers or gateways\n *\n * @example\n * ```typescript\n * try {\n *   const files = await vana.data.getUserFiles({ owner: '0x...' });\n * } catch (error) {\n *   if (error instanceof NetworkError) {\n *     // Implement retry with exponential backoff\n *     await retryWithBackoff(() => vana.data.getUserFiles({ owner: '0x...' }));\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class NetworkError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"NETWORK_ERROR\");\n  }\n}\n\n/**\n * Thrown when transaction nonce retrieval fails during gasless operations.\n *\n * @remarks\n * This error occurs when the SDK cannot retrieve the user's current nonce from\n * smart contracts, preventing gasless transaction submission. Nonces are critical\n * for preventing replay attacks in signed transactions.\n *\n * Recovery strategies:\n * - Retry nonce retrieval after brief delay\n * - Check wallet connection and account status\n * - Use manual nonce specification if supported by the operation\n * - Switch to direct transactions as fallback\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.grant({ grantee: '0x...' });\n * } catch (error) {\n *   if (error instanceof NonceError) {\n *     // Wait and retry\n *     await delay(1000);\n *     await vana.permissions.grant({ grantee: '0x...' });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class NonceError extends VanaError {\n  constructor(message: string) {\n    super(message, \"NONCE_ERROR\");\n  }\n}\n\n/**\n * Thrown when personal server operations fail or cannot be completed.\n *\n * @remarks\n * This error occurs during interactions with personal servers for computation\n * requests, identity retrieval, or operation status checks. Common causes include\n * server unavailability, untrusted server status, or invalid permission grants.\n *\n * Recovery strategies:\n * - Verify server URL accessibility\n * - Check server trust status via `vana.permissions.getTrustedServers()`\n * - Ensure valid permissions exist for the operation\n * - Retry after server becomes available\n *\n * @example\n * ```typescript\n * try {\n *   const result = await vana.server.createOperation({ permissionId: 123 });\n * } catch (error) {\n *   if (error instanceof PersonalServerError) {\n *     // Check if server is trusted\n *     const trustedServers = await vana.permissions.getTrustedServers();\n *     if (!trustedServers.includes(serverId)) {\n *       await vana.permissions.trustServer({ serverId });\n *     }\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class PersonalServerError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"PERSONAL_SERVER_ERROR\");\n  }\n}\n\n/**\n * Thrown when attempting to register a server with a URL different from its existing registration.\n *\n * @remarks\n * This error occurs when trying to add or trust a server that's already registered\n * on-chain with a different URL. Server URLs are immutable once registered to\n * maintain consistency and security. Applications should use the existing URL\n * or register a new server with a different ID.\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.addAndTrustServer({\n *     serverId: 1,\n *     serverUrl: 'https://new-url.com',\n *     publicKey: '0x...'\n *   });\n * } catch (error) {\n *   if (error instanceof ServerUrlMismatchError) {\n *     console.log(`Server already registered with: ${error.existingUrl}`);\n *     // Use existing URL or register new server\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class ServerUrlMismatchError extends VanaError {\n  constructor(existingUrl: string, providedUrl: string, serverId: string) {\n    super(\n      `Server ${serverId} is already registered with URL \"${existingUrl}\". Cannot change to \"${providedUrl}\".`,\n      \"SERVER_URL_MISMATCH\",\n    );\n    this.existingUrl = existingUrl;\n    this.providedUrl = providedUrl;\n    this.serverId = serverId;\n  }\n\n  public readonly existingUrl: string;\n  public readonly providedUrl: string;\n  public readonly serverId: string;\n}\n\n/**\n * Thrown when permission grant, revoke, or validation operations fail.\n *\n * @remarks\n * This error occurs during permission management operations including grants,\n * revocations, and permission validation checks. Common causes include invalid\n * grantee addresses, expired permissions, or insufficient privileges.\n *\n * @example\n * ```typescript\n * try {\n *   await vana.permissions.revoke({ permissionId: 999999 });\n * } catch (error) {\n *   if (error instanceof PermissionError) {\n *     console.error('Permission operation failed:', error.message);\n *     // Permission may not exist or user may not be owner\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class PermissionError extends VanaError {\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n  ) {\n    super(message, \"PERMISSION_ERROR\");\n  }\n}\n\n/**\n * Thrown when attempting to perform write operations without a wallet client.\n *\n * @remarks\n * This error occurs when trying to execute operations that require wallet\n * interaction (signing, encrypting, or submitting transactions) while the SDK\n * is initialized in read-only mode without a wallet client. To perform write\n * operations, the SDK must be initialized with a wallet client.\n *\n * Common operations that require a wallet:\n * - Signing transactions or typed data\n * - Encrypting or decrypting files\n * - Granting or revoking permissions\n * - Uploading data to IPFS\n * - Submitting blockchain transactions\n *\n * @example\n * ```typescript\n * try {\n *   // This will throw if no wallet client is provided\n *   await vana.data.decryptFile({ fileId: 'abc123' });\n * } catch (error) {\n *   if (error instanceof ReadOnlyError) {\n *     console.error(`Cannot ${error.operation}: ${error.message}`);\n *     // Initialize with wallet client to enable write operations\n *     const vanaWithWallet = Vana({\n *       walletClient: createWalletClient(...)\n *     });\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class ReadOnlyError extends VanaError {\n  constructor(\n    operation: string,\n    suggestion: string = \"Initialize the SDK with a walletClient to perform this operation\",\n  ) {\n    super(\n      `Operation '${operation}' requires a wallet client. ${suggestion}`,\n      \"READ_ONLY_ERROR\",\n    );\n    this.operation = operation;\n    this.suggestion = suggestion;\n  }\n\n  /** The operation that was attempted */\n  public readonly operation: string;\n  /** Suggested solution for fixing the error */\n  public readonly suggestion: string;\n}\n\n/**\n * Thrown when a long-running transaction operation times out or fails during polling.\n *\n * @remarks\n * This error occurs when asynchronous relayer operations exceed the configured timeout\n * or encounter non-recoverable errors during status polling. It preserves the operation ID\n * to allow recovery and status checking at a later time.\n *\n * The error includes:\n * - Operation ID for recovery and status checking\n * - Last known status before failure\n * - Original error details\n *\n * Recovery strategies:\n * - Save the operation ID for later status checking\n * - Implement manual recovery flow using the operation ID\n * - Check transaction status through alternative means\n * - Contact support if operation remains stuck\n *\n * @example\n * ```typescript\n * try {\n *   const result = await vana.permissions.grant({\n *     grantee: '0x...',\n *     files: [1, 2, 3]\n *   });\n * } catch (error) {\n *   if (error instanceof TransactionPendingError) {\n *     // Save operation ID for recovery\n *     localStorage.setItem('pending_operation', error.operationId);\n *\n *     // Show recovery UI\n *     showRecoveryDialog({\n *       operationId: error.operationId,\n *       lastStatus: error.lastKnownStatus\n *     });\n *\n *     // Attempt recovery later\n *     const status = await vana.checkOperationStatus(error.operationId);\n *   }\n * }\n * ```\n * @category Error Handling\n */\nexport class TransactionPendingError extends VanaError {\n  constructor(\n    /** The operation ID that can be used for status checking */\n    public readonly operationId: string,\n    message: string,\n    /** The last known status of the operation before failure */\n    public readonly lastKnownStatus?: unknown,\n  ) {\n    super(\n      `Transaction operation pending: ${message} (operationId: ${operationId})`,\n      \"TRANSACTION_PENDING\",\n    );\n  }\n\n  /**\n   * Converts the error to a JSON-serializable format.\n   *\n   * @remarks\n   * Useful for logging, storage, or transmission of error details.\n   *\n   * @returns JSON representation of the error\n   */\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      operationId: this.operationId,\n      lastKnownStatus: this.lastKnownStatus,\n    };\n  }\n}\n\n/**\n * Personal Server error codes a Write API call can surface in\n * {@link PersonalServerWriteError.errorCode}.\n *\n * @remarks\n * The `WRITE_*` and `LINEAGE_*` codes are specific to the Write API; the\n * rest are the shared protocol codes the write policy reuses. The string\n * escape hatch keeps codes introduced by a newer Personal Server readable.\n * @category Error Handling\n */\nexport type PersonalServerWriteErrorCode =\n  | \"WRITE_SESSION_AUTH_FAILED\"\n  | \"WRITE_SESSION_PROOF_REQUIRED\"\n  | \"WRITE_SESSION_PROOF_REPLAY\"\n  | \"GRANT_ID_REQUIRED\"\n  | \"WRITE_ATTRIBUTION_REQUIRED\"\n  | \"WRITE_ATTRIBUTION_INVALID\"\n  | \"WRITE_ATTRIBUTION_SIGNER_MISMATCH\"\n  | \"WRITE_ATTRIBUTION_GRANT_MISMATCH\"\n  | \"WRITE_ATTRIBUTION_REPLAY\"\n  | \"WRITE_BODY_NOT_CANONICAL\"\n  | \"LINEAGE_INVALID\"\n  | \"LINEAGE_SCOPE_UNDER_SOURCE_PREFIX\"\n  | \"LINEAGE_SOURCE_UNKNOWN\"\n  | \"LINEAGE_SOURCE_LOOKUP_FAILED\"\n  | \"LINEAGE_FORBIDDEN\"\n  | \"LINEAGE_GATEWAY_ERROR\"\n  | \"LINEAGE_UNAVAILABLE\"\n  | \"LINEAGE_CASCADE_UNAVAILABLE\"\n  | \"LINEAGE_SIGNATURE_REQUIRED\"\n  | \"LINEAGE_SIGNATURE_INVALID\"\n  | \"INVALID_CASCADE\"\n  | \"INVALID_VERSION\"\n  | \"NOT_FOUND\"\n  | \"MISSING_AUTH\"\n  | \"INVALID_SIGNATURE\"\n  | \"UNREGISTERED_BUILDER\"\n  | \"GRANT_REQUIRED\"\n  | \"GRANT_REVOKED\"\n  | \"GRANT_EXPIRED\"\n  | \"GRANT_OWNER_MISMATCH\"\n  | \"SCOPE_MISMATCH\"\n  | \"INVALID_BODY\"\n  | \"CONTENT_TOO_LARGE\"\n  | \"PS_UNAVAILABLE\"\n  | \"SERVER_NOT_CONFIGURED\"\n  | \"INTERNAL_ERROR\"\n  | (string & {});\n\n/**\n * Base class for every Personal Server Write API failure.\n *\n * @remarks\n * `status` is the HTTP status the Personal Server answered with (absent for\n * failures raised before a request was sent or when no response arrived),\n * `errorCode` is the Personal Server's protocol error code when the body\n * carried one, and `details` is the server-supplied detail object.\n * @category Error Handling\n */\nexport class PersonalServerWriteError extends VanaError {\n  constructor(\n    message: string,\n    code: string,\n    public readonly status?: number,\n    public readonly errorCode: PersonalServerWriteErrorCode | null = null,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, code);\n  }\n}\n\n/**\n * Thrown before any request is sent when the write input is invalid: no\n * payload, a payload that is not a JSON object, a reserved `$writtenBy` /\n * `$lineage` key, a malformed lineage source id, or an unusable signer.\n * @category Error Handling\n */\nexport class WriteRequestError extends PersonalServerWriteError {\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message, \"WRITE_INVALID_REQUEST\", undefined, null, details);\n  }\n}\n\n/**\n * Thrown when the transport failed (fetch threw) on every attempt.\n *\n * @remarks\n * A write whose response was lost may still have been stored: the Personal\n * Server commits before answering. Check the scope before re-sending the\n * same record.\n * @category Error Handling\n */\nexport class WriteTransportError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    public readonly attempts: number,\n    cause?: unknown,\n  ) {\n    super(message, \"WRITE_TRANSPORT_ERROR\", undefined, null, { attempts });\n    this.cause = cause;\n  }\n}\n\n/**\n * Thrown when `POST /v1/write/session` refused the handshake (any non-2xx),\n * or answered with a body the SDK cannot read.\n * @category Error Handling\n */\nexport class WriteSessionError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status?: number,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_SESSION_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown by {@link writeData} when the session's bearer token has passed its\n * `expires_in` lifetime. Open a new session; nothing was sent.\n * @category Error Handling\n */\nexport class WriteSessionExpiredError extends PersonalServerWriteError {\n  constructor(message: string, details?: Record<string, unknown>) {\n    super(message, \"WRITE_SESSION_EXPIRED\", undefined, null, details);\n  }\n}\n\n/**\n * Thrown when a write answered 401.\n *\n * @remarks\n * `WRITE_ATTRIBUTION_*` codes describe the per-write proof. A plain\n * `INVALID_SIGNATURE` or `MISSING_AUTH` on a write usually means the session\n * token is no longer known to the Personal Server (expired, or the server\n * restarted and dropped its in-memory sessions): open a new session.\n * @category Error Handling\n */\nexport class WriteUnauthorizedError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_UNAUTHORIZED\", 401, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered 403: the live grant no longer authorizes it\n * (revoked, expired, wrong owner) or the scope is outside its write patterns.\n * @category Error Handling\n */\nexport class WriteForbiddenError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_FORBIDDEN\", 403, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered 409 (the record conflicts with server state).\n * @category Error Handling\n */\nexport class WriteConflictError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_CONFLICT\", 409, errorCode, details);\n  }\n}\n\n/**\n * Thrown when the Personal Server rejected the write's lineage: 422\n * `LINEAGE_SOURCE_UNKNOWN` (`details.unknown` lists the offending ids), 400\n * `LINEAGE_INVALID` / `LINEAGE_SCOPE_UNDER_SOURCE_PREFIX`, or 502\n * `LINEAGE_SOURCE_LOOKUP_FAILED`.\n * @category Error Handling\n */\nexport class WriteLineageError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status = 422,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_LINEAGE_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a write answered any other non-2xx status (400 for a body the\n * server cannot store, 413 for an oversized payload, 5xx).\n * @category Error Handling\n */\nexport class WriteRejectedError extends PersonalServerWriteError {\n  constructor(\n    message: string,\n    status: number,\n    errorCode: PersonalServerWriteErrorCode | null = null,\n    details?: Record<string, unknown>,\n  ) {\n    super(message, \"WRITE_REJECTED\", status, errorCode, details);\n  }\n}\n\n/**\n * Thrown when a lineage read (Personal Server or gateway) fails: a non-2xx\n * answer, a body that is not a lineage graph, a malformed data point id, or\n * a transport failure.\n * @category Error Handling\n */\nexport class LineageReadError extends VanaError {\n  constructor(\n    message: string,\n    public readonly status?: number,\n    public readonly errorCode: PersonalServerWriteErrorCode | null = null,\n    public readonly details?: Record<string, unknown>,\n  ) {\n    super(message, \"LINEAGE_READ_ERROR\");\n  }\n}\n\n/**\n * Thrown when a DataRegistryV2 data point has been deleted (tombstoned).\n *\n * @remarks\n * Raised by gateway reads that hit HTTP 410, by Personal Server reads of a\n * deleted scope, and by any SDK read helper that would otherwise hand a\n * tombstone back to the caller as if it were data. Pass\n * `includeDeleted: true` to the gateway read helpers to opt in to seeing the\n * tombstone row (with its `deletedAt`) instead of this error.\n * @category Error Handling\n */\nexport class DataPointDeletedError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details: {\n      dataPointId?: string;\n      scope?: string;\n      ownerAddress?: string;\n      deletedAt?: string | null;\n    } = {},\n  ) {\n    super(message, \"DATA_POINT_DELETED\");\n  }\n}\n\n/**\n * Thrown when a data point operation targets a (owner, scope) the gateway\n * has no record of.\n * @category Error Handling\n */\nexport class DataPointNotFoundError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details: {\n      dataPointId?: string;\n      scope?: string;\n      ownerAddress?: string;\n    } = {},\n  ) {\n    super(message, \"DATA_POINT_NOT_FOUND\");\n  }\n}\n\n/**\n * Thrown when the gateway rejects a data point write with HTTP 409 because\n * the signed `expectedVersion` is stale.\n *\n * @remarks\n * `currentExpectedVersion` is the version the gateway currently holds (when\n * the gateway surfaced it); re-sign against `currentExpectedVersion + 1`.\n * @category Error Handling\n */\nexport class DataPointVersionConflictError extends VanaError {\n  constructor(\n    message: string,\n    public readonly details: {\n      dataPointId?: string;\n      scope?: string;\n      ownerAddress?: string;\n      expectedVersion?: string;\n      currentExpectedVersion?: string;\n    } = {},\n  ) {\n    super(message, \"DATA_POINT_VERSION_CONFLICT\");\n  }\n}\n"],"mappings":"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","names":[]}