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

package/src/query/selectQueryBuilder.test.ts

@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test"
+import type { ArkivClient } from "../clients/baseClient"
+import type { Entity } from "../types/entity"
+import { RpcAttributeValueType } from "../types/rpcSchema"
+import * as entitiesUtils from "../utils/entities"
+import * as engine from "./engine"
+import { eq, gte } from "./predicate"
+import { SelectQueryBuilder } from "./queryBuilder"
+import { selectionToIncludeData } from "./selection"
+
+describe("SelectQueryBuilder", () => {
+  let mockClient: ArkivClient
+  let mockProcessQuery: any
+
+  beforeEach(() => {
+    mockClient = {
+      request: jest.fn(),
+    } as unknown as ArkivClient
+
+    mockProcessQuery = jest.spyOn(engine, "processQuery")
+    jest.spyOn(entitiesUtils, "entityFromRpcResult")
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  test("select() with no argument forwards include-data for everything", async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    await new SelectQueryBuilder(mockClient).where(eq("name", "test")).fetch()
+
+    expect(mockProcessQuery).toHaveBeenCalledWith(
+      mockClient,
+      expect.objectContaining({
+        predicates: [eq("name", "test")],
+        includeData: selectionToIncludeData(),
+      }),
+    )
+  })
+
+  test('select("*") forwards include-data for everything', async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    await new SelectQueryBuilder(mockClient, "*").fetch()
+
+    expect(mockProcessQuery).toHaveBeenCalledWith(
+      mockClient,
+      expect.objectContaining({
+        includeData: selectionToIncludeData("*"),
+      }),
+    )
+  })
+
+  test("select({ owner: true, attributes: true }) forwards the resolved include-data", async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    await new SelectQueryBuilder(mockClient, { owner: true, attributes: true }).fetch()
+
+    expect(mockProcessQuery).toHaveBeenCalledWith(
+      mockClient,
+      expect.objectContaining({
+        includeData: selectionToIncludeData({ owner: true, attributes: true }),
+      }),
+    )
+  })
+
+  test("select({ owner: true }) forwards narrowed include-data", async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    await new SelectQueryBuilder(mockClient, { owner: true }).fetch()
+
+    const call = mockProcessQuery.mock.calls[0][1]
+    expect(call.includeData).toEqual(selectionToIncludeData({ owner: true }))
+    expect(call.includeData.owner).toBe(true)
+    expect(call.includeData.creator).toBe(false)
+    // key is opt-in: not selected here, so it is excluded
+    expect(call.includeData.key).toBe(false)
+  })
+
+  test("does not forward the with* boolean flags", async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    await new SelectQueryBuilder(mockClient, { attributes: true }).fetch()
+
+    const call = mockProcessQuery.mock.calls[0][1]
+    expect(call.withAttributes).toBeUndefined()
+    expect(call.withMetadata).toBeUndefined()
+    expect(call.withPayload).toBeUndefined()
+  })
+
+  test("shares the filtering/ordering/pagination chain methods", async () => {
+    mockProcessQuery.mockResolvedValue({ data: [] })
+
+    const owner = "0x1234567890123456789012345678901234567890" as const
+    await new SelectQueryBuilder(mockClient, { attributes: true })
+      .where(eq("name", "test"))
+      .where(gte("age", 18))
+      .ownedBy(owner)
+      .createdBy(owner)
+      .orderBy("name", "string", "desc")
+      .limit(10)
+      .cursor("0xABC123")
+      .validAtBlock(123n)
+      .fetch()
+
+    expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
+      predicates: [eq("name", "test"), gte("age", 18)],
+      limit: 10,
+      cursor: "0xABC123",
+      ownedBy: owner,
+      createdBy: owner,
+      orderBy: [{ name: "name", type: "string", desc: true }],
+      validAtBlock: 123n,
+      includeData: selectionToIncludeData({ attributes: true }),
+    })
+  })
+
+  test("count() ignores the selection and requests no data", async () => {
+    mockProcessQuery.mockResolvedValue({
+      data: [
+        { key: "0xabc", value: "data1" },
+        { key: "0xdef", value: "data2" },
+      ],
+    })
+
+    const count = await new SelectQueryBuilder(mockClient, "*")
+      .where(eq("status", "active"))
+      .count()
+
+    expect(count).toBe(2)
+    expect(mockProcessQuery).toHaveBeenCalledWith(mockClient, {
+      predicates: [eq("status", "active")],
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      createdBy: undefined,
+      orderBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: false,
+      withMetadata: false,
+      withPayload: false,
+    })
+  })
+
+  describe("result entities", () => {
+    test("fetch returns flat Entity instances with the selected data and methods", async () => {
+      mockProcessQuery.mockResolvedValue({
+        data: [
+          {
+            key: "0xabc",
+            owner: "0xowner",
+            value: "0x68656c6c6f", // "hello"
+            attributes: [
+              { key: "category", value: "docs", valueType: RpcAttributeValueType.String },
+              { key: "score", value: "0x2a", valueType: RpcAttributeValueType.Uint },
+            ],
+          },
+        ],
+        cursor: "",
+        blockNumber: "0x1",
+      })
+
+      const result = await new SelectQueryBuilder(mockClient, {
+        key: true,
+        owner: true,
+        attributes: true,
+        payload: true,
+      }).fetch()
+
+      expect(result.entities).toHaveLength(1)
+      const entity = result.entities[0] as unknown as Entity
+      // flat, backwards-compatible field access
+      expect(entity.key).toBe("0xabc")
+      expect(entity.owner).toBe("0xowner")
+      expect(entity.attributes).toEqual([
+        { key: "category", value: "docs" },
+        { key: "score", value: 42 },
+      ])
+      // entity methods are preserved on the result
+      expect(typeof entity.toText).toBe("function")
+      expect(entity.toText()).toBe("hello")
+    })
+
+    test("toJson decodes a JSON payload", async () => {
+      mockProcessQuery.mockResolvedValue({
+        data: [{ key: "0xabc", value: "0x7b2261223a317d" }], // {"a":1}
+        cursor: "",
+        blockNumber: "0x1",
+      })
+
+      const result = await new SelectQueryBuilder(mockClient, { payload: true }).fetch()
+      const entity = result.entities[0] as unknown as Entity
+      expect(entity.toJson()).toEqual({ a: 1 })
+    })
+
+    test("fields the RPC omits (because they were not selected) are undefined at runtime", async () => {
+      // The RPC honours includeData and returns only the key.
+      mockProcessQuery.mockResolvedValue({
+        data: [{ key: "0xabc" }],
+        cursor: "",
+        blockNumber: "0x1",
+      })
+
+      const result = await new SelectQueryBuilder(mockClient, { key: true }).fetch()
+      const entity = result.entities[0] as unknown as Entity
+      expect(entity.key).toBe("0xabc")
+      expect(entity.owner).toBeUndefined()
+      expect(entity.payload).toBeUndefined()
+      expect(entity.attributes).toEqual([])
+    })
+  })
+})

package/src/query/selection.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test"
+import { selectionToIncludeData } from "./selection"
+
+const ALL = {
+  key: true,
+  attributes: true,
+  payload: true,
+  contentType: true,
+  expiration: true,
+  owner: true,
+  creator: true,
+  createdAtBlock: true,
+  lastModifiedAtBlock: true,
+  transactionIndexInBlock: true,
+  operationIndexInTransaction: true,
+}
+
+const EMPTY = {
+  key: false,
+  attributes: false,
+  payload: false,
+  contentType: false,
+  expiration: false,
+  owner: false,
+  creator: false,
+  createdAtBlock: false,
+  lastModifiedAtBlock: false,
+  transactionIndexInBlock: false,
+  operationIndexInTransaction: false,
+}
+
+describe("selectionToIncludeData", () => {
+  test("select() with no argument selects everything", () => {
+    expect(selectionToIncludeData()).toEqual(ALL)
+  })
+
+  test('select("*") selects everything', () => {
+    expect(selectionToIncludeData("*")).toEqual(ALL)
+  })
+
+  test("empty object throws", () => {
+    // @ts-expect-error – select requires at least one field
+    expect(() => selectionToIncludeData({})).toThrow()
+  })
+
+  test("an all-false selection throws (no field is actually selected)", () => {
+    expect(() => selectionToIncludeData({ key: false })).toThrow()
+    expect(() => selectionToIncludeData({ owner: false, payload: false })).toThrow()
+  })
+
+  test("key: true selects only the key", () => {
+    expect(selectionToIncludeData({ key: true })).toEqual({ ...EMPTY, key: true })
+  })
+
+  test("key is opt-in like every other field", () => {
+    expect(selectionToIncludeData({ key: true }).key).toBe(true)
+    expect(selectionToIncludeData({ attributes: true }).key).toBe(false)
+    expect(selectionToIncludeData({ owner: true }).key).toBe(false)
+  })
+
+  test("attributes only (no key)", () => {
+    expect(selectionToIncludeData({ attributes: true })).toEqual({
+      ...EMPTY,
+      attributes: true,
+    })
+  })
+
+  test("payload only (no key)", () => {
+    expect(selectionToIncludeData({ payload: true })).toEqual({
+      ...EMPTY,
+      payload: true,
+    })
+  })
+
+  test("a single metadata field, selected flat (no key)", () => {
+    expect(selectionToIncludeData({ owner: true })).toEqual({
+      ...EMPTY,
+      owner: true,
+    })
+  })
+
+  test("expiresAtBlock maps to the RPC `expiration` field", () => {
+    expect(selectionToIncludeData({ expiresAtBlock: true })).toEqual({
+      ...EMPTY,
+      expiration: true,
+    })
+  })
+
+  test("several fields selected together", () => {
+    expect(
+      selectionToIncludeData({
+        owner: true,
+        creator: true,
+        createdAtBlock: true,
+        attributes: true,
+      }),
+    ).toEqual({
+      ...EMPTY,
+      owner: true,
+      creator: true,
+      createdAtBlock: true,
+      attributes: true,
+    })
+  })
+
+  test("key can be combined with other fields", () => {
+    expect(selectionToIncludeData({ key: true, attributes: true })).toEqual({
+      ...EMPTY,
+      key: true,
+      attributes: true,
+    })
+  })
+
+  test("a field set to false is not selected", () => {
+    expect(selectionToIncludeData({ owner: true, creator: false })).toEqual({
+      ...EMPTY,
+      owner: true,
+    })
+  })
+})

package/src/query/selection.ts

@@ -0,0 +1,116 @@
+import type { Entity } from "../types/entity"
+import type { RpcIncludeData } from "../types/rpcSchema"
+
+/** The entity fields that can be selected. These match the fields of {@link Entity} one-to-one. */
+type DataKey =
+  | "key"
+  | "contentType"
+  | "owner"
+  | "creator"
+  | "expiresAtBlock"
+  | "createdAtBlock"
+  | "lastModifiedAtBlock"
+  | "transactionIndexInBlock"
+  | "operationIndexInTransaction"
+  | "attributes"
+  | "payload"
+
+/**
+ * The parts of an entity that can be selected. Every field is opt-in (including the `key`) and maps
+ * directly to a field of the returned {@link Entity} — the selection is flat.
+ */
+export type SelectionFields = { [K in DataKey]?: boolean }
+
+/**
+ * Requires at least one property of `T` to be present.
+ * `{}` is not assignable, which is how `select({})` is rejected at compile time.
+ */
+type AtLeastOne<T, K extends keyof T = keyof T> = {
+  [P in K]: Required<Pick<T, P>> & Partial<Omit<T, P>>
+}[K]
+
+/**
+ * A non-empty entity selection — the object form accepted by `select()`. At least one field must be
+ * selected.
+ */
+export type EntitySelection = AtLeastOne<SelectionFields>
+
+/** Argument accepted by `select()` — a non-empty {@link EntitySelection}, or `"*"` for everything. */
+export type SelectArg = EntitySelection | "*"
+
+/**
+ * The result of a selection `S`: an {@link Entity} narrowed to exactly the selected fields (each
+ * non-`undefined`). The shape is flat and backwards compatible — e.g. `select({ owner: true })`
+ * yields `{ owner: Hex }` accessed as `entity.owner`. Accessing an unselected field is a compile
+ * error.
+ *
+ * The `toText()` / `toJson()` helpers operate on the payload, so they are only present when
+ * `payload` was selected — calling them otherwise would always throw.
+ */
+export type ProjectedEntity<S> = {
+  readonly [K in keyof S as S[K] extends true ? K : never]: K extends keyof Entity
+    ? NonNullable<Entity[K]>
+    : never
+} & (S extends { payload: true } ? Pick<Entity, "toText" | "toJson"> : unknown)
+
+/** A selection of every field, used to type the result of `select()` / `select("*")`. */
+type AllSelected = { [K in DataKey]: true }
+
+/** The projected entity type when everything is selected — every field, plus the methods. */
+export type FullEntity = ProjectedEntity<AllSelected>
+
+/**
+ * Converts a {@link SelectArg} into the {@link RpcIncludeData} understood by the query engine.
+ * Every field is opt-in — anything not explicitly selected defaults to `false`, including the key.
+ * `undefined` or `"*"` selects everything.
+ *
+ * @param selection - The selection to convert
+ * @returns The fully-resolved include-data object for the RPC query
+ * @throws If an empty selection object is provided
+ *
+ * @example
+ * selectionToIncludeData() // everything
+ * selectionToIncludeData("*") // everything
+ * selectionToIncludeData({ key: true }) // only the key
+ * selectionToIncludeData({ owner: true }) // only the owner
+ */
+export function selectionToIncludeData(selection?: SelectArg): RpcIncludeData {
+  if (selection === undefined || selection === "*") {
+    return {
+      key: true,
+      attributes: true,
+      payload: true,
+      contentType: true,
+      expiration: true,
+      owner: true,
+      creator: true,
+      createdAtBlock: true,
+      lastModifiedAtBlock: true,
+      transactionIndexInBlock: true,
+      operationIndexInTransaction: true,
+    }
+  }
+
+  // At least one field must be opted in. This rejects both `{}` and selections whose fields are
+  // all explicitly `false` (e.g. `select({ key: false })`), which the type system permits.
+  if (!Object.values(selection).some((selected) => selected === true)) {
+    throw new Error(
+      'select() requires at least one field to be selected. Pass select() or select("*") to select everything.',
+    )
+  }
+
+  return {
+    key: selection.key ?? false,
+    attributes: selection.attributes ?? false,
+    payload: selection.payload ?? false,
+    contentType: selection.contentType ?? false,
+    // The selection uses the entity field name `expiresAtBlock`; the RPC calls it `expiration`.
+    expiration: selection.expiresAtBlock ?? false,
+    owner: selection.owner ?? false,
+    creator: selection.creator ?? false,
+    createdAtBlock: selection.createdAtBlock ?? false,
+    lastModifiedAtBlock: selection.lastModifiedAtBlock ?? false,
+    transactionIndexInBlock: selection.transactionIndexInBlock ?? false,
+    operationIndexInTransaction: selection.operationIndexInTransaction ?? false,
+  }
+}

package/src/types/attributes.ts

@@ -1,4 +1,28 @@
+import type { Hex } from "viem"
+
+/**
+ * An entity attribute (key/value pair).
+ *
+ * Arkiv supports string, Hex and number values.
+ *
+ * Hex values are stored as the on-chain `EntityKey` type **only when they are
+ * exactly 32 bytes** (66 characters, e.g. an entity key). Hex-looking strings
+ * of any other length are stored as plain strings: they round-trip unchanged
+ * and compare lexicographically, not as hex.
+ *
+ * Numeric values **must be non-negative integers** (they are stored on-chain
+ * as unsigned 256-bit) — passing a non-integer (e.g. `1.5`) or negative number
+ * throws an {@link InvalidAttributeError} at mutation time. To store a
+ * non-integer value:
+ * - Scale it to an integer (e.g. `1.5` -> `1500`, dividing by the same factor on
+ *   read) to keep numeric ordering and range queries working.
+ * - Or pass it as a string (e.g. `"1.5"`), which sorts lexicographically and so
+ *   does not support numeric comparisons.
+ *
+ * To store a negative value, offset it into the non-negative range (subtracting
+ * the offset on read) or store it as a string.
+ */
 export type Attribute = {
   key: string
-  value: string | number
+  value: number | string | Hex
 }

package/src/types/entity.ts

@@ -1,10 +1,20 @@
 import { bytesToString, type Hex } from "viem"
+
+export enum EntityOperationType {
+  Create = 1,
+  Update = 2,
+  Extend = 3,
+  Transfer = 4,
+  Delete = 5,
+  Expire = 6,
+}
+
 import type { MimeType } from "../types"
 import type { Attribute } from "./attributes"
 
 export class Entity {
   key: Hex
-  contentType: MimeType | undefined
+  contentType: MimeType | `${string}/${string}` | undefined
   owner: Hex | undefined
   creator: Hex | undefined
   expiresAtBlock: bigint | undefined
@@ -17,7 +27,7 @@ export class Entity {
 
   constructor(
     key: Hex,
-    contentType: MimeType | undefined = undefined,
+    contentType: MimeType | `${string}/${string}` | undefined = undefined,
     owner: Hex | undefined = undefined,
     creator: Hex | undefined = undefined,
     expiresAtBlock: bigint | undefined = undefined,

package/src/types/events.ts

@@ -1,40 +1,38 @@
-import type { Hex } from "viem"
+import type { Address, Hex } from "viem"
 
 export type OnEntityCreatedEvent = {
   entityKey: Hex
-  owner: Hex
-  expirationBlock: number
-  cost: bigint
+  owner: Address
+  expiresAt: number
+  entityHash: Hex
 }
 
 export type OnEntityUpdatedEvent = {
   entityKey: Hex
-  owner: Hex
-  oldExpirationBlock: number
-  newExpirationBlock: number
-  cost: bigint
+  owner: Address
+  expiresAt: number
+  entityHash: Hex
 }
 
 export type OnEntityDeletedEvent = {
   entityKey: Hex
-  owner: Hex
+  owner: Address
 }
 
 export type OnEntityExpiredEvent = {
   entityKey: Hex
-  owner: Hex
+  owner: Address
 }
 
 export type OnEntityExpiresInExtendedEvent = {
   entityKey: Hex
-  owner: Hex
-  oldExpirationBlock: number
-  newExpirationBlock: number
-  cost: bigint
+  owner: Address
+  expiresAt: number
+  entityHash: Hex
 }
 
 export type OnEntityOwnerChangedEvent = {
   entityKey: Hex
-  oldOwner: Hex
-  newOwner: Hex
+  owner: Address
+  entityHash: Hex
 }

package/src/types/index.ts

@@ -19,6 +19,7 @@ export type {
 export type { UpdateEntityParameters, UpdateEntityReturnType } from "../actions/wallet/updateEntity"
 export type { Attribute } from "./attributes"
 export type { Entity } from "./entity"
+export { EntityOperationType } from "./entity"
 export type {
   OnEntityCreatedEvent,
   OnEntityDeletedEvent,

package/src/types/rpcSchema.ts

@@ -12,8 +12,13 @@ export type RpcEntity = {
   operationIndexInTransaction: Hex
   owner: Hex
   creator: Hex
-  stringAttributes?: [{ key: string; value: string }]
-  numericAttributes?: [{ key: string; value: Hex }]
+  attributes?: { key: string; value: string; valueType: RpcAttributeValueType }[]
+}
+
+export enum RpcAttributeValueType {
+  Uint = 1,
+  String = 2,
+  EntityKey = 3,
 }
 
 export type RpcOrderByAttribute = {