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

package/dist/flags-CRjPpoh3.d.cts

@@ -0,0 +1,41 @@
+//#region src/entity/flags.d.ts
+/**
+ * The immutable properties an entity is created with. Both default to `false`.
+ *
+ * Creation flags are fixed at creation: there is no operation that changes them, so an entity is
+ * whatever it was created as for its whole life.
+ */
+type CreationFlags = {
+  /**
+   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * ownership transferred, and the entity deleted.
+   */
+  readonly?: boolean;
+  /**
+   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something
+   * alive without being able to change it.
+   */
+  permissionlessExtension?: boolean;
+};
+/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */
+type ResolvedCreationFlags = {
+  readonly: boolean;
+  permissionlessExtension: boolean;
+  raw: number;
+};
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+declare function encodeCreationFlags(flags?: CreationFlags): number;
+/**
+ * Reads the `creationFlags` byte back.
+ *
+ * @param raw - The `creationFlags` byte.
+ * @throws {InvalidCreationFlagsError} Malformed input
+ */
+declare function decodeCreationFlags(raw: number): ResolvedCreationFlags;
+//#endregion
+export { encodeCreationFlags as i, ResolvedCreationFlags as n, decodeCreationFlags as r, CreationFlags as t };
+//# sourceMappingURL=flags-CRjPpoh3.d.cts.map

package/dist/flags-CRjPpoh3.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-CRjPpoh3.d.cts","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":[],"mappings":";;AAYA;AAcA;AAWA;AAkBA;;KA3CY,aAAA;;;;;;;;;;;;;KAcA,qBAAA;;;;;;;;;;iBAWI,mBAAA,SAA2B;;;;;;;iBAkB3B,mBAAA,eAAkC"}

package/dist/flags-DFBs2J94.js

@@ -0,0 +1,33 @@
+import { t as InvalidCreationFlagsError } from "./errors-LTe7bOYS.js";
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+export { encodeCreationFlags as n, decodeCreationFlags as t };
+//# sourceMappingURL=flags-DFBs2J94.js.map

package/dist/flags-DFBs2J94.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-DFBs2J94.js","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":["import { InvalidCreationFlagsError } from \"./errors\"\n\n/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */\nconst READONLY_BIT = 0b0000_0001\nconst PERMISSIONLESS_EXTENSION_BIT = 0b0000_0010\n\n/**\n * The immutable properties an entity is created with. Both default to `false`.\n *\n * Creation flags are fixed at creation: there is no operation that changes them, so an entity is\n * whatever it was created as for its whole life.\n */\nexport type CreationFlags = {\n  /**\n   * The entity's attributes and payload can never be changed — only its expiry extended, its\n   * ownership transferred, and the entity deleted.\n   */\n  readonly?: boolean\n  /**\n   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something\n   * alive without being able to change it.\n   */\n  permissionlessExtension?: boolean\n}\n\n/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */\nexport type ResolvedCreationFlags = {\n  readonly: boolean\n  permissionlessExtension: boolean\n  raw: number\n}\n\n/**\n * Packs creation flags into the `creationFlags` byte.\n *\n * @throws {InvalidCreationFlagsError} If a value is not a boolean.\n */\nexport function encodeCreationFlags(flags: CreationFlags = {}): number {\n  for (const [name, value] of Object.entries(flags)) {\n    if (value !== undefined && typeof value !== \"boolean\") {\n      throw new InvalidCreationFlagsError(`\"${name}\" must be a boolean, got ${typeof value}`)\n    }\n  }\n  return (\n    (flags.readonly ? READONLY_BIT : 0) |\n    (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0)\n  )\n}\n\n/**\n * Reads the `creationFlags` byte back.\n *\n * @param raw - The `creationFlags` byte.\n * @throws {InvalidCreationFlagsError} Malformed input\n */\nexport function decodeCreationFlags(raw: number): ResolvedCreationFlags {\n  if (!Number.isInteger(raw) || raw < 0 || raw > 0xff) {\n    throw new InvalidCreationFlagsError(`${raw} is not a byte`)\n  }\n  return {\n    readonly: (raw & READONLY_BIT) !== 0,\n    permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,\n    raw,\n  }\n}\n"],"mappings":";;;;AAGA,MAAM,eAAe;AACrB,MAAM,+BAA+B;;;;;;AAiCrC,SAAgB,oBAAoB,QAAuB,EAAE,EAAU;AACrE,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,CAC/C,KAAI,UAAU,UAAa,OAAO,UAAU,UAC1C,OAAM,IAAI,0BAA0B,IAAI,KAAK,2BAA2B,OAAO,QAAQ;AAG3F,SACG,MAAM,WAAW,eAAe,MAChC,MAAM,0BAA0B,+BAA+B;;;;;;;;AAUpE,SAAgB,oBAAoB,KAAoC;AACtE,KAAI,CAAC,OAAO,UAAU,IAAI,IAAI,MAAM,KAAK,MAAM,IAC7C,OAAM,IAAI,0BAA0B,GAAG,IAAI,gBAAgB;AAE7D,QAAO;EACL,WAAW,MAAM,kBAAkB;EACnC,0BAA0B,MAAM,kCAAkC;EAClE;EACD"}

package/dist/flags-kr276q6i.cjs

@@ -0,0 +1,43 @@
+const require_errors = require('./errors-BVbjKVMN.cjs');
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new require_errors.InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new require_errors.InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'decodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return decodeCreationFlags;
+  }
+});
+Object.defineProperty(exports, 'encodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return encodeCreationFlags;
+  }
+});

package/dist/index-B5j76711.d.ts

@@ -0,0 +1,184 @@
+import { j as ArkivClient } from "./selection-C4UhsMOO.js";
+import { f as Operation } from "./index-fX_XyqLp.js";
+import { c as TxParams, t as EntityMutationOps } from "./arkivTransactions-NtGD6uk5.js";
+import { Address, Hash, Hex, TransactionReceipt } from "viem";
+
+//#region src/actions/advanced/buildMutation.d.ts
+/** Options for the advanced-path builders ({@link buildMutation}, {@link sendMutation}). */
+type BuildMutationOptions = {
+  /**
+   * The chain head to resolve relative expiries against.
+   *
+   * Pass a block number you already hold — from a previous call, `getBlockTiming()`, or your own
+   * tracking — and the build spends no RPC call at all. Without it, one `eth_blockNumber` is made,
+   * and only when the batch actually needs the head (a relative lifetime or a `Date` deadline);
+   * purely absolute `atBlock(n)` expiries never trigger it.
+   *
+   * Supplying it also buys back a check: absolute expiries are validated against it, so an
+   * `atBlock(n)` already in the past throws {@link InvalidExpiryError} locally instead of
+   * reverting on-chain. When the head is neither supplied nor fetched, that dead-on-arrival
+   * check is skipped — the one local validation of the everyday path this path trades away.
+   */
+  currentBlock?: bigint;
+};
+/** What {@link buildMutation} hands back: the batch in every form a sender might want. */
+type BuildMutationReturnType = {
+  /** The encoded batch, in engine order, for `writeContract`-style sends. */
+  operations: Operation[];
+  /** The Arkiv engine address the transaction must be sent to. */
+  to: Address;
+  /**
+   * The full `execute(operations)` calldata. Sign a transaction carrying it offline (with your own
+   * nonce, gas and fees) and the whole mutation costs exactly one `eth_sendRawTransaction`.
+   */
+  data: Hex;
+  /**
+   * How many operations of each kind went into the batch — which is how many events of each kind a
+   * successful transaction emits, in batch order, for cross-checking a decoded result.
+   */
+  expected: {
+    creates: number;
+    patches: number;
+    deletes: number;
+    extensions: number;
+    ownershipChanges: number;
+  };
+};
+/**
+ * Encodes a mutation batch without sending anything.
+ *
+ * This is the first step of the advanced path: it performs only local validation and encoding, so
+ * it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
+ * and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
+ * to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
+ *
+ * One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
+ * locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
+ * expiry encodes cleanly and the engine reverts it on-chain — see
+ * {@link BuildMutationOptions.currentBlock}.
+ *
+ * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
+ * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+ * @throws {EmptyPatchError} If a patch has nothing to apply.
+ */
+declare function buildMutation(client: ArkivClient, data: EntityMutationOps, options?: BuildMutationOptions): Promise<BuildMutationReturnType>;
+//#endregion
+//#region src/actions/advanced/getMutationResult.d.ts
+/**
+ * A mined mutation, decoded from its receipt alone.
+ *
+ * Everything here comes out of the events the batch emitted, so no request context is needed to
+ * read it — a process that holds nothing but the transaction hash gets the full picture. Arrays
+ * are in batch order, which is the order the operations were applied in.
+ */
+type MutationResult = {
+  /** `success` means the whole batch applied; `reverted` means none of it did (arrays are empty). */
+  status: "success" | "reverted";
+  /** The transaction hash. */
+  txHash: Hash;
+  /** The block the transaction landed in. */
+  blockNumber: bigint;
+  /** The keys the engine minted for the created entities, in batch order. */
+  createdEntities: Hex[];
+  /** The block each created entity expires at, as the engine recorded it, in the same order. */
+  createdExpiries: bigint[];
+  /** The keys of the patched entities. */
+  patchedEntities: Hex[];
+  /** The keys of the deleted entities. */
+  deletedEntities: Hex[];
+  /** The keys of the extended entities. */
+  extendedEntities: Hex[];
+  /** The block each extended entity now expires at, in the same order. */
+  extendedExpiries: bigint[];
+  /** The keys of the entities handed to a new owner. */
+  ownershipChanges: Hex[];
+  /** The raw receipt, so nothing the chain said is lost. */
+  receipt: TransactionReceipt;
+};
+/** Return type for {@link getMutationResult}: the decoded result, or still pending. */
+type GetMutationResultReturnType = MutationResult | {
+  status: "pending";
+};
+/**
+ * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
+ *
+ * The pure tail of the advanced path: if a receipt reached you some other way — your own
+ * `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
+ * expiries without touching the network. Lenient by design: it reports what the events say,
+ * without counting them against a request it never saw.
+ */
+declare function decodeMutationResult(receipt: TransactionReceipt): MutationResult;
+/**
+ * Fetches a transaction's receipt — once — and decodes what the mutation did.
+ *
+ * Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
+ * decoded entity events as well: created keys, recorded expiries, and the keys of everything
+ * patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
+ * `{ status: "pending" }` — check `status` before reading the rest.
+ *
+ * No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
+ * spending a `simulateContract` on the why is your call, not the SDK's.
+ */
+declare function getMutationResult(client: ArkivClient, txHash: Hash): Promise<GetMutationResultReturnType>;
+//#endregion
+//#region src/actions/advanced/pingTransaction.d.ts
+/** Return type for {@link pingTransaction}. */
+type PingTransactionReturnType = {
+  /** Not mined yet (or unknown to this node). Ping again later. */
+  status: "pending";
+  blockNumber?: undefined;
+} | {
+  /** Mined. `success` means the whole batch applied; `reverted` means none of it did. */
+  status: "success" | "reverted";
+  /** The block the transaction landed in. */
+  blockNumber: bigint;
+};
+/**
+ * Asks the chain — once — whether a transaction has landed.
+ *
+ * Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
+ * back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
+ * path — you own the schedule, the SDK owns nothing.
+ *
+ * When it reports `success` and you need the created keys or recorded expiries, spend the next
+ * call on `getMutationResult` — or none at all, if you predicted the keys up front with
+ * `predictEntityKeys`.
+ */
+declare function pingTransaction(client: ArkivClient, txHash: Hash): Promise<PingTransactionReturnType>;
+//#endregion
+//#region src/actions/advanced/sendMutation.d.ts
+/** Options for {@link sendMutation}. */
+type SendMutationOptions = BuildMutationOptions & {
+  /**
+   * Transaction parameters. Supply `nonce`, `gas` and the fee fields and viem has nothing left to
+   * look up — the send collapses to a single `eth_sendRawTransaction`.
+   */
+  txParams?: TxParams;
+};
+/** Return type for {@link sendMutation}. */
+type SendMutationReturnType = {
+  /** The transaction hash. Poll it with `pingTransaction` / fetch it with `getMutationResult`. */
+  txHash: Hash;
+  /** The per-kind operation counts of the batch that was sent, for cross-checking the result. */
+  expected: BuildMutationReturnType["expected"];
+};
+/**
+ * Signs and sends a mutation batch, returning as soon as the transaction is submitted.
+ *
+ * The fire-and-forget half of the advanced path. Unlike `mutateEntities`, this does **not** wait
+ * for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
+ * costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
+ * RPC call; each omitted piece adds only the lookup viem needs to fill it.
+ *
+ * Follow up separately, on your own schedule:
+ * - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
+ * - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
+ *
+ * @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
+ * the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
+ * Anything after that — inclusion, success — is yours to check.
+ */
+declare function sendMutation(client: ArkivClient, data: EntityMutationOps, options?: SendMutationOptions): Promise<SendMutationReturnType>;
+//#endregion
+export { pingTransaction as a, decodeMutationResult as c, BuildMutationReturnType as d, buildMutation as f, PingTransactionReturnType as i, getMutationResult as l, SendMutationReturnType as n, GetMutationResultReturnType as o, sendMutation as r, MutationResult as s, SendMutationOptions as t, BuildMutationOptions as u };
+//# sourceMappingURL=index-B5j76711.d.ts.map

package/dist/index-B5j76711.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B5j76711.d.ts","names":[],"sources":["../src/actions/advanced/buildMutation.ts","../src/actions/advanced/getMutationResult.ts","../src/actions/advanced/pingTransaction.ts","../src/actions/advanced/sendMutation.ts"],"sourcesContent":[],"mappings":";;;;;;;KAeY,oBAAA;EAAA;AAkBZ;;;;;AAwCA;;;;;;;;;;AC1DY,KDkBA,uBAAA,GClBc;EAIhB;EAIS,UAAA,EDYL,SCZK,EAAA;EAIA;EAEA,EAAA,EDQb,OCRa;EAEC;;;;EAUR,IAAA,EDCJ,GCDI;EAUI;AA4BhB;;;EAGW,QAAA,EAAA;IAAR,OAAA,EAAA,MAAA;IAAO,OAAA,EAAA,MAAA;;;;EC1EE,CAAA;AAwBZ,CAAA;;;;;;;;;AClBA;AASA;AAuBA;;;;;;;iBH2BsB,aAAA,SACZ,mBACF,6BACG,uBACR,QAAQ;;;;;;;AA9DX;AAkBA;;AAIM,KCtBM,cAAA,GDsBN;EAKE;EAAG,MAAA,EAAA,SAAA,GAAA,UAAA;EA+BW;EACZ,MAAA,ECvDA,IDuDA;EACF;EACG,WAAA,EAAA,MAAA;EACA;EAAR,eAAA,ECtDgB,GDsDhB,EAAA;EAAO;;;mBClDS;EAZP;EAIF,eAAA,EAUS,GAVT,EAAA;EAIS;EAIA,gBAAA,EAIC,GAJD,EAAA;EAEA;EAEC,gBAAA,EAAA,MAAA,EAAA;EAIA;EAET,gBAAA,EAFS,GAET,EAAA;EAAkB;EAIjB,OAAA,EAJD,kBAIC;AAUZ,CAAA;AA4BA;AACU,KAvCE,2BAAA,GAA8B,cAuChC,GAAA;EACA,MAAA,EAAA,SAAA;CACC;;;;;;AC1EX;AAwBA;;AAEU,iBDiBM,oBAAA,CCjBN,OAAA,EDiBoC,kBCjBpC,CAAA,EDiByD,cCjBzD;;;;;;;ACpBV;AASA;AAuBA;;;AAGW,iBF8BW,iBAAA,CE9BX,MAAA,EF+BD,WE/BC,EAAA,MAAA,EFgCD,IEhCC,CAAA,EFiCR,OEjCQ,CFiCA,2BEjCA,CAAA;;;;KDzCC,yBAAA;;;EFOA,WAAA,CAAA,EAAA,SAAoB;AAkBhC,CAAA,GAAY;EAEE;EAER,MAAA,EAAA,SAAA,GAAA,UAAA;EAKE;EAAG,WAAA,EAAA,MAAA;AA+BX,CAAA;;;;;;;;;;AC1DA;;AAQmB,iBCSG,eAAA,CDTH,MAAA,ECUT,WDVS,EAAA,MAAA,ECWT,IDXS,CAAA,ECYhB,ODZgB,CCYR,yBDZQ,CAAA;;;;ADRP,KGDA,mBAAA,GAAsB,oBHCF,GAAA;EAkBpB;;;;EASD,QAAA,CAAA,EGvBE,QHuBF;AA+BX,CAAA;;AAEQ,KGpDI,sBAAA,GHoDJ;EACG;EACA,MAAA,EGpDD,IHoDC;EAAR;EAAO,QAAA,EGlDE,uBHkDF,CAAA,UAAA,CAAA;;;;AC9DV;;;;;;;;;AA0BA;AAUA;AA4BA;;;AAGW,iBEpCW,YAAA,CFoCX,MAAA,EEnCD,WFmCC,EAAA,IAAA,EElCH,iBFkCG,EAAA,OAAA,CAAA,EEjCA,mBFiCA,CAAA,EEhCR,OFgCQ,CEhCA,sBFgCA,CAAA"}

package/dist/index-BF7Mq9Is.d.cts

@@ -0,0 +1,280 @@
+import { R as RpcSelect, i as SelectArg, j as ArkivClient, p as Expression, s as Entity } from "./selection-DPg0uyJf.cjs";
+import { K as TypeTag } from "./index-CV5zCdpa.cjs";
+import { Hex } from "viem";
+
+//#region src/query/engine.d.ts
+declare const MAX_LIMIT = 200;
+/** One `arkiv_query` call. */
+type QueryRequest = {
+  /** The query expression, already rendered. */
+  query: string;
+  /** What to return. */
+  select: RpcSelect;
+  /** Page size, up to {@link MAX_LIMIT}. Defaults to the node's own page size. */
+  limit?: number | undefined;
+  /** Cursor from a previous page. */
+  cursor?: string | undefined;
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined;
+};
+/** One page of results. */
+type QueryResponse = {
+  entities: Entity[];
+  /** The block the page was read at — the same for every page of a paginated query. */
+  blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  cursor: string | undefined;
+};
+/**
+ * Runs one query and decodes the page it returns.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+declare function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse>;
+//#endregion
+//#region src/query/errors.d.ts
+/**
+ * A predicate asked for an operator the query language does not define for that type.
+ *
+ * The operator × type matrix is part of the language, not a policy: a range comparison on an
+ * equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
+ * a round trip and an RPC error code into a stack trace pointing at the call site.
+ *
+ * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
+ * | --- | --- | --- | --- |
+ * | `bool` | yes | no | no |
+ * | `i32` `u256` `dec` | yes | yes | no |
+ * | `str` | yes | no | yes |
+ * | `addr` `key` `bytes32` | yes | no | no |
+ */
+declare class UnsupportedOperatorError extends Error {
+  /** The attribute the predicate names. */
+  readonly attributeName: string;
+  /** The operator, as it would have been written in the query. */
+  readonly operator: string;
+  /** The type of the value it was applied to. */
+  readonly tag: TypeTag;
+  constructor(attributeName: string, operator: string, tag: TypeTag, hint?: string);
+}
+/**
+ * A predicate could not be expressed in the query language for a reason other than its operator —
+ * a system attribute that is returned in results but cannot be filtered on, a system attribute
+ * compared against the wrong type, or a combinator with nothing to combine.
+ */
+declare class InvalidPredicateError extends Error {
+  /** The attribute the predicate names, where there is one. */
+  readonly attributeName: string | undefined;
+  constructor(message: string, attributeName?: string);
+}
+/**
+ * What a node rejected a query for. Part of the frozen RPC surface, so it is safe to branch on —
+ * a `"cursor"` failure means start the query again, a `"block"` failure means the node no longer
+ * retains that height, and the rest mean the query itself needs fixing.
+ */
+type QueryErrorKind = /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
+"parse"
+/** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */ | "type"
+/** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */ | "literal"
+/** A node budget was exceeded — query length, predicate count, nesting depth, bitmap operations. */ | "limits"
+/** The cursor expired, is malformed, or belongs to a different query, block or selection. */ | "cursor"
+/** `atBlock` is outside the range the node retains. */ | "block";
+/**
+ * The node rejected a query.
+ *
+ * These codes are part of the frozen `arkiv_query` surface, so {@link kind} and {@link data} are
+ * stable enough to branch on — which the underlying JSON-RPC error is not, because the codes
+ * overlap Ethereum's own EIP-1474 numbering and get wrapped accordingly on the way up.
+ *
+ * @example
+ * try {
+ *   await result.next()
+ * } catch (error) {
+ *   if (error instanceof QueryError && error.kind === "cursor") {
+ *     // The page is gone — start the query over.
+ *   }
+ * }
+ */
+declare class QueryError extends Error {
+  /** Which failure this is. */
+  readonly kind: QueryErrorKind;
+  /** The JSON-RPC error code. */
+  readonly code: number;
+  /** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+  readonly data: unknown;
+  /** The query string that was rejected. */
+  readonly query: string;
+  constructor(kind: QueryErrorKind, code: number, query: string, data: unknown, detail?: string);
+}
+//#endregion
+//#region src/query/queryResult.d.ts
+/** Fetches the page a cursor points at. */
+type FetchPage<TEntity> = (cursor: string) => Promise<QueryResult<TEntity>>;
+/**
+ * One page of query results.
+ *
+ * A page is immutable: {@link next} returns the following page rather than mutating this one, so a
+ * page that has been read stays readable.
+ *
+ * @typeParam TEntity - The shape of each entity, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * let page = await client.select({ key: true }).where(eq("category", "docs")).limit(100).fetch()
+ * while (page.hasNextPage()) {
+ *   page = await page.next()
+ * }
+ */
+declare class QueryResult<TEntity = Entity> {
+  /** The entities on this page. */
+  readonly entities: readonly TEntity[];
+  /**
+   * The block this page was read at.
+   *
+   * Every page of one walk reads the same block — the cursor is bound to it — so results cannot
+   * shift under a paginating reader.
+   */
+  readonly blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  readonly cursor: string | undefined;
+  private readonly fetchPage;
+  constructor(entities: readonly TEntity[], blockNumber: bigint, cursor: string | undefined, fetchPage: FetchPage<TEntity>);
+  /**
+   * Whether another page follows.
+   *
+   * The node omits the cursor once nothing remains, so this is an answer rather than the guess a
+   * short final page would be — a full last page is reported correctly.
+   */
+  hasNextPage(): boolean;
+  /**
+   * Fetches the next page.
+   *
+   * @throws {NoMoreResultsError} If this was the last page — check {@link hasNextPage} first.
+   * @throws {QueryError} If the node rejects the request; `kind === "cursor"` means the cursor
+   * expired and the walk has to start again.
+   */
+  next(): Promise<QueryResult<TEntity>>;
+}
+//#endregion
+//#region src/query/queryBuilder.d.ts
+/**
+ * Builds and runs a query.
+ *
+ * The selection is fixed when the builder is created and the filter is added by chaining, so the
+ * result type is known before a single predicate is written. Create one with `client.select(...)`
+ * rather than constructing it directly — that is what infers the entity shape from the selection.
+ *
+ * Every filter added with {@link where}, {@link ownedBy} and {@link createdBy} must hold; use
+ * {@link or} for alternatives inside one call.
+ *
+ * @typeParam TEntity - The projected entity shape, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * import { createPublicClient } from "@arkiv-network/sdk"
+ * import { i32 } from "@arkiv-network/sdk/attr"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { eq, gte, or } from "@arkiv-network/sdk/query"
+ * import { http } from "viem"
+ *
+ * const client = createPublicClient({ chain: cheesecake, transport: http() })
+ *
+ * const page = await client
+ *   .select({ key: true, attributes: true })
+ *   .where(gte("level", i32(10)), or(eq("status", "open"), eq("status", "review")))
+ *   .ownedBy(owner)
+ *   .limit(100)
+ *   .fetch()
+ *
+ * for (const entity of page.entities) console.log(entity.key, entity.attributes)
+ */
+declare class SelectQueryBuilder<TEntity = Entity> {
+  private readonly _client;
+  private readonly _select;
+  private readonly _filters;
+  private _ownedBy;
+  private _createdBy;
+  private _limit;
+  private _cursor;
+  private _atBlock;
+  constructor(client: ArkivClient, selection?: SelectArg);
+  /**
+   * Adds filters. Everything passed here, and across repeated calls, must hold.
+   *
+   * @param expressions - The expressions, as separate arguments or one array.
+   *
+   * @example
+   * builder.where(eq("category", "docs"))
+   * builder.where(gte("level", i32(10)), lt("level", i32(20)))
+   * builder.where(or(eq("status", "open"), not(exists("closedAt"))))
+   */
+  where(expressions: readonly Expression[]): this;
+  where(...expressions: Expression[]): this;
+  /**
+   * Restricts the results to entities this account owns — shorthand for
+   * `where(eq("$owner", addr(owner)))`. Calling it again replaces the filter.
+   *
+   * @example
+   * builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+   */
+  ownedBy(owner: Hex): this;
+  /**
+   * Restricts the results to entities this account created — shorthand for
+   * `where(eq("$creator", addr(creator)))`. Calling it again replaces the filter.
+   *
+   * The creator never changes; the owner does, so these differ after a transfer.
+   */
+  createdBy(creator: Hex): this;
+  /**
+   * Sets the page size, up to the node maximum of 200. Without it the node picks the page size.
+   *
+   * @example
+   * builder.limit(100)
+   */
+  limit(limit: number): this;
+  /**
+   * Starts from a cursor returned by an earlier page.
+   *
+   * Pagination normally goes through {@link QueryResult.next}, which carries the cursor for you;
+   * this is for resuming a walk in a later process. A cursor is bound to the query, block and
+   * selection it came from, so it must be used with an identically-built query — {@link atBlock}
+   * set to the `blockNumber` of the page the cursor came from is required (persist the two
+   * together), and a fetch with a cursor but no block rejects locally.
+   */
+  cursor(cursor: string): this;
+  /**
+   * Reads the state as of a given block rather than the head. The block must be within the range
+   * the node retains.
+   *
+   * @example
+   * builder.atBlock(1_297_000n)
+   */
+  atBlock(block: bigint): this;
+  /**
+   * The query string this builder will send — the same text the node parses.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   */
+  toString(): string;
+  /**
+   * Runs the query and returns the first page.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   * @throws {QueryError} If the node rejects the query.
+   *
+   * @example
+   * const page = await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * page.entities        // this page
+   * await page.next()    // the next one
+   */
+  fetch(): Promise<QueryResult<TEntity>>;
+  /**
+   * Walks every page, yielding one entity at a time.
+   *
+   * @example
+   * for await (const entity of client.select({ key: true }).where(eq("category", "docs"))) {
+   *   console.log(entity.key)
+   * }
+   */
+  [Symbol.asyncIterator](): AsyncGenerator<TEntity>;
+}
+//#endregion
+export { QueryErrorKind as a, QueryRequest as c, QueryError as i, QueryResponse as l, QueryResult as n, UnsupportedOperatorError as o, InvalidPredicateError as r, MAX_LIMIT as s, SelectQueryBuilder as t, runQuery as u };
+//# sourceMappingURL=index-BF7Mq9Is.d.cts.map

package/dist/index-BF7Mq9Is.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BF7Mq9Is.d.cts","names":[],"sources":["../src/query/engine.ts","../src/query/errors.ts","../src/query/queryResult.ts","../src/query/queryBuilder.ts"],"sourcesContent":[],"mappings":";;;;;cAUa,SAAA;;AAAA,KAGD,YAAA,GAHU;EAGV;EAcA,KAAA,EAAA,MAAA;EAaU;EAAiB,MAAA,EAvB7B,SAuB6B;EAAsB;EAAuB,KAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAR;EAAO,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;;;ACxBnF;AAMgB,KDKJ,aAAA,GCLI;EAE4C,QAAA,EDIhD,MCJgD,EAAA;EARd;EAAK,WAAA,EAAA,MAAA;EAyBtC;EAgBD,MAAA,EAAA,MAAA,GAAc,SAAA;AAwC1B,CAAA;;;;;;iBDzDsB,QAAA,SAAiB,sBAAsB,eAAe,QAAQ;;;;;;;AA9BpF;AAGA;AAcA;AAaA;;;;;;;cCxBa,wBAAA,SAAiC,KAAA;;EAAjC,SAAA,aAAA,EAAA,MAAyB;EAMtB;EAE4C,SAAA,QAAA,EAAA,MAAA;EARd;EAAK,SAAA,GAAA,EAMnC,OANmC;EAyBtC,WAAA,CAAA,aAAsB,EAAA,MAAA,EAAA,QAAa,EAAA,MAAA,EAAA,GAAA,EAjBY,OAiBZ,EAAA,IAAA,CAAA,EAAA,MAAA;AAgBhD;AAwCA;;;;;cAxDa,qBAAA,SAA8B,KAAA;;;ECrCtC,WAAA,CAAS,OAAA,EAAA,MAAA,EAAA,aAAA,CAAA,EAAA,MAAA;;;;;AAgBd;;AAE8B,KDmClB,cAAA;;+GCSwB;kHAApB;;;ACzBhB,0DAA0C,OAAA;;;;;;;;;;;;;;;;;cFwD7B,UAAA,SAAmB,KAAA;;iBAEf;;;;;;;oBAQG;;;;;KCvGf,yCAAyC,QAAQ,YAAY;;;AFMlE;AAGA;AAcA;AAaA;;;;;;;;;ACxBa,cCIA,WDJyB,CAAA,UCIH,MDJG,CAAA,CAAA;EAMtB;EAE4C,SAAA,QAAA,EAAA,SCF9B,ODE8B,EAAA;EARd;;AAyB9C;AAgBA;AAwCA;;EAUoB,SAAA,WAAA,EAAA,MAAA;EAVY;EAAK,SAAA,MAAA,EAAA,MAAA,GAAA,SAAA;;iCC7Dd,uEAGR,UAAU;;AAtCoB;;;;;EAmBhC,WAAA,CAAA,CAAA,EAAW,OAAA;EAAW;;;;;;;EA8CnB,IAAA,CAAA,CAAA,EAAA,OAAA,CAAQ,WAAR,CAAoB,OAApB,CAAA,CAAA;;;;AFrDhB;AAcA;AAaA;;;;;;;;;ACxBA;;;;;AAyBA;AAgBA;AAwCA;;;;;;;;AChG6C;;;;AAGQ,cCqCxC,kBDrCwC,CAAA,UCqCX,MDrCW,CAAA,CAAA;EAgBxC,iBAAW,OAAA;EAAW,iBAAA,OAAA;EAEL,iBAAA,QAAA;EAcP,QAAA,QAAA;EAGE,QAAA,UAAA;EAAV,QAAA,MAAA;EA2BqB,QAAA,OAAA;EAAZ,QAAA,QAAA;EAAR,WAAA,CAAA,MAAA,ECfM,WDeN,EAAA,SAAA,CAAA,ECf+B,SDe/B;EAAO;;;;ACzBvB;;;;;;EAuCiB,KAAA,CAAA,WAAA,EAAA,SAda,UAcb,EAAA,CAAA,EAAA,IAAA;EAWI,KAAA,CAAA,GAAA,WAAA,EAxBG,UAwBH,EAAA,CAAA,EAAA,IAAA;EAyEgB;;;;;;;iBApFpB;;;;;;;qBAWI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAyEJ,QAAQ,YAAY;;;;;;;;;GAqB3B,MAAA,CAAO,aAAA,KAAkB,eAAe"}