@algorandfoundation/asa-metadata-registry-sdk 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -1,28 +1,71 @@
-# asa-metadata-registry-ts
+# ASA Metadata Registry TypeScript SDK
 
-ASA Metadata Registry TypeScript SDK
+[![npm](https://img.shields.io/npm/v/@algorandfoundation/asa-metadata-registry-sdk)](https://www.npmjs.com/package/@algorandfoundation/asa-metadata-registry-sdk)
+[![Release](https://github.com/algorandfoundation/asa-metadata-registry-ts/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/algorandfoundation/asa-metadata-registry-ts/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-## Devs
+TypeScript SDK for the [ARC-89](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0089.md) ASA Metadata
+Registry, the singleton Algorand application that stores ASA metadata on-chain. It is a port of the
+[reference Python SDK](https://github.com/algorandfoundation/arc89) v1.0.0 with full feature parity.
 
-### Dependencies
+- **Read** metadata straight from the box (one Algod request) or through AVM simulation, so you get exactly what a
+  smart contract gets.
+- **Write** metadata: create, replace (in full or one byte range) and delete it, and set flags and immutability.
+  Large payloads are split into chunks for you.
+- **Migrate** legacy ARC-3, ARC-19 and ARC-69 ASAs, and build and parse ARC-90 URIs.
+- **Call the registry from contracts** with the Algorand TypeScript client at `/avm`.
 
-Node: 22.17.0 (see `.nvmrc`)
+Built on [AlgoKit Utils](https://github.com/algorandfoundation/algokit-utils-ts) v9 and
+[algosdk](https://github.com/algorand/js-algorand-sdk) v3 (consensus v42 / AVM 13).
+
+The registry is deployed on TestNet (app ID `772968354`). MainNet is not deployed yet, so `forNetwork('mainnet')` throws
+until it is.
+
+## Install
+
+The package has no runtime dependencies. Install the peer dependencies alongside it:
 
 ```sh
-git submodule update --init --recursive
-pnpm install
-pnpm exec husky
+pnpm add @algorandfoundation/asa-metadata-registry-sdk @algorandfoundation/algokit-utils algosdk
 ```
 
-> `ignore-scripts=true` is set in `.npmrc` to block postinstall scripts from running on install. This means husky won't set up git hooks automatically and should be manually executed after cloning.
+Requires Node.js 22.17 or later.
 
-### Code Quality
+## Quick start
 
-```sh
-pnpm run format
-pnpm run lint
+Read an ASA's metadata from TestNet:
+
+```ts
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { AsaMetadataRegistry } from '@algorandfoundation/asa-metadata-registry-sdk'
+
+const algod = AlgorandClient.testNet().client.algod
+const registry = AsaMetadataRegistry.forNetwork('testnet', { algod })
+
+const record = await registry.read.getAssetMetadata({ assetId: 772968365n })
+console.log(record.json) // { name: 'Cusma #2', description: 'Cusma autograph #2', ... }
 ```
 
-This project uses **Husky** and **lint-staged** to automatically lint and format staged files before they are committed.
+Writes need an app client signed by the ASA manager. See the cookbook for the full setup.
+
+## Documentation
+
+- [Cookbook](./docs/cookbook.md): tested recipes for every main feature, on TestNet and LocalNet.
+- [SDK reference](./.claude/skills/using-asa-metadata-registry/reference.md): every signature, model, flag and error.
+- [Parity contract](./docs/PARITY_CONTRACT.md): how the API maps to the Python SDK.
+- [ARC-89 specification](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0089.md).
+
+### Agent skill
+
+[`.claude/skills/using-asa-metadata-registry`](./.claude/skills/using-asa-metadata-registry) is an
+[agent skill](https://code.claude.com/docs/en/skills) that teaches coding agents how to use this SDK. To use it in your
+own project, copy the folder into the project's `.claude/skills/` folder (or into `~/.claude/skills/` for all your
+projects).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup, tests, generated clients and dependency policy.
+
+## License
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for dependency policy and lockfile rules.
+[MIT](./LICENSE)

package/dist/cjs/algod.d.ts

@@ -2,35 +2,36 @@
  * Algod helpers (ARC-89 box reads).
  *
  * Ported from `asa_metadata_registry/algod.py`.
- * Uses the minimal Algod subset for box reads and ASA params.
+ * Uses the minimal algosdk Algod client subset for box reads, ASA params and network identity.
  */
-import type { AlgodClient, Box, Asset } from '@algorandfoundation/algokit-utils/algod-client';
-import { Arc90Uri } from './codec';
-import { AssetMetadataBox, AssetMetadataRecord, RegistryParameters } from './models';
-export type AlgodClientSubset = Pick<AlgodClient, 'applicationBoxByName' | 'assetById'>;
+import type { Algodv2, modelsv2 } from 'algosdk';
+import { Arc90Uri } from './codec.js';
+import { AssetMetadataBox, AssetMetadataRecord, RegistryParameters } from './models.js';
+/** The algosdk `Algodv2` methods required by {@link AlgodBoxReader}. */
+export type AlgodClientSubset = Pick<Algodv2, 'getApplicationBoxByName' | 'getAssetByID' | 'getTransactionParams'>;
 /**
  * Read ARC-89 metadata by directly reading the registry application box via Algod.
  *
  * This avoids transactions entirely and is usually the fastest read path.
  *
  * Required Algod methods:
- * - getApplicationBoxByName
- * - getAssetByID (for URI resolution)
+ * - `getApplicationBoxByName` (box reads)
+ * - `getAssetByID` (ASA existence and params)
+ * - `getTransactionParams` (network genesis hash)
  */
 export declare class AlgodBoxReader {
     readonly algod: AlgodClientSubset;
     constructor(algod: AlgodClientSubset);
     /**
-     * Fetch a box by name.
+     * Fetch a raw box value.
      * @throws {BoxNotFoundError} If the box does not exist.
      */
     getBoxValue(args: {
         appId: bigint | number;
         boxName: Uint8Array;
-    }): Promise<Box>;
+    }): Promise<Uint8Array>;
     /**
      * Return the parsed metadata box, or null if the box doesn't exist.
-     * @throws {BoxNotFoundError} If the box does not exist.
      */
     tryGetMetadataBox(args: {
         appId: bigint | number;
@@ -57,11 +58,13 @@ export declare class AlgodBoxReader {
         assetId: bigint | number;
         params?: RegistryParameters;
     }): Promise<AssetMetadataRecord>;
+    /** Genesis hash (base64) of the connected network, or null if unavailable. */
+    getGenesisHashB64(): Promise<string | null>;
     /**
      * Fetch ASA info from Algod.
      * @throws {AsaNotFoundError} If the ASA does not exist.
      */
-    getAssetInfo(assetId: bigint | number): Promise<Asset>;
+    getAssetInfo(assetId: bigint | number): Promise<modelsv2.Asset>;
     /**
      * Return the ASA's URL as a string, or null if missing.
      * @param assetId - The ASA ID whose URL field should be retrieved.

package/dist/cjs/algod.js

@@ -3,36 +3,24 @@
  * Algod helpers (ARC-89 box reads).
  *
  * Ported from `asa_metadata_registry/algod.py`.
- * Uses the minimal Algod subset for box reads and ASA params.
+ * Uses the minimal algosdk Algod client subset for box reads, ASA params and network identity.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AlgodBoxReader = void 0;
-const codec_1 = require("./codec");
-const numbers_1 = require("./internal/numbers");
-const errors_1 = require("./errors");
-const models_1 = require("./models");
-const asErrorMessage = (e) => {
-    if (e instanceof Error)
-        return e.message;
-    try {
-        return String(e);
-    }
-    catch {
-        return '';
-    }
-};
-const looksNotFound = (e) => {
-    const msg = asErrorMessage(e).toLowerCase();
-    return msg.includes('404') || msg.includes('not found') || msg.includes('does not exist');
-};
+const codec_js_1 = require("./codec.js");
+const http_js_1 = require("./internal/http.js");
+const numbers_js_1 = require("./internal/numbers.js");
+const errors_js_1 = require("./errors.js");
+const models_js_1 = require("./models.js");
 /**
  * Read ARC-89 metadata by directly reading the registry application box via Algod.
  *
  * This avoids transactions entirely and is usually the fastest read path.
  *
  * Required Algod methods:
- * - getApplicationBoxByName
- * - getAssetByID (for URI resolution)
+ * - `getApplicationBoxByName` (box reads)
+ * - `getAssetByID` (ASA existence and params)
+ * - `getTransactionParams` (network genesis hash)
  */
 class AlgodBoxReader {
     algod;
@@ -40,37 +28,36 @@ class AlgodBoxReader {
         this.algod = algod;
     }
     /**
-     * Fetch a box by name.
+     * Fetch a raw box value.
      * @throws {BoxNotFoundError} If the box does not exist.
      */
     async getBoxValue(args) {
-        const appId = (0, numbers_1.toBigInt)(args.appId);
+        const appId = (0, numbers_js_1.toBigInt)(args.appId);
         try {
-            return await this.algod.applicationBoxByName(appId, args.boxName);
+            const box = await this.algod.getApplicationBoxByName(appId, args.boxName).do();
+            return box.value;
         }
         catch (e) {
-            if (looksNotFound(e))
-                throw new errors_1.BoxNotFoundError('Box not found', { cause: e });
+            if ((0, http_js_1.isNotFoundError)(e))
+                throw new errors_js_1.BoxNotFoundError('Box not found', { cause: e });
             throw e;
         }
     }
     /**
      * Return the parsed metadata box, or null if the box doesn't exist.
-     * @throws {BoxNotFoundError} If the box does not exist.
      */
     async tryGetMetadataBox(args) {
         let value;
         try {
-            const box = await this.getBoxValue({ appId: args.appId, boxName: (0, codec_1.assetIdToBoxName)(args.assetId) });
-            value = box.value;
+            value = await this.getBoxValue({ appId: args.appId, boxName: (0, codec_js_1.assetIdToBoxName)(args.assetId) });
         }
         catch (e) {
-            if (e instanceof errors_1.BoxNotFoundError)
+            if (e instanceof errors_js_1.BoxNotFoundError)
                 return null;
             throw e;
         }
-        const p = args.params ?? (0, models_1.getDefaultRegistryParams)();
-        return models_1.AssetMetadataBox.parse({
+        const p = args.params ?? (0, models_js_1.getDefaultRegistryParams)();
+        return models_js_1.AssetMetadataBox.parse({
             assetId: args.assetId,
             value,
             headerSize: p.headerSize,
@@ -84,7 +71,7 @@ class AlgodBoxReader {
     async getMetadataBox(args) {
         const box = await this.tryGetMetadataBox(args);
         if (!box)
-            throw new errors_1.BoxNotFoundError('Metadata box not found');
+            throw new errors_js_1.BoxNotFoundError('Metadata box not found');
         return box;
     }
     /**
@@ -95,7 +82,7 @@ class AlgodBoxReader {
      */
     async getAssetMetadataRecord(args) {
         const box = await this.getMetadataBox(args);
-        return new models_1.AssetMetadataRecord({
+        return new models_js_1.AssetMetadataRecord({
             appId: args.appId,
             assetId: args.assetId,
             header: box.header,
@@ -105,18 +92,24 @@ class AlgodBoxReader {
     // ---------------------------------------------------------------------
     // ASA lookups (optional)
     // ---------------------------------------------------------------------
+    /** Genesis hash (base64) of the connected network, or null if unavailable. */
+    async getGenesisHashB64() {
+        const params = await this.algod.getTransactionParams().do();
+        const gh = params.genesisHash;
+        return gh instanceof Uint8Array && gh.length > 0 ? (0, codec_js_1.b64Encode)(gh) : null;
+    }
     /**
      * Fetch ASA info from Algod.
      * @throws {AsaNotFoundError} If the ASA does not exist.
      */
     async getAssetInfo(assetId) {
-        const id = (0, numbers_1.toBigInt)(assetId);
+        const id = (0, numbers_js_1.toBigInt)(assetId);
         try {
-            return await this.algod.assetById(id);
+            return await this.algod.getAssetByID(id).do();
         }
         catch (e) {
-            if (looksNotFound(e))
-                throw new errors_1.AsaNotFoundError(`ASA ${id} not found`, { cause: e });
+            if ((0, http_js_1.isNotFoundError)(e))
+                throw new errors_js_1.AsaNotFoundError(`ASA ${id} not found`, { cause: e });
             throw e;
         }
     }
@@ -140,14 +133,14 @@ class AlgodBoxReader {
     async resolveMetadataUriFromAsset(args) {
         const url = await this.getAssetUrl(args.assetId);
         if (!url) {
-            throw new errors_1.InvalidArc90UriError('ASA has no url field; cannot resolve ARC-89 metadata URI');
+            throw new errors_js_1.InvalidArc90UriError('ASA has no url field; cannot resolve ARC-89 metadata URI');
         }
         try {
-            const full = (0, codec_1.completePartialAssetUrl)(url, args.assetId);
-            return codec_1.Arc90Uri.parse(full);
+            const full = (0, codec_js_1.completePartialAssetUrl)(url, args.assetId);
+            return codec_js_1.Arc90Uri.parse(full);
         }
         catch (e) {
-            throw new errors_1.InvalidArc90UriError('Failed to resolve ARC-89 URI from ASA url', { cause: e });
+            throw new errors_js_1.InvalidArc90UriError('Failed to resolve ARC-89 URI from ASA url', { cause: e });
         }
     }
 }

package/dist/cjs/algod.js.map

@@ -1 +1 @@
-{"version":3,"file":"algod.js","sourceRoot":"","sources":["../../src/algod.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"algod.js","sourceRoot":"","sources":["../../src/algod.ts"],"names":[],"mappings":"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"}

package/dist/cjs/bitmasks.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MASK_IRR_IMMUTABLE = exports.MASK_IRR_RESERVED_6 = exports.MASK_IRR_RESERVED_5 = exports.MASK_IRR_RESERVED_4 = exports.MASK_IRR_RESERVED_3 = exports.MASK_IRR_ARC54 = exports.MASK_IRR_ARC89 = exports.MASK_IRR_ARC3 = exports.MASK_REV_RESERVED_7 = exports.MASK_REV_RESERVED_6 = exports.MASK_REV_RESERVED_5 = exports.MASK_REV_RESERVED_4 = exports.MASK_REV_RESERVED_3 = exports.MASK_REV_NTT = exports.MASK_REV_ARC62 = exports.MASK_REV_ARC20 = exports.MASK_ID_SHORT = void 0;
-const flags = __importStar(require("./flags"));
+const flags = __importStar(require("./flags.js"));
 /**
  * Derived bitmasks for ASA Metadata Registry flags (ported from Python `bitmasks.py`).
  */

package/dist/cjs/bitmasks.js.map

@@ -1 +1 @@
-{"version":3,"file":"bitmasks.js","sourceRoot":"","sources":["../../src/bitmasks.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,+CAAgC;AAEhC;;GAEG;AAEH,kFAAkF;AACrE,QAAA,aAAa,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAA;AAEhD,qDAAqD;AACxC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,CAAA;AACrC,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AAEhE,uDAAuD;AAC1C,QAAA,aAAa,GAAG,CAAC,IAAI,KAAK,CAAC,YAAY,CAAA;AACvC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,kBAAkB,GAAG,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAA"}
+{"version":3,"file":"bitmasks.js","sourceRoot":"","sources":["../../src/bitmasks.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,kDAAmC;AAEnC;;GAEG;AAEH,kFAAkF;AACrE,QAAA,aAAa,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAA;AAEhD,qDAAqD;AACxC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,YAAY,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,CAAA;AACrC,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AAEhE,uDAAuD;AAC1C,QAAA,aAAa,GAAG,CAAC,IAAI,KAAK,CAAC,YAAY,CAAA;AACvC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,cAAc,GAAG,CAAC,IAAI,KAAK,CAAC,aAAa,CAAA;AACzC,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,mBAAmB,GAAG,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAA;AACnD,QAAA,kBAAkB,GAAG,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAA"}

package/dist/cjs/codec.d.ts

@@ -11,19 +11,19 @@ export declare const boxNameToAssetId: (boxName: Uint8Array) => bigint;
 export declare const b64Encode: (data: Uint8Array) => string;
 /** Standard base64 decode (accepts padding). */
 export declare const b64Decode: (dataB64: string) => Uint8Array;
-/** URL-safe base64, per ARC-90 examples (padding preserved to match Python SDK). */
+/** Canonical unpadded URL-safe base64. */
 export declare const b64UrlEncode: (data: Uint8Array) => string;
-/** URL-safe base64 decode. */
+/**
+ * Decode canonical unpadded URL-safe base64.
+ *
+ * @throws {Error} If the input has padding, characters outside the URL-safe alphabet, or is not
+ * the canonical encoding of the decoded bytes (e.g. non-zero trailing bits).
+ */
 export declare const b64UrlDecode: (dataB64Url: string) => Uint8Array;
 /**
- * Represents the ARC-90 compliance fragment '#arc<A>+<B>+...'.
- *
- * Per ARC-90:
- * - Format: #arc<A>+<B>+<C> where A, B, C are decimal numbers
- * - First entry has 'arc' prefix, subsequent entries are bare numbers
- * - No leading zeros allowed
- * - Special case: ARC-3 must be sole entry (#arc3)
- * - Order is not enforced (clients MUST accept any order)
+ * The ARC-90 compliance fragment '#arc<A>+<B>+...': unpadded decimal ARC numbers in
+ * strictly ascending order, 'arc' literal on the first entry only, ARC-3 sole entry.
+ * Non-compliant fragments parse as empty (ignored), as ARC-90 requires.
  */
 export declare class Arc90Compliance {
     readonly arcs: readonly number[];
@@ -36,8 +36,12 @@ export declare class Arc90Compliance {
  *
  * ARC-89 uses URIs of the form:
  *   algorand://<netauth>/app/<app_id>?box=<base64url_box_name>#arc<A>+<B>...
+ *
+ * The URI can be *partial* (Asset URL field), where the `box` query parameter exists
+ * but has an empty value; the SDK can complete it given an Asset ID.
  */
 export declare class Arc90Uri {
+    /** Network authority; examples: "net:testnet", "gh:<base64url>", null (mainnet / unspecified). */
     readonly netauth: string | null;
     readonly appId: bigint;
     readonly boxName: Uint8Array | null;
@@ -51,13 +55,33 @@ export declare class Arc90Uri {
     get assetId(): bigint | null;
     get isPartial(): boolean;
     withAssetId(assetId: bigint | number): Arc90Uri;
-    /** Render the URI using ARC-89 conventions (base64url for box query parameter). */
+    /** Render the URI (canonical unpadded base64url box value). */
     toUri(): string;
     /** The Algod `/box?name=` query parameter expects standard base64 (with padding). */
     toAlgodBoxNameB64(): string;
+    /**
+     * Parse an ARC-89 Asset Metadata URI, with the exact shape the registry enforces:
+     *
+     *   algorand://[<netauth>/]app/<app_id>?box=<base64url>[#arc<A>+<B>...]
+     *
+     * where <netauth> is `net:<label>` or `gh:<base64url>` (absent on MainNet), <app_id>
+     * is an unpadded decimal, `box` is the only query parameter and its value is empty
+     * (partial URI) or the canonical unpadded base64url of the 8-byte Asset ID.
+     */
     static parse(uri: string): Arc90Uri;
 }
 /**
  * Complete an ARC-89 partial Asset URL (Asset Params `url`) into a full Asset Metadata URI.
+ *
+ * The partial URL is expected to include the registry app reference and `box=` query key, but
+ * not the box value itself.
+ *
+ * Example (partial):
+ *   algorand://net:testnet/app/772968354?box=#arc89
+ *
+ * Output (complete):
+ *   algorand://net:testnet/app/772968354?box=<base64url(asset_id_bytes)>#arc89
+ *
+ * @throws {InvalidArc90UriError} If the Asset URL is not an ARC-89 partial URI (non-empty box value).
  */
 export declare const completePartialAssetUrl: (assetUrl: string, assetId: bigint | number) => string;