@feralfile/cli 2.10.0 → 3.0.0

package/dist/src/utilities/token-item.js

@@ -0,0 +1,428 @@
+"use strict";
+/**
+ * Token item construction shared by every token source.
+ *
+ * This module turns a StandardToken, the vendor-neutral token shape, into a
+ * DP-1 playlist item. It used to live inside nft-indexer.js, which meant the
+ * item id, provenance, inline manifest and timing rules would have been
+ * deleted along with the ff-indexer-v2 client if Raster replaces it
+ * (feral-file#3576). Keeping them here, with no knowledge of any vendor, is
+ * what lets two providers emit byte-identical items for the same token: the
+ * indexer provider and the Raster provider both map their rows to
+ * a StandardToken and hand it to convertToDP1Item.
+ *
+ * Invariants that must not change without a migration of existing playlists:
+ *   - the item id is sha256(`${contractAddress}-${tokenId}`) formatted as a
+ *     UUID, so the same token always yields the same id across vendors;
+ *   - provenance.contract.chain comes from the row's CAIP-2 chain when the
+ *     row has one, and only falls back to the caller's chain name otherwise;
+ *   - the inline manifest id is derived from the token coordinate by
+ *     ref-manifest.ts, independent of which vendor supplied the metadata.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CID_STANDARDS = void 0;
+exports.detectTokenStandard = detectTokenStandard;
+exports.normalizeCidStandard = normalizeCidStandard;
+exports.resolveTokenStandard = resolveTokenStandard;
+exports.dp1ChainFromCaip2 = dp1ChainFromCaip2;
+exports.resolveDp1Chain = resolveDp1Chain;
+exports.extractArtistName = extractArtistName;
+exports.isUsableSourceUrl = isUsableSourceUrl;
+exports.getBestMediaUrl = getBestMediaUrl;
+exports.itemIdFor = itemIdFor;
+exports.convertToDP1Item = convertToDP1Item;
+exports.stillOf = stillOf;
+const node_crypto_1 = require("node:crypto");
+const dp1_js_1 = require("dp1-js");
+const logger = __importStar(require("../logger"));
+const ref_manifest_1 = require("./ref-manifest");
+// playlist-builder.js is still CommonJS; require keeps interop simple, the
+// same way find.ts and playlist-source.ts load it.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { applyTimingToItemBuilder, buildDefaultDisplay } = require('./playlist-builder');
+/**
+ * detectTokenStandard guesses a token standard from a chain name and an address.
+ *
+ * This is the last-resort fallback, not the answer. It sees no token, only a
+ * chain name and an address format, so it cannot tell ERC-721 from ERC-1155
+ * and answers `erc721` for every EVM contract. It is still needed in two
+ * places: a lookup by coordinate has to build some key before a provider has
+ * been asked anything, and a token row that arrived without a `standard`
+ * field has nothing better to offer.
+ *
+ * Prefer, in order: the provider row's own standard, a caller's assertion, and
+ * only then this. On-chain detection is deliberately not attempted here.
+ *
+ * @param chain - Blockchain network
+ * @param contractAddress - Contract address
+ * @returns Token standard (erc721, erc1155, fa2, or other)
+ */
+function detectTokenStandard(chain, contractAddress) {
+    const lowerChain = String(chain || '').toLowerCase();
+    // Tezos contracts use FA2 standard
+    if (lowerChain === 'tezos' || String(contractAddress || '').startsWith('KT')) {
+        return 'fa2';
+    }
+    // Ethereum: erc721 is a guess, not a reading. Only the provider row or a
+    // caller's assertion can distinguish an ERC-1155 token from an ERC-721 one.
+    if (lowerChain === 'ethereum') {
+        return 'erc721';
+    }
+    return 'other';
+}
+/**
+ * CID_STANDARDS are the token standards the indexer keys CIDs on and DP-1
+ * `provenance.contract.standard` accepts from this CLI. A standard outside
+ * this set, asserted by a caller or arriving on a row, says nothing the key
+ * can carry, so detection decides instead.
+ */
+exports.CID_STANDARDS = new Set(['erc721', 'erc1155', 'fa2']);
+/**
+ * normalizeCidStandard returns a standard the CID format can carry, or ''.
+ *
+ * Both a provider row and a caller's assertion are untrusted strings from
+ * outside this module ('ERC1155', ' fa2 ', 'ERC-1155', undefined). Anything not
+ * in CID_STANDARDS is treated as absent rather than passed through, so a
+ * misspelled standard never reaches a CID or a DP-1 `provenance.contract`.
+ *
+ * @param value - Candidate standard
+ * @returns Normalized standard, or '' when it is not one we can use
+ */
+function normalizeCidStandard(value) {
+    const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return exports.CID_STANDARDS.has(normalized) ? normalized : '';
+}
+/**
+ * resolveTokenStandard picks the standard a lookup key is built with.
+ *
+ * detectTokenStandard cannot tell ERC-721 from ERC-1155, so when the caller
+ * knows the standard (a DP-1 playlist carries it in
+ * `provenance.contract.standard`) that assertion wins.
+ *
+ * @param chain - Blockchain network
+ * @param contractAddress - Contract address
+ * @param asserted - Standard the caller vouches for, if any
+ * @returns Token standard for the lookup key
+ */
+function resolveTokenStandard(chain, contractAddress, asserted) {
+    return normalizeCidStandard(asserted) || detectTokenStandard(chain, contractAddress);
+}
+/**
+ * CAIP2_NAMESPACE_TO_DP1_CHAIN maps CAIP-2 namespaces to the chain values DP-1
+ * `provenance.contract` allows. Namespaces outside this map have no DP-1
+ * equivalent.
+ */
+const CAIP2_NAMESPACE_TO_DP1_CHAIN = {
+    eip155: 'evm',
+    tezos: 'tezos',
+    bitmark: 'bitmark',
+};
+/**
+ * dp1ChainFromCaip2 derives a DP-1 chain from a CAIP-2 chain id.
+ *
+ * @param caip2Chain - CAIP-2 chain id from a provider row, e.g. `eip155:1`
+ * @returns DP-1 chain (`evm`, `tezos`, `bitmark`), or '' when unknown or absent
+ */
+function dp1ChainFromCaip2(caip2Chain) {
+    if (typeof caip2Chain !== 'string') {
+        return '';
+    }
+    const namespace = caip2Chain.trim().toLowerCase().split(':')[0];
+    return CAIP2_NAMESPACE_TO_DP1_CHAIN[namespace] || '';
+}
+/**
+ * CHAIN_NAME_TO_DP1_CHAIN maps client chain names to the chain values DP-1
+ * `provenance.contract` allows. It answers only for tokens that reached us
+ * without a provider row, that is a caller-supplied coordinate.
+ */
+const CHAIN_NAME_TO_DP1_CHAIN = {
+    ethereum: 'evm',
+    polygon: 'evm',
+    arbitrum: 'evm',
+    optimism: 'evm',
+    base: 'evm',
+    zora: 'evm',
+    tezos: 'tezos',
+    bitmark: 'bitmark',
+};
+/**
+ * resolveDp1Chain picks the DP-1 chain for a token's `provenance.contract`.
+ *
+ * The row's CAIP-2 chain and the caller's chain name are not two guesses to try
+ * in turn: they are different claims, and the row's is the network the
+ * provider recorded. So a token carrying a row chain is answered from that
+ * chain alone; a namespace with no DP-1 equivalent becomes `other`, never the
+ * caller's name. Falling through would be actively wrong, because owner and
+ * contract lookups label every non-KT address `ethereum` before mapping, so a
+ * Solana row would inherit that label and be published as an EVM contract.
+ *
+ * @param token - Token in the internal standard format
+ * @returns DP-1 chain (`evm`, `tezos`, `bitmark`, or `other`)
+ */
+function resolveDp1Chain(token) {
+    const rowChain = typeof token.caip2Chain === 'string' ? token.caip2Chain.trim() : '';
+    if (rowChain) {
+        return dp1ChainFromCaip2(rowChain) || 'other';
+    }
+    return CHAIN_NAME_TO_DP1_CHAIN[String(token.chain || '').toLowerCase()] || 'other';
+}
+/**
+ * extractArtistName returns the first artist's name from an artists array, or ''.
+ *
+ * @param artists - Array of artist objects with a name
+ * @returns Artist name or empty string
+ */
+function extractArtistName(artists) {
+    if (!Array.isArray(artists) || artists.length === 0) {
+        return '';
+    }
+    const first = artists[0];
+    return typeof first?.name === 'string' ? first.name : '';
+}
+/**
+ * isUsableSourceUrl reports whether a media URL can be a DP-1 item source.
+ *
+ * Data URIs are refused because the FF1 display path cannot load them and
+ * inlining base64 would dwarf the playlist; URLs over 1024 characters exceed
+ * the DP-1 limit on `source`.
+ *
+ * @param url - Candidate media URL
+ * @returns True when URL is usable in a DP-1 source
+ */
+function isUsableSourceUrl(url) {
+    if (!url || typeof url !== 'string') {
+        return false;
+    }
+    if (url.startsWith('data:')) {
+        return false;
+    }
+    if (url.length > 1024) {
+        return false;
+    }
+    return true;
+}
+/**
+ * getBestMediaUrl picks a DP-1 usable URL from a `display` block and asset rows.
+ *
+ * Order: display.animation_url, transcoded asset URLs (source + variants),
+ * display.image_url. The thumbnail is always `display.image_url`, the field
+ * reserved for a still.
+ *
+ * @param display - Merged presentation block
+ * @param mediaAssets - Transcoded asset rows
+ * @returns Object with url and thumbnail properties
+ */
+function getBestMediaUrl(display = {}, mediaAssets = []) {
+    const urlsFromAssets = [];
+    for (const asset of Array.isArray(mediaAssets) ? mediaAssets : []) {
+        if (asset?.source_url) {
+            urlsFromAssets.push(asset.source_url);
+        }
+        const v = asset?.variants;
+        if (v && typeof v === 'object') {
+            for (const val of Object.values(v)) {
+                if (typeof val === 'string') {
+                    urlsFromAssets.push(val);
+                }
+            }
+        }
+    }
+    const candidates = [display?.animation_url, ...urlsFromAssets, display?.image_url];
+    for (const candidate of candidates) {
+        if (isUsableSourceUrl(candidate)) {
+            return {
+                url: candidate,
+                thumbnail: display?.image_url || '',
+            };
+        }
+    }
+    const imageUrl = display?.image_url || '';
+    return {
+        url: imageUrl,
+        thumbnail: imageUrl,
+    };
+}
+/**
+ * itemIdFor derives the deterministic DP-1 item id for a token coordinate.
+ *
+ * sha256 of `${contractAddress}-${tokenId}` formatted UUID-style. This is a
+ * cross-vendor contract: a playlist built from the indexer and one built from
+ * Raster must carry the same id for the same token.
+ *
+ * @param token - Token coordinate
+ * @returns UUID-formatted id
+ */
+function itemIdFor(token) {
+    const idSource = `${token.contractAddress}-${token.tokenId}`;
+    const hash = (0, node_crypto_1.createHash)('sha256').update(idSource).digest('hex');
+    return `${hash.substr(0, 8)}-${hash.substr(8, 4)}-${hash.substr(12, 4)}-${hash.substr(16, 4)}-${hash.substr(20, 12)}`;
+}
+/**
+ * pickSourceUrl chooses the item source from a token's media candidates.
+ *
+ * Priority: animation_url, then image.url. The first usable candidate wins;
+ * when none is usable the first non-empty one is returned so the caller can
+ * report precisely why it was rejected.
+ *
+ * @param token - Token in the internal standard format
+ * @returns Source URL, or '' when the token names no media at all
+ */
+function pickSourceUrl(token) {
+    const candidateSourceUrls = [
+        token.animation_url || token.animationUrl,
+        token.image && typeof token.image === 'object' ? token.image.url : '',
+    ]
+        .map((value) => String(value || ''))
+        .filter(Boolean);
+    return candidateSourceUrls.find((url) => isUsableSourceUrl(url)) || candidateSourceUrls[0] || '';
+}
+/**
+ * rejectSourceUrl explains why a source URL cannot be used, or returns ''.
+ *
+ * @param token - Token the URL belongs to, for the log line
+ * @param sourceUrl - Candidate source
+ * @returns Error message, or '' when the URL is usable
+ */
+function rejectSourceUrl(token, sourceUrl) {
+    const coordinate = { contractAddress: token.contractAddress, tokenId: token.tokenId };
+    if (!sourceUrl) {
+        logger.warn('[Token Item] No source URL found for token:', coordinate);
+        return 'No source URL available';
+    }
+    if (sourceUrl.startsWith('data:')) {
+        logger.debug('[Token Item] Skipping token with data URI:', coordinate);
+        return 'Source is a data URI (not supported)';
+    }
+    if (sourceUrl.length > 1024) {
+        logger.debug('[Token Item] Skipping token with source URL too long:', {
+            ...coordinate,
+            urlLength: sourceUrl.length,
+        });
+        return `Source URL too long (${sourceUrl.length} chars, max 1024)`;
+    }
+    return '';
+}
+/**
+ * convertToDP1Item converts a token in the standard format to a DP-1 item.
+ *
+ * When the token carries description, artist, or a still image distinct from
+ * the source, the item also gets an inline Ref Manifest (see ref-manifest.ts).
+ *
+ * @param tokenData - Token data in standard format
+ * @param duration - Explicit display seconds; omit for auto timing
+ *   (video/audio play natural length per DP-1 §4.1)
+ * @returns DP-1 item with success/error status, plus the token's still
+ */
+function convertToDP1Item(tokenData, duration) {
+    const { token } = tokenData;
+    if (!token) {
+        return {
+            success: false,
+            error: tokenData.error || 'Invalid token data',
+        };
+    }
+    const sourceUrl = pickSourceUrl(token);
+    const rejection = rejectSourceUrl(token, sourceUrl);
+    if (rejection) {
+        return { success: false, error: rejection };
+    }
+    // Build via dp1-js PlaylistItemBuilder so leaf blocks match the DP-1 AJV schema.
+    const itemBuilder = new dp1_js_1.PlaylistItemBuilder()
+        .id(itemIdFor(token))
+        .source(sourceUrl)
+        .license('open')
+        .provenance(new dp1_js_1.ProvenanceBuilder().type('onChain').contract(new dp1_js_1.ContractBuilder()
+        // resolveDp1Chain and the standard helpers only ever return members
+        // of the dp1-js unions, so the casts narrow rather than lie.
+        .chain(resolveDp1Chain(token))
+        .standard((token.standard ||
+        detectTokenStandard(token.chain, token.contractAddress)))
+        .address(token.contractAddress)
+        .tokenId(String(token.tokenId))));
+    if (token.name) {
+        itemBuilder.title(token.name);
+    }
+    // Carry description, artist, and still image inline (DP-1 Playlist Extension
+    // §3.6). The helper returns undefined when the token has nothing beyond its
+    // title, so thin tokens stay thin.
+    const inlineManifest = (0, ref_manifest_1.buildInlineManifestForToken)(token, { sourceUrl });
+    if (inlineManifest) {
+        itemBuilder.inlineManifest(inlineManifest);
+    }
+    const mimeType = typeof token.image === 'object' && token.image ? token.image.mimeType : undefined;
+    applyTimingToItemBuilder(itemBuilder, { mimeType, sourceUrl }, duration, buildDefaultDisplay());
+    let dp1Item;
+    try {
+        dp1Item = itemBuilder.build();
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    logger.debug('[Token Item] ✓ Converted to DP-1:', {
+        title: token.name,
+        source: sourceUrl ? sourceUrl.substring(0, 60) + '...' : '(no source URL)',
+    });
+    return {
+        success: true,
+        item: dp1Item,
+        still: stillOf(token),
+    };
+}
+/**
+ * stillOf names the token's still image as the provider identifies it, or ''.
+ *
+ * Only `image.thumbnail` qualifies. `image.url` is the media the provider
+ * selected as the source, which is the live rendition whenever one exists,
+ * exactly what must never land in a thumbnail slot. It is returned beside the
+ * DP-1 item rather than inside it because the item only carries the still when
+ * it differs from the item's own source, and a consumer building a manifest
+ * against a different source (see enrich-playlist.ts) needs the still
+ * regardless. Nothing about the URL's shape is inspected: the provider's word
+ * that it is an image is the evidence, and a suffix check would reject the
+ * extensionless CDN URLs providers commonly return.
+ *
+ * @param token - Token in the internal standard format
+ * @returns http(s) still URL, or '' when the provider named none
+ */
+function stillOf(token) {
+    const image = token.image;
+    const candidate = typeof image === 'string' ? image : typeof image === 'object' && image ? image.thumbnail : '';
+    const trimmed = String(candidate || '').trim();
+    return trimmed.startsWith('http://') || trimmed.startsWith('https://') ? trimmed : '';
+}

package/dist/src/utilities/token-source-contract.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Token source contract: the vendor-neutral seam between commands and the
+ * services that answer "which token is this, and what does it display".
+ *
+ * Commands (`find`, `build`, `enrich`) depend on this contract only. Each
+ * vendor is one provider module that implements it: token-source-indexer.ts
+ * (the default) and token-source-raster.ts (opt-in, feral-file#3576).
+ * A future art-catalog-service adapter would be a third provider, and nothing
+ * outside token-source.ts would change.
+ *
+ * Kept free of provider imports so providers can import it without a cycle;
+ * the factory that chooses a provider lives in token-source.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RASTER_CANNOT_LIST_CONTRACT = exports.TokenSourceCapabilityError = void 0;
+exports.isResolved = isResolved;
+exports.isFailed = isFailed;
+exports.itemsOf = itemsOf;
+exports.failureMessages = failureMessages;
+/**
+ * isResolved narrows a result. This repo compiles without strictNullChecks,
+ * under which TypeScript does not narrow a union on a boolean discriminant,
+ * so callers use these guards instead of `if (result.success)`.
+ */
+function isResolved(result) {
+    return result.success === true;
+}
+/** isFailed is the complement of isResolved. */
+function isFailed(result) {
+    return result.success === false;
+}
+/**
+ * TokenSourceCapabilityError means the active provider cannot answer this
+ * kind of request at all. It is deliberately not retried against another
+ * provider: one vendor answers a whole run (owner decision, feral-file#3576).
+ */
+class TokenSourceCapabilityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TokenSourceCapabilityError';
+    }
+}
+exports.TokenSourceCapabilityError = TokenSourceCapabilityError;
+/** RASTER_CANNOT_LIST_CONTRACT is the user-facing reason contract listing fails on Raster. */
+exports.RASTER_CANNOT_LIST_CONTRACT = 'Raster cannot list a contract. Give tokenIds, an owner address, or run find on the series URL.';
+/** itemsOf keeps the items of the successful results, in order. */
+function itemsOf(results) {
+    return results.filter(isResolved).map((result) => result.item);
+}
+/** failureMessages returns each distinct failure reason once, for a summary line. */
+function failureMessages(results) {
+    const messages = results.filter(isFailed).map((result) => result.error);
+    return [...new Set(messages)];
+}

package/dist/src/utilities/token-source-indexer.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Indexer token source: adapter over the ff-indexer-v2 client.
+ *
+ * The indexer is the default token source. Raster is the opt-in alternative
+ * under evaluation (feral-file#3576); keep both behind the TokenSource
+ * contract so the vendor stays a configuration switch. This adapter keeps the
+ * pre-Raster behaviour on purpose, including the indexing trigger and the
+ * polling that makes unseen tokens slow (ff-cli#132).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIndexerTokenSource = createIndexerTokenSource;
+// nft-indexer.js is CommonJS and is required lazily so a Raster run never
+// loads the indexer client at all.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const loadIndexer = () => require('./nft-indexer');
+/** Page size the owner walk has always used against the indexer. */
+const OWNER_PAGE_SIZE = 50;
+/** Per-request cap the indexer path has always applied to a bounded listing. */
+const MAX_BOUNDED_LIMIT = 100;
+/** chainOfContract infers a chain from an address; listings carry no chain name. */
+function chainOfContract(contractAddress) {
+    return contractAddress.startsWith('KT') ? 'tezos' : 'ethereum';
+}
+/** rowsToResults converts raw indexer rows to results, one per row. */
+function rowsToResults(rows, duration) {
+    const indexer = loadIndexer();
+    return rows.map((row) => {
+        const contractAddress = row.contract_address || '';
+        const coordinate = {
+            chain: chainOfContract(contractAddress),
+            contractAddress,
+            tokenId: String(row.token_number ?? ''),
+        };
+        const mapped = indexer.mapIndexerDataToStandardFormat(row, coordinate.chain);
+        const converted = mapped.success ? indexer.convertToDP1Item(mapped, duration) : mapped;
+        if (!converted.success || !converted.item) {
+            return { success: false, coordinate, error: converted.error || 'Item build failed' };
+        }
+        return { success: true, coordinate, item: converted.item, still: converted.still || '' };
+    });
+}
+/**
+ * walkOwner pages through the indexer for an owner, as queryTokensByAddress did.
+ * A failed first page throws; a failed later page keeps what was collected,
+ * which is the indexer path's long-standing behaviour.
+ */
+async function walkOwner(address, limit) {
+    const indexer = loadIndexer();
+    if (limit !== 'all') {
+        const result = await indexer.queryTokensByOwner(address, Math.min(limit, MAX_BOUNDED_LIMIT));
+        if (!result.success) {
+            throw new Error(result.error || 'Indexer owner query failed');
+        }
+        return result.tokens;
+    }
+    const rows = [];
+    for (let offset = 0;; offset += OWNER_PAGE_SIZE) {
+        const result = await indexer.queryTokensByOwner(address, OWNER_PAGE_SIZE, offset);
+        if (!result.success && offset === 0) {
+            throw new Error(result.error || 'Indexer owner query failed');
+        }
+        if (!result.success || result.tokens.length === 0) {
+            return rows;
+        }
+        rows.push(...result.tokens);
+        if (result.tokens.length < OWNER_PAGE_SIZE) {
+            return rows;
+        }
+    }
+}
+/** createIndexerTokenSource builds the indexer provider. */
+function createIndexerTokenSource() {
+    return {
+        name: 'indexer',
+        async resolveTokens(coords, opts = {}) {
+            const raw = await loadIndexer().resolveTokenBatch(coords, opts.duration, opts.onProgress);
+            return coords.map((coordinate, i) => {
+                const result = raw[i];
+                if (result?.success && result.item) {
+                    return { success: true, coordinate, item: result.item, still: result.still || '' };
+                }
+                return { success: false, coordinate, error: result?.error || 'Token not resolved' };
+            });
+        },
+        async listTokensByOwner(address, opts) {
+            const rows = await walkOwner(address, opts.limit);
+            return { results: rowsToResults(rows, opts.duration), skippedUnsupported: 0 };
+        },
+        async listTokensByContract(address, opts) {
+            const limit = opts.limit === 'all' ? MAX_BOUNDED_LIMIT : Math.min(opts.limit, MAX_BOUNDED_LIMIT);
+            const result = await loadIndexer().queryTokensByContract(address, limit);
+            if (!result.success) {
+                throw new Error(result.error || 'Indexer contract query failed');
+            }
+            return { results: rowsToResults(result.tokens, opts.duration), skippedUnsupported: 0 };
+        },
+    };
+}