@arkiv-network/sdk 0.6.8 → 0.7.0-dev.1

package/src/clients/decorators/arkivPublic.ts

@@ -4,7 +4,8 @@ import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
 import { type QueryOptions, type QueryReturnType, query } from "../../actions/public/query"
 import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
-import { QueryBuilder } from "../../query/queryBuilder"
+import { QueryBuilder, SelectQueryBuilder } from "../../query/queryBuilder"
+import type { EntitySelection, FullEntity, ProjectedEntity, SelectArg } from "../../query/selection"
 import type { Entity } from "../../types/entity"
 import type {
   OnEntityCreatedEvent,
@@ -55,12 +56,76 @@ export type PublicArkivActions<
    */
   getEntity: (key: Hex) => Promise<Entity>
 
+  /**
+   * Returns a SelectQueryBuilder for building and executing queries — the recommended way to
+   * read entities. You declare up front which parts of an entity you want returned, so results
+   * always contain exactly the data you asked for.
+   *
+   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   *
+   * @param selection - What to include in the results. Omit it (or pass `"*"`) to select everything,
+   *   or pass an object to select specific parts (at least one field is required). Every part is
+   *   opt-in, including the `key`. The selection is flat — each field maps to an entity field.
+   *   {@link SelectArg}
+   * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { braga } from 'arkiv/chains'
+   * import { eq } from 'arkiv/query'
+   *
+   * const client = createPublicClient({
+   *   chain: braga,
+   *   transport: http(),
+   * })
+   * // select everything
+   * await client.select().where(eq("category", "docs")).fetch()
+   * await client.select("*").where(eq("category", "docs")).fetch()
+   * // only the key
+   * await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * // select specific fields — result typed { owner: Hex; attributes: Attribute[] }
+   * await client.select({ owner: true, attributes: true }).fetch()
+   * // a single field — result typed { owner: Hex }
+   * await client.select({ owner: true }).fetch()
+   */
+  select: {
+    /** Select every field. Pass nothing or `"*"`; the returned entities contain all fields. */
+    (selection?: "*"): SelectQueryBuilder<FullEntity>
+    /**
+     * Pick the entity fields to return. Set the ones you want to `true` (at least one is required);
+     * the result is typed to exactly those fields, so reading anything else is a compile error.
+     *
+     * Available fields: `key`, `owner`, `creator`, `contentType`, `payload`, `attributes`,
+     * `expiresAtBlock`, `createdAtBlock`, `lastModifiedAtBlock`, `transactionIndexInBlock`,
+     * `operationIndexInTransaction`.
+     *
+     * Pass the selection inline so its fields stay literal `true`. A selection stored in a `let`/
+     * `const` variable widens to `boolean` and the result type can no longer be narrowed — annotate
+     * it `as const` (e.g. `const sel = { owner: true } as const`) in that case.
+     *
+     * @example
+     * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
+     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     */
+    <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
+    /**
+     * Dynamic selection: accepts a value typed {@link SelectArg} (e.g. built at runtime). The
+     * result cannot be narrowed in this case, so the entities are typed as the full entity.
+     */
+    (selection: SelectArg): SelectQueryBuilder<FullEntity>
+  }
+
   /**
    * Returns a QueryBuilder instance for building and executing queries.
    * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
    *
+   * @deprecated Use {@link select} instead. `buildQuery()` returns only the entity `key` unless
+   * you remember to opt in to data with `withAttributes()`/`withMetadata()`/`withPayload()`, which
+   * is an easy mistake. `select()` makes the selection explicit. This method remains for backwards
+   * compatibility and will be removed in a future release.
+   *
    * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
    *
    * @example
@@ -100,7 +165,6 @@ export type PublicArkivActions<
    *     payload: true,
    *     metadata: true,
    *   },
-   *   orderBy: [{ name: "key", type: "string", desc: "asc" }],
    *   resultsPerPage: 10,
    *   cursor: undefined,
    *   atBlock: undefined,
@@ -200,6 +264,7 @@ export function publicArkivActions<
     getEntity: (key: Hex) => getEntity(client, key),
     query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
     buildQuery: () => new QueryBuilder(client),
+    select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),
     subscribeEntityEvents: (

package/src/clients/decorators/arkivWallet.ts

@@ -35,7 +35,10 @@ export type WalletArkivActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
-> = Pick<PublicActions<transport, chain, account>, "waitForTransactionReceipt" | "call"> &
+> = Pick<
+  PublicActions<transport, chain, account>,
+  "waitForTransactionReceipt" | "call" | "simulateContract" | "readContract" | "getBlockNumber"
+> &
   Pick<
     WalletActions<chain, account>,
     | "addChain"
@@ -45,6 +48,7 @@ export type WalletArkivActions<
     | "sendRawTransaction"
     | "signMessage"
     | "signTransaction"
+    | "writeContract"
   > & {
     /**
      * Creates a new entity.
@@ -56,6 +60,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The created entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createPublicClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -91,6 +100,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The updated entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -146,6 +160,9 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The updated entity with transaction hash
      *
+     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
+     * that is a multiple of the block time (2 seconds).
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'
@@ -194,6 +211,11 @@ export type WalletArkivActions<
      * @param txParams - Optional transaction parameters
      * @returns The mutation result with transaction hash
      *
+     * @throws {InvalidExpirationError} If any create/update/extension `expiresIn`
+     * is not a positive integer that is a multiple of the block time (2 seconds).
+     * @throws {InvalidAttributeError} If a numeric attribute value is not an
+     * integer.
+     *
      * @example
      * import { createWalletClient, http } from 'arkiv'
      * import { braga } from 'arkiv/chains'

package/src/consts.ts

@@ -1,2 +1,3 @@
-export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+//export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+export const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044" as `0x${string}`
 export const BLOCK_TIME = 2 // 2 seconds

package/src/errors.ts

@@ -1,9 +1,46 @@
+import { BLOCK_TIME } from "./consts"
+
 export class EntityMutationError extends Error {
   constructor(message: string) {
     super(message)
     this.name = "EntityMutationError"
   }
 }
+export class InvalidExpirationError extends Error {
+  constructor(expiresIn: unknown) {
+    super(
+      `Invalid expiresIn: ${String(expiresIn)}. expiresIn must be a positive integer and a multiple of the Arkiv block time (${BLOCK_TIME} seconds), because expiration is measured in whole blocks (1 block = ${BLOCK_TIME} seconds).`,
+    )
+    this.name = "InvalidExpirationError"
+  }
+}
+export class InvalidAttributeError extends Error {
+  constructor(key: string, value: number) {
+    const remedy = Number.isInteger(value)
+      ? `Offset it into the non-negative range (e.g. store ${String(value)} + OFFSET, subtracting OFFSET on read) to keep numeric ordering/range queries; otherwise store it as a string (e.g. "${String(value)}")`
+      : `To keep numeric ordering/range queries, scale it to an integer (e.g. Math.round(${String(value)} * 1000), dividing by 1000 on read); otherwise store it as a string (e.g. "${String(value)}")`
+    super(
+      `Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be non-negative integers (stored on-chain as unsigned 256-bit). ${remedy}.`,
+    )
+    this.name = "InvalidAttributeError"
+  }
+}
+
+export class InvalidAttributeKeyError extends Error {
+  constructor(key: string, reason: string) {
+    super(
+      `Invalid attribute key "${key}": ${reason}. Keys must be 1-32 bytes, start with a lowercase letter (a-z), and contain only a-z, 0-9, ".", "-" or "_".`,
+    )
+    this.name = "InvalidAttributeKeyError"
+  }
+}
+
+export class DuplicateAttributeError extends Error {
+  constructor(key: string) {
+    super(`Duplicate attribute key "${key}". Attribute keys must be unique per entity.`)
+    this.name = "DuplicateAttributeError"
+  }
+}
 
 export class NoMoreResultsError extends Error {
   constructor() {
@@ -25,3 +62,12 @@ export class NoEntityFoundError extends Error {
     this.name = "NoEntityFoundError"
   }
 }
+
+export class InvalidContentTypeError extends Error {
+  constructor(contentType: string) {
+    super(
+      `Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`,
+    )
+    this.name = "InvalidContentTypeError"
+  }
+}

package/src/index.ts

@@ -2,9 +2,6 @@
  * @module main
  */
 
-// Re-export all viem stuff
-export * from "viem"
-
 // export main arkiv stuff
 export type { ArkivClient } from "./clients/baseClient"
 export type { PublicArkivClient } from "./clients/createPublicClient"

package/src/query/engine.test.ts

@@ -47,6 +47,51 @@ describe("processQuery tests", () => {
     })
   })
 
+  it("should serialize 32-byte hex values as unquoted literals and other hex as strings", async () => {
+    const hexValue = "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
+    const predicates = [
+      { type: "eq" as const, key: "hexattr", value: hexValue },
+      { type: "eq" as const, key: "strattr", value: "value" },
+      // hex-looking but not 32 bytes — stored as strings, so compared quoted
+      { type: "eq" as const, key: "shorthex", value: "0xab" },
+      { type: "eq" as const, key: "addrhex", value: "0x6186b0dba9652262942d5a465d49686eb560834c" },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      createdBy: undefined,
+      orderBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+      withPayload: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `hexattr = ${hexValue} && strattr = "value" && shorthex = "0xab" && addrhex = "0x6186b0dba9652262942d5a465d49686eb560834c"`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+            creator: false,
+            createdAtBlock: false,
+            lastModifiedAtBlock: false,
+            transactionIndexInBlock: false,
+            operationIndexInTransaction: false,
+          },
+        },
+      ],
+    })
+  })
+
   it("should process all simple predicates - flat", async () => {
     const predicates = [
       { type: "eq" as const, key: "key", value: "value" },

package/src/query/engine.ts

@@ -3,6 +3,7 @@ import { hexToNumber, numberToHex } from "viem"
 import type { ArkivClient } from "../clients/baseClient"
 import type { RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions } from "../types/rpcSchema"
 import { getLogger } from "../utils/logger"
+import { isEntityKey } from "../utils/validation"
 import type { Predicate } from "./predicate"
 
 const logger = getLogger("query:engine")
@@ -10,7 +11,11 @@ const logger = getLogger("query:engine")
 function processPredicates(predicates: Predicate[]): string {
   const processValue = (value: string | number) => {
     if (typeof value === "string") {
-      return `"${value}"`
+      // 32-byte hex strings are stored as the EntityKey attribute type (see
+      // encodeAttribute), which the query language only matches against unquoted
+      // hex literals. All other strings — including shorter hex — are stored and
+      // compared as quoted strings.
+      return isEntityKey(value) ? value : `"${value}"`
     }
     return value
   }
@@ -55,6 +60,11 @@ export async function processQuery(
     withAttributes?: boolean | undefined
     withMetadata?: boolean | undefined
     withPayload?: boolean | undefined
+    /**
+     * Fully-resolved include-data for fine-grained selection. When provided it takes
+     * precedence over the `withAttributes`/`withMetadata`/`withPayload` booleans.
+     */
+    includeData?: RpcIncludeData | undefined
   },
 ) {
   const {
@@ -68,6 +78,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   } = queryParams
 
   logger("Processing query with params %o", {
@@ -81,6 +92,7 @@ export async function processQuery(
     withAttributes,
     withMetadata,
     withPayload,
+    includeData,
   })
 
   let query = processPredicates(predicates)
@@ -98,19 +110,21 @@ export async function processQuery(
   }
 
   const queryOptions: RpcQueryOptions = {
-    includeData: {
-      key: true,
-      attributes: withAttributes ?? false,
-      payload: withPayload ?? false,
-      contentType: withMetadata ?? false,
-      expiration: withMetadata ?? false,
-      owner: withMetadata ?? false,
-      creator: withMetadata ?? false,
-      createdAtBlock: withMetadata ?? false,
-      lastModifiedAtBlock: withMetadata ?? false,
-      transactionIndexInBlock: withMetadata ?? false,
-      operationIndexInTransaction: withMetadata ?? false,
-    } as RpcIncludeData,
+    includeData:
+      includeData ??
+      ({
+        key: true,
+        attributes: withAttributes ?? false,
+        payload: withPayload ?? false,
+        contentType: withMetadata ?? false,
+        expiration: withMetadata ?? false,
+        owner: withMetadata ?? false,
+        creator: withMetadata ?? false,
+        createdAtBlock: withMetadata ?? false,
+        lastModifiedAtBlock: withMetadata ?? false,
+        transactionIndexInBlock: withMetadata ?? false,
+        operationIndexInTransaction: withMetadata ?? false,
+      } as RpcIncludeData),
   }
 
   if (validAtBlock !== undefined) {

package/src/query/index.ts

@@ -1,3 +1,4 @@
 export * from "./predicate"
 export * from "./queryBuilder"
 export * from "./queryResult"
+export * from "./selection"

package/src/query/predicate.test.ts

@@ -244,6 +244,27 @@ describe("Predicate Factory Functions", () => {
       })
     })
 
+    test("creates or predicate from varargs", () => {
+      const result = or(eq("type", "admin"), eq("type", "moderator"))
+
+      expect(result).toEqual({
+        type: "or",
+        predicates: [
+          { type: "eq", key: "type", value: "admin" },
+          { type: "eq", key: "type", value: "moderator" },
+        ],
+      })
+    })
+
+    test("creates or predicate with no arguments", () => {
+      const result = or()
+
+      expect(result).toEqual({
+        type: "or",
+        predicates: [],
+      })
+    })
+
     test("creates or predicate with nested and", () => {
       const nestedAnd = and([eq("verified", 1), gte("age", 18)])
       const predicates = [eq("status", "premium"), nestedAnd]
@@ -314,6 +335,28 @@ describe("Predicate Factory Functions", () => {
       })
     })
 
+    test("creates and predicate from varargs", () => {
+      const result = and(eq("status", "active"), gte("age", 18), not("deleted"))
+
+      expect(result).toEqual({
+        type: "and",
+        predicates: [
+          { type: "eq", key: "status", value: "active" },
+          { type: "gte", key: "age", value: 18 },
+          { type: "not", key: "deleted", value: "" },
+        ],
+      })
+    })
+
+    test("creates and predicate with no arguments", () => {
+      const result = and()
+
+      expect(result).toEqual({
+        type: "and",
+        predicates: [],
+      })
+    })
+
     test("creates and predicate with nested or", () => {
       const nestedOr = or([eq("type", "admin"), eq("type", "moderator")])
       const predicates = [eq("active", 1), nestedOr]

package/src/query/predicate.ts

@@ -14,32 +14,36 @@ export type Predicate =
 
 /**
  * Creates an OR predicate
- * @param predicates - The predicates to combine
+ * @param predicates - The predicates to combine, either as a single array or as separate arguments
  * @returns The OR predicate
  *
  * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = or(predicates)
+ * const result = or(eq("name", "John"), eq("age", 30))
+ * // or equivalently: or([eq("name", "John"), eq("age", 30)])
  * // result = { type: "or", predicates: [eq("name", "John"), eq("age", 30)] }
  *
  */
-export function or(predicates: Predicate[]): Predicate {
-  return { type: "or", predicates }
+export function or(predicates: Predicate[]): Predicate
+export function or(...predicates: Predicate[]): Predicate
+export function or(...predicates: (Predicate | Predicate[])[]): Predicate {
+  return { type: "or", predicates: predicates.flat() }
 }
 
 /**
  * Creates an AND predicate
- * @param predicates - The predicates to combine
+ * @param predicates - The predicates to combine, either as a single array or as separate arguments
  * @returns The AND predicate
  *
  * @example
- * const predicates = [eq("name", "John"), eq("age", 30)]
- * const result = and(predicates)
+ * const result = and(eq("name", "John"), eq("age", 30))
+ * // or equivalently: and([eq("name", "John"), eq("age", 30)])
  * // result = { type: "and", predicates: [eq("name", "John"), eq("age", 30)] }
  *
  */
-export function and(predicates: Predicate[]): Predicate {
-  return { type: "and", predicates }
+export function and(predicates: Predicate[]): Predicate
+export function and(...predicates: Predicate[]): Predicate
+export function and(...predicates: (Predicate | Predicate[])[]): Predicate {
+  return { type: "and", predicates: predicates.flat() }
 }
 
 /**

package/src/query/queryBuilder.test.ts

@@ -78,6 +78,28 @@ describe("QueryBuilder", () => {
       })
     })
 
+    test("adds multiple predicates as varargs", async () => {
+      mockProcessQuery.mockResolvedValue({
+        data: [],
+      })
+
+      const builder = new QueryBuilder(mockClient)
+      await builder.where(eq("name", "test"), gt("age", 18), neq("status", "inactive")).fetch()
+
+      expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
+        predicates: [eq("name", "test"), gt("age", 18), neq("status", "inactive")],
+        limit: undefined,
+        offset: undefined,
+        ownedBy: undefined,
+        createdBy: undefined,
+        orderBy: undefined,
+        validBeforeBlock: undefined,
+        withAttributes: undefined,
+        withMetadata: undefined,
+        withPayload: undefined,
+      })
+    })
+
     test("chains multiple where() calls", async () => {
       mockProcessQuery.mockResolvedValue({
         data: [],