@arkiv-network/sdk 0.4.5 → 0.5.0-dev.2

package/dist/{queryBuilder-Cn5JJRMM.cjs → queryBuilder-KrdIUVZv.cjs}

@@ -1,29 +1,7 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc$1) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc$1 = __getOwnPropDesc(from, key)) || desc$1.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
+const require_chunk = require('./chunk-pbleEpgJ.cjs');
 let viem = require("viem");
 let debug = require("debug");
-debug = __toESM(debug);
+debug = require_chunk.__toESM(debug);
 
 //#region src/utils/logger.ts
 const ROOT_NAMESPACE = "arkiv";
@@ -41,11 +19,6 @@ var NoCursorOrLimitError = class extends Error {
 		super("Cursor and limit must be defined to fetch next");
 	}
 };
-var OffsetCannotBeLessThanZeroError = class extends Error {
-	constructor() {
-		super("Offset cannot be less than 0");
-	}
-};
 var NoEntityFoundError = class extends Error {
 	constructor() {
 		super("No entity found");
@@ -216,7 +189,7 @@ var QueryResult = class {
 * Helper function to create an ascending order by attribute
 * @param attributeName - The name of the attribute to order by
 * @param attributeType - The type of the attribute to order by (string or number)
-* @returns The OrderByAttribute instance
+* @returns Input for orderBy method
 *
 * @example
 * const ascAttribute = asc("name", "string")
@@ -232,7 +205,7 @@ function asc(attributeName, attributeType) {
 * Helper function to create a descending order by attribute
 * @param attributeName - The name of the attribute to order by
 * @param attributeType - The type of the attribute to order by (string or number)
-* @returns The OrderByAttribute instance
+* @returns Input for orderBy method
 *
 * @example
 * const descAttribute = desc("name", "string")
@@ -467,12 +440,6 @@ Object.defineProperty(exports, 'NoMoreResultsError', {
     return NoMoreResultsError;
   }
 });
-Object.defineProperty(exports, 'OffsetCannotBeLessThanZeroError', {
-  enumerable: true,
-  get: function () {
-    return OffsetCannotBeLessThanZeroError;
-  }
-});
 Object.defineProperty(exports, 'QueryBuilder', {
   enumerable: true,
   get: function () {
@@ -485,12 +452,6 @@ Object.defineProperty(exports, 'QueryResult', {
     return QueryResult;
   }
 });
-Object.defineProperty(exports, '__toESM', {
-  enumerable: true,
-  get: function () {
-    return __toESM;
-  }
-});
 Object.defineProperty(exports, 'asc', {
   enumerable: true,
   get: function () {

package/dist/types/index.cjs

@@ -1 +1 @@
-require('../types-CBTc19th.cjs');
+require('../types-o3zWarRp.cjs');

package/dist/types/index.d.cts

@@ -1,2 +1,3 @@
-import { _ as ArkivRpcSchema, a as MutateEntitiesReturnType, b as RpcQueryOptions, c as ExtendEntityParameters, d as DeleteEntityReturnType, f as CreateEntityParameters, h as ChangeOwnershipReturnType, i as MutateEntitiesParameters, l as ExtendEntityReturnType, m as ChangeOwnershipParameters, n as TxParams, o as UpdateEntityParameters, p as CreateEntityReturnType, r as Attribute, s as UpdateEntityReturnType, t as Entity, u as DeleteEntityParameters, v as RpcEntity, x as MimeType, y as RpcIncludeData } from "../entity-BNSCqNpu.cjs";
-export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, RpcEntity, RpcIncludeData, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };
+import { $ as RpcIncludeData, A as CreateEntityParameters, C as MutateEntitiesReturnType, D as ExtendEntityReturnType, E as ExtendEntityParameters, J as QueryOptionsIncludeData, M as ChangeOwnershipParameters, N as ChangeOwnershipReturnType, O as DeleteEntityParameters, P as GetBlockTimingReturnType, Q as RpcEntity, S as MutateEntitiesParameters, T as UpdateEntityReturnType, Y as QueryOptionsOrderBy, Z as ArkivRpcSchema, _ as OnEntityExpiredEvent, b as OnEntityUpdatedEvent, et as RpcOrderByAttribute, g as OnEntityDeletedEvent, h as OnEntityCreatedEvent, j as CreateEntityReturnType, k as DeleteEntityReturnType, m as TxParams, nt as MimeType, p as Entity, q as QueryOptions, tt as RpcQueryOptions, v as OnEntityExpiresInExtendedEvent, w as UpdateEntityParameters, x as Attribute, y as OnEntityOwnerChangedEvent } from "../index-DQGx5KZ6.cjs";
+import "../payload-D3fyOBWn.cjs";
+export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, OnEntityCreatedEvent, OnEntityDeletedEvent, OnEntityExpiredEvent, OnEntityExpiresInExtendedEvent, OnEntityOwnerChangedEvent, OnEntityUpdatedEvent, QueryOptions, QueryOptionsIncludeData, QueryOptionsOrderBy, RpcEntity, RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };

package/dist/types/index.d.ts

@@ -1,2 +1,3 @@
-import { _ as ArkivRpcSchema, a as MutateEntitiesReturnType, b as RpcQueryOptions, c as ExtendEntityParameters, d as DeleteEntityReturnType, f as CreateEntityParameters, h as ChangeOwnershipReturnType, i as MutateEntitiesParameters, l as ExtendEntityReturnType, m as ChangeOwnershipParameters, n as TxParams, o as UpdateEntityParameters, p as CreateEntityReturnType, r as Attribute, s as UpdateEntityReturnType, t as Entity, u as DeleteEntityParameters, v as RpcEntity, x as MimeType, y as RpcIncludeData } from "../entity-CWj4qVCX.js";
-export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, RpcEntity, RpcIncludeData, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };
+import { $ as RpcIncludeData, A as CreateEntityParameters, C as MutateEntitiesReturnType, D as ExtendEntityReturnType, E as ExtendEntityParameters, J as QueryOptionsIncludeData, M as ChangeOwnershipParameters, N as ChangeOwnershipReturnType, O as DeleteEntityParameters, P as GetBlockTimingReturnType, Q as RpcEntity, S as MutateEntitiesParameters, T as UpdateEntityReturnType, Y as QueryOptionsOrderBy, Z as ArkivRpcSchema, _ as OnEntityExpiredEvent, b as OnEntityUpdatedEvent, et as RpcOrderByAttribute, g as OnEntityDeletedEvent, h as OnEntityCreatedEvent, j as CreateEntityReturnType, k as DeleteEntityReturnType, m as TxParams, nt as MimeType, p as Entity, q as QueryOptions, tt as RpcQueryOptions, v as OnEntityExpiresInExtendedEvent, w as UpdateEntityParameters, x as Attribute, y as OnEntityOwnerChangedEvent } from "../index-B801JxcV.js";
+import "../payload-BI2NXPDf.js";
+export { ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, Entity, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, OnEntityCreatedEvent, OnEntityDeletedEvent, OnEntityExpiredEvent, OnEntityExpiresInExtendedEvent, OnEntityOwnerChangedEvent, OnEntityUpdatedEvent, QueryOptions, QueryOptionsIncludeData, QueryOptionsOrderBy, RpcEntity, RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType };

package/dist/types/index.js

@@ -1 +1 @@
-import "../types-Cv8NMtbo.js";
+import "../types-H-TSmRpm.js";

package/dist/utils/index.cjs

@@ -1,6 +1,4 @@
-const require_queryBuilder = require('../queryBuilder-Cn5JJRMM.cjs');
-const require_consts = require('../consts-BV9DVKgE.cjs');
-let viem = require("viem");
+const require_payload = require('../payload-eB1a8vZH.cjs');
 
 //#region src/utils/expirationTime.ts
 const ExpirationTime = {
@@ -11,23 +9,14 @@ const ExpirationTime = {
 	fromWeeks: (weeks) => weeks * 7 * 24 * 60 * 60,
 	fromMonths: (months) => months * 30 * 24 * 60 * 60,
 	fromYears: (years) => years * 365 * 24 * 60 * 60,
-	fromBlocks: (blocks) => blocks * require_consts.BLOCK_TIME,
+	fromBlocks: (blocks) => blocks * require_payload.BLOCK_TIME,
 	fromDate: (date) => Math.floor(date.getTime() / 1e3) - Math.floor(Date.now() / 1e3)
 };
 
-//#endregion
-//#region src/utils/payload.ts
-function jsonToPayload(json) {
-	return (0, viem.toBytes)(JSON.stringify(json));
-}
-function stringToPayload(data) {
-	return (0, viem.toBytes)(data);
-}
-
 //#endregion
 exports.ExpirationTime = ExpirationTime;
-exports.jsonToPayload = jsonToPayload;
-exports.stringToPayload = stringToPayload;
+exports.jsonToPayload = require_payload.jsonToPayload;
+exports.stringToPayload = require_payload.stringToPayload;
 var viem_utils = require("viem/utils");
 Object.keys(viem_utils).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/dist/utils/index.d.cts

@@ -1,3 +1,4 @@
+import { n as stringToPayload, t as jsonToPayload } from "../payload-D3fyOBWn.cjs";
 export * from "viem/utils";
 
 //#region src/utils/expirationTime.d.ts
@@ -13,9 +14,5 @@ declare const ExpirationTime: {
   fromDate: (date: Date) => number;
 };
 //#endregion
-//#region src/utils/payload.d.ts
-declare function jsonToPayload(json: object): Uint8Array;
-declare function stringToPayload(data: string): Uint8Array;
-//#endregion
 export { ExpirationTime, jsonToPayload, stringToPayload };
 //# sourceMappingURL=index.d.cts.map

package/dist/utils/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/utils/expirationTime.ts","../../src/utils/payload.ts"],"sourcesContent":[],"mappings":";;;cAEa;;;EAAA,SAAA,EAAA,CAAA,KAUZ,EAAA,MAAA,EAAA,GADkB,MAAI;;;;ECTP,SAAA,EAAA,CAAA,KAAa,EAAA,MAAA,EAAA,GAAgB,MAAA;EAI7B,UAAA,EAAA,CAAA,MAAe,EAAA,MAAA,EAAA,GAAgB,MAAA;mBDK5B;;;;iBCTH,aAAA,gBAA6B;iBAI7B,eAAA,gBAA+B"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/utils/expirationTime.ts"],"sourcesContent":[],"mappings":";;;;cAEa;;;;;EAAA,SAAA,EAAA,CAAA,KAUZ,EAAA,MAAA,EAAA,GADkB,MAAI;;;;mBAAJ"}

package/dist/utils/index.d.ts

@@ -1,3 +1,4 @@
+import { n as stringToPayload, t as jsonToPayload } from "../payload-BI2NXPDf.js";
 export * from "viem/utils";
 
 //#region src/utils/expirationTime.d.ts
@@ -13,9 +14,5 @@ declare const ExpirationTime: {
   fromDate: (date: Date) => number;
 };
 //#endregion
-//#region src/utils/payload.d.ts
-declare function jsonToPayload(json: object): Uint8Array;
-declare function stringToPayload(data: string): Uint8Array;
-//#endregion
 export { ExpirationTime, jsonToPayload, stringToPayload };
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/utils/expirationTime.ts","../../src/utils/payload.ts"],"sourcesContent":[],"mappings":";;;cAEa;;;EAAA,SAAA,EAAA,CAAA,KAUZ,EAAA,MAAA,EAAA,GADkB,MAAI;;;;ECTP,SAAA,EAAA,CAAA,KAAa,EAAA,MAAA,EAAA,GAAgB,MAAA;EAI7B,UAAA,EAAA,CAAA,MAAe,EAAA,MAAA,EAAA,GAAgB,MAAA;mBDK5B;;;;iBCTH,aAAA,gBAA6B;iBAI7B,eAAA,gBAA+B"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/utils/expirationTime.ts"],"sourcesContent":[],"mappings":";;;;cAEa;;;;;EAAA,SAAA,EAAA,CAAA,KAUZ,EAAA,MAAA,EAAA,GADkB,MAAI;;;;mBAAJ"}

package/dist/utils/index.js

@@ -1,5 +1,4 @@
-import { n as BLOCK_TIME } from "../consts-CHtLBwGd.js";
-import { toBytes } from "viem";
+import { i as BLOCK_TIME, n as stringToPayload, t as jsonToPayload } from "../payload-DKBYYjeA.js";
 
 export * from "viem/utils"
 
@@ -16,15 +15,6 @@ const ExpirationTime = {
 	fromDate: (date) => Math.floor(date.getTime() / 1e3) - Math.floor(Date.now() / 1e3)
 };
 
-//#endregion
-//#region src/utils/payload.ts
-function jsonToPayload(json) {
-	return toBytes(JSON.stringify(json));
-}
-function stringToPayload(data) {
-	return toBytes(data);
-}
-
 //#endregion
 export { ExpirationTime, jsonToPayload, stringToPayload };
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/utils/expirationTime.ts","../../src/utils/payload.ts"],"sourcesContent":["import { BLOCK_TIME } from \"../consts\"\n\nexport const ExpirationTime = {\n  fromSeconds: (seconds: number) => seconds,\n  fromMinutes: (minutes: number) => minutes * 60,\n  fromHours: (hours: number) => hours * 60 * 60,\n  fromDays: (days: number) => days * 24 * 60 * 60,\n  fromWeeks: (weeks: number) => weeks * 7 * 24 * 60 * 60,\n  fromMonths: (months: number) => months * 30 * 24 * 60 * 60,\n  fromYears: (years: number) => years * 365 * 24 * 60 * 60,\n  fromBlocks: (blocks: number) => blocks * BLOCK_TIME,\n  fromDate: (date: Date) => Math.floor(date.getTime() / 1000) - Math.floor(Date.now() / 1000),\n}\n","import { toBytes } from \"viem\"\n\nexport function jsonToPayload(json: object): Uint8Array {\n  return toBytes(JSON.stringify(json))\n}\n\nexport function stringToPayload(data: string): Uint8Array {\n  return toBytes(data)\n}\n"],"mappings":";;;;;;AAEA,MAAa,iBAAiB;CAC5B,cAAc,YAAoB;CAClC,cAAc,YAAoB,UAAU;CAC5C,YAAY,UAAkB,QAAQ,KAAK;CAC3C,WAAW,SAAiB,OAAO,KAAK,KAAK;CAC7C,YAAY,UAAkB,QAAQ,IAAI,KAAK,KAAK;CACpD,aAAa,WAAmB,SAAS,KAAK,KAAK,KAAK;CACxD,YAAY,UAAkB,QAAQ,MAAM,KAAK,KAAK;CACtD,aAAa,WAAmB,SAAS;CACzC,WAAW,SAAe,KAAK,MAAM,KAAK,SAAS,GAAG,IAAK,GAAG,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;CAC5F;;;;ACVD,SAAgB,cAAc,MAA0B;AACtD,QAAO,QAAQ,KAAK,UAAU,KAAK,CAAC;;AAGtC,SAAgB,gBAAgB,MAA0B;AACxD,QAAO,QAAQ,KAAK"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/utils/expirationTime.ts"],"sourcesContent":["import { BLOCK_TIME } from \"../consts\"\n\nexport const ExpirationTime = {\n  fromSeconds: (seconds: number) => seconds,\n  fromMinutes: (minutes: number) => minutes * 60,\n  fromHours: (hours: number) => hours * 60 * 60,\n  fromDays: (days: number) => days * 24 * 60 * 60,\n  fromWeeks: (weeks: number) => weeks * 7 * 24 * 60 * 60,\n  fromMonths: (months: number) => months * 30 * 24 * 60 * 60,\n  fromYears: (years: number) => years * 365 * 24 * 60 * 60,\n  fromBlocks: (blocks: number) => blocks * BLOCK_TIME,\n  fromDate: (date: Date) => Math.floor(date.getTime() / 1000) - Math.floor(Date.now() / 1000),\n}\n"],"mappings":";;;;;AAEA,MAAa,iBAAiB;CAC5B,cAAc,YAAoB;CAClC,cAAc,YAAoB,UAAU;CAC5C,YAAY,UAAkB,QAAQ,KAAK;CAC3C,WAAW,SAAiB,OAAO,KAAK,KAAK;CAC7C,YAAY,UAAkB,QAAQ,IAAI,KAAK,KAAK;CACpD,aAAa,WAAmB,SAAS,KAAK,KAAK,KAAK;CACxD,YAAY,UAAkB,QAAQ,MAAM,KAAK,KAAK;CACtD,aAAa,WAAmB,SAAS;CACzC,WAAW,SAAe,KAAK,MAAM,KAAK,SAAS,GAAG,IAAK,GAAG,KAAK,MAAM,KAAK,KAAK,GAAG,IAAK;CAC5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkiv-network/sdk",
-  "version": "0.4.5",
+  "version": "0.5.0-dev.2",
   "description": "TypeScript client library for Arkiv's blockchains interactions",
   "type": "module",
   "target": "esnext",
@@ -73,6 +73,7 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
     "test:unit": "bun test src/**/*",
+    "docs": "bunx typedoc --plugin typedoc-plugin-markdown",
     "package": "rimraf arkiv-network-sdk-*.tgz && bun run build && bun pm pack --no-cache",
     "package:test": "bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",
     "prepublishOnly": "bun run build && bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",
@@ -84,11 +85,12 @@
     "publish-dev:dry": "npm publish ./arkiv-network-sdk-latest.tgz --access public --tag dev --dry-run"
   },
   "devDependencies": {
-    "@types/debug": "^4.1.12",
     "@biomejs/biome": "2.2.4",
     "@types/bun": "latest",
+    "@types/debug": "^4.1.12",
     "rimraf": "^6.0.1",
-    "tsdown": "^0.16.0"
+    "tsdown": "^0.16.0",
+    "typedoc": "^0.28.14"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
@@ -117,7 +119,8 @@
   "homepage": "https://arkiv.network",
   "dependencies": {
     "brotli-wasm": "^3.0.1",
-    "viem": "^2.38.2",
-    "debug": "^4.3.7"
+    "debug": "^4.3.7",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "viem": "^2.38.2"
   }
 }

package/src/actions/public/query.ts

@@ -1,10 +1,57 @@
 import type { ArkivClient } from "../../clients/baseClient"
+import type { RpcQueryOptions } from "../../types/rpcSchema"
 import { entityFromRpcResult } from "../../utils/entities"
 
-export async function query(client: ArkivClient, query: string) {
+export type QueryOptionsIncludeData = {
+  attributes?: boolean
+  payload?: boolean
+  metadata?: boolean
+}
+export type QueryOptionsOrderBy = {
+  name: string
+  type: "string" | "numeric"
+  desc: "asc" | "desc"
+}
+
+export type QueryOptions = {
+  includeData?: QueryOptionsIncludeData
+  atBlock?: bigint
+  orderBy?: QueryOptionsOrderBy[]
+  resultsPerPage?: number | undefined
+  cursor?: string | undefined
+}
+
+export async function query(client: ArkivClient, query: string, queryOptions?: QueryOptions) {
+  const rpcQueryOptions: RpcQueryOptions = {
+    includeData: {
+      key: true,
+      payload: queryOptions?.includeData?.payload ?? true,
+      attributes: queryOptions?.includeData?.attributes ?? false,
+      contentType: queryOptions?.includeData?.metadata ?? false,
+      expiration: queryOptions?.includeData?.metadata ?? false,
+      owner: queryOptions?.includeData?.metadata ?? false,
+      createdAtBlock: queryOptions?.includeData?.metadata ?? false,
+      lastModifiedAtBlock: queryOptions?.includeData?.metadata ?? false,
+      transactionIndexInBlock: queryOptions?.includeData?.metadata ?? false,
+      operationIndexInTransaction: queryOptions?.includeData?.metadata ?? false,
+    },
+    ...(queryOptions?.atBlock !== undefined && { atBlock: Number(queryOptions.atBlock) }),
+    ...(queryOptions?.orderBy && {
+      orderBy: queryOptions?.orderBy.map((order) => ({
+        name: order.name,
+        type: order.type,
+        desc: order.desc === "desc",
+      })),
+    }),
+    ...(queryOptions?.resultsPerPage !== undefined && {
+      resultsPerPage: queryOptions.resultsPerPage,
+    }),
+    ...(queryOptions?.cursor !== undefined && { cursor: queryOptions?.cursor }),
+  }
+
   const result = await client.request({
     method: "arkiv_query",
-    params: [query],
+    params: [query, rpcQueryOptions],
   })
 
   const entities = await Promise.all(result.data.map((entity) => entityFromRpcResult(entity)))

package/src/actions/public/subscribeEntityEvents.ts

@@ -1,4 +1,4 @@
-import { decodeEventLog, parseAbi, toHex } from "viem"
+import { decodeEventLog, type Hex, parseAbi, toHex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { PublicArkivClient } from "../../clients/createPublicClient"
 import type {
@@ -46,14 +46,14 @@ export async function subscribeEntityEvents(
 ): Promise<() => void> {
   const unsubscribe = (client as PublicArkivClient).watchEvent({
     pollingInterval: pollingInterval ?? 1000,
-    fromBlock: fromBlock,
+    fromBlock,
     events: arkivABI,
     onLogs: (logs) => {
       logger("logs from subscribeEntityEvents %o", logs)
       for (const log of logs) {
         const event = decodeEventLog({
           abi: arkivABI,
-          topics: log.topics as [string, string, string] | [string, string, string, string],
+          topics: log.topics as [Hex, ...Hex[]] | [],
           data: log.data,
         })
         logger("event from subscribeEntityEvents %o", event)

package/src/clients/createPublicClient.ts

@@ -29,7 +29,7 @@ export type PublicArkivClient<
  *
  * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.arkiv.network/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.arkiv.network/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
  *
- * @param config - {@link PublicClientConfig}
+ * @param parameters - Configuration object for the public client (chain, transport, etc.)
  * @returns A Arkiv Public Client. {@link PublicArkivClient}
  *
  * @example

package/src/clients/createWalletClient.ts

@@ -29,8 +29,8 @@ export type WalletArkivClient<
  *
  * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.arkiv.network/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.arkiv.network/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
  *
- * @param config - {@link PublicClientConfig}
- * @returns A Arkiv Public Client. {@link PublicArkivClient}
+ * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
+ * @returns A Arkiv Wallet Client. {@link WalletArkivClient}
  *
  * @example
  * import { createPublicClient, http } from 'arkiv'

package/src/clients/decorators/arkivPublic.ts

@@ -2,7 +2,7 @@ import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem
 import { getBlockTiming } from "../../actions/public/getBlockTiming"
 import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
-import { query } from "../../actions/public/query"
+import { type QueryOptions, query } from "../../actions/public/query"
 import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
 import { QueryBuilder } from "../../query/queryBuilder"
 import type { Entity } from "../../types/entity"
@@ -36,7 +36,7 @@ export type PublicArkivActions<
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
    *
-   * @param args - {entityKey}
+   * @param key - The entity key (hex string)
    * @returns The entity with the given key. {@link Entity}
    *
    * @example
@@ -79,7 +79,10 @@ export type PublicArkivActions<
 
   /**
    * Returns a QueryResult instance for fetching the results of a raw query.
-   * @returns A QueryResult instance for fetching the results of a raw query. {@link QueryResult}
+   * If no query options are provided, all payload is included, but no metadata (like owner, expiredAt, etc.) and attributes.
+   * @param query - The raw query string
+   * @param queryOptions - The optional query options - {@link QueryOptions}
+   * @returns An array of entities matching the query. {@link Entity}
    *
    * @example
    * import { createPublicClient, http } from 'arkiv'
@@ -90,13 +93,25 @@ export type PublicArkivActions<
    *   transport: http(),
    * })
    * const queryResult = client.query('key = value && $owner = 0x123')
-   *
+   * // queryResult = [{ key: "0x123", value: "0x123" }]
+   * const queryResultWithOptions = client.query('key = value && $owner = 0x123', {
+   *   includeData: {
+   *     attributes: false,
+   *     payload: true,
+   *     metadata: true,
+   *   },
+   *   orderBy: [{ name: "key", type: "string", desc: "asc" }],
+   *   resultsPerPage: 10,
+   *   cursor: undefined,
+   *   atBlock: undefined,
+   * })
+   * // queryResultWithOptions = [{ key: "0x123", value: "0x123" }]
    */
-  query: (query: string) => Promise<Entity[]>
+  query: (query: string, queryOptions?: QueryOptions) => Promise<Entity[]>
 
   /**
    * Returns the number of entities in the DBChain.
-   * @returns The number of entities in the DBChain. {@link number}
+   * @returns The number of entities in the DBChain
    *
    * @example
    * import { createPublicClient, http } from 'arkiv'
@@ -136,6 +151,26 @@ export type PublicArkivActions<
     blockDuration: number
   }>
 
+  /**
+   * Subscribes to entity events.
+   * Takes an object with event handlers: {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
+   * @param pollingInterval - The polling interval in milliseconds
+   * @param fromBlock - The block number to start from
+   * @returns A function to unsubscribe from the events
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const unsubscribe = await client.subscribeEntityEvents({
+   *   onError: (error) => console.error("subscribeEntityEvents error", error),
+   * })
+   * unsubscribe() // unsubscribe from the events
+   */
   subscribeEntityEvents: (
     {
       onError,
@@ -163,7 +198,7 @@ export function publicArkivActions<
 >(client: Client<transport, chain, account>) {
   return {
     getEntity: (key: Hex) => getEntity(client, key),
-    query: (rawQuery: string) => query(client, rawQuery),
+    query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
     buildQuery: () => new QueryBuilder(client),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),

package/src/clients/decorators/arkivWallet.ts

@@ -29,7 +29,7 @@ import type {
   UpdateEntityReturnType,
 } from "../../actions/wallet/updateEntity"
 import { updateEntity } from "../../actions/wallet/updateEntity"
-import type { Entity, TxParams } from "../../types"
+import type { TxParams } from "../../types"
 
 export type WalletArkivActions<
   transport extends Transport = Transport,
@@ -47,13 +47,14 @@ export type WalletArkivActions<
     | "signTransaction"
   > & {
     /**
-     * Returns the entity with the given key.
+     * Creates a new entity.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
+     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/createEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity creation parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The created entity with transaction hash
      *
      * @example
      * import { createPublicClient, http } from 'arkiv'
@@ -86,8 +87,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/updateEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity update parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The updated entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -109,8 +111,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/deleteEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity deletion parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The deleted entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -139,8 +142,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/extendEntity
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The entity update parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The updated entity with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'
@@ -171,8 +175,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/changeOwnership
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {entityKey, newOwner}
-     * @returns The entity with the given address. {@link Entity}
+     * @param data - The ownership change parameters
+     * @param txParams - Optional transaction parameters
+     * @returns The entity with updated ownership and transaction hash
      */
     changeOwnership: (
       data: ChangeOwnershipParameters,
@@ -185,8 +190,9 @@ export type WalletArkivActions<
      * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/mutateEntities
      * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
      *
-     * @param args - {data}
-     * @returns The entity with the given key. {@link Entity}
+     * @param data - The mutation parameters (creates, updates, deletes, extensions)
+     * @param txParams - Optional transaction parameters
+     * @returns The mutation result with transaction hash
      *
      * @example
      * import { createWalletClient, http } from 'arkiv'

package/src/index.ts

@@ -1,3 +1,7 @@
+/**
+ * @module main
+ */
+
 // Re-export all viem stuff
 export * from "viem"
 
@@ -7,6 +11,12 @@ export type { PublicArkivClient } from "./clients/createPublicClient"
 export { createPublicClient } from "./clients/createPublicClient"
 export type { WalletArkivClient } from "./clients/createWalletClient"
 export { createWalletClient } from "./clients/createWalletClient"
+export type { PublicArkivActions } from "./clients/decorators/arkivPublic"
+export type { WalletArkivActions } from "./clients/decorators/arkivWallet"
 
 // re-export arkiv types in main index file
 export * from "./types"
+
+// re-export chosen utils
+export { chainFromName } from "./utils/chains"
+export { jsonToPayload, stringToPayload } from "./utils/payload"

package/src/query/errors.ts

@@ -10,12 +10,6 @@ export class NoCursorOrLimitError extends Error {
   }
 }
 
-export class OffsetCannotBeLessThanZeroError extends Error {
-  constructor() {
-    super("Offset cannot be less than 0")
-  }
-}
-
 export class NoEntityFoundError extends Error {
   constructor() {
     super("No entity found")

package/src/query/queryBuilder.ts

@@ -6,7 +6,7 @@ import { processQuery } from "./engine"
 import type { Predicate } from "./predicate"
 import { QueryResult } from "./queryResult"
 
-type OrderByAttribute = {
+export type OrderByAttribute = {
   name: string
   type: "string" | "number"
   order: "asc" | "desc"
@@ -16,7 +16,7 @@ type OrderByAttribute = {
  * Helper function to create an ascending order by attribute
  * @param attributeName - The name of the attribute to order by
  * @param attributeType - The type of the attribute to order by (string or number)
- * @returns The OrderByAttribute instance
+ * @returns Input for orderBy method
  *
  * @example
  * const ascAttribute = asc("name", "string")
@@ -33,7 +33,7 @@ export function asc(attributeName: string, attributeType: "string" | "number"):
  * Helper function to create a descending order by attribute
  * @param attributeName - The name of the attribute to order by
  * @param attributeType - The type of the attribute to order by (string or number)
- * @returns The OrderByAttribute instance
+ * @returns Input for orderBy method
  *
  * @example
  * const descAttribute = desc("name", "string")
@@ -86,14 +86,17 @@ export class QueryBuilder {
    * Sets the orderBy for the query.
    * It can be called multiple times to order by multiple attributes.
    * The order of the attributes is important. The first attribute is the primary order by attribute.
+   * You can use the helper functions asc() and desc() as input for this method.
    * @param attributeName - The name of the attribute to order by
    * @param attributeType - The type of the attribute to order by (string or number)
    * @param order - The order to set the order by (asc or desc)
    * @returns The QueryBuilder instance
    *
    * @example
-   * const builder = new QueryBuilder(client)
+   * const builder = client.buildQuery()
    * builder.orderBy("name", "string", "desc")
+   * builder.orderBy(asc("name", "string"))
+   * builder.orderBy(desc("name", "string"))
    */
   orderBy(attributeName: string, attributeType: "string" | "number", order?: "asc" | "desc"): this
   /**