@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/types/entity.ts

@@ -1,6 +1,6 @@
-import { bytesToString, type Hex } from "viem"
-import type { AttributeSchema, Attributes } from "../attr"
+import type { Hex } from "viem"
 import type { ResolvedCreationFlags } from "../entity/flags"
+import type { AttributeSchema, Attributes } from "../schema"
 
 /**
  * The fields an {@link Entity} can carry. Every one is optional: a query returns exactly the parts
@@ -18,20 +18,20 @@ export type EntityFields = {
   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. */
+  /** Attribute names, types and indexing, with no values. */
   attributeSchema?: AttributeSchema | undefined
   /** Attribute names, types and values. */
   attributes?: Attributes | undefined
 }
 
 /**
- * An entity as it comes back from a query.
+ * An entity as the node returns it, decoded: the fields a query selected, with its attributes as a
+ * map keyed by name. Which fields are populated is decided by the selection, so each may be
+ * `undefined`.
  *
- * 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.
+ * Queries do not return these: `select()`, `query()` and `getEntity()` lay each one out as a flat
+ * row — the selected entity fields and attributes side by side, typed by the selection and, through
+ * a schema, by its columns.
  */
 export class Entity implements EntityFields {
   key: Hex | undefined
@@ -41,8 +41,6 @@ export class Entity implements EntityFields {
   updatedAt: bigint | undefined
   expiresAt: bigint | undefined
   creationFlags: ResolvedCreationFlags | undefined
-  contentType: string | undefined
-  payload: Uint8Array | undefined
   attributeSchema: AttributeSchema | undefined
   attributes: Attributes | undefined
 
@@ -54,51 +52,7 @@ export class Entity implements EntityFields {
     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
   }
-
-  /**
-   * 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 — the query did not select it. Use select({ payload: true }).",
-      )
-    }
-    try {
-      return bytesToString(this.payload)
-    } catch (e) {
-      throw new Error(
-        `Failed to convert entity payload to text: ${e instanceof Error ? e.message : String(e)}`,
-        { cause: e },
-      )
-    }
-  }
-
-  /**
-   * 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) {
-      throw new Error("Entity has empty payload, cannot parse as JSON")
-    }
-    try {
-      return JSON.parse(text)
-    } catch (e) {
-      throw new Error(
-        `Failed to parse entity payload as JSON: ${e instanceof Error ? e.message : String(e)}`,
-        { cause: e },
-      )
-    }
-  }
 }

package/src/types/events.ts

@@ -31,7 +31,7 @@ export type EntityCreatedEvent = EntityEventContext & {
 }
 
 /**
- * An entity's attributes or payload changed.
+ * An entity's attributes changed.
  *
  * The event says *that* it changed, not what to — read the entity to see the new state.
  */

package/src/types/index.ts

@@ -4,20 +4,28 @@ export type {
   PredictEntityKeysReturnType,
   PredictedEntityKey,
 } from "../actions/public/predictEntityKeys"
-export type { QueryOptions, QueryReturnType } from "../actions/public/query"
+export type { QueryOptions, QueryReturnType, QueryRow } from "../actions/public/query"
 export type { WatchEntityEventsParameters } from "../actions/public/watchEntityEvents"
 export type {
   ChangeOwnershipParameters,
   ChangeOwnershipReturnType,
 } from "../actions/wallet/changeOwnership"
-export type { CreateEntityParameters, CreateEntityReturnType } from "../actions/wallet/createEntity"
+export type {
+  CreateEntityOptions,
+  CreateEntityParameters,
+  CreateEntityReturnType,
+} from "../actions/wallet/createEntity"
 export type { DeleteEntityParameters, DeleteEntityReturnType } from "../actions/wallet/deleteEntity"
 export type {
   ExecuteBatchParameters,
   ExecuteBatchReturnType,
 } from "../actions/wallet/executeBatch"
 export type { ExtendEntityParameters, ExtendEntityReturnType } from "../actions/wallet/extendEntity"
-export type { PatchEntityParameters, PatchEntityReturnType } from "../actions/wallet/patchEntity"
+export type {
+  PatchEntityChanges,
+  PatchEntityParameters,
+  PatchEntityReturnType,
+} from "../actions/wallet/patchEntity"
 export type { EntityFields } from "./entity"
 export { Entity } from "./entity"
 export type {
@@ -29,7 +37,6 @@ export type {
   ExpiryExtendedEvent,
   OwnershipTransferredEvent,
 } from "./events"
-export type { MimeType } from "./mimeTypes"
 export type {
   ArkivRpcSchema,
   RpcAttribute,

package/src/types/rpcSchema.ts

@@ -1,10 +1,10 @@
-import type { Hex, PublicRpcSchema } from "viem"
+import type { Hex } from "viem"
 
 /**
  * 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`.
+ * `u64` and `u256`, a decimal string for `dec`, `0x` DATA for the byte-shaped types (`bytes`
+ * included), 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.
@@ -15,10 +15,14 @@ export type RpcAttribute = {
   value: unknown
 }
 
-/** An entry of the `attributeSchema` projection — a name and its type, with no value. */
+/**
+ * An entry of the `attributeSchema` projection — a name, its type, and whether the node indexes
+ * it, with no value.
+ */
 export type RpcAttributeSchemaEntry = {
   name: string
   type: string
+  indexed?: boolean
 }
 
 /**
@@ -42,8 +46,6 @@ export type RpcEntity = {
   updatedAt?: Hex
   expiresAt?: Hex
   creationFlags?: RpcCreationFlags | number
-  contentType?: string
-  payload?: Hex
   attributeSchema?: RpcAttributeSchemaEntry[]
   attributes?: RpcAttribute[]
 }
@@ -63,10 +65,13 @@ export type RpcSelect = {
   updatedAt?: boolean
   expiresAt?: boolean
   creationFlags?: boolean
-  contentType?: boolean
-  payload?: boolean
   attributeSchema?: boolean
   attributes?: boolean | Record<string, boolean>
+  /**
+   * Not a field of each entity but of the page: the number of entities the query matches at the
+   * block, regardless of `limit` and `cursor`, returned as the response's `count`.
+   */
+  count?: boolean
 }
 
 /** The second parameter of `arkiv_query` — what to return, and where in the results to start. */
@@ -75,7 +80,7 @@ export type RpcQueryOptions = {
   atBlock?: Hex
   /** What to return. Defaults to `{ key: true }`. */
   select?: RpcSelect
-  /** Page size, as a hex quantity. Node maximum is 200. */
+  /** Page size, as a hex quantity. Node maximum is 100. */
   limit?: Hex
   /** Opaque cursor from a previous response; bound to that query, block and selection. */
   cursor?: string
@@ -90,8 +95,16 @@ export type ArkivRpcSchema = [
       blockNumber: Hex
       /** Omitted when no pages remain. */
       cursor?: string
+      /** How many entities the query matches, as a hex quantity. Present only when selected. */
+      count?: Hex
     }
   },
+  {
+    Method: "arkiv_getEntity"
+    Parameters: [entityKey: Hex]
+    /** Every field except `attributeSchema`, or `null` if no live entity has the key. */
+    ReturnType: RpcEntity | null
+  },
   {
     Method: "arkiv_getBlockTiming"
     Parameters?: []
@@ -101,11 +114,4 @@ export type ArkivRpcSchema = [
       duration: number
     }
   },
-  {
-    Method: "arkiv_getEntityCount"
-    Parameters?: []
-    ReturnType: number
-  },
 ]
-
-export type PublicArkivRpcSchema = [...PublicRpcSchema, ...ArkivRpcSchema]