@feralfile/cli 1.1.1 → 1.2.0

package/dist/src/utilities/fxhash-marketplace.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * fxhash marketplace resolver.
+ *
+ * fxhash's UI exposes:
+ *  - individual iterations under `/iteration/{slug}` (e.g. `garden-monoliths-215`)
+ *    — resolved via `objkt(slug:)` to (contract, onChainId).
+ *  - generative projects (series) under `/project/{slug}` and `/generative/{slug}`
+ *    — resolved via `generativeToken(slug:)` to (contract, first iteration's
+ *    onChainId), which Raster then reverse-looks-up to enumerate the rest of
+ *    the series. Mirrors the AB collection flow.
+ *
+ * Tezos-only: FX1-prefixed gentks live on Tezos. FX2 (EVM) tokens / projects
+ * are out of scope. EVM gentk URLs are caught earlier in the URL parser; EVM
+ * projects under `/project/{slug}` will simply not resolve via the Tezos
+ * GraphQL endpoint and surface as "slug not found".
+ */
+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.resolveFxhashIteration = resolveFxhashIteration;
+exports.resolveFxhashProject = resolveFxhashProject;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+const FXHASH_GRAPHQL = 'https://api.fxhash.xyz/graphql';
+/**
+ * Resolve an fxhash iteration URL slug to its on-chain Tezos coordinates.
+ *
+ * @throws When the slug is unknown, the GraphQL call fails, or the resolved
+ *   objkt is missing its on-chain fields (un-minted / pre-reveal).
+ */
+async function resolveFxhashIteration(slug) {
+    logger.debug(`[fxhash] Resolving iteration slug "${slug}"`);
+    const query = 'query ($slug: String!) { objkt(slug: $slug) { gentkContractAddress onChainId } }';
+    const response = await fetch(FXHASH_GRAPHQL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
+        body: JSON.stringify({ query, variables: { slug } }),
+    });
+    if (!response.ok) {
+        throw new Error(`fxhash GraphQL ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (data.errors && data.errors.length > 0) {
+        throw new Error(`fxhash GraphQL errors: ${data.errors.map((e) => e.message).join('; ')}`);
+    }
+    const objkt = data.data?.objkt;
+    if (!objkt) {
+        throw new Error(`fxhash: no iteration found for slug "${slug}". ` +
+            'Check the URL — slugs come from fxhash.xyz/iteration/{slug}. ' +
+            'Pre-reveal or unminted iterations may not be queryable yet.');
+    }
+    if (!objkt.gentkContractAddress || objkt.onChainId === null) {
+        throw new Error(`fxhash: iteration "${slug}" is missing on-chain coordinates ` +
+            '(gentkContractAddress / onChainId). It may be pre-reveal or unassigned.');
+    }
+    return {
+        chain: 'tezos',
+        contract: objkt.gentkContractAddress,
+        tokenId: String(objkt.onChainId),
+    };
+}
+/**
+ * Resolve an fxhash generative project slug (e.g. `garden-monoliths`) to its
+ * contract + a representative on-chain tokenId — the first minted iteration.
+ * Raster then enumerates the rest of the series via the standard reverse
+ * lookup, identical to the AB collection flow.
+ *
+ * Note: each Objkt has its own `gentkContractAddress`. fxhash projects can
+ * span multiple gentk contracts (V1/V2/V3 mint phases), so we read the contract
+ * off the iteration itself, not the project header.
+ *
+ * @throws When the slug is unknown (Tezos endpoint won't see EVM-only
+ *   projects), the project has no minted iterations, or the GraphQL call
+ *   fails.
+ */
+async function resolveFxhashProject(slug) {
+    logger.debug(`[fxhash] Resolving project slug "${slug}"`);
+    const query = 'query ($slug: String!) {' +
+        '  generativeToken(slug: $slug) {' +
+        '    objkts(skip: 0, take: 1, sort: { iteration: "ASC" }) {' +
+        '      gentkContractAddress' +
+        '      onChainId' +
+        '    }' +
+        '  }' +
+        '}';
+    const response = await fetch(FXHASH_GRAPHQL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
+        body: JSON.stringify({ query, variables: { slug } }),
+    });
+    if (!response.ok) {
+        throw new Error(`fxhash GraphQL ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (data.errors && data.errors.length > 0) {
+        throw new Error(`fxhash GraphQL errors: ${data.errors.map((e) => e.message).join('; ')}`);
+    }
+    const project = data.data?.generativeToken;
+    if (!project) {
+        throw new Error(`fxhash: no project found for slug "${slug}". ` +
+            'Check the URL — slugs come from fxhash.xyz/project/{slug} or /generative/{slug}. ' +
+            'EVM-only projects on fxhash are not covered (FF indexer is Tezos mainnet only for fxhash).');
+    }
+    const firstObjkt = project.objkts?.[0];
+    if (!firstObjkt || !firstObjkt.gentkContractAddress || firstObjkt.onChainId === null) {
+        throw new Error(`fxhash: project "${slug}" has no minted iterations yet, or is pre-reveal. ` +
+            'Paste a specific iteration URL once at least one edition is minted.');
+    }
+    return {
+        chain: 'tezos',
+        contract: firstObjkt.gentkContractAddress,
+        tokenId: String(firstObjkt.onChainId),
+    };
+}

package/dist/src/utilities/index.js

@@ -2,6 +2,39 @@
  * Utilities - Actual function implementations
  * Contains the real logic for querying NFTs and building playlists
  */
+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;
+    };
+})();
 const chalk = require('chalk');
 const nftIndexer = require('./nft-indexer');
 const feedFetcher = require('./feed-fetcher');
@@ -214,7 +247,7 @@ async function queryTokensByAddress(ownerAddress, quantity, duration = 10, optio
  * @returns {Promise<Array>} Array of DP1 playlist items
  */
 async function queryRequirement(requirement, duration = 10) {
-    const { type, blockchain, contractAddress, tokenIds, ownerAddress, playlistName, quantity } = requirement;
+    const { type, blockchain, contractAddress, tokenIds, ownerAddress, playlistName, quantity, artworkId, } = requirement;
     // Handle query_address type
     if (type === 'query_address') {
         // Check if ownerAddress is a domain name (.eth or .tez)
@@ -262,6 +295,19 @@ async function queryRequirement(requirement, duration = 10) {
             return [];
         }
     }
+    if (type === 'feral_file_artwork') {
+        console.log(chalk.cyan(`Resolving Feral File artwork ${artworkId}...`));
+        const { parseFeralFileArtworkId, resolveFeralFileArtwork } = require('./feral-file-artwork');
+        const coords = await resolveFeralFileArtwork(parseFeralFileArtworkId(artworkId));
+        const items = await nftIndexer.getNFTTokenInfoBatch([coords], duration);
+        if (items.length > 0) {
+            console.log(chalk.green(`✓ Got ${items.length} item(s)`));
+        }
+        else {
+            console.log(chalk.yellow('   No items found for Feral File artwork'));
+        }
+        return items;
+    }
     // Handle build_playlist type (original NFT querying logic)
     console.log(chalk.cyan(`Querying ${blockchain}${contractAddress ? ' (' + contractAddress.substring(0, 10) + '...)' : ''}...`));
     let items = [];
@@ -343,11 +389,39 @@ async function buildDP1Playlist(items, title, slug) {
 /**
  * Send playlist to FF1 device
  *
+ * This gateway verifies the playlist before any device transport happens.
+ * Callers in the AI orchestrator and deterministic build path both route
+ * through here, so the delivery policy stays consistent across the CLI.
+ * TODO: Propagate structured send failures consistently from every caller;
+ * buildPlaylistDirect currently preserves the pre-existing non-fatal behavior.
+ *
  * @param {Object} playlist - DP1 playlist
  * @param {string} [deviceName] - Device name
  * @returns {Promise<Object>} Result
  */
 async function sendToDevice(playlist, deviceName) {
+    const playlistVerifier = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
+    const verifyPlaylist = playlistVerifier.verifyPlaylist ||
+        (playlistVerifier.default && playlistVerifier.default.verifyPlaylist) ||
+        playlistVerifier.default;
+    if (typeof verifyPlaylist !== 'function') {
+        return {
+            success: false,
+            error: 'Playlist verifier is not available',
+        };
+    }
+    const verificationResult = await verifyPlaylist(playlist);
+    if (!verificationResult.valid) {
+        return {
+            success: false,
+            error: verificationResult.error || 'Failed to verify playlist before sending',
+            details: verificationResult.details
+                ? verificationResult.details
+                    .map((detail) => `• ${detail.path}: ${detail.message}`)
+                    .join('\n')
+                : undefined,
+        };
+    }
     const { sendPlaylistToDevice } = require('./functions');
     return await sendPlaylistToDevice({ playlist, deviceName });
 }
@@ -367,6 +441,11 @@ function shuffleArray(array) {
 /**
  * Build playlist directly from requirements (deterministic, no AI)
  *
+ * TODO: Treat requested device send and feed publish failures consistently.
+ * This function currently keeps the pre-existing main-branch behavior where
+ * send/publish failures are non-fatal to the playlist build; fix that in a
+ * dedicated follow-up when the command contract changes.
+ *
  * @param {Object} params - Playlist parameters
  * @param {Array<Object>} params.requirements - Array of requirements
  * @param {Object} params.playlistSettings - Playlist settings

package/dist/src/utilities/marketplace-url.js

@@ -0,0 +1,373 @@
+"use strict";
+/**
+ * Marketplace URL parser for `ff-cli find`.
+ *
+ * Accepts user input in any of these forms and returns a normalized result:
+ *  - Marketplace token URL (Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort)
+ *  - Raw on-chain coordinates: "ethereum:0xabc...:123" / "tezos:KT1...:456"
+ *  - Wallet address: 0x{40-hex} (Ethereum) or tz1/tz2/tz3{33} (Tezos)
+ *
+ * The unified entry point is {@link parseFindInput}. Per-marketplace parsers
+ * are exposed for unit testing.
+ *
+ * Series URLs (fxhash `/generative/...`, Feral File `/artworks/...`,
+ * Art Blocks `/projects/...`) are recognized but not resolved in v1 — they
+ * require a per-marketplace API call to derive a representative token. The
+ * parser returns an `unsupported` result with a clear reason so the caller
+ * can surface guidance instead of a generic "could not parse" error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFindInput = parseFindInput;
+exports.parseMarketplaceUrl = parseMarketplaceUrl;
+exports.parseObjkt = parseObjkt;
+exports.parseArtBlocks = parseArtBlocks;
+exports.parseFxhash = parseFxhash;
+exports.parseOpenSea = parseOpenSea;
+exports.parseSuperRare = parseSuperRare;
+exports.parseNeort = parseNeort;
+exports.parseFeralFile = parseFeralFile;
+const ETH_ADDR = /^0x[a-fA-F0-9]{40}$/;
+const TEZOS_ADDR = /^(tz1|tz2|tz3)[1-9A-HJ-NP-Za-km-z]{33}$/;
+const RAW_COORDS = /^(ethereum|tezos):([^:]+):([^:]+)$/i;
+/**
+ * Parse any user-supplied input for the `ff-cli find` command.
+ *
+ * Returns:
+ *  - `{ kind: 'token', ... }`   — successfully extracted on-chain coordinates
+ *  - `{ kind: 'address', ... }` — wallet/artist address (for the artist path)
+ *  - `{ kind: 'unsupported', reason }` — recognized but cannot extract a token
+ *  - `null` — input does not match any recognized form; caller may show help
+ */
+function parseFindInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (ETH_ADDR.test(trimmed)) {
+        return { kind: 'address', chain: 'ethereum', address: trimmed.toLowerCase() };
+    }
+    if (TEZOS_ADDR.test(trimmed)) {
+        return { kind: 'address', chain: 'tezos', address: trimmed };
+    }
+    const rawMatch = RAW_COORDS.exec(trimmed);
+    if (rawMatch) {
+        return {
+            kind: 'token',
+            source: 'raw',
+            coords: {
+                chain: rawMatch[1].toLowerCase(),
+                contract: normalizeContract(rawMatch[2]),
+                tokenId: rawMatch[3],
+            },
+        };
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    return parseMarketplaceUrl(parsedUrl);
+}
+/**
+ * Dispatch a URL to the per-host parser. Returns `null` when the host is
+ * not one of the supported sources.
+ */
+function parseMarketplaceUrl(url) {
+    const host = url.hostname.toLowerCase().replace(/^www\./, '');
+    if (host === 'objkt.com' || host.endsWith('.objkt.com')) {
+        return parseObjkt(url);
+    }
+    if (host === 'artblocks.io' || host.endsWith('.artblocks.io')) {
+        return parseArtBlocks(url);
+    }
+    if (host === 'fxhash.xyz' || host.endsWith('.fxhash.xyz')) {
+        return parseFxhash(url);
+    }
+    if (host === 'feralfile.com' || host.endsWith('.feralfile.com')) {
+        return parseFeralFile(url);
+    }
+    if (host === 'opensea.io' || host.endsWith('.opensea.io')) {
+        return parseOpenSea(url);
+    }
+    if (host === 'superrare.com' || host.endsWith('.superrare.com')) {
+        return parseSuperRare(url);
+    }
+    if (host === 'neort.io' || host.endsWith('.neort.io')) {
+        return parseNeort(url);
+    }
+    return null;
+}
+/**
+ * Lowercase Ethereum contracts; leave Tezos KT1 contracts case-sensitive
+ * (base58 prefix is case-significant on Tezos).
+ */
+function normalizeContract(contract) {
+    return contract.startsWith('0x') ? contract.toLowerCase() : contract;
+}
+/**
+ * Objkt URL forms:
+ *   objkt.com/tokens/{KT1...}/{tokenId}        — raw FA contract
+ *   objkt.com/tokens/{alias}/{tokenId}         — collection alias (e.g. "hicetnunc")
+ *   objkt.com/asset/{KT1...}/{tokenId}         — legacy redirect
+ *
+ * Aliases are resolved to KT1 contracts via
+ * {@link ./objkt-marketplace#resolveObjktAlias} (separate file because the
+ * lookup is async).
+ */
+function parseObjkt(url) {
+    const direct = /^\/(?:tokens|asset)\/(KT[A-Za-z0-9]+)\/(\d+)\/?$/.exec(url.pathname);
+    if (direct) {
+        return {
+            kind: 'token',
+            source: 'objkt',
+            coords: { chain: 'tezos', contract: direct[1], tokenId: direct[2] },
+        };
+    }
+    const alias = /^\/(?:tokens|asset)\/([a-zA-Z][a-zA-Z0-9_-]*)\/(\d+)\/?$/.exec(url.pathname);
+    if (alias) {
+        return { kind: 'objkt-alias', alias: alias[1], tokenId: alias[2] };
+    }
+    if (url.pathname.startsWith('/collections/') || url.pathname.startsWith('/collection/')) {
+        return {
+            kind: 'unsupported',
+            reason: 'Objkt collection URLs are not yet supported in v1. Paste a specific token URL ' +
+                '(objkt.com/tokens/{contract-or-alias}/{tokenId}) or use `tezos:{contract}:{tokenId}`.',
+        };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Objkt URL not recognized: ${url.pathname}. Expected /tokens/{contract-or-alias}/{tokenId}.`,
+    };
+}
+/**
+ * Art Blocks URL forms:
+ *   artblocks.io/token/{0xcontract}-{tokenId}                       — direct token
+ *   artblocks.io/marketplace/collections/{0xcontract}/tokens/{id}   — marketplace UI token
+ *   artblocks.io/collection/{slug}                                  — collection (series)
+ *   artblocks.io/collections/{slug}                                 — plural; 307→singular
+ *
+ * Collection slugs are resolved to (contract, first_tokenId) via
+ * {@link ./ab-marketplace#resolveArtBlocksCollection} (one Hasura GraphQL
+ * call). `/projects/{id}` legacy URLs return 404 on artblocks.io and are
+ * surfaced as a clear unsupported message.
+ */
+function parseArtBlocks(url) {
+    let m = /^\/token\/(0x[a-fA-F0-9]{40})-(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'artblocks',
+            coords: { chain: 'ethereum', contract: m[1].toLowerCase(), tokenId: m[2] },
+        };
+    }
+    m = /^\/marketplace\/collections\/(0x[a-fA-F0-9]{40})\/tokens\/(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'artblocks',
+            coords: { chain: 'ethereum', contract: m[1].toLowerCase(), tokenId: m[2] },
+        };
+    }
+    m = /^\/collections?\/([a-z0-9][a-z0-9-]*)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'ab-collection', slug: m[1] };
+    }
+    if (url.pathname.startsWith('/projects/')) {
+        return {
+            kind: 'unsupported',
+            reason: 'Art Blocks `/projects/{id}` URLs are legacy and no longer resolve on artblocks.io. ' +
+                'Paste the current `/collection/{slug}` URL or a specific token URL.',
+        };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Art Blocks URL not recognized: ${url.pathname}.`,
+    };
+}
+/**
+ * fxhash URL forms (Tezos):
+ *   fxhash.xyz/gentk/FX1-{KT1...}-{tokenId}                  (canonical token URL)
+ *   fxhash.xyz/iteration/{slug}                              (single iteration; resolves via fxhash API)
+ *   fxhash.xyz/project/{slug}                                (series; current UI form)
+ *   fxhash.xyz/generative/{slug}                             (series; legacy URL form, both supported)
+ *   fxhash.xyz/gentk/{numericId}                             (legacy — needs fxhash API)
+ *
+ * Series URLs (`/project/`, `/generative/`) resolve to the project's first
+ * minted iteration via `generativeToken(slug:)`; Raster then enumerates the
+ * rest of the series. EVM-only projects won't be found on the Tezos GraphQL
+ * endpoint and surface as a clean "slug not found" error.
+ *
+ * EVM (FX2-prefixed) gentks are not in scope: the FF indexer does not index
+ * fxhash's EVM contracts in v1.
+ */
+function parseFxhash(url) {
+    const m = /^\/gentk\/FX1-(KT[A-Za-z0-9]+)-(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'fxhash',
+            coords: { chain: 'tezos', contract: m[1], tokenId: m[2] },
+        };
+    }
+    if (/^\/gentk\/FX2-/.test(url.pathname)) {
+        return {
+            kind: 'unsupported',
+            reason: 'fxhash FX2 (EVM) tokens are not supported — FF indexer covers Tezos mainnet only ' +
+                'for fxhash. Paste a Tezos fxhash token or a different marketplace URL.',
+        };
+    }
+    if (/^\/gentk\/\d+\/?$/.test(url.pathname)) {
+        return {
+            kind: 'unsupported',
+            reason: 'fxhash legacy numeric gentk URLs require an fxhash API lookup — not supported in v1. ' +
+                'Paste the FX1-{contract}-{tokenId} form or use `tezos:{contract}:{tokenId}`.',
+        };
+    }
+    const iter = /^\/iteration\/([a-z0-9][a-z0-9-]*)\/?$/.exec(url.pathname);
+    if (iter) {
+        return { kind: 'fxhash-iteration', slug: iter[1] };
+    }
+    const project = /^\/(?:project|generative)\/([a-z0-9][a-z0-9-]*)\/?$/.exec(url.pathname);
+    if (project) {
+        return { kind: 'fxhash-project', slug: project[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `fxhash URL not recognized: ${url.pathname}.`,
+    };
+}
+/**
+ * OpenSea URL forms:
+ *   opensea.io/assets/{chain}/{contract}/{tokenId}
+ *   opensea.io/item/{chain}/{contract}/{tokenId}    — newer naming
+ *   opensea.io/collection/{slug}                    — series slug (not yet)
+ *
+ * Only `ethereum` is in scope; other chains (matic, base, solana, etc.)
+ * fall outside the FF indexer's coverage. Token URLs resolve end-to-end only
+ * when Raster also indexes the underlying series — Raster's coverage of
+ * mainstream PFP collections (Azuki, BAYC, etc.) is partial.
+ */
+function parseOpenSea(url) {
+    const tokenMatch = /^\/(?:assets|item)\/([a-z_]+)\/(0x[a-fA-F0-9]{40})\/(\d+)\/?$/.exec(url.pathname);
+    if (tokenMatch) {
+        const chain = tokenMatch[1];
+        if (chain !== 'ethereum') {
+            return {
+                kind: 'unsupported',
+                reason: `OpenSea ${chain} URLs aren't supported — ff-cli covers Ethereum and Tezos mainnet only. ` +
+                    'Paste an Ethereum-chain OpenSea URL or a Tezos source (Objkt, fxhash).',
+            };
+        }
+        return {
+            kind: 'token',
+            source: 'opensea',
+            coords: { chain: 'ethereum', contract: tokenMatch[2].toLowerCase(), tokenId: tokenMatch[3] },
+        };
+    }
+    if (url.pathname.startsWith('/collection/')) {
+        return {
+            kind: 'unsupported',
+            reason: 'OpenSea `/collection/{slug}` URLs are not yet supported in v1. Paste a specific token ' +
+                'URL (opensea.io/assets/ethereum/{contract}/{tokenId}) or use `ethereum:{contract}:{tokenId}`.',
+        };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `OpenSea URL not recognized: ${url.pathname}.`,
+    };
+}
+/**
+ * SuperRare URL forms (Ethereum-only platform):
+ *   superrare.com/artwork/eth/{contract}/{tokenId}
+ *   superrare.com/collection/{contract}             — per-artist contract page, not supported in v1
+ *   superrare.com/{artist}/{slug}                   — slug form, not supported in v1
+ *
+ * SuperRare's `/artwork/eth/...` URLs encode both the contract and tokenId
+ * directly, so no API call is needed. Token URLs resolve end-to-end only when
+ * Raster also indexes the underlying series; for 1/1 artworks the find flow
+ * falls through to a single-token playlist via the Raster 404 path.
+ *
+ * `/collection/{contract}` URLs on SuperRare point to a per-artist contract
+ * (each SuperRare artist mints from their own ERC-721). There is no direct
+ * contract→series mapping in Raster, so this is surfaced as a specific
+ * unsupported message rather than the generic "URL not recognized" fall-through.
+ */
+function parseSuperRare(url) {
+    const m = /^\/artwork\/eth\/(0x[a-fA-F0-9]{40})\/(\d+)\/?$/.exec(url.pathname);
+    if (m) {
+        return {
+            kind: 'token',
+            source: 'superrare',
+            coords: { chain: 'ethereum', contract: m[1].toLowerCase(), tokenId: m[2] },
+        };
+    }
+    if (/^\/collection\/(0x[a-fA-F0-9]{40})\/?$/.test(url.pathname)) {
+        return {
+            kind: 'unsupported',
+            reason: 'SuperRare `/collection/{contract}` URLs (per-artist contract pages) are not yet ' +
+                'supported in v1. Paste a specific token URL ' +
+                '(superrare.com/artwork/eth/{contract}/{tokenId}) or use ' +
+                '`ethereum:{contract}:{tokenId}`.',
+        };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `SuperRare URL not recognized: ${url.pathname}. Expected ` +
+            '/artwork/eth/{contract}/{tokenId}. For artist-slug URLs, paste the canonical ' +
+            '/artwork/eth/... form (the SuperRare detail page links it under the artwork title).',
+    };
+}
+/**
+ * Neort URL forms (off-chain code-art platform):
+ *   neort.io/art/{id}     — art detail page; id is opaque alphanumeric (~20 chars)
+ *
+ * Neort items are not on-chain, so the find flow handles them specially:
+ * resolve via Neort's public API and build a DP-1 item directly with
+ * `provenance.offChainURI`, bypassing Raster + FF indexer entirely.
+ */
+function parseNeort(url) {
+    const m = /^\/art\/([a-zA-Z0-9]+)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'neort-art', id: m[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Neort URL not recognized: ${url.pathname}. Expected /art/{id}.`,
+    };
+}
+/**
+ * Feral File URL forms (source of truth: feralfile-client app-routing
+ * + collection-routing modules):
+ *   /exhibitions/artwork/{tokenId}       — single artwork by on-chain tokenId
+ *   /exhibitions/series/{slug}           — series detail (multi-token)
+ *   /exhibitions/shows/{slug}            — full exhibition (multiple series)
+ *
+ * These URLs do not include `chain` or `contract`; FF API walks are required
+ * to derive them. The parser stays sync — it returns an `ff-url` marker that
+ * the caller resolves asynchronously via `ff-marketplace#resolveFeralFileToken`.
+ * Tracked for collapse to a single GET in feral-file/ff-exhibition#3039.
+ */
+function parseFeralFile(url) {
+    // Public artwork ids may be numeric (legacy: URL id == on-chain tokenID) or
+    // hex hashes (swapped-id editions). Accept any URL-safe alphanumeric form;
+    // the FF API rejects unknown ids cleanly downstream.
+    let m = /^\/exhibitions\/artwork\/([A-Za-z0-9]+)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'ff-url', urlKind: 'artwork', identifier: m[1] };
+    }
+    m = /^\/exhibitions\/series\/([^/]+)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'ff-url', urlKind: 'series', identifier: m[1] };
+    }
+    m = /^\/exhibitions\/shows\/([^/]+)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'ff-url', urlKind: 'show', identifier: m[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Feral File URL not recognized: ${url.pathname}. Supported: ` +
+            '/exhibitions/artwork/{tokenId}, /exhibitions/series/{slug}, /exhibitions/shows/{slug}.',
+    };
+}