@opendatalabs/vana-sdk 3.4.0 → 3.4.1-canary.7afbfe0

package/dist/protocol/gateway.d.ts

@@ -1,6 +1,22 @@
 export interface GatewayEnvelope<T> {
     data: T;
     proof: GatewayProof;
+    /**
+     * Cursor-based pagination metadata, present on list endpoints (e.g.
+     * `GET /v1/data`). A sibling of `data`, not nested inside it — so callers
+     * that need it must read the full envelope rather than going through
+     * `unwrapEnvelope`, which intentionally returns only `data`.
+     */
+    pagination?: GatewayPagination;
+}
+export interface GatewayPagination {
+    limit: number;
+    hasMore: boolean;
+    /**
+     * Opaque cursor for the NEXT page; pass back as the `cursor` query param.
+     * Null when there are no further pages.
+     */
+    nextCursor: string | null;
 }
 export interface GatewayProof {
     signature: string;
@@ -35,75 +51,71 @@ export interface ServerInfo {
     publicKey: string;
     serverUrl: string;
     addedAt: string;
+    revokedAt: string | null;
 }
+export interface GatewayGrantFee {
+    asset: string;
+    registrationFee: string;
+    dataAccessFee: string;
+    totalDue: string;
+}
+export type GatewayGrantStatus = "pending" | "submitting" | "confirmed" | "finalized" | "reorged";
 export interface GatewayGrantResponse {
     id: string;
     grantorAddress: string;
     granteeId: string;
-    grant: string;
-    fileIds: string[];
-    status: "pending" | "confirmed";
+    scopes: string[];
+    status: GatewayGrantStatus;
     addedAt: string;
+    expiresAt: string | null;
+    expired: boolean;
     revokedAt: string | null;
     revocationSignature: string | null;
+    paymentStatus: "pending" | "paid";
+    paidAt: string | null;
+    paidBy: string | null;
+    grantVersion: string;
+    settleTxHash: string | null;
+    settleSubmittedAt: string | null;
+    revocationTxHash: string | null;
+    revocationSubmittedAt: string | null;
+    fee: GatewayGrantFee;
 }
-export interface GrantListItem {
+export type GrantListItem = GatewayGrantResponse;
+export interface DataPointRecord {
     id: string;
-    grantorAddress: string;
-    granteeId: string;
-    grant: string;
-    fileIds: string[];
-    status: "pending" | "confirmed";
+    ownerAddress: string;
+    scope: string;
+    dataHash: string;
+    metadataHash: string;
+    expectedVersion: string;
     addedAt: string;
-    revokedAt: string | null;
-    revocationSignature: string | null;
-}
-export interface FileRecord {
-    fileId: string;
-    owner: string;
-    url: string;
-    schemaId: string;
-    createdAt: string;
-    /**
-     * Soft-deletion timestamp (ISO 8601), or null if the file is active. Always present
-     * (`normalizeFileRecord` populates it); non-null only when the gateway returns deletion state
-     * (e.g. listed with `includeDeleted`). Drives the PS sync delete-reconciliation.
-     */
-    deletedAt: string | null;
 }
-export interface FileListResult {
-    files: FileRecord[];
+export interface DataPointListResult {
+    dataPoints: DataPointRecord[];
     cursor: string | null;
 }
-export interface ListFilesOptions {
+export interface ListDataPointsOptions {
     /**
-     * Include soft-deleted files in the result (each carries a non-null `deletedAt`). Default false.
-     * Used by the PS sync download worker to reconcile deletions of files it already holds locally.
+     * Only return rows added at or after this ISO 8601 timestamp. Used by sync
+     * loops that want incremental tails — pass the last seen `addedAt`.
      */
-    includeDeleted?: boolean;
-}
-export interface RegisterFileParams {
-    ownerAddress: string;
-    url: string;
-    schemaId: string;
-    signature: string;
+    since?: string;
+    /** Page size. Capped at 1000 by the gateway. */
+    limit?: number;
 }
 export interface CreateGrantParams {
     grantorAddress: string;
     granteeId: string;
-    grant: string;
-    fileIds: string[];
+    scopes: string[];
+    grantVersion: string;
+    expiresAt: string;
     signature: string;
 }
 export interface RevokeGrantParams {
     grantId: string;
     grantorAddress: string;
-    signature: string;
-}
-export interface DeleteFileParams {
-    fileId: string;
-    ownerAddress: string;
-    /** EIP-712 FileDeletion signature, signed by the owner or the owner's registered server. */
+    grantVersion: string;
     signature: string;
 }
 export interface RegisterServerParams {
@@ -117,6 +129,171 @@ export interface RegisterServerResult {
     serverId?: string;
     alreadyRegistered: boolean;
 }
+export interface RegisterBuilderParams {
+    ownerAddress: string;
+    granteeAddress: string;
+    publicKey: string;
+    appUrl: string;
+    signature: string;
+}
+export interface RegisterBuilderResult {
+    builderId?: string;
+    alreadyRegistered: boolean;
+}
+export interface RegisterDataPointParams {
+    ownerAddress: string;
+    scope: string;
+    dataHash: string;
+    metadataHash: string;
+    expectedVersion: string;
+    signature: string;
+}
+export interface RegisterDataPointResult {
+    dataPointId?: string;
+    expectedVersion?: string;
+}
+export interface AccessRecord {
+    dataPointId: string;
+    version: string;
+    accessor: string;
+    recordId: string;
+    signature: string;
+}
+export interface PayForOperationParams {
+    payerAddress: string;
+    opType: string;
+    opId: string;
+    asset: string;
+    amount: string;
+    paymentNonce: string;
+    signature: string;
+    accessRecord?: AccessRecord;
+}
+export interface PayForOperationResult {
+    opType: string;
+    opId: string;
+    payerAddress: string;
+    asset: string;
+    amount: string;
+    breakdown: {
+        registrationFee: string;
+        dataAccessFee: string;
+        registrationPaid: boolean;
+    };
+    paymentNonce: string;
+    paidAt: string;
+}
+export type SettleOpType = "grant" | "server" | "data" | "access";
+export type SettleItem = {
+    opType: SettleOpType;
+    opId: string;
+    status: "submitting" | "confirmed";
+    settleTxHash: string | null;
+    settleSubmittedAt: string | null;
+    chainBlockHeight: string | null;
+    revocationTxHash: string | null;
+    revocationSubmittedAt: string | null;
+    placeholder: boolean;
+} | {
+    opType: SettleOpType;
+    opId: string;
+    status: "skipped";
+    reason: string;
+} | {
+    opType: SettleOpType;
+    opId: string;
+    status: "failed";
+    error: string;
+};
+export interface SettlePromoteResult {
+    opType: SettleOpType;
+    opId: string;
+    status: "confirmed" | "failed" | "pending" | "skipped";
+    txHash: string;
+    chainBlockHeight: string | null;
+    reason?: string;
+}
+export interface SettleReconcileItem {
+    opId: string;
+    status: "finalized" | "reorged" | "unchanged";
+    chainBlockHeight: string | null;
+    settleTxHash: string | null;
+    reason?: string;
+}
+export interface SettleParams {
+    limit?: number;
+}
+export interface SettleResult {
+    scanned: number;
+    submitted: number;
+    confirmed: number;
+    skipped: number;
+    failed: number;
+    items: SettleItem[];
+    promoted: {
+        count: number;
+        items: SettlePromoteResult[];
+    };
+    reconciled: {
+        scanned: number;
+        finalized: number;
+        reorged: number;
+        unchanged: number;
+        items: SettleReconcileItem[];
+    };
+    paced?: {
+        iterations: number;
+    };
+}
+export interface EscrowBalanceEntry {
+    asset: string;
+    balance: string;
+    pendingAmount: string;
+    authorizedAmount: string;
+    availableAmount: string;
+    updatedAt: string | null;
+}
+export interface EscrowDepositSubmitted {
+    txHash: string;
+    submittedAt: string;
+    claimedAsset: string;
+    claimedAmount: string;
+}
+export interface EscrowDepositFinalized {
+    txHash: string;
+    finalizedAt: string | null;
+    blockNumber: string | null;
+    claimedAsset: string;
+    claimedAmount: string;
+}
+export interface EscrowDepositFailed {
+    txHash: string;
+    submittedAt: string;
+    claimedAsset: string;
+    claimedAmount: string;
+    lastError: string | null;
+}
+export interface EscrowBalance {
+    account: string;
+    balances: EscrowBalanceEntry[];
+    deposits: {
+        submitted: EscrowDepositSubmitted[];
+        finalized: EscrowDepositFinalized[];
+        failed: EscrowDepositFailed[];
+    };
+}
+export interface SubmitDepositParams {
+    txHash: string;
+}
+export interface DepositState {
+    txHash: string;
+    account: string;
+    status: string;
+    blockNumber: string | null;
+    submittedAt: string;
+    finalizedAt: string | null;
+    lastError: string | null;
+}
 export interface GatewayClient {
     isRegisteredBuilder(address: string): Promise<boolean>;
     getBuilder(address: string): Promise<Builder | null>;
@@ -124,23 +301,28 @@ export interface GatewayClient {
     listGrantsByUser(userAddress: string): Promise<GrantListItem[]>;
     getSchemaForScope(scope: string): Promise<Schema | null>;
     getServer(address: string): Promise<ServerInfo | null>;
-    getFile(fileId: string): Promise<FileRecord | null>;
-    listFilesSince(owner: string, cursor: string | null, options?: ListFilesOptions): Promise<FileListResult>;
+    /**
+     * Fetch a single data point by its deterministic id (keccak256 of (owner, scope)).
+     * Returns null on 404. The gateway omits `status` from the response body — read it
+     * from the on-chain DataRegistryV2 contract when you need the canonical lifecycle state.
+     */
+    getDataPoint(dataPointId: string): Promise<DataPointRecord | null>;
+    /**
+     * Page through an owner's data points. Cursor is opaque; pass `null` for the first
+     * page and feed back `result.cursor` until it returns null.
+     */
+    listDataPointsByOwner(owner: string, cursor: string | null, options?: ListDataPointsOptions): Promise<DataPointListResult>;
     getSchema(schemaId: string): Promise<Schema | null>;
     registerServer(params: RegisterServerParams): Promise<RegisterServerResult>;
-    registerFile(params: RegisterFileParams): Promise<{
-        fileId?: string;
-    }>;
+    registerBuilder(params: RegisterBuilderParams): Promise<RegisterBuilderResult>;
+    registerDataPoint(params: RegisterDataPointParams): Promise<RegisterDataPointResult>;
     createGrant(params: CreateGrantParams): Promise<{
         grantId?: string;
     }>;
     revokeGrant(params: RevokeGrantParams): Promise<void>;
-    /**
-     * Soft-deletes (de-registers) a file at the gateway. Resolves on 200 and on 409
-     * (already deleted) — 409 is treated as idempotent success. Other non-2xx, including
-     * 404 (file not registered), throw; the PS delete cascade decides whether a 404 is
-     * benign (blob already gone) or a hard failure.
-     */
-    deleteFile(params: DeleteFileParams): Promise<void>;
+    getEscrowBalance(account: string): Promise<EscrowBalance>;
+    submitEscrowDeposit(params: SubmitDepositParams): Promise<DepositState>;
+    payForOperation(params: PayForOperationParams): Promise<PayForOperationResult>;
+    settle(params?: SettleParams): Promise<SettleResult>;
 }
 export declare function createGatewayClient(baseUrl: string): GatewayClient;

package/dist/protocol/gateway.js

@@ -4,16 +4,6 @@ function createGatewayClient(baseUrl) {
     const envelope = await res.json();
     return envelope.data;
   }
-  function normalizeFileRecord(record) {
-    return {
-      fileId: record.fileId ?? record.id ?? "",
-      owner: record.owner ?? record.ownerAddress ?? "",
-      url: record.url,
-      schemaId: record.schemaId,
-      createdAt: record.createdAt ?? record.addedAt ?? "",
-      deletedAt: record.deletedAt ?? null
-    };
-  }
   function getMutationId(body, key) {
     const value = body[key] ?? body["id"];
     return typeof value === "string" ? value : void 0;
@@ -63,30 +53,34 @@ function createGatewayClient(baseUrl) {
       }
       return unwrapEnvelope(res);
     },
-    async getFile(fileId) {
-      const res = await fetch(`${base}/v1/files/${fileId}`);
+    async getDataPoint(dataPointId) {
+      const res = await fetch(`${base}/v1/data/${dataPointId}`);
       if (res.status === 404) return null;
       if (!res.ok) {
         throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
       }
-      return normalizeFileRecord(await unwrapEnvelope(res));
+      return unwrapEnvelope(res);
     },
-    async listFilesSince(owner, cursor, options) {
+    async listDataPointsByOwner(owner, cursor, options) {
       const params = new URLSearchParams({ user: owner });
       if (cursor !== null) {
-        params.set("since", cursor);
+        params.set("cursor", cursor);
+      }
+      if (options?.since) {
+        params.set("since", options.since);
       }
-      if (options?.includeDeleted) {
-        params.set("includeDeleted", "true");
+      if (options?.limit !== void 0) {
+        params.set("limit", String(options.limit));
       }
-      const res = await fetch(`${base}/v1/files?${params.toString()}`);
+      const res = await fetch(`${base}/v1/data?${params.toString()}`);
       if (!res.ok) {
         throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
       }
-      const data = await unwrapEnvelope(res);
+      const envelope = await res.json();
+      const nextCursor = envelope.pagination?.hasMore === false ? null : envelope.pagination?.nextCursor ?? null;
       return {
-        files: data.files.map(normalizeFileRecord),
-        cursor: data.cursor
+        dataPoints: envelope.data.dataPoints,
+        cursor: nextCursor
       };
     },
     async getSchema(schemaId) {
@@ -127,8 +121,8 @@ function createGatewayClient(baseUrl) {
         alreadyRegistered: false
       };
     },
-    async registerFile(params) {
-      const res = await fetch(`${base}/v1/files`, {
+    async registerBuilder(params) {
+      const res = await fetch(`${base}/v1/builders`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -136,22 +130,57 @@ function createGatewayClient(baseUrl) {
         },
         body: JSON.stringify({
           ownerAddress: params.ownerAddress,
-          url: params.url,
-          schemaId: params.schemaId
+          granteeAddress: params.granteeAddress,
+          publicKey: params.publicKey,
+          appUrl: params.appUrl
         })
       });
       if (res.status === 409) {
         const body2 = await res.json().catch(() => ({}));
         return {
-          fileId: getMutationId(body2, "fileId")
+          builderId: getMutationId(
+            body2,
+            "builderId"
+          ),
+          alreadyRegistered: true
         };
       }
       if (!res.ok) {
         throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
       }
-      const body = await res.json();
+      const body = await res.json().catch(() => ({}));
+      return {
+        builderId: getMutationId(body, "builderId"),
+        alreadyRegistered: false
+      };
+    },
+    async registerDataPoint(params) {
+      const res = await fetch(`${base}/v1/data`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Web3Signed ${params.signature}`
+        },
+        body: JSON.stringify({
+          ownerAddress: params.ownerAddress,
+          scope: params.scope,
+          dataHash: params.dataHash,
+          metadataHash: params.metadataHash,
+          expectedVersion: params.expectedVersion
+        })
+      });
+      if (!res.ok) {
+        const body2 = await res.json().catch(() => ({}));
+        const detail = body2.error ?? res.statusText;
+        throw new Error(`Gateway error: ${res.status} ${detail}`);
+      }
+      const body = await res.json().catch(() => ({}));
       return {
-        fileId: getMutationId(body, "fileId")
+        dataPointId: getMutationId(
+          body,
+          "dataPointId"
+        ),
+        expectedVersion: body.expectedVersion
       };
     },
     async createGrant(params) {
@@ -164,8 +193,9 @@ function createGatewayClient(baseUrl) {
         body: JSON.stringify({
           grantorAddress: params.grantorAddress,
           granteeId: params.granteeId,
-          grant: params.grant,
-          fileIds: params.fileIds
+          scopes: params.scopes,
+          grantVersion: params.grantVersion,
+          expiresAt: params.expiresAt
         })
       });
       if (res.status === 409) {
@@ -190,7 +220,8 @@ function createGatewayClient(baseUrl) {
           Authorization: `Web3Signed ${params.signature}`
         },
         body: JSON.stringify({
-          grantorAddress: params.grantorAddress
+          grantorAddress: params.grantorAddress,
+          grantVersion: params.grantVersion
         })
       });
       if (res.status === 409) return;
@@ -198,21 +229,62 @@ function createGatewayClient(baseUrl) {
         throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
       }
     },
-    async deleteFile(params) {
-      const res = await fetch(`${base}/v1/files/${params.fileId}`, {
-        method: "DELETE",
+    async getEscrowBalance(account) {
+      const res = await fetch(`${base}/v1/escrow/balance?account=${account}`);
+      if (!res.ok) {
+        throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    async submitEscrowDeposit(params) {
+      const res = await fetch(`${base}/v1/escrow/deposit`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ txHash: params.txHash })
+      });
+      if (res.status !== 200 && res.status !== 202) {
+        throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    async payForOperation(params) {
+      const body = {
+        payerAddress: params.payerAddress,
+        opType: params.opType,
+        opId: params.opId,
+        asset: params.asset,
+        amount: params.amount,
+        paymentNonce: params.paymentNonce
+      };
+      if (params.accessRecord) {
+        body["accessRecord"] = params.accessRecord;
+      }
+      const res = await fetch(`${base}/v1/escrow/pay`, {
+        method: "POST",
         headers: {
           "Content-Type": "application/json",
           Authorization: `Web3Signed ${params.signature}`
         },
-        body: JSON.stringify({
-          ownerAddress: params.ownerAddress
-        })
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) {
+        throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    async settle(params) {
+      const res = await fetch(`${base}/v1/settle`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        // The gateway accepts an empty body; only `limit` is recognised.
+        // Always send a JSON body so the gateway's req.body shape parse
+        // doesn't have to deal with an undefined.
+        body: JSON.stringify(params ?? {})
       });
-      if (res.status === 409) return;
       if (!res.ok) {
         throw new Error(`Gateway error: ${res.status} ${res.statusText}`);
       }
+      return await res.json();
     }
   };
 }