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

package/src/clients/decorators/arkivPublic.ts

@@ -1,19 +1,22 @@
-import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem"
+import type { Account, Address, 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 { getEntityNonce } from "../../actions/public/getEntityNonce"
+import {
+  type PredictEntityKeysParameters,
+  type PredictEntityKeysReturnType,
+  predictEntityKeys,
+} from "../../actions/public/predictEntityKeys"
 import { type QueryOptions, type QueryReturnType, query } from "../../actions/public/query"
-import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
-import { QueryBuilder, SelectQueryBuilder } from "../../query/queryBuilder"
+import {
+  type WatchEntityEventsParameters,
+  watchEntityEvents,
+} from "../../actions/public/watchEntityEvents"
+import type { Expression } from "../../query/expression"
+import { SelectQueryBuilder } from "../../query/queryBuilder"
 import type { EntitySelection, FullEntity, ProjectedEntity, SelectArg } from "../../query/selection"
 import type { Entity } from "../../types/entity"
-import type {
-  OnEntityCreatedEvent,
-  OnEntityDeletedEvent,
-  OnEntityExpiredEvent,
-  OnEntityExpiresInExtendedEvent,
-  OnEntityUpdatedEvent,
-} from "../../types/events"
 
 export type PublicArkivActions<
   transport extends Transport = Transport,
@@ -38,23 +41,28 @@ export type PublicArkivActions<
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
    *
    * @param key - The entity key (hex string)
-   * @returns The entity with the given key. {@link Entity}
+   * @returns The entity with the given key, with every field populated. {@link FullEntity}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entity = await client.getEntity("0x123")
-   * // {
-   * //   key: "0x123",
-   * //   value: "0x123",
+   * const entity = await client.getEntity(entityKey)
+   * // Entity {
+   * //   key: "0x9f2c…",
+   * //   owner: "0xabc…",
+   * //   contentType: "application/json",
+   * //   payload: Uint8Array,          // entity.toJson() / entity.toText() decode it
+   * //   attributes: { category: { type: "str", value: "docs" } },
+   * //   expiresAt: 1_297_000n,
    * // }
    */
-  getEntity: (key: Hex) => Promise<Entity>
+  getEntity: (key: Hex) => Promise<FullEntity>
 
   /**
    * Returns a SelectQueryBuilder for building and executing queries — the recommended way to
@@ -70,12 +78,13 @@ export type PublicArkivActions<
    * @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'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { eq } from "@arkiv-network/sdk/query"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * // select everything
@@ -83,7 +92,7 @@ export type PublicArkivActions<
    * 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[] }
+   * // select specific fields — result typed { owner: Hex; attributes: Attributes }
    * await client.select({ owner: true, attributes: true }).fetch()
    * // a single field — result typed { owner: Hex }
    * await client.select({ owner: true }).fetch()
@@ -95,9 +104,11 @@ export type PublicArkivActions<
      * 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`.
+     * Available fields: `key`, `owner`, `creator`, `createdAt`, `updatedAt`, `expiresAt`,
+     * `creationFlags`, `contentType`, `payload`, `attributeSchema` and `attributes`.
+     *
+     * `attributes` also takes a map of names, to fetch only those:
+     * `select({ key: true, attributes: { projectId: true } })`.
      *
      * 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
@@ -105,7 +116,8 @@ export type PublicArkivActions<
      *
      * @example
      * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
-     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     * client.select({ key: true, payload: true })      // includes payload → toText()/toJson() too
+     * client.select({ key: true, attributeSchema: true }) // what shape is the data?
      */
     <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
     /**
@@ -116,90 +128,133 @@ export type PublicArkivActions<
   }
 
   /**
-   * 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
+   * Runs one query and returns one page, with no builder in between.
    *
-   * @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.
+   * Use {@link select} for anything typed — this returns full {@link Entity} objects whatever the
+   * selection, and takes a raw string as an escape hatch for a query built elsewhere. A raw string
+   * goes to the node exactly as written, with none of the name, type or operator checks the
+   * expression combinators apply.
    *
-   * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
+   * @param query - An {@link Expression}, or the raw query string.
+   * @param queryOptions - Selection, page size, cursor and block. {@link QueryOptions}
+   * @returns One page of entities. {@link QueryReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { and, eq, gte } from "@arkiv-network/sdk/query"
+   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const query = client.buildQuery()
-   * const entities = await query.where("key", "=", "value").ownedBy("0x123").fetch()
+   * const page = await client.query(and(eq("category", "docs"), gte("level", i32(10))), {
+   *   select: { key: true, attributes: true },
+   *   limit: 100,
+   * })
+   * // { entities: [Entity], cursor: "b64:…", blockNumber: 32223n }
    *
+   * // The raw form, unchecked:
+   * await client.query("category = str('docs') AND level >= i32(10)")
    */
-  buildQuery: () => QueryBuilder
+  query: (query: Expression | string, queryOptions?: QueryOptions) => Promise<QueryReturnType>
 
   /**
-   * Returns a QueryResult instance for fetching the results of a raw query.
-   * 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 A QueryReturnType instance - {@link QueryReturnType}
+   * Returns the total number of entities on the chain.
+   * @returns The number of entities currently stored
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const queryResult = client.query('key = value && $owner = 0x123')
-   * // queryResult = { entities: [{ key: "0x123", value: "0x123" }], cursor: undefined, blockNumber: undefined }
-   * const queryResultWithOptions = client.query('key = value && $owner = 0x123', {
-   *   includeData: {
-   *     attributes: false,
-   *     payload: true,
-   *     metadata: true,
-   *   },
-   *   resultsPerPage: 10,
-   *   cursor: undefined,
-   *   atBlock: undefined,
-   * })
-   * // queryResultWithOptions = { entities: [{ key: "0x123", value: "0x123" }], cursor: "...", blockNumber: 32223n }
+   * const entityCount = await client.getEntityCount()
+   * // entityCount = 0
    */
-  query: (query: string, queryOptions?: QueryOptions) => Promise<QueryReturnType>
+  getEntityCount: () => Promise<number>
 
   /**
-   * Returns the number of entities in the DBChain.
-   * @returns The number of entities in the DBChain
+   * Returns how many entities an account has created — its entity-minting nonce.
+   *
+   * Not the account's transaction nonce: the engine keeps its own counter per creator and mixes it
+   * into every key it mints, which is why two identical creates from one account never collide.
+   *
+   * @param owner - The account whose nonce to read.
+   * @returns The nonce the account's next create will use.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entityCount = await client.getEntityCount()
-   * // entityCount = 0
+   * const nonce = await client.getEntityNonce("0xabc…")
+   * // 7n — the next entity this account creates is its eighth
    */
-  getEntityCount: () => Promise<number>
+  getEntityNonce: (owner: Address) => Promise<bigint>
+
+  /**
+   * Works out the keys an account's next creates will be given, before sending them.
+   *
+   * The engine derives a key from the chain, the registry, the owner, the owner's nonce and a
+   * salt — everything but the nonce is known to the caller, and the nonce is read here. This is
+   * what lets a batch reference an entity it is about to mint.
+   *
+   * Each key arrives paired with the salt that mints it, because a create defaults to a *random*
+   * salt: a predicted key only holds if the create carries the salt it was predicted with. And the
+   * prediction holds only while nothing else from this owner is in flight — for a key you can rely
+   * on unconditionally, read it back from the create instead.
+   *
+   * A literal `count` comes back as a fixed-length tuple, so the pairs destructure into names.
+   *
+   * @param parameters - Owner, and either a count or the salts. {@link PredictEntityKeysParameters}
+   * @returns One `{ key, salt }` pair per create, in batch order.
+   *   {@link PredictEntityKeysReturnType}
+   *
+   * @example A batch whose second entity points at its first.
+   * import { key } from "@arkiv-network/sdk/attr"
+   *
+   * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
+   * await wallet.mutateEntities({
+   *   creates: [
+   *     { payload, contentType, expires, salt: parent.salt },
+   *     {
+   *       payload,
+   *       contentType,
+   *       expires,
+   *       salt: child.salt,
+   *       attributes: { parent: key(parent.key) },
+   *     },
+   *   ],
+   * })
+   */
+  predictEntityKeys: <
+    const TCount extends number = number,
+    const TSalts extends readonly bigint[] | undefined = undefined,
+  >(
+    parameters: PredictEntityKeysParameters<TCount, TSalts>,
+  ) => Promise<PredictEntityKeysReturnType<TCount, TSalts>>
 
   /**
    * Returns the current block timing.
    * @returns The current block timing. {@link GetBlockTimingReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * const blockTiming = await client.getBlockTiming()
@@ -216,43 +271,32 @@ export type PublicArkivActions<
   }>
 
   /**
-   * Subscribes to entity events.
-   * 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
+   * Watches entity events, calling the handlers you pass as they arrive.
+   *
+   * All five are decoded from logs — `onEntityCreated`, `onEntityPatched`, `onExpiryExtended`,
+   * `onOwnershipTransferred`, `onEntityDeleted` — and each carries the block, transaction and log
+   * index it came from, which is the order the operations were applied in. `onEvent` receives all
+   * of them, whatever their type.
+   *
+   * @param parameters - Handlers and options, all optional. {@link WatchEntityEventsParameters}
+   * @returns A function that stops the watcher.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const unsubscribe = await client.subscribeEntityEvents({
-   *   onError: (error) => console.error("subscribeEntityEvents error", error),
+   * const unwatch = client.watchEntityEvents({
+   *   onEntityCreated: ({ entityKey, expiresAt }) => console.log(entityKey, "until", expiresAt),
+   *   onError: (error) => console.error("watchEntityEvents error", error),
    * })
-   * unsubscribe() // unsubscribe from the events
+   * unwatch() // stop watching
    */
-  subscribeEntityEvents: (
-    {
-      onError,
-      onEntityCreated,
-      onEntityUpdated,
-      onEntityDeleted,
-      onEntityExpiresInExtended,
-    }: {
-      onError?: (error: Error) => void
-      onEntityCreated?: (event: OnEntityCreatedEvent) => void
-      onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
-      onEntityDeleted?: (event: OnEntityDeletedEvent) => void
-      onEntityExpired?: (event: OnEntityExpiredEvent) => void
-      onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
-    },
-    pollingInterval?: number,
-    fromBlock?: bigint,
-  ) => Promise<() => void>
+  watchEntityEvents: (parameters: WatchEntityEventsParameters) => () => void
 }
 
 export function publicArkivActions<
@@ -262,42 +306,19 @@ export function publicArkivActions<
 >(client: Client<transport, chain, account>) {
   return {
     getEntity: (key: Hex) => getEntity(client, key),
-    query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
-    buildQuery: () => new QueryBuilder(client),
+    query: (rawQuery: Expression | string, queryOptions?: QueryOptions) =>
+      query(client, rawQuery, queryOptions),
     select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),
-    subscribeEntityEvents: (
-      {
-        onError,
-        onEntityCreated,
-        onEntityUpdated,
-        onEntityDeleted,
-        onEntityExpired,
-        onEntityExpiresInExtended,
-      }: {
-        onError?: (error: Error) => void
-        onEntityCreated?: (event: OnEntityCreatedEvent) => void
-        onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
-        onEntityDeleted?: (event: OnEntityDeletedEvent) => void
-        onEntityExpired?: (event: OnEntityExpiredEvent) => void
-        onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
-      },
-      pollingInterval?: number,
-      fromBlock?: bigint,
-    ) =>
-      subscribeEntityEvents(
-        client,
-        {
-          onError,
-          onEntityCreated,
-          onEntityUpdated,
-          onEntityDeleted,
-          onEntityExpired,
-          onEntityExpiresInExtended,
-        },
-        pollingInterval,
-        fromBlock,
-      ),
+    getEntityNonce: (owner: Address) => getEntityNonce(client, owner),
+    predictEntityKeys: <
+      const TCount extends number = number,
+      const TSalts extends readonly bigint[] | undefined = undefined,
+    >(
+      parameters: PredictEntityKeysParameters<TCount, TSalts>,
+    ) => predictEntityKeys(client, parameters),
+    watchEntityEvents: (parameters: WatchEntityEventsParameters) =>
+      watchEntityEvents(client, parameters),
   }
 }