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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkiv-network/sdk",
-  "version": "0.5.0-dev.1",
+  "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 {
@@ -53,7 +53,7 @@ export async function subscribeEntityEvents(
       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'
@@ -138,10 +153,10 @@ export type PublicArkivActions<
 
   /**
    * Subscribes to entity events.
-   * @param events to watch - {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
-   * @param pollingInterval - The polling interval in milliseconds. {@link number}
-   * @param fromBlock - The block number to start from. {@link bigint}
-   * @returns A function to unsubscribe from the events. {() => void}
+   * 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'
@@ -183,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,8 @@ 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"

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
   /**

package/src/types/index.ts

@@ -1,3 +1,9 @@
+export type { GetBlockTimingReturnType } from "../actions/public/getBlockTiming"
+export type {
+  QueryOptions,
+  QueryOptionsIncludeData,
+  QueryOptionsOrderBy,
+} from "../actions/public/query"
 export type {
   ChangeOwnershipParameters,
   ChangeOwnershipReturnType,
@@ -12,6 +18,20 @@ export type {
 export type { UpdateEntityParameters, UpdateEntityReturnType } from "../actions/wallet/updateEntity"
 export type { Attribute } from "./attributes"
 export type { Entity } from "./entity"
+export type {
+  OnEntityCreatedEvent,
+  OnEntityDeletedEvent,
+  OnEntityExpiredEvent,
+  OnEntityExpiresInExtendedEvent,
+  OnEntityOwnerChangedEvent,
+  OnEntityUpdatedEvent,
+} from "./events"
 export type { MimeType } from "./mimeTypes"
-export type { ArkivRpcSchema, RpcEntity, RpcIncludeData, RpcQueryOptions } from "./rpcSchema"
+export type {
+  ArkivRpcSchema,
+  RpcEntity,
+  RpcIncludeData,
+  RpcOrderByAttribute,
+  RpcQueryOptions,
+} from "./rpcSchema"
 export type { TxParams } from "./txParams"

package/src/types/rpcSchema.ts

@@ -30,16 +30,16 @@ export type RpcQueryOptions = {
 }
 
 export type RpcIncludeData = {
-  key: boolean
-  attributes: boolean
-  payload: boolean
-  contentType: boolean
-  expiration: boolean
-  owner: boolean
-  createdAtBlock: boolean
-  lastModifiedAtBlock: boolean
-  transactionIndexInBlock: boolean
-  operationIndexInTransaction: boolean
+  key?: boolean
+  attributes?: boolean
+  payload?: boolean
+  contentType?: boolean
+  expiration?: boolean
+  owner?: boolean
+  createdAtBlock?: boolean
+  lastModifiedAtBlock?: boolean
+  transactionIndexInBlock?: boolean
+  operationIndexInTransaction?: boolean
 }
 
 export type ArkivRpcSchema = [

package/src/utils/compression.ts

@@ -32,7 +32,7 @@ async function getBrotli(): Promise<BrotliWasmType | null> {
 
   try {
     const brotliModule = await import("brotli-wasm")
-    brotli = brotliModule.default || brotliModule
+    brotli = (brotliModule.default ? await brotliModule.default : brotliModule) as BrotliWasmType
   } catch (error) {
     console.error("Error importing brotli-wasm", error)
     return null