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

package/src/types/entity.test.ts

@@ -1,179 +1,68 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, it } from "bun:test"
+import { i32, str } from "../attr"
 import { Entity } from "./entity"
 
-const KEY = "0xabc" as const
+const KEY = `0x${"ab".repeat(32)}` as const
 
-describe("Entity.toText()", () => {
-  test("throws when payload is undefined", () => {
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      [],
-    )
-    expect(() => entity.toText()).toThrow(
-      "Entity has no payload – it was probably queried without withPayload(true) via QueryBuilder",
-    )
-  })
+function withPayload(text: string): Entity {
+  return new Entity({ key: KEY, payload: new TextEncoder().encode(text) })
+}
 
-  test("returns string when payload is valid bytes", () => {
-    const payload = new TextEncoder().encode("hello world")
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      payload,
-      [],
-    )
-    expect(entity.toText()).toBe("hello world")
+describe("Entity", () => {
+  it("carries only the fields it was built with", () => {
+    const entity = new Entity({
+      key: KEY,
+      expiresAt: 1_297_000n,
+      attributes: { level: i32(10), name: str("Bob") },
+    })
+    expect(entity.key).toBe(KEY)
+    expect(entity.expiresAt).toBe(1_297_000n)
+    expect(entity.attributes?.level.value).toBe(10)
+    // Not selected is not the same as empty: nothing here stands in for data that was not asked for.
+    expect(entity.owner).toBeUndefined()
+    expect(entity.payload).toBeUndefined()
+    expect(entity.attributeSchema).toBeUndefined()
   })
 
-  test("returns empty string when payload is empty", () => {
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      new Uint8Array([]),
-      [],
-    )
-    expect(entity.toText()).toBe("")
+  it("defaults to carrying nothing at all", () => {
+    expect(new Entity().key).toBeUndefined()
   })
 })
 
-describe("Entity.toJson()", () => {
-  test("throws when payload is undefined", () => {
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      [],
-    )
-    expect(() => entity.toJson()).toThrow(
-      "Entity has no payload – it was probably queried without withPayload(true) via QueryBuilder",
-    )
+describe("toText", () => {
+  it("decodes the payload as UTF-8", () => {
+    expect(withPayload("hello world").toText()).toBe("hello world")
+    expect(withPayload("").toText()).toBe("")
+  })
+
+  it("says how to ask for the payload when it was not selected", () => {
+    expect(() => new Entity({ key: KEY }).toText()).toThrow(/select\(\{ payload: true \}\)/)
   })
+})
 
-  test("throws when payload is empty", () => {
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      new Uint8Array([]),
-      [],
-    )
-    expect(() => entity.toJson()).toThrow("Entity has empty payload, cannot parse as JSON")
+describe("toJson", () => {
+  it("parses objects and arrays", () => {
+    expect(withPayload('{"a":1,"b":[2,3]}').toJson()).toEqual({ a: 1, b: [2, 3] })
+    expect(withPayload("[1,2,3]").toJson()).toEqual([1, 2, 3])
   })
 
-  test("throws when payload is invalid JSON", () => {
-    const payload = new TextEncoder().encode("not valid json {")
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      payload,
-      [],
-    )
-    expect(() => entity.toJson()).toThrow("Failed to parse entity payload as JSON")
+  it("throws on an empty payload rather than returning undefined", () => {
+    expect(() => withPayload("").toJson()).toThrow(/empty payload/)
   })
 
-  test("preserves original error as cause when JSON parsing fails", () => {
-    const payload = new TextEncoder().encode("not valid json {")
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      payload,
-      [],
-    )
+  it("keeps the parse failure as the cause", () => {
     let caught: unknown
     try {
-      entity.toJson()
-    } catch (e) {
-      caught = e
+      withPayload("not json").toJson()
+    } catch (error) {
+      caught = error
     }
     expect(caught).toBeInstanceOf(Error)
+    expect((caught as Error).message).toMatch(/Failed to parse entity payload as JSON/)
     expect((caught as Error).cause).toBeInstanceOf(Error)
   })
 
-  test("returns parsed object for valid JSON payload", () => {
-    const data = { foo: "bar", count: 42 }
-    const payload = new TextEncoder().encode(JSON.stringify(data))
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      payload,
-      [],
-    )
-    expect(entity.toJson()).toEqual(data)
-  })
-
-  test("returns parsed array for valid JSON array payload", () => {
-    const data = [1, 2, 3]
-    const payload = new TextEncoder().encode(JSON.stringify(data))
-    const entity = new Entity(
-      KEY,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      undefined,
-      payload,
-      [],
-    )
-    expect(entity.toJson()).toEqual(data)
+  it("reports the missing payload, not a JSON error", () => {
+    expect(() => new Entity({ key: KEY }).toJson()).toThrow(/did not select it/)
   })
 })

package/src/types/entity.ts

@@ -1,56 +1,74 @@
 import { bytesToString, type Hex } from "viem"
-import type { MimeType } from "../types"
-import type { Attribute } from "./attributes"
+import type { AttributeSchema, Attributes } from "../attr"
+import type { ResolvedCreationFlags } from "../entity/flags"
 
-export class Entity {
-  key: Hex
-  contentType: MimeType | undefined
+/**
+ * The fields an {@link Entity} can carry. Every one is optional: a query returns exactly the parts
+ * it selected, and `undefined` means "not asked for" rather than "empty".
+ */
+export type EntityFields = {
+  key?: Hex | undefined
+  owner?: Hex | undefined
+  creator?: Hex | undefined
+  /** Block the entity was created at. */
+  createdAt?: bigint | undefined
+  /** Block the entity was last patched at. */
+  updatedAt?: bigint | undefined
+  /** Block the entity expires at. */
+  expiresAt?: bigint | undefined
+  /** The immutable properties the entity was created with. */
+  creationFlags?: ResolvedCreationFlags | undefined
+  contentType?: string | undefined
+  payload?: Uint8Array | undefined
+  /** Attribute names and types, with no values. */
+  attributeSchema?: AttributeSchema | undefined
+  /** Attribute names, types and values. */
+  attributes?: Attributes | undefined
+}
+
+/**
+ * An entity as it comes back from a query.
+ *
+ * Which fields are populated is decided by the query's selection — `select({ key: true })` gives
+ * back an entity carrying only its key. The static type of a `select()` result is narrowed to
+ * exactly the selected fields, so in typed code the `undefined`s here are not reachable.
+ */
+export class Entity implements EntityFields {
+  key: Hex | undefined
   owner: Hex | undefined
   creator: Hex | undefined
-  expiresAtBlock: bigint | undefined
-  createdAtBlock: bigint | undefined
-  lastModifiedAtBlock: bigint | undefined
-  transactionIndexInBlock: bigint | undefined
-  operationIndexInTransaction: bigint | undefined
+  createdAt: bigint | undefined
+  updatedAt: bigint | undefined
+  expiresAt: bigint | undefined
+  creationFlags: ResolvedCreationFlags | undefined
+  contentType: string | undefined
   payload: Uint8Array | undefined
-  attributes: Attribute[]
+  attributeSchema: AttributeSchema | undefined
+  attributes: Attributes | undefined
 
-  constructor(
-    key: Hex,
-    contentType: MimeType | undefined = undefined,
-    owner: Hex | undefined = undefined,
-    creator: Hex | undefined = undefined,
-    expiresAtBlock: bigint | undefined = undefined,
-    createdAtBlock: bigint | undefined = undefined,
-    lastModifiedAtBlock: bigint | undefined = undefined,
-    transactionIndexInBlock: bigint | undefined = undefined,
-    operationIndexInTransaction: bigint | undefined = undefined,
-    payload: Uint8Array | undefined = undefined,
-    attributes: Attribute[],
-  ) {
-    this.key = key
-    this.owner = owner
-    this.creator = creator
-    this.expiresAtBlock = expiresAtBlock
-    this.createdAtBlock = createdAtBlock
-    this.lastModifiedAtBlock = lastModifiedAtBlock
-    this.transactionIndexInBlock = transactionIndexInBlock
-    this.operationIndexInTransaction = operationIndexInTransaction
-    this.payload = payload
-    this.attributes = attributes
-    this.contentType = contentType
+  constructor(fields: EntityFields = {}) {
+    this.key = fields.key
+    this.owner = fields.owner
+    this.creator = fields.creator
+    this.createdAt = fields.createdAt
+    this.updatedAt = fields.updatedAt
+    this.expiresAt = fields.expiresAt
+    this.creationFlags = fields.creationFlags
+    this.contentType = fields.contentType
+    this.payload = fields.payload
+    this.attributeSchema = fields.attributeSchema
+    this.attributes = fields.attributes
   }
 
   /**
-   * Converts the entity payload from bytes to a string and returns it.
-   * Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-   * Throws an error if the conversion from bytes to string fails.
-   * @returns The entity payload as a string.
+   * The payload decoded as UTF-8 text.
+   *
+   * @throws If the payload was not selected, or is not valid UTF-8.
    */
   toText(): string {
     if (this.payload === undefined) {
       throw new Error(
-        "Entity has no payload – it was probably queried without withPayload(true) via QueryBuilder",
+        "Entity has no payload — the query did not select it. Use select({ payload: true }).",
       )
     }
     try {
@@ -64,11 +82,11 @@ export class Entity {
   }
 
   /**
-   * Parses the entity payload as JSON and returns the resulting object.
-   * Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-   * Throws an error if the payload is empty or cannot be parsed as JSON.
-   * @returns The parsed JSON object from the entity payload.
+   * The payload parsed as JSON.
+   *
+   * @throws If the payload was not selected, is empty, or is not valid JSON.
    */
+  // biome-ignore lint/suspicious/noExplicitAny: JSON.parse returns whatever the payload holds.
   toJson(): any {
     const text = this.toText()
     if (!text) {

package/src/types/events.ts

@@ -1,40 +1,81 @@
-import type { Hex } from "viem"
+import type { Address, Hex } from "viem"
+import type { ResolvedCreationFlags } from "../entity/flags"
 
-export type OnEntityCreatedEvent = {
-  entityKey: Hex
-  owner: Hex
-  expirationBlock: number
-  cost: bigint
+/**
+ * Where an event sits in the chain — carried by every on-chain entity event.
+ *
+ * Operations apply in batch order and emit one event each, so `blockNumber` and `logIndex` together
+ * are the order the operations were applied in. A replica that replays them in that order sees
+ * exactly what the engine did.
+ */
+export type EntityEventContext = {
+  /** The block the operation was applied in. */
+  blockNumber: bigint
+  /** The transaction the operation was part of. */
+  transactionHash: Hex
+  /** The event's position within its block. */
+  logIndex: number
 }
 
-export type OnEntityUpdatedEvent = {
+/** An entity was created. */
+export type EntityCreatedEvent = EntityEventContext & {
+  type: "EntityCreated"
   entityKey: Hex
-  owner: Hex
-  oldExpirationBlock: number
-  newExpirationBlock: number
-  cost: bigint
+  owner: Address
+  /** The block the entity is set to expire at. */
+  expiresAt: bigint
+  /**
+   * The immutable properties the entity was created with, decoded from its `creationFlags` byte.
+   */
+  creationFlags: ResolvedCreationFlags
 }
 
-export type OnEntityDeletedEvent = {
+/**
+ * An entity's attributes or payload changed.
+ *
+ * The event says *that* it changed, not what to — read the entity to see the new state.
+ */
+export type EntityPatchedEvent = EntityEventContext & {
+  type: "EntityPatched"
   entityKey: Hex
-  owner: Hex
+  owner: Address
 }
 
-export type OnEntityExpiredEvent = {
+/** An entity's expiry moved further out. */
+export type ExpiryExtendedEvent = EntityEventContext & {
+  type: "ExpiryExtended"
   entityKey: Hex
-  owner: Hex
+  /**
+   * The entity's owner — **not** whoever extended it. An entity created with
+   * `permissionlessExtension` can be extended by anyone, and the event does not say by whom; read
+   * the transaction's sender if you need that.
+   */
+  owner: Address
+  /** The block the entity is now set to expire at. */
+  expiresAt: bigint
 }
 
-export type OnEntityExpiresInExtendedEvent = {
+/** An entity changed hands. */
+export type OwnershipTransferredEvent = EntityEventContext & {
+  type: "OwnershipTransferred"
   entityKey: Hex
-  owner: Hex
-  oldExpirationBlock: number
-  newExpirationBlock: number
-  cost: bigint
+  previousOwner: Address
+  newOwner: Address
 }
 
-export type OnEntityOwnerChangedEvent = {
+/** An entity was deleted by its owner, before its expiry. */
+export type EntityDeletedEvent = EntityEventContext & {
+  type: "EntityDeleted"
   entityKey: Hex
-  oldOwner: Hex
-  newOwner: Hex
+  owner: Address
 }
+
+/**
+ * Every event the engine emits, discriminated by `type`.
+ */
+export type EntityEvent =
+  | EntityCreatedEvent
+  | EntityPatchedEvent
+  | ExpiryExtendedEvent
+  | OwnershipTransferredEvent
+  | EntityDeletedEvent

package/src/types/index.ts

@@ -1,10 +1,11 @@
 export type { GetBlockTimingReturnType } from "../actions/public/getBlockTiming"
 export type {
-  QueryOptions,
-  QueryOptionsIncludeData,
-  QueryOptionsOrderBy,
-  QueryReturnType,
-} from "../actions/public/query"
+  PredictEntityKeysParameters,
+  PredictEntityKeysReturnType,
+  PredictedEntityKey,
+} from "../actions/public/predictEntityKeys"
+export type { QueryOptions, QueryReturnType } from "../actions/public/query"
+export type { WatchEntityEventsParameters } from "../actions/public/watchEntityEvents"
 export type {
   ChangeOwnershipParameters,
   ChangeOwnershipReturnType,
@@ -16,23 +17,26 @@ export type {
   MutateEntitiesParameters,
   MutateEntitiesReturnType,
 } from "../actions/wallet/mutateEntities"
-export type { UpdateEntityParameters, UpdateEntityReturnType } from "../actions/wallet/updateEntity"
-export type { Attribute } from "./attributes"
-export type { Entity } from "./entity"
+export type { PatchEntityParameters, PatchEntityReturnType } from "../actions/wallet/patchEntity"
+export type { EntityFields } from "./entity"
+export { Entity } from "./entity"
 export type {
-  OnEntityCreatedEvent,
-  OnEntityDeletedEvent,
-  OnEntityExpiredEvent,
-  OnEntityExpiresInExtendedEvent,
-  OnEntityOwnerChangedEvent,
-  OnEntityUpdatedEvent,
+  EntityCreatedEvent,
+  EntityDeletedEvent,
+  EntityEvent,
+  EntityEventContext,
+  EntityPatchedEvent,
+  ExpiryExtendedEvent,
+  OwnershipTransferredEvent,
 } from "./events"
 export type { MimeType } from "./mimeTypes"
 export type {
   ArkivRpcSchema,
+  RpcAttribute,
+  RpcAttributeSchemaEntry,
+  RpcCreationFlags,
   RpcEntity,
-  RpcIncludeData,
-  RpcOrderByAttribute,
   RpcQueryOptions,
+  RpcSelect,
 } from "./rpcSchema"
 export type { TxParams } from "./txParams"

package/src/types/rpcSchema.ts

@@ -1,47 +1,83 @@
 import type { Hex, PublicRpcSchema } from "viem"
-import type { MimeType } from "./mimeTypes"
 
-export type RpcEntity = {
-  key: Hex
-  contentType: MimeType
-  value: string
-  expiresAt: Hex
-  createdAtBlock: Hex
-  lastModifiedAtBlock: Hex
-  transactionIndexInBlock: Hex
-  operationIndexInTransaction: Hex
-  owner: Hex
-  creator: Hex
-  stringAttributes?: [{ key: string; value: string }]
-  numericAttributes?: [{ key: string; value: Hex }]
+/**
+ * An attribute as the node renders it: the name, the type **tag** (not the wire typeId), and the
+ * value in the JSON encoding that type prescribes — a JSON number for `i32`, a `0x` QUANTITY for
+ * `u64` and `u256`, a decimal string for `dec`, `0x` DATA for the byte-shaped types, and a string for
+ * `str`.
+ *
+ * The encoding follows the *declared type*, never the magnitude, so a decoder dispatches on `type`
+ * and never has to guess from the shape of the value.
+ */
+export type RpcAttribute = {
+  name: string
+  type: string
+  value: unknown
 }
 
-export type RpcOrderByAttribute = {
+/** An entry of the `attributeSchema` projection — a name and its type, with no value. */
+export type RpcAttributeSchemaEntry = {
   name: string
-  type: "string" | "numeric"
-  desc: boolean
+  type: string
 }
 
-export type RpcQueryOptions = {
-  atBlock?: Hex
-  includeData?: RpcIncludeData
-  orderBy?: RpcOrderByAttribute[]
-  resultsPerPage?: Hex
-  cursor?: string
+/**
+ * The `creationFlags` projection.
+ */
+export type RpcCreationFlags = {
+  readonly?: boolean
+  permissionlessExtension?: boolean
+  raw: number
 }
 
-export type RpcIncludeData = {
+/**
+ * An entity as `arkiv_query` returns it. Every field is present only if it was selected, so all of
+ * them are optional here — {@link RpcSelect} is what decides which arrive.
+ */
+export type RpcEntity = {
+  key?: Hex
+  owner?: Hex
+  creator?: Hex
+  createdAt?: Hex
+  updatedAt?: Hex
+  expiresAt?: Hex
+  creationFlags?: RpcCreationFlags | number
+  contentType?: string
+  payload?: Hex
+  attributeSchema?: RpcAttributeSchemaEntry[]
+  attributes?: RpcAttribute[]
+}
+
+/**
+ * The `select` projection: flat, per-field booleans. Everything except `key` defaults to **off**,
+ * so a query asks for exactly what it needs and nothing more.
+ *
+ * `attributes` is the one field with a third form: `true` for every attribute, or a map of names
+ * for a subset.
+ */
+export type RpcSelect = {
   key?: boolean
-  attributes?: boolean
-  payload?: boolean
-  contentType?: boolean
-  expiration?: boolean
   owner?: boolean
   creator?: boolean
-  createdAtBlock?: boolean
-  lastModifiedAtBlock?: boolean
-  transactionIndexInBlock?: boolean
-  operationIndexInTransaction?: boolean
+  createdAt?: boolean
+  updatedAt?: boolean
+  expiresAt?: boolean
+  creationFlags?: boolean
+  contentType?: boolean
+  payload?: boolean
+  attributeSchema?: boolean
+  attributes?: boolean | Record<string, boolean>
+}
+
+export type RpcQueryOptions = {
+  /** Block height to read at, as a hex quantity. Defaults to the head, and must be within the node's retained range. */
+  atBlock?: Hex
+  /** What to return. Defaults to `{ key: true }`. */
+  select?: RpcSelect
+  /** Page size, as a hex quantity. Node maximum is 200. */
+  limit?: Hex
+  /** Opaque cursor from a previous response; bound to that query, block and selection. */
+  cursor?: string
 }
 
 export type ArkivRpcSchema = [
@@ -51,7 +87,8 @@ export type ArkivRpcSchema = [
     ReturnType: {
       data: RpcEntity[]
       blockNumber: Hex
-      cursor: string
+      /** Omitted when no pages remain. */
+      cursor?: string
     }
   },
   {