@opendatalabs/vana-sdk 3.16.0 → 3.17.0

package/dist/index.node.js

@@ -1288,6 +1288,76 @@ var TransactionPendingError = class extends VanaError {
     };
   }
 };
+var PersonalServerWriteError = class extends VanaError {
+  constructor(message, code, status, errorCode = null, details) {
+    super(message, code);
+    this.status = status;
+    this.errorCode = errorCode;
+    this.details = details;
+  }
+  status;
+  errorCode;
+  details;
+};
+var WriteRequestError = class extends PersonalServerWriteError {
+  constructor(message, details) {
+    super(message, "WRITE_INVALID_REQUEST", void 0, null, details);
+  }
+};
+var WriteTransportError = class extends PersonalServerWriteError {
+  constructor(message, attempts, cause) {
+    super(message, "WRITE_TRANSPORT_ERROR", void 0, null, { attempts });
+    this.attempts = attempts;
+    this.cause = cause;
+  }
+  attempts;
+};
+var WriteSessionError = class extends PersonalServerWriteError {
+  constructor(message, status, errorCode = null, details) {
+    super(message, "WRITE_SESSION_REJECTED", status, errorCode, details);
+  }
+};
+var WriteSessionExpiredError = class extends PersonalServerWriteError {
+  constructor(message, details) {
+    super(message, "WRITE_SESSION_EXPIRED", void 0, null, details);
+  }
+};
+var WriteUnauthorizedError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "WRITE_UNAUTHORIZED", 401, errorCode, details);
+  }
+};
+var WriteForbiddenError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "WRITE_FORBIDDEN", 403, errorCode, details);
+  }
+};
+var WriteConflictError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "WRITE_CONFLICT", 409, errorCode, details);
+  }
+};
+var WriteLineageError = class extends PersonalServerWriteError {
+  constructor(message, status = 422, errorCode = null, details) {
+    super(message, "WRITE_LINEAGE_REJECTED", status, errorCode, details);
+  }
+};
+var WriteRejectedError = class extends PersonalServerWriteError {
+  constructor(message, status, errorCode = null, details) {
+    super(message, "WRITE_REJECTED", status, errorCode, details);
+  }
+};
+var LineageReadError = class extends VanaError {
+  constructor(message, status, errorCode = null, details) {
+    super(message, "LINEAGE_READ_ERROR");
+    this.status = status;
+    this.errorCode = errorCode;
+    this.details = details;
+  }
+  status;
+  errorCode;
+  details;
+};
 
 // src/contracts/contractController.ts
 import {
@@ -32799,13 +32869,13 @@ function createViemPersonalServerRegistrationSigner(source, options = {}) {
   if (isPersonalServerRegistrationSigner(source)) {
     return source;
   }
-  const accountAddress = getAccountAddress(options.account) ?? getAccountAddress(source.account);
-  if (accountAddress) {
+  const accountAddress2 = getAccountAddress(options.account) ?? getAccountAddress(source.account);
+  if (accountAddress2) {
     return {
-      address: accountAddress,
+      address: accountAddress2,
       signTypedData: (typedData) => source.signTypedData({
         ...typedData,
-        account: options.account ?? source.account ?? accountAddress
+        account: options.account ?? source.account ?? accountAddress2
       })
     };
   }
@@ -32890,12 +32960,12 @@ function createViemPersonalServerLiteOwnerBindingSigner(source, options = {}) {
   if (isPersonalServerLiteOwnerBindingSigner(source)) {
     return source;
   }
-  const accountAddress = getAccountAddress2(options.account) ?? getAccountAddress2(source.account);
-  if (accountAddress) {
+  const accountAddress2 = getAccountAddress2(options.account) ?? getAccountAddress2(source.account);
+  if (accountAddress2) {
     return {
-      address: accountAddress,
+      address: accountAddress2,
       signMessage: ({ message }) => source.signMessage({
-        account: options.account ?? source.account ?? accountAddress,
+        account: options.account ?? source.account ?? accountAddress2,
         message
       })
     };
@@ -33718,6 +33788,867 @@ function tryGrantPermissions(scopes) {
   }
 }
 
+// src/protocol/personal-server-write.ts
+import { sha256 as sha2565 } from "@noble/hashes/sha2";
+import { bytesToHex as bytesToHex2, isAddress as isAddress5 } from "viem";
+import { z as z4 } from "zod";
+
+// src/protocol/lineage.ts
+import {
+  encodeAbiParameters,
+  isAddress as isAddress4,
+  keccak256
+} from "viem";
+import { z as z3 } from "zod";
+
+// src/protocol/personal-server-error-body.ts
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+async function readPersonalServerErrorBody(response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return { errorCode: null, message: null };
+  }
+  if (!isRecord2(body)) return { errorCode: null, message: null };
+  const nested = isRecord2(body.error) ? body.error : null;
+  const gatewayShape = typeof body.error === "string" && typeof body.code === "string";
+  const code = nested?.errorCode ?? nested?.code ?? body.errorCode ?? (gatewayShape ? body.code : void 0) ?? (typeof body.error === "string" ? body.error : void 0) ?? body.code;
+  const message = nested?.message ?? body.message ?? (gatewayShape ? body.error : void 0);
+  const gatewayDetails = {};
+  for (const key of ["unknown", "scope", "sourceScope"]) {
+    if (gatewayShape && body[key] !== void 0)
+      gatewayDetails[key] = body[key];
+  }
+  const details = nested?.details ?? body.details ?? (Object.keys(gatewayDetails).length > 0 ? gatewayDetails : void 0);
+  return {
+    errorCode: typeof code === "string" ? code : null,
+    message: typeof message === "string" ? message : null,
+    ...isRecord2(details) ? { details } : {}
+  };
+}
+
+// src/protocol/write-signer.ts
+function isRecord3(value) {
+  return value !== null && typeof value === "object";
+}
+function isViemWriteAccount(source) {
+  return isRecord3(source) && source.type === "local" && typeof source.address === "string" && typeof source.signMessage === "function";
+}
+function isViemWriteWalletClient(source) {
+  return isRecord3(source) && typeof source.signMessage === "function" && source.type !== "local" && (source.type === "walletClient" || "transport" in source);
+}
+function accountAddress(account) {
+  return typeof account === "string" ? account : account.address;
+}
+function resolveWriteSigner(source, options = {}) {
+  if (isViemWriteWalletClient(source)) {
+    const account = options.account ?? source.account;
+    if (account === void 0) {
+      throw new WriteRequestError(
+        "Viem wallet client requires an account option or account property"
+      );
+    }
+    return {
+      address: accountAddress(account),
+      signMessage: (message) => source.signMessage({ account, message })
+    };
+  }
+  if (isViemWriteAccount(source)) {
+    return {
+      address: source.address,
+      signMessage: (message) => source.signMessage({ message })
+    };
+  }
+  if (!isRecord3(source) || typeof source.signMessage !== "function") {
+    throw new WriteRequestError(
+      "signer must be a viem LocalAccount, a viem WalletClient, or a { signMessage } object"
+    );
+  }
+  return source;
+}
+
+// src/protocol/lineage.ts
+var DATA_POINT_ID_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+function isDataPointId(value) {
+  return typeof value === "string" && DATA_POINT_ID_PATTERN.test(value);
+}
+function deriveDataPointId(ownerAddress, scope) {
+  if (!isAddress4(ownerAddress, { strict: false })) {
+    throw new Error(
+      `ownerAddress is not an EVM address: ${String(ownerAddress)}`
+    );
+  }
+  return keccak256(
+    encodeAbiParameters(
+      [
+        { name: "ownerAddress", type: "address" },
+        { name: "scope", type: "string" }
+      ],
+      [ownerAddress, scope]
+    )
+  );
+}
+var DataPointIdSchema = z3.string().regex(DATA_POINT_ID_PATTERN).transform((value) => value.toLowerCase());
+var VERSION_PATTERN = /^[1-9]\d*$/;
+var NODE_VERSION_PATTERN = /^(0|[1-9]\d*)$/;
+var VersionSchema = z3.union([z3.string(), z3.number()]).transform(String).refine((value) => NODE_VERSION_PATTERN.test(value), {
+  message: "version must be a decimal integer"
+});
+var ViewVersionSchema = VersionSchema.refine(
+  (value) => VERSION_PATTERN.test(value),
+  { message: "version must be a positive decimal integer" }
+);
+function scopeNamespace(scope) {
+  const dot = scope.indexOf(".");
+  return dot === -1 ? scope : scope.slice(0, dot);
+}
+function derivedScopeViolatesNaming(derivedScope, sourceScope) {
+  return scopeNamespace(derivedScope) === scopeNamespace(sourceScope);
+}
+function assertDerivedScopeNaming(derivedScope, sourceScopes) {
+  for (const sourceScope of sourceScopes) {
+    if (derivedScopeViolatesNaming(derivedScope, sourceScope)) {
+      throw new WriteRequestError(
+        `Derived scope ${derivedScope} must not share its first segment with source scope ${sourceScope}; put derivatives in the app's own namespace`,
+        { scope: derivedScope, sourceScope }
+      );
+    }
+  }
+}
+var LineageNodeSchema = z3.object({
+  dataPointId: DataPointIdSchema,
+  scope: z3.string(),
+  /**
+   * The node's current version, decimal string; `"0"` for a source that no
+   * longer resolves to a registered data point.
+   */
+  version: VersionSchema,
+  /** The node's tombstone time, or `null` when live. */
+  deletedAt: z3.string().nullable()
+});
+var RedactedLineageNodeSchema = z3.object({
+  dataPointId: DataPointIdSchema,
+  redacted: z3.literal(true)
+});
+var LineageEntrySchema = z3.union([
+  RedactedLineageNodeSchema,
+  LineageNodeSchema
+]);
+var LineageGraphSchema = z3.object({
+  dataPointId: DataPointIdSchema,
+  /** The data point owner; every node in the view belongs to it. */
+  ownerAddress: z3.string().optional(),
+  scope: z3.string(),
+  /**
+   * The derived record's version whose lineage is shown: the requested one,
+   * else the current one, else (current is a tombstone) the last version
+   * that carried lineage.
+   */
+  version: ViewVersionSchema,
+  deletedAt: z3.string().nullable(),
+  sources: z3.array(LineageEntrySchema),
+  derivatives: z3.array(LineageEntrySchema),
+  /** `true` when `derivatives` was cut at the server's cap (1000). */
+  derivativesTruncated: z3.boolean().optional()
+});
+function isRedactedLineageNode(entry) {
+  return "redacted" in entry && entry.redacted === true;
+}
+function personalServerLineagePath(scope, version) {
+  return `/v1/data/${encodeURIComponent(scope)}/lineage${version === void 0 ? "" : `/${String(version)}`}`;
+}
+function gatewayLineagePath(dataPointId, version) {
+  return `/v1/data/${dataPointId.toLowerCase()}/lineage${version === void 0 ? "" : `/${String(version)}`}`;
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new LineageReadError("No fetch implementation available");
+  }
+  return resolved;
+}
+function normalizeVersion(version) {
+  if (version === void 0) return void 0;
+  const text = String(version);
+  if (!VERSION_PATTERN.test(text)) {
+    throw new LineageReadError(
+      "version must be a positive decimal integer",
+      void 0,
+      "INVALID_VERSION",
+      { version }
+    );
+  }
+  return text;
+}
+async function lineageReadFailure(source, response) {
+  const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+  return new LineageReadError(
+    message ?? `${source} lineage read failed: ${response.status} ${response.statusText}`,
+    response.status,
+    errorCode,
+    details
+  );
+}
+async function parseLineageGraph(source, response) {
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new LineageReadError(
+      `${source} lineage response is not JSON`,
+      response.status,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const envelope = isRecord2(body) && isRecord2(body.data) ? body : void 0;
+  const parsed = LineageGraphSchema.safeParse(envelope?.data ?? body);
+  if (!parsed.success) {
+    throw new LineageReadError(
+      `${source} lineage response is not a lineage view`,
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  const proof = isRecord2(envelope?.proof) ? envelope.proof : void 0;
+  return proof === void 0 ? parsed.data : { ...parsed.data, proof };
+}
+async function sendLineageRead(source, fetchFn, url, headers) {
+  let response;
+  try {
+    response = await fetchFn(url, { method: "GET", headers });
+  } catch (err) {
+    throw new LineageReadError(
+      `${source} lineage read failed: ${err instanceof Error ? err.message : String(err)}`,
+      void 0,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  if (!response.ok) {
+    throw await lineageReadFailure(source, response);
+  }
+  return parseLineageGraph(source, response);
+}
+async function getPersonalServerLineage(params) {
+  const fetchFn = resolveFetch(params.fetch);
+  const baseUrl = normalizeBaseUrl(params.personalServerUrl);
+  const audience = params.audience ?? baseUrl;
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const path = personalServerLineagePath(
+    params.scope,
+    normalizeVersion(params.version)
+  );
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await buildWeb3SignedHeader({
+      signMessage: signer.signMessage,
+      aud: audience,
+      method: "GET",
+      uri: path,
+      grantId: params.grantId
+    })
+  );
+  return sendLineageRead(
+    "Personal Server",
+    fetchFn,
+    `${baseUrl}${path}`,
+    headers
+  );
+}
+async function getGatewayLineage(params) {
+  if (!isDataPointId(params.dataPointId)) {
+    throw new LineageReadError(
+      "dataPointId must be a 32-byte hex string (see deriveDataPointId)",
+      void 0,
+      "INVALID_DATA_POINT_ID",
+      { dataPointId: params.dataPointId }
+    );
+  }
+  const fetchFn = resolveFetch(params.fetch);
+  const baseUrl = normalizeBaseUrl(params.gatewayUrl);
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const uri = gatewayLineagePath(
+    params.dataPointId,
+    normalizeVersion(params.version)
+  );
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await buildWeb3SignedHeader({
+      signMessage: signer.signMessage,
+      aud: baseUrl,
+      method: "GET",
+      uri,
+      grantId: params.grantId?.toLowerCase()
+    })
+  );
+  return sendLineageRead("Gateway", fetchFn, `${baseUrl}${uri}`, headers);
+}
+function getLineage(params) {
+  return "personalServerUrl" in params ? getPersonalServerLineage(params) : getGatewayLineage(params);
+}
+
+// src/protocol/personal-server-write.ts
+var WRITE_SESSION_PATH = "/v1/write/session";
+var WRITE_SIGNATURE_HEADER = "X-Vana-Write-Signature";
+var WRITE_METADATA_HEADER = "X-Vana-Metadata";
+var LINEAGE_FIELD = "lineage";
+var MAX_LINEAGE_SOURCES = 256;
+var WRITE_FILENAME_HEADER = "X-Filename";
+var WRITE_CONTENT_DISPOSITION_HEADER = "Content-Disposition";
+var WRITER_ATTRIBUTION_KEY = "$writtenBy";
+var LINEAGE_KEY = "$lineage";
+var RESERVED_WRITE_KEYS = [
+  WRITER_ATTRIBUTION_KEY,
+  LINEAGE_KEY
+];
+var WriteDataResultSchema = IngestResponseSchema.extend({
+  // Present when the write carried lineage: the validated, lowercased ids.
+  lineage: z4.object({ sources: z4.array(z4.string()) }).optional()
+});
+var WriteSessionResponseSchema = z4.object({
+  access_token: z4.string().min(1),
+  token_type: z4.string(),
+  expires_in: z4.number().nonnegative(),
+  scope: z4.string()
+});
+function normalizeBaseUrl2(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch2(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new WriteRequestError("No fetch implementation available");
+  }
+  return resolved;
+}
+function dataPath(scope) {
+  return `/v1/data/${encodeURIComponent(scope)}`;
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function finiteOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var issuedProofIats = /* @__PURE__ */ new Map();
+var issuedProofBuckets = /* @__PURE__ */ new Map();
+var issuedProofIatsPrunedAtSec = 0;
+var WEB3_SIGNED_PROOF_LIFETIME_SECONDS = 300;
+var WEB3_SIGNED_CLOCK_SKEW_SECONDS = 60;
+var PROOF_IAT_RETENTION_SECONDS = WEB3_SIGNED_PROOF_LIFETIME_SECONDS + WEB3_SIGNED_CLOCK_SKEW_SECONDS;
+var PROOF_IAT_MAX_AHEAD_SECONDS = 30;
+function pruneIssuedProofIats(nowSec) {
+  if (issuedProofIatsPrunedAtSec === nowSec) return;
+  issuedProofIatsPrunedAtSec = nowSec;
+  const cutoff = nowSec - PROOF_IAT_RETENTION_SECONDS;
+  for (const [sec, keys] of issuedProofBuckets) {
+    if (sec >= cutoff) continue;
+    for (const key of keys) issuedProofIats.delete(key);
+    issuedProofBuckets.delete(sec);
+  }
+}
+function setIssuedProofIat(key, iat, previous) {
+  if (previous !== void 0) {
+    const bucket2 = issuedProofBuckets.get(previous);
+    bucket2?.delete(key);
+    if (bucket2?.size === 0) issuedProofBuckets.delete(previous);
+  }
+  issuedProofIats.set(key, iat);
+  let bucket = issuedProofBuckets.get(iat);
+  if (bucket === void 0) {
+    bucket = /* @__PURE__ */ new Set();
+    issuedProofBuckets.set(iat, bucket);
+  }
+  bucket.add(key);
+}
+function nextProofIat(proofKey) {
+  const nowSec = Math.floor(Date.now() / 1e3);
+  pruneIssuedProofIats(nowSec);
+  const last = issuedProofIats.get(proofKey);
+  const iat = last === void 0 ? nowSec : Math.max(nowSec, last + 1);
+  setIssuedProofIat(proofKey, iat, last);
+  const waitSec = iat - nowSec - PROOF_IAT_MAX_AHEAD_SECONDS;
+  if (waitSec <= 0) return Promise.resolve(iat);
+  return sleep2(waitSec * 1e3).then(() => iat);
+}
+function proofKeyFor(parts) {
+  return bytesToHex2(
+    sha2565(
+      new TextEncoder().encode(
+        JSON.stringify([
+          parts.aud,
+          parts.method,
+          parts.uri,
+          parts.grantId,
+          parts.signedBytes ? bytesToHex2(sha2565(parts.signedBytes)) : ""
+        ])
+      )
+    )
+  );
+}
+async function sendWithFreshProof(label, fetchFn, options, proofKey, build) {
+  const attempts = Math.max(1, Math.floor(finiteOr(options?.attempts, 3)));
+  let delayMs = Math.max(0, finiteOr(options?.initialDelayMs, 1e3));
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const { url, init } = await build(await nextProofIat(proofKey));
+    try {
+      return await fetchFn(url, init);
+    } catch (err) {
+      lastError = err;
+    }
+    if (attempt < attempts - 1) {
+      await sleep2(delayMs);
+      delayMs *= 2;
+    }
+  }
+  throw new WriteTransportError(
+    `${label} failed after ${attempts} attempt(s): ${errorMessage(lastError)}`,
+    attempts,
+    lastError
+  );
+}
+async function openWriteSession(params) {
+  const fetchFn = resolveFetch2(params.fetch);
+  const personalServerUrl = normalizeBaseUrl2(params.personalServerUrl);
+  const audience = params.audience ?? personalServerUrl;
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const response = await sendWithFreshProof(
+    "Write session handshake",
+    fetchFn,
+    params.retry,
+    proofKeyFor({
+      aud: audience,
+      method: "POST",
+      uri: WRITE_SESSION_PATH,
+      grantId: params.grantId
+    }),
+    async (iat) => {
+      const headers = new Headers(params.headers);
+      headers.set(
+        "Authorization",
+        await buildWeb3SignedHeader({
+          signMessage: signer.signMessage,
+          aud: audience,
+          method: "POST",
+          uri: WRITE_SESSION_PATH,
+          grantId: params.grantId,
+          iat
+        })
+      );
+      return {
+        url: `${personalServerUrl}${WRITE_SESSION_PATH}`,
+        init: { method: "POST", headers }
+      };
+    }
+  );
+  const mintedAt = Date.now();
+  if (!response.ok) {
+    const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+    throw new WriteSessionError(
+      message ?? `Write session handshake failed: ${response.status} ${response.statusText}`,
+      response.status,
+      errorCode,
+      details
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new WriteSessionError(
+      "Write session response is not JSON",
+      response.status,
+      null,
+      { cause: errorMessage(err) }
+    );
+  }
+  const parsed = WriteSessionResponseSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new WriteSessionError(
+      "Write session response is not a session",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  if (parsed.data.token_type.toLowerCase() !== "bearer") {
+    throw new WriteSessionError(
+      `Write session token type is not Bearer: ${parsed.data.token_type}`,
+      response.status
+    );
+  }
+  return {
+    personalServerUrl,
+    audience,
+    grantId: params.grantId,
+    accessToken: parsed.data.access_token,
+    expiresAt: mintedAt + parsed.data.expires_in * 1e3,
+    writeScopes: parsed.data.scope.split(" ").filter((s) => s.length > 0),
+    signer
+  };
+}
+function isWriteSession(value) {
+  if (!isRecord2(value)) return false;
+  const signer = value.signer;
+  return typeof value.personalServerUrl === "string" && typeof value.audience === "string" && typeof value.grantId === "string" && typeof value.accessToken === "string" && value.accessToken.length > 0 && typeof value.expiresAt === "number" && Number.isFinite(value.expiresAt) && Array.isArray(value.writeScopes) && value.writeScopes.every((scope) => typeof scope === "string") && isRecord2(signer) && typeof signer.signMessage === "function";
+}
+function sessionCoversScope(session, scope) {
+  if (!isRecord2(session) || !Array.isArray(session.writeScopes) || !session.writeScopes.every((pattern) => typeof pattern === "string")) {
+    throw new WriteRequestError("session must come from openWriteSession");
+  }
+  return session.writeScopes.some(
+    (pattern) => scopeMatchesPattern(scope, pattern)
+  );
+}
+function normalizeBinaryMimeType(contentType) {
+  if (!contentType) return "application/octet-stream";
+  return contentType.split(";")[0].trim() || "application/octet-stream";
+}
+function parseWriteMetadataHeader(value) {
+  if (value === null) return void 0;
+  const trimmed = value.trim();
+  if (trimmed === "") return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return value;
+  }
+}
+function encodeWriteMetadataHeader(metadata) {
+  let json;
+  try {
+    json = JSON.stringify(metadata);
+  } catch (err) {
+    throw new WriteRequestError(
+      `metadata is not JSON-serialisable: ${errorMessage(err)}`
+    );
+  }
+  if (typeof json !== "string") {
+    throw new WriteRequestError("metadata must serialise to JSON");
+  }
+  return json.replace(
+    /[\u007f-\uffff]/g,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+function binaryWriteSignedBytes(input) {
+  const metadata = parseWriteMetadataHeader(input.metadataHeader ?? null);
+  const record = {
+    $binary: true,
+    mimeType: normalizeBinaryMimeType(input.contentType),
+    ...input.filename ? { filename: input.filename } : {},
+    sizeBytes: input.bytes.length,
+    contentHash: bytesToHex2(sha2565(input.bytes)),
+    encoding: "base64",
+    content: toBase64(input.bytes),
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+  return new TextEncoder().encode(JSON.stringify(record));
+}
+var PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+function setFilenameHeader(headers, filename) {
+  if (PRINTABLE_ASCII.test(filename)) {
+    headers.set(WRITE_FILENAME_HEADER, filename);
+    return;
+  }
+  headers.set(
+    WRITE_CONTENT_DISPOSITION_HEADER,
+    `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`
+  );
+}
+function assertNoReservedKeys(value, where) {
+  for (const key of RESERVED_WRITE_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      throw new WriteRequestError(
+        `${where} must not contain the reserved ${key} key; the Personal Server stamps it`,
+        { key }
+      );
+    }
+  }
+}
+function isLineagePair(value) {
+  return isRecord2(value) && typeof value.ownerAddress === "string" && typeof value.scope === "string";
+}
+function normalizeLineage(lineage, derivedScope) {
+  if (!Array.isArray(lineage)) {
+    throw new WriteRequestError("lineage must be an array of data point ids");
+  }
+  if (lineage.length > MAX_LINEAGE_SOURCES) {
+    throw new WriteRequestError(
+      `lineage lists ${lineage.length} sources; the maximum is ${MAX_LINEAGE_SOURCES}`,
+      { max: MAX_LINEAGE_SOURCES, count: lineage.length }
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const sources = [];
+  const sourceScopes = [];
+  const ownIds = /* @__PURE__ */ new Set();
+  for (const entry of lineage) {
+    let id;
+    if (isLineagePair(entry)) {
+      if (!isAddress5(entry.ownerAddress, { strict: false })) {
+        throw new WriteRequestError(
+          "lineage source ownerAddress must be an EVM address",
+          { ownerAddress: entry.ownerAddress }
+        );
+      }
+      if (entry.scope.length === 0) {
+        throw new WriteRequestError("lineage source scope is required");
+      }
+      id = deriveDataPointId(entry.ownerAddress, entry.scope);
+      sourceScopes.push(entry.scope);
+      ownIds.add(deriveDataPointId(entry.ownerAddress, derivedScope));
+    } else if (isDataPointId(entry)) {
+      id = entry;
+    } else {
+      throw new WriteRequestError(
+        "lineage entries must be 32-byte hex data point ids or { ownerAddress, scope } pairs",
+        { entry }
+      );
+    }
+    const normalized = id.toLowerCase();
+    if (seen.has(normalized)) {
+      throw new WriteRequestError("lineage must not repeat a data point id", {
+        dataPointId: normalized
+      });
+    }
+    seen.add(normalized);
+    sources.push(normalized);
+  }
+  for (const own of ownIds) {
+    if (seen.has(own)) {
+      throw new WriteRequestError(
+        "lineage must not cite the record's own data point",
+        { dataPointId: own, scope: derivedScope }
+      );
+    }
+  }
+  assertDerivedScopeNaming(derivedScope, sourceScopes);
+  return sources;
+}
+function assertNoLineageField(value, where) {
+  if (Object.prototype.hasOwnProperty.call(value, LINEAGE_FIELD)) {
+    throw new WriteRequestError(
+      `${where}.${LINEAGE_FIELD} is reserved; pass sources through the lineage option`
+    );
+  }
+}
+function buildMetadataHeader(metadata, sources) {
+  if (metadata !== void 0) {
+    if (!isRecord2(metadata)) {
+      throw new WriteRequestError("metadata must be a plain object");
+    }
+    assertNoReservedKeys(metadata, "metadata");
+    assertNoLineageField(metadata, "metadata");
+  }
+  if (metadata === void 0 && sources === void 0) return void 0;
+  return encodeWriteMetadataHeader({
+    ...metadata ?? {},
+    ...sources !== void 0 ? { [LINEAGE_FIELD]: sources } : {}
+  });
+}
+function prepareWrite(params) {
+  if (params.binary !== void 0 && params.data !== void 0) {
+    throw new WriteRequestError("Pass either data or binary, not both");
+  }
+  const rawLineage = params.lineage;
+  const sources = rawLineage === void 0 || rawLineage === null ? void 0 : normalizeLineage(rawLineage, params.scope);
+  if (params.binary !== void 0) {
+    const { bytes, contentType, filename } = params.binary;
+    if (!(bytes instanceof Uint8Array)) {
+      throw new WriteRequestError("binary.bytes must be a Uint8Array");
+    }
+    if (typeof contentType !== "string" || contentType.trim() === "") {
+      throw new WriteRequestError("binary.contentType is required");
+    }
+    if (filename !== void 0) {
+      if (typeof filename !== "string") {
+        throw new WriteRequestError("binary.filename must be a string");
+      }
+      if (filename !== filename.trim()) {
+        throw new WriteRequestError(
+          "binary.filename must not have leading or trailing whitespace"
+        );
+      }
+    }
+    const metadataHeader = buildMetadataHeader(params.metadata, sources);
+    return {
+      body: bytes,
+      signedBytes: binaryWriteSignedBytes({
+        bytes,
+        contentType,
+        filename,
+        metadataHeader
+      }),
+      contentType,
+      filename,
+      metadataHeader
+    };
+  }
+  if (params.data === void 0) {
+    throw new WriteRequestError("Pass data (a JSON object) or binary");
+  }
+  if (!isRecord2(params.data)) {
+    throw new WriteRequestError("data must be a plain JSON object");
+  }
+  if (params.metadata !== void 0) {
+    throw new WriteRequestError(
+      "metadata applies to binary writes; put fields to store inside data"
+    );
+  }
+  assertNoReservedKeys(params.data, "data");
+  assertNoLineageField(params.data, "data");
+  const record = sources === void 0 ? params.data : { ...params.data, [LINEAGE_FIELD]: sources };
+  let text;
+  try {
+    text = JSON.stringify(record);
+  } catch (err) {
+    throw new WriteRequestError(
+      `data is not JSON-serialisable: ${errorMessage(err)}`
+    );
+  }
+  if (typeof text !== "string" || !text.startsWith("{")) {
+    throw new WriteRequestError("data must serialise to a JSON object");
+  }
+  const body = new TextEncoder().encode(text);
+  return {
+    body,
+    signedBytes: body,
+    contentType: "application/json"
+  };
+}
+async function writeErrorFromResponse(response) {
+  const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+  const text = message ?? `Personal Server write failed: ${response.status} ${response.statusText}`;
+  if (response.status === 422 || errorCode?.startsWith("LINEAGE_")) {
+    return new WriteLineageError(text, response.status, errorCode, details);
+  }
+  switch (response.status) {
+    case 401:
+      return new WriteUnauthorizedError(text, errorCode, details);
+    case 403:
+      return new WriteForbiddenError(text, errorCode, details);
+    case 409:
+      return new WriteConflictError(text, errorCode, details);
+    default:
+      return new WriteRejectedError(text, response.status, errorCode, details);
+  }
+}
+async function writeData(params) {
+  const { session } = params;
+  if (!isWriteSession(session)) {
+    throw new WriteRequestError("session must come from openWriteSession");
+  }
+  const fetchFn = resolveFetch2(params.fetch);
+  if (typeof params.scope !== "string" || params.scope.length === 0) {
+    throw new WriteRequestError("scope is required");
+  }
+  const prepared = prepareWrite(params);
+  if (Date.now() >= session.expiresAt) {
+    throw new WriteSessionExpiredError(
+      "Write session has expired; open a new session",
+      { grantId: session.grantId, expiresAt: session.expiresAt }
+    );
+  }
+  const path = dataPath(params.scope);
+  const response = await sendWithFreshProof(
+    `Write to ${params.scope}`,
+    fetchFn,
+    params.retry,
+    proofKeyFor({
+      aud: session.audience,
+      method: "POST",
+      uri: path,
+      grantId: session.grantId,
+      signedBytes: prepared.signedBytes
+    }),
+    async (iat) => {
+      const headers = new Headers(params.headers);
+      headers.set("Content-Type", prepared.contentType);
+      headers.set("Authorization", `Bearer ${session.accessToken}`);
+      if (prepared.filename) {
+        setFilenameHeader(headers, prepared.filename);
+      }
+      if (prepared.metadataHeader !== void 0) {
+        headers.set(WRITE_METADATA_HEADER, prepared.metadataHeader);
+      }
+      headers.set(
+        WRITE_SIGNATURE_HEADER,
+        await buildWeb3SignedHeader({
+          signMessage: session.signer.signMessage,
+          aud: session.audience,
+          method: "POST",
+          uri: path,
+          body: prepared.signedBytes,
+          grantId: session.grantId,
+          iat
+        })
+      );
+      return {
+        url: `${session.personalServerUrl}${path}`,
+        init: {
+          method: "POST",
+          headers,
+          body: prepared.body
+        }
+      };
+    }
+  );
+  if (!response.ok) {
+    throw await writeErrorFromResponse(response);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new WriteRejectedError(
+      "Personal Server write response is not JSON",
+      response.status,
+      null,
+      { cause: errorMessage(err) }
+    );
+  }
+  const parsed = WriteDataResultSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new WriteRejectedError(
+      "Personal Server write response is not an ingest result",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+async function writePersonalServerData(params) {
+  const session = await openWriteSession({
+    personalServerUrl: params.personalServerUrl,
+    signer: params.signer,
+    grantId: params.grantId,
+    account: params.account,
+    audience: params.audience,
+    fetch: params.fetch,
+    headers: params.headers,
+    retry: params.retry
+  });
+  const writeParams = { ...params, session };
+  const result = await writeData(writeParams);
+  return { ...result, session };
+}
+
 // src/protocol/gateway.ts
 function withGrantPermissions(grant) {
   const stripped = { ...grant };
@@ -34638,7 +35569,7 @@ var KNOWN_CODES = /* @__PURE__ */ new Set([
   "server_not_configured",
   "content_too_large"
 ]);
-function isRecord2(value) {
+function isRecord4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeCode(value) {
@@ -34649,10 +35580,10 @@ function normalizeCode(value) {
   return KNOWN_CODES.has(code) ? code : null;
 }
 function extractPSErrorBody(body) {
-  if (!isRecord2(body)) {
+  if (!isRecord4(body)) {
     return null;
   }
-  const nested = isRecord2(body.error) ? body.error : null;
+  const nested = isRecord4(body.error) ? body.error : null;
   const code = normalizeCode(
     nested?.errorCode ?? nested?.code ?? body.errorCode ?? body.code
   );
@@ -34707,7 +35638,14 @@ export {
   InvalidScopeEntryError,
   InvalidSignatureError,
   IpfsStorage,
+  LINEAGE_FIELD,
+  LINEAGE_KEY,
+  LineageEntrySchema,
+  LineageGraphSchema,
+  LineageNodeSchema,
+  LineageReadError,
   MASTER_KEY_MESSAGE,
+  MAX_LINEAGE_SOURCES,
   MissingAuthError,
   NATIVE_ASSET_ADDRESS,
   NATIVE_VANA_ASSET,
@@ -34726,11 +35664,14 @@ export {
   PSError,
   PermissionError,
   PersonalServerError,
+  PersonalServerWriteError,
   PinataStorage,
   R2Storage,
   RECORD_DATA_ACCESS_TYPES,
   REGISTRATION_KIND_FOR_OP,
+  RESERVED_WRITE_KEYS,
   ReadOnlyError,
+  RedactedLineageNodeSchema,
   RelayerError,
   SCOPE_ACTIONS,
   SERVER_REGISTRATION_TYPES,
@@ -34744,9 +35685,26 @@ export {
   UserRejectedRequestError,
   VanaError,
   VanaStorage,
+  WRITER_ATTRIBUTION_KEY,
+  WRITE_CONTENT_DISPOSITION_HEADER,
+  WRITE_FILENAME_HEADER,
+  WRITE_METADATA_HEADER,
+  WRITE_SESSION_PATH,
+  WRITE_SIGNATURE_HEADER,
+  WriteConflictError,
+  WriteForbiddenError,
+  WriteLineageError,
+  WriteRejectedError,
+  WriteRequestError,
+  WriteSessionError,
+  WriteSessionExpiredError,
+  WriteTransportError,
+  WriteUnauthorizedError,
+  assertDerivedScopeNaming,
   assertValidPkceVerifier,
   authorizeEscrowPayment,
   authorizeGrantPayment,
+  binaryWriteSignedBytes,
   buildDepositNativeRequest,
   buildDepositTokenRequest,
   buildEscrowPaymentHeader,
@@ -34780,17 +35738,21 @@ export {
   dataRegistryContractAddress,
   dataRegistryDomain,
   decryptWithPassword,
+  deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
+  derivedScopeViolatesNaming,
   deserializeECIES,
   detectPlatform,
   encodeDepositNativeData,
   encodeDepositTokenData,
   encodeSetDataPointStatusData,
+  encodeWriteMetadataHeader,
   encryptWithPassword,
   escrowContractAddress,
   escrowPaymentDomain,
   formatScopeEntry,
+  gatewayLineagePath,
   generatePkceVerifier,
   genericPaymentDomain,
   getAbi,
@@ -34800,38 +35762,50 @@ export {
   getContractController,
   getContractInfo,
   getFee,
+  getGatewayLineage,
+  getLineage,
   getOpFee,
+  getPersonalServerLineage,
   getPlatformCapabilities,
   getServiceEndpoints,
   grantPermissions,
   grantRegistrationDomain,
   grantRevocationDomain,
   hasAction,
+  isDataPointId,
   isDataPortabilityGatewayConfig,
   isECIESEncrypted,
   isPlatformSupported,
+  isRedactedLineageNode,
   mainnetServices,
   moksha,
   mokshaServices,
   mokshaTestnet2 as mokshaTestnet,
+  normalizeBinaryMimeType,
+  openWriteSession,
   parsePSError,
   parsePersonalServerPaymentRequired,
   parseScope,
   parseScopeEntry,
   parseWeb3SignedHeader,
+  parseWriteMetadataHeader,
   paymentReceiptFromHeader,
   paymentResponseMetadataFromHeader,
   permissionsToScopes,
   personalServerDataReadPath,
+  personalServerLineagePath,
   personalServerRegistrationDomain,
   readPersonalServerData,
   recoverServerOwner,
   registerPersonalServerSignature,
+  resolveWriteSigner,
   scopeCoveredByGrant,
   scopeMatchesPattern,
+  scopeNamespace,
   scopeToPathSegments,
   serializeECIES,
   serverRegistrationDomain,
+  sessionCoversScope,
   signPersonalServerLiteOwnerBinding,
   signPersonalServerLiteOwnerBindingWithAccountClient,
   signPersonalServerRegistrationWithAccount,
@@ -34841,6 +35815,8 @@ export {
   vanaMainnet2 as vanaMainnet,
   verifyGrantRegistration,
   verifyPkceChallenge,
-  verifyWeb3Signed
+  verifyWeb3Signed,
+  writeData,
+  writePersonalServerData
 };
 //# sourceMappingURL=index.node.js.map