@feralfile/cli 2.10.1 → 4.0.0

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

@@ -0,0 +1,378 @@
+"use strict";
+/**
+ * Raster token source: the opt-in provider under evaluation (feral-file#3576).
+ *
+ * Reads token rows from Raster's public GraphQL API and maps each one to the
+ * vendor-neutral StandardToken, which token-item.ts turns into a DP-1 item
+ * with the same code the indexer path uses. Item ids, provenance, inline
+ * manifests and timing therefore come out identical in shape to the indexer's.
+ *
+ * What Raster cannot do, and how this provider answers instead of guessing:
+ *   - no contract listing query: listTokensByContract throws a capability
+ *     error rather than inventing a probe;
+ *   - a token it does not cover, or a burned one, comes back null: reported
+ *     as a failure, never filled from another vendor (one vendor per run);
+ *   - Feral File metadata is a snapshot: bare ipfs:// and a retired CDN host
+ *     are fixed up in media-url.ts;
+ *   - `media.contentType` is a category, not a MIME type: rasterTimingMime
+ *     turns it into a timing hint that never reaches the document.
+ */
+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.rasterTokenStandard = rasterTokenStandard;
+exports.rasterTokenName = rasterTokenName;
+exports.rasterTimingMime = rasterTimingMime;
+exports.rasterTokenToStandardToken = rasterTokenToStandardToken;
+exports.itemsFromRasterTokens = itemsFromRasterTokens;
+exports.createRasterTokenSource = createRasterTokenSource;
+const viem_1 = require("viem");
+const logger = __importStar(require("../logger"));
+const raster_client_1 = require("./raster-client");
+const media_url_1 = require("./media-url");
+const token_item_1 = require("./token-item");
+const token_source_contract_1 = require("./token-source-contract");
+/** CAIP-2 chains ff-cli builds items for. Others are skipped and counted. */
+const CAIP_TO_CHAIN = {
+    'eip155:1': 'ethereum',
+    'tezos:NetXdQprcVkpaWU': 'tezos',
+};
+/** Raster standards DP-1 can name; others become `other` (see rasterTokenStandard). */
+const RASTER_STANDARDS = {
+    ERC721: 'erc721',
+    ERC1155: 'erc1155',
+    FA2: 'fa2',
+};
+/** Page size for the wallet walk. 100 matches listArtistArtworks; 200 was probed fine. */
+const OWNED_PAGE_SIZE = 100;
+/** NOT_ON_RASTER explains a null `tokenByRef` in the user's terms. */
+const NOT_ON_RASTER = 'Raster has no record of this token (not indexed, burned, or nonexistent)';
+/**
+ * rasterTokenStandard maps Raster's standard enum to a DP-1 standard.
+ *
+ * CRYPTOPUNKS and ORDINAL_INSCRIPTION have no DP-1 name, so they are `other`;
+ * falling through to detection would call a punk `erc721`, which it is not.
+ * A missing standard uses the caller's assertion, then detection.
+ */
+function rasterTokenStandard(raw, chain, contractAddress, asserted) {
+    if (raw) {
+        return RASTER_STANDARDS[raw.toUpperCase()] ?? 'other';
+    }
+    return (0, token_item_1.resolveTokenStandard)(chain, contractAddress, asserted);
+}
+/**
+ * rasterTokenName picks the display title.
+ *
+ * Raster's GraphQL `Token.name` is empty for Art Blocks tokens (a known Raster
+ * bug, feral-file#3546). Art Blocks token ids are project * 1,000,000 + mint,
+ * so "<series> #<mint>" reproduces the title Art Blocks itself publishes,
+ * e.g. "Fidenza #629".
+ */
+function rasterTokenName(token) {
+    const name = (token.name ?? '').trim();
+    if (name) {
+        return name;
+    }
+    const artwork = token.artworks[0];
+    if (artwork?.platform?.id === 'artblocks' && /^\d+$/.test(token.tokenId)) {
+        return `${artwork.title} #${BigInt(token.tokenId) % 1000000n}`;
+    }
+    return artwork?.title || `Token #${token.tokenId}`;
+}
+/**
+ * rasterTimingMime turns Raster's media category into a timing hint.
+ *
+ * The value only steers DP-1 §4.1 timing (video plays its length, web works
+ * get the generative duration, the rest the static duration); it is never
+ * written into the playlist. `previewType` describes how Raster encoded the
+ * preview, not the work (a web app's preview is an image), so it is consulted
+ * only when it says video. Empty means unknown, and the URL extension decides,
+ * which is the indexer path's behaviour for extensionless URLs too.
+ */
+function rasterTimingMime(media) {
+    switch ((media?.contentType ?? '').toLowerCase()) {
+        case 'video':
+            return 'video/*';
+        case 'webapp':
+            return 'text/html';
+        case 'gif':
+            return 'image/gif';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'image':
+            return 'image/*';
+    }
+    return (media?.previewType ?? '').toLowerCase().startsWith('video/') ? 'video/*' : '';
+}
+/**
+ * RASTER_STILL is deliberately empty: Raster items carry no still image.
+ *
+ * Raster's preview renditions (`bits.raster.art/.../7200.avif`) load for a
+ * browser user agent but answer 403 to curl and to the Feral File app's
+ * default `dart:io` client (verified 2026-10-21), and AVIF decoding outside
+ * browsers is not guaranteed. A still lands in `thumbnails.default` of a
+ * manifest the curator signs, so a URL that is dead for some readers is worse
+ * than none. Set a real rendition here only once Raster confirms access that
+ * does not depend on the user agent, and record that evidence here.
+ */
+const RASTER_STILL = '';
+/**
+ * canonicalContract returns the address as the indexer recorded it.
+ *
+ * Raster lowercases EVM addresses; the indexer returned them checksummed, and
+ * the DP-1 item id is sha256 of the address. Checksumming keeps ids and
+ * provenance identical across vendors. Tezos addresses are case-sensitive
+ * Base58 and Raster keeps them as written.
+ */
+function canonicalContract(chain, address) {
+    if (chain !== 'ethereum') {
+        return address;
+    }
+    try {
+        return (0, viem_1.getAddress)(address);
+    }
+    catch {
+        return address;
+    }
+}
+/**
+ * rasterTokenToStandardToken maps one Raster row to the vendor-neutral token.
+ *
+ * @param token - Raster row selected through TOKEN_FIELDS
+ * @param gateways - IPFS gateways for bare ipfs:// sources
+ * @param requested - The coordinate asked for, when there was one
+ * @returns TokenData ready for convertToDP1Item
+ */
+function rasterTokenToStandardToken(token, gateways, requested) {
+    const chain = CAIP_TO_CHAIN[token.chainId];
+    const rawAddress = token.contractAddress ?? requested?.contractAddress;
+    if (!chain || !rawAddress) {
+        return { success: false, error: `Unsupported chain ${token.chainId}` };
+    }
+    const contractAddress = canonicalContract(chain, rawAddress);
+    const artwork = token.artworks[0];
+    const platformId = artwork?.platform?.id ?? null;
+    const name = rasterTokenName(token);
+    const description = (token.description || artwork?.description || '').trim();
+    const artistName = (token.artists[0] ?? artwork?.artists?.[0])?.name ?? '';
+    const sourceUrl = (0, media_url_1.fixUpMediaUrl)(token.media?.contentUrl || token.media?.normalizedContentUrl, platformId, gateways);
+    return {
+        success: true,
+        token: {
+            chain,
+            caip2Chain: token.chainId,
+            contractAddress,
+            tokenId: token.tokenId,
+            standard: rasterTokenStandard(token.tokenStandard, chain, contractAddress, requested?.standard),
+            name,
+            description,
+            image: {
+                url: sourceUrl,
+                mimeType: rasterTimingMime(token.media),
+                thumbnail: RASTER_STILL,
+            },
+            metadata: { attributes: [], artistName },
+            collection: { name: artwork?.title || name, description },
+            burned: false,
+        },
+    };
+}
+/**
+ * itemsFromRasterTokens builds results from rows already in hand.
+ *
+ * Used by the series path of `find`, whose `artwork.tokens` page already
+ * carries every field, and by the wallet walk, so neither pays a second
+ * round trip.
+ */
+function itemsFromRasterTokens(entries, gateways, duration) {
+    return entries.map(({ token, requested }) => {
+        const tokenData = rasterTokenToStandardToken(token, gateways, requested);
+        const coordinate = requested ?? coordinateOf(tokenData, token);
+        if (!tokenData.success) {
+            return { success: false, coordinate, error: tokenData.error ?? 'Unmappable token' };
+        }
+        const converted = (0, token_item_1.convertToDP1Item)(tokenData, duration);
+        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 ?? '' };
+    });
+}
+/** coordinateOf names the coordinate a row describes when nobody asked for it. */
+function coordinateOf(tokenData, token) {
+    return {
+        chain: tokenData.token?.chain ?? token.chainId,
+        contractAddress: tokenData.token?.contractAddress ?? token.contractAddress ?? '',
+        tokenId: token.tokenId,
+    };
+}
+/**
+ * normalizeChain maps a coordinate's chain to Raster's vocabulary, or null.
+ *
+ * The address prefix outranks the caller's chain name: `KT…` is Tezos and
+ * `0x…` is EVM whatever the caller said, mirroring the auto-correction the
+ * indexer path applied. Only Ethereum and Tezos mainnet are supported.
+ */
+function normalizeChain(coord) {
+    if (coord.contractAddress.startsWith('KT')) {
+        return 'tezos';
+    }
+    if (coord.contractAddress.startsWith('0x')) {
+        const chain = coord.chain.toLowerCase();
+        return chain === 'ethereum' || chain === 'eth' || chain === 'evm' ? 'ethereum' : null;
+    }
+    return null;
+}
+/** reportProgress calls a progress callback, which must never break a run. */
+function reportProgress(opts, done, total) {
+    try {
+        opts.onProgress?.(done, total);
+    }
+    catch {
+        /* progress display is best-effort */
+    }
+}
+/** DECIMAL_TOKEN_ID is the only token id shape Raster's BigInt scalar accepts. */
+const DECIMAL_TOKEN_ID = /^\d+$/;
+/**
+ * rejectionFor explains why a coordinate cannot be sent to Raster, or ''.
+ *
+ * Checked before batching because Raster validates every variable of a query
+ * together: one non-decimal token id (`0x1f`, `#12`, a typo) rejects the whole
+ * request, which would fail up to 39 valid neighbours with an unrelated error.
+ */
+function rejectionFor(coord) {
+    if (normalizeChain(coord) === null) {
+        return `Unsupported chain "${coord.chain}" (Ethereum and Tezos mainnet only)`;
+    }
+    if (!DECIMAL_TOKEN_ID.test(String(coord.tokenId ?? '').trim())) {
+        return `Invalid token id "${coord.tokenId}" (expected a decimal integer)`;
+    }
+    return '';
+}
+/**
+ * resolveBatch looks up one batch and turns each answer into a result.
+ * Coordinates that cannot be sent fail on their own; a failed request fails
+ * every coordinate it carried with the same reason.
+ */
+async function resolveBatch(batch, gateways, duration) {
+    const lookups = batch.filter((coord) => rejectionFor(coord) === '');
+    let rows;
+    try {
+        rows = await (0, raster_client_1.fetchTokensByRef)(lookups.map((coord) => ({
+            chain: normalizeChain(coord),
+            contractAddress: coord.contractAddress,
+            tokenId: String(coord.tokenId).trim(),
+        })));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return batch.map((coordinate) => {
+            const rejection = rejectionFor(coordinate);
+            return { success: false, coordinate, error: rejection || message };
+        });
+    }
+    const byCoord = new Map(lookups.map((coord, i) => [coord, rows[i]]));
+    return batch.map((coordinate) => resolveOne(coordinate, byCoord, gateways, duration));
+}
+/** resolveOne turns one coordinate's row (or its absence) into a result. */
+function resolveOne(coordinate, rows, gateways, duration) {
+    const rejection = rejectionFor(coordinate);
+    if (rejection) {
+        return { success: false, coordinate, error: rejection };
+    }
+    const row = rows.get(coordinate);
+    if (!row) {
+        return { success: false, coordinate, error: NOT_ON_RASTER };
+    }
+    return itemsFromRasterTokens([{ token: row, requested: coordinate }], gateways, duration)[0];
+}
+/**
+ * walkOwnedTokens pages through an address's holdings until `limit` supported
+ * tokens are collected or the walk ends. Any page failure throws: a silently
+ * truncated wallet would look like a complete one.
+ */
+async function walkOwnedTokens(address, limit) {
+    const tokens = [];
+    let skippedUnsupported = 0;
+    let after;
+    do {
+        const page = await (0, raster_client_1.fetchTokensOwned)(address, { first: OWNED_PAGE_SIZE, after });
+        for (const token of page.tokens) {
+            if (!CAIP_TO_CHAIN[token.chainId] || !token.contractAddress) {
+                skippedUnsupported += 1;
+            }
+            else if (limit === 'all' || tokens.length < limit) {
+                tokens.push(token);
+            }
+        }
+        after = page.nextCursor ?? undefined;
+    } while (after && (limit === 'all' || tokens.length < limit));
+    return { tokens, skippedUnsupported };
+}
+/**
+ * createRasterTokenSource builds the Raster provider.
+ *
+ * Batches run one after another: 40 tokens per request already turns the
+ * ff-cli#132 case (43 tokens, ~10 minutes on the indexer) into two requests,
+ * and sequential batches keep load on an unmetered beta API predictable.
+ *
+ * @param gateways - Resolved IPFS gateways from config
+ */
+function createRasterTokenSource(gateways) {
+    return {
+        name: 'raster',
+        async resolveTokens(coords, opts = {}) {
+            const results = [];
+            for (let i = 0; i < coords.length; i += raster_client_1.RASTER_TOKEN_BATCH_SIZE) {
+                const batch = coords.slice(i, i + raster_client_1.RASTER_TOKEN_BATCH_SIZE);
+                results.push(...(await resolveBatch(batch, gateways, opts.duration)));
+                reportProgress(opts, results.length, coords.length);
+            }
+            logger.debug(`[Raster] Resolved ${results.filter((r) => r.success).length}/${coords.length}`);
+            return results;
+        },
+        async listTokensByOwner(address, opts) {
+            const walked = await walkOwnedTokens(address, opts.limit);
+            const entries = walked.tokens.map((token) => ({ token }));
+            return {
+                results: itemsFromRasterTokens(entries, gateways, opts.duration),
+                skippedUnsupported: walked.skippedUnsupported,
+            };
+        },
+        async listTokensByContract() {
+            throw new token_source_contract_1.TokenSourceCapabilityError(token_source_contract_1.RASTER_CANNOT_LIST_CONTRACT);
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Token source factory: the one place that decides which vendor answers.
+ *
+ * Commands call getTokenSource() and see only the TokenSource contract.
+ * The Feral File indexer (ff-indexer-v2) is the default. Raster is opt-in with
+ * `tokenSource: "raster"` (or FF_TOKEN_SOURCE=raster) while it is evaluated:
+ * its data still has open bugs (feral-file#3546), so it is not the default
+ * until they are fixed (owner decision, 2026-10-22). There is no fallback
+ * between providers: one vendor answers a whole run (feral-file#3576).
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTokenSource = createTokenSource;
+exports.getTokenSource = getTokenSource;
+const config_1 = require("../config");
+const token_source_indexer_1 = require("./token-source-indexer");
+const token_source_raster_1 = require("./token-source-raster");
+__exportStar(require("./token-source-contract"), exports);
+/**
+ * createTokenSource builds the provider a configuration selects.
+ *
+ * @param config - Resolved token source configuration
+ * @returns The selected provider
+ */
+function createTokenSource(config) {
+    if (config.source === 'raster') {
+        return (0, token_source_raster_1.createRasterTokenSource)(config.ipfsGateways);
+    }
+    return (0, token_source_indexer_1.createIndexerTokenSource)();
+}
+/** getTokenSource builds the provider from the current configuration. */
+function getTokenSource() {
+    return createTokenSource((0, config_1.getTokenSourceConfig)());
+}