@feralfile/cli 1.4.0 → 1.6.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "1.4.0",
+    "version": "1.6.0",
     "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
     "repository": {
         "type": "git",

package/dist/src/commands/find.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCommand = void 0;
+exports.buildRasterMediaItems = buildRasterMediaItems;
 exports.parseLimitOption = parseLimitOption;
 exports.decideActions = decideActions;
 const commander_1 = require("commander");
@@ -68,7 +69,7 @@ const DP1_MAX_ITEMS = 1024;
 const RASTER_PAGE_SIZE = 100;
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
-    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
+    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
     .option('-p, --play', 'Play the playlist on an FF1 device after building')
@@ -83,7 +84,7 @@ exports.findCommand = new commander_1.Command('find')
         const parsed = (0, marketplace_url_1.parseFindInput)(input);
         if (!parsed) {
             console.error(chalk_1.default.red('Could not understand input.'));
-            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse. ' +
+            console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse, Raster. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
             process.exit(1);
@@ -109,34 +110,64 @@ exports.findCommand = new commander_1.Command('find')
         }
         console.log();
         const userLimit = parseLimitOption(options.limit);
-        const seriesTotal = target.kind === 'series' ? target.summary.tokenCount : 1;
         // Implicit cap: no --limit + series > 1024 → cap to DP-1 max with a
         // clear warning. Explicit `--limit > 1024` was already rejected by
         // parseLimitOption, so reaching here means either capped-by-default or
         // the user picked a value within spec.
         const limit = Math.min(userLimit, DP1_MAX_ITEMS);
-        if (userLimit === Number.POSITIVE_INFINITY && seriesTotal > DP1_MAX_ITEMS) {
-            console.log(chalk_1.default.yellow(`Series has ${seriesTotal} tokens; DP-1 caps playlists at ${DP1_MAX_ITEMS}. ` +
+        // Raster's GraphQL API exposes no series token counts, so enumerate
+        // tokens first (up to the effective limit) and confirm with the real
+        // number afterward. `hasMore` means the series continues past `limit`.
+        let tokens;
+        let seriesHasMore = false;
+        if (target.kind === 'series') {
+            const fetched = await fetchTokens(target.summary, limit);
+            tokens = fetched.tokens;
+            seriesHasMore = fetched.hasMore;
+        }
+        else {
+            tokens = [{ ...target.coords, mediaUrl: null, mediaType: null }];
+        }
+        if (tokens.length === 0) {
+            console.error(chalk_1.default.red('Series has no tokens on supported chains (Ethereum + Tezos mainnet).'));
+            process.exit(1);
+        }
+        if (userLimit === Number.POSITIVE_INFINITY && seriesHasMore) {
+            console.log(chalk_1.default.yellow(`Series has more than ${DP1_MAX_ITEMS} tokens; DP-1 caps playlists at ${DP1_MAX_ITEMS}. ` +
                 `Building with the first ${DP1_MAX_ITEMS} — pass \`--limit N\` (≤ ${DP1_MAX_ITEMS}) for fewer.`));
             console.log();
         }
-        const willInclude = Math.min(seriesTotal, limit);
-        const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(willInclude, seriesTotal));
+        const shouldBuild = !!options.yes ||
+            !!options.output ||
+            (await confirmMakePlaylist(tokens.length, seriesHasMore));
         if (!shouldBuild) {
             console.log(chalk_1.default.dim('Cancelled.'));
             return;
         }
-        const tokens = target.kind === 'series' ? await fetchTokens(target.summary, limit) : [target.coords];
         console.log(chalk_1.default.dim(`Indexing ${tokens.length} token${tokens.length === 1 ? '' : 's'} via FF indexer...`));
         // Second positional arg on getNFTTokenInfoBatch is `duration` (DP-1 item
         // display seconds), not concurrency — concurrency is hardcoded inside.
         // Omit it for auto timing: video/audio items carry no duration and play
         // their natural length (DP-1 §4.1); static items get the config default.
-        const items = await getNFTTokenInfoBatch(tokens.map((t) => ({
+        let items = await getNFTTokenInfoBatch(tokens.map((t) => ({
             chain: t.chain,
             contractAddress: t.contract,
             tokenId: t.tokenId,
         })));
+        // FF-indexer bypass for Raster-minted tokens. The indexer doesn't carry
+        // Raster's tokens, so it returns nothing — but Raster handed us each
+        // token's playable `media.contentUrl`. Build DP-1 items straight from
+        // that (off-chain provenance, same shape as the Neort path), so the
+        // series still builds into a signable, verifiable playlist instead of
+        // failing the way it did before. The indexer is tried first so tokens
+        // it *can* resolve keep their richer on-chain provenance.
+        if (!Array.isArray(items) || items.length === 0) {
+            const rasterItems = buildRasterMediaItems(tokens, target);
+            if (rasterItems.length > 0) {
+                console.log(chalk_1.default.dim(`  FF indexer returned nothing; building ${rasterItems.length} item${rasterItems.length === 1 ? '' : 's'} directly from Raster media.`));
+                items = rasterItems;
+            }
+        }
         if (!Array.isArray(items) || items.length === 0) {
             console.error(chalk_1.default.red('No tokens could be indexed; cannot build playlist.'));
             console.error(chalk_1.default.dim('  The FF indexer may be under load when warming a series of previously-unseen tokens.'));
@@ -201,33 +232,42 @@ async function resolveTarget(parsed, skipPrompt) {
         const coords = await (0, verse_marketplace_1.resolveVerseSeries)(parsed.slug);
         return resolveCoords(coords);
     }
+    if (parsed.kind === 'raster-artwork') {
+        const summary = await (0, raster_client_1.resolveSlugToArtwork)(parsed.slug);
+        if (summary === null) {
+            throw new Error(`No artwork found on Raster for slug "${parsed.slug}". ` +
+                'Check the URL — Raster artwork URLs are raster.art/artwork/{slug}.');
+        }
+        return { kind: 'series', summary };
+    }
     if (parsed.kind === 'address') {
-        const artistId = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
-        if (artistId === null) {
+        const artist = await (0, raster_client_1.resolveAddressToArtist)(parsed.address);
+        if (artist === null) {
             throw new Error(`No artist found on Raster for address ${parsed.address}. ` +
                 'Raster indexes artists by their on-chain addresses; this address may not yet be claimed.');
         }
-        const catalog = await (0, raster_client_1.listArtistArtworks)(artistId);
+        const catalog = await (0, raster_client_1.listArtistArtworks)(artist.id);
         if (catalog.length === 0) {
             throw new Error('Artist has no artworks indexed on Raster.');
         }
         const picked = await pickFromCatalog(catalog, skipPrompt);
-        const summary = await (0, raster_client_1.getArtworkSummary)(picked.artworkId);
-        return { kind: 'series', summary };
+        return {
+            kind: 'series',
+            summary: { artworkId: picked.artworkId, title: picked.title, artists: [artist] },
+        };
     }
     // `unsupported` is handled upstream; this branch keeps the type narrowing honest.
     throw new Error(`Unsupported parse result: ${parsed.kind}`);
 }
 /**
- * Resolve on-chain coords to a target. If Raster doesn't index this token
- * (404), fall back to single-token mode so we still build something playable.
+ * Resolve on-chain coords to a target. If Raster doesn't index this token,
+ * fall back to single-token mode so we still build something playable.
  */
 async function resolveCoords(coords) {
-    const lookup = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
-    if (lookup === null) {
+    const summary = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
+    if (summary === null) {
         return { kind: 'single', coords };
     }
-    const summary = await (0, raster_client_1.getArtworkSummary)(lookup.artworkId);
     return { kind: 'series', summary };
 }
 /**
@@ -242,6 +282,32 @@ function playlistTitleFor(target, items) {
     }
     return items[0]?.title ?? `Token ${target.coords.tokenId}`;
 }
+/**
+ * Build DP-1 items directly from Raster's per-token media, bypassing the FF
+ * indexer. Used as a fallback when the indexer resolves nothing — tokens
+ * without a Raster `mediaUrl` are dropped (nothing playable to point at).
+ *
+ * Item shape matches the Neort off-chain path (`buildUrlItem` →
+ * `provenance.offChainURI`), so the resulting playlist signs and verifies
+ * normally. Titles are "<Series> #<tokenId>" for series, falling back to the
+ * series/coords title for a single token.
+ */
+function buildRasterMediaItems(tokens, target) {
+    const seriesTitle = target.kind === 'series' ? target.summary.title : undefined;
+    const items = [];
+    for (const t of tokens) {
+        if (!t.mediaUrl) {
+            continue;
+        }
+        const title = seriesTitle ? `${seriesTitle} #${t.tokenId}` : `Token ${t.tokenId}`;
+        // No explicit duration: auto timing (video/audio play their natural
+        // length). `mediaType` carries Raster's type so an extensionless IPFS
+        // contentUrl is still classified correctly — otherwise a video would be
+        // stamped a fixed duration and play as a still.
+        items.push(buildUrlItem(t.mediaUrl, undefined, { title, mimeType: t.mediaType ?? undefined }));
+    }
+    return items;
+}
 function parseLimitOption(limitStr) {
     if (limitStr === undefined) {
         return Number.POSITIVE_INFINITY;
@@ -258,11 +324,17 @@ function parseLimitOption(limitStr) {
     }
     return n;
 }
+/**
+ * Enumerate series tokens from Raster up to `limit`. `hasMore` reports
+ * whether the series continues past what was collected — the API exposes
+ * no total counts, so this is all the size information the flow gets.
+ */
 async function fetchTokens(summary, limit) {
     const collected = [];
     let cursor;
     let skipped = 0;
-    while (collected.length < limit) {
+    let hasMore = false;
+    for (;;) {
         const page = await (0, raster_client_1.listArtworkTokens)(summary.artworkId, {
             cursor,
             pageSize: RASTER_PAGE_SIZE,
@@ -270,15 +342,22 @@ async function fetchTokens(summary, limit) {
         skipped += page.skippedUnsupported;
         for (const t of page.tokens) {
             if (collected.length >= limit) {
+                hasMore = true;
                 break;
             }
             collected.push({
                 chain: t.chain,
                 contract: t.contractAddress,
                 tokenId: t.tokenId,
+                mediaUrl: t.mediaUrl,
+                mediaType: t.mediaType,
             });
         }
-        if (page.nextCursor === null) {
+        if (hasMore || page.nextCursor === null) {
+            break;
+        }
+        if (collected.length >= limit) {
+            hasMore = true;
             break;
         }
         cursor = page.nextCursor;
@@ -286,7 +365,7 @@ async function fetchTokens(summary, limit) {
     if (skipped > 0) {
         console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (FF indexer covers eth + tezos mainnet only).`));
     }
-    return collected;
+    return { tokens: collected, hasMore };
 }
 async function pickFromCatalog(catalog, skipPrompt) {
     if (catalog.length === 1 || skipPrompt) {
@@ -294,8 +373,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
     }
     console.log(chalk_1.default.cyan(`Found ${catalog.length} artworks for this artist:`));
     catalog.forEach((row, i) => {
-        const count = `${row.tokenCount} token${row.tokenCount === 1 ? '' : 's'}`;
-        console.log(chalk_1.default.dim(`  ${i}: ${row.title} (${count})`));
+        console.log(chalk_1.default.dim(`  ${i}: ${row.title}`));
     });
     console.log();
     const prompt = (0, prompt_1.createPrompt)();
@@ -310,9 +388,9 @@ async function pickFromCatalog(catalog, skipPrompt) {
     }
     return catalog[index];
 }
-async function confirmMakePlaylist(count, total) {
-    const noun = total === 1 ? 'token' : 'tokens';
-    const label = count < total ? `${count} of ${total} ${noun}` : `${count} ${noun}`;
+async function confirmMakePlaylist(count, hasMore) {
+    const noun = count === 1 ? 'token' : 'tokens';
+    const label = hasMore ? `the first ${count} ${noun}` : `${count} ${noun}`;
     const prompt = (0, prompt_1.createPrompt)();
     const yes = await (0, prompt_1.promptYesNo)(prompt.ask, `Build playlist with ${label}?`, true);
     prompt.close();
@@ -488,7 +566,7 @@ async function runNeortFind(id, options) {
     console.log(chalk_1.default.cyan(`Neort — ${artistLabel} — ${art.title}`));
     console.log(chalk_1.default.dim('  (Off-chain platform; building a one-item playlist directly from Neort.)'));
     console.log();
-    const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(1, 1));
+    const shouldBuild = !!options.yes || !!options.output || (await confirmMakePlaylist(1, false));
     if (!shouldBuild) {
         console.log(chalk_1.default.dim('Cancelled.'));
         return;

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

@@ -26,6 +26,7 @@ exports.parseOpenSea = parseOpenSea;
 exports.parseSuperRare = parseSuperRare;
 exports.parseNeort = parseNeort;
 exports.parseVerse = parseVerse;
+exports.parseRaster = parseRaster;
 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}$/;
@@ -101,6 +102,9 @@ function parseMarketplaceUrl(url) {
     if (host === 'verse.works' || host.endsWith('.verse.works')) {
         return parseVerse(url);
     }
+    if (host === 'raster.art' || host.endsWith('.raster.art')) {
+        return parseRaster(url);
+    }
     return null;
 }
 /**
@@ -382,6 +386,27 @@ function parseVerse(url) {
             '/items/ethereum/{contract}/{tokenId} or /series/{slug}.',
     };
 }
+/**
+ * Raster URL forms (raster.art):
+ *   raster.art/artwork/{slug}   — artwork (series) detail page
+ *
+ * Unlike the other marketplaces, Raster is already the find flow's backend
+ * resolver — so a Raster URL resolves to an artwork by slug via
+ * `artworkBySlug` and (crucially) builds DP-1 items straight from Raster's
+ * own `media.contentUrl`, bypassing the FF indexer the way Neort does. This
+ * is what lets Raster-minted tokens (which the FF indexer doesn't carry)
+ * build a verifiable playlist without `--skip-verify`.
+ */
+function parseRaster(url) {
+    const m = /^\/artwork\/([A-Za-z0-9][A-Za-z0-9_-]*)\/?$/.exec(url.pathname);
+    if (m) {
+        return { kind: 'raster-artwork', slug: m[1] };
+    }
+    return {
+        kind: 'unsupported',
+        reason: `Raster URL not recognized: ${url.pathname}. Expected /artwork/{slug}.`,
+    };
+}
 /**
  * Feral File URL forms (source of truth: feralfile-client app-routing
  * + collection-routing modules):

package/dist/src/utilities/playlist-builder.js

@@ -536,6 +536,10 @@ function detectMimeType(url) {
  *   (video/audio URLs play their natural length per DP-1 §4.1)
  * @param {Object} [options] - Optional configuration
  * @param {string} [options.title] - Optional item title override
+ * @param {string} [options.mimeType] - Source media type hint for timing
+ *   (DP-1 §4.1). Needed when the URL has no file extension to detect from —
+ *   e.g. extensionless IPFS gateway URLs, where without this hint a video
+ *   would be misclassified as a static image and stamped a fixed duration.
  * @returns {Object} DP1 playlist item
  */
 function buildUrlItem(url, duration, options = {}) {
@@ -580,7 +584,7 @@ function buildUrlItem(url, duration, options = {}) {
             margin: 0,
         },
     };
-    return applyItemTiming(item, { sourceUrl }, duration);
+    return applyItemTiming(item, { sourceUrl, mimeType: options.mimeType }, duration);
 }
 module.exports = {
     convertTokenToDP1Item,

package/dist/src/utilities/raster-client.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * Raster API client (kit.raster.art)
+ * Raster API client (api.raster.art — public GraphQL API).
  *
- * Resolves on-chain coordinates and artist addresses into Raster `artwork_id`
- * (series) and `artist_id` (catalog) — the inputs the `ff-cli find` flow needs
+ * Resolves on-chain coordinates and artist addresses into Raster artworks
+ * (series) and artists (catalog) — the inputs the `ff-cli find` flow needs
  * before handing tokens to the FF GraphQL indexer for DP-1 conversion.
  *
  * This module is pure data: it does not construct DP-1 items, send anything
@@ -14,6 +14,14 @@
  * mainnet. Token lists are filtered here at the CAIP level and a
  * `skippedUnsupported` count is surfaced so callers can warn-skip without
  * walking every row themselves.
+ *
+ * API notes (v0.1.0, https://docs.api.raster.art/):
+ *  - Auth: `x-api-key` header, sent when RASTER_API_KEY is set in the
+ *    environment. The endpoint currently answers without a key; the docs
+ *    declare one required, so the hook is wired in ahead of enforcement.
+ *  - Not-found is a `null` query field, not an HTTP 404.
+ *  - Connections expose no total counts — callers learn series size by
+ *    paginating, so the find flow fetches before it prompts.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -49,130 +57,137 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RasterNotFoundError = void 0;
 exports.resolveTokenToArtwork = resolveTokenToArtwork;
-exports.getArtworkSummary = getArtworkSummary;
+exports.resolveSlugToArtwork = resolveSlugToArtwork;
 exports.resolveAddressToArtist = resolveAddressToArtist;
 exports.listArtworkTokens = listArtworkTokens;
 exports.listArtistArtworks = listArtistArtworks;
 exports.formatSummaryLine = formatSummaryLine;
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
-const RASTER_BASE_URL = 'https://kit.raster.art';
+const DEFAULT_RASTER_GRAPHQL_URL = 'https://api.raster.art/graphql';
 // CAIP-2 chain IDs for the chains the FF indexer supports.
 // Tezos mainnet's CAIP form uses the genesis block hash (NetXdQprcVkpaWU),
 // not the human-readable "tezos:mainnet" — Raster returns the hash form on
-// token rows and rejects "tezos:mainnet" with HTTP 400.
+// token rows and resolves nothing for "tezos:mainnet".
 const CAIP_TO_INDEXER_CHAIN = {
     'eip155:1': 'ethereum',
     'tezos:NetXdQprcVkpaWU': 'tezos',
 };
-function stripContractChainPrefix(raw) {
-    const slash = raw.indexOf('/');
-    return slash >= 0 ? raw.slice(slash + 1) : raw;
-}
+const INDEXER_CHAIN_TO_CAIP = {
+    ethereum: 'eip155:1',
+    tezos: 'tezos:NetXdQprcVkpaWU',
+};
 function caipToIndexerChain(caip) {
     return CAIP_TO_INDEXER_CHAIN[caip] ?? null;
 }
 /**
- * Thrown when Raster returns 404 for a requested path. Used as a soft signal
- * by callers that have a fallback path (e.g. `find` falls back to a
- * single-token playlist when Raster doesn't index the artwork).
+ * POST one GraphQL operation to Raster and return `data`.
+ *
+ * Throws on HTTP errors and on GraphQL `errors` entries. "Not found" never
+ * lands here — Raster models it as a null query field with no error, so
+ * callers check their own field for null.
  */
-class RasterNotFoundError extends Error {
-    notFound = true;
-    constructor(path) {
-        super(`Raster: not found (${path})`);
-        this.name = 'RasterNotFoundError';
+async function rasterQuery(query, variables) {
+    const endpoint = process.env.RASTER_API_URL ?? DEFAULT_RASTER_GRAPHQL_URL;
+    logger.debug(`[Raster] POST ${endpoint} ${JSON.stringify(variables)}`);
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': user_agent_1.USER_AGENT,
+    };
+    const apiKey = process.env.RASTER_API_KEY;
+    if (apiKey) {
+        headers['x-api-key'] = apiKey;
     }
-}
-exports.RasterNotFoundError = RasterNotFoundError;
-async function rasterFetch(path) {
-    const url = `${RASTER_BASE_URL}${path}`;
-    logger.debug(`[Raster] GET ${url}`);
-    const response = await fetch(url, {
-        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ query, variables }),
     });
-    if (response.status === 404) {
-        throw new RasterNotFoundError(path);
-    }
     if (!response.ok) {
         const body = await response.text();
-        throw new Error(`Raster API ${response.status} ${response.statusText} for ${path}: ${body.slice(0, 200)}`);
+        throw new Error(`Raster API ${response.status} ${response.statusText}: ${body.slice(0, 200)}`);
     }
-    return (await response.json());
+    const payload = (await response.json());
+    if (payload.errors && payload.errors.length > 0) {
+        throw new Error(`Raster API error: ${payload.errors.map((e) => e.message).join('; ')}`);
+    }
+    if (payload.data === undefined) {
+        throw new Error('Raster API returned no data.');
+    }
+    return payload.data;
+}
+function toRasterArtist(raw) {
+    return { id: raw.id, name: raw.name ?? 'Unknown artist', slug: raw.slug };
 }
 /**
- * Resolve a token's on-chain coordinates to its Raster artwork (series) id.
+ * Resolve a token's on-chain coordinates to its Raster artwork (series).
  *
- * Accepts either a CAIP chain id (`eip155:1`) or human slug (`ethereum`) —
- * Raster handles both. Returns `null` when Raster doesn't index this token
- * (HTTP 404); callers can fall back to a single-token playlist in that case.
- * Other Raster errors throw normally.
+ * One round trip: `tokenByRef` returns the artwork with artists inline, so
+ * this yields the full summary directly. Returns `null` when Raster doesn't
+ * index this token; callers fall back to a single-token playlist in that
+ * case. Tokens occasionally belong to multiple artworks; the first one is
+ * Raster's primary association.
  */
 async function resolveTokenToArtwork(chain, contract, tokenId) {
-    const path = `/token/${encodeURIComponent(chain)}` +
-        `/${encodeURIComponent(contract)}` +
-        `/${encodeURIComponent(tokenId)}`;
-    try {
-        const data = await rasterFetch(path);
-        return {
-            artworkId: data.artwork.id,
-            artworkTitle: data.artwork.title,
-        };
-    }
-    catch (error) {
-        if (error instanceof RasterNotFoundError) {
-            return null;
-        }
-        throw error;
+    const data = await rasterQuery(`query ResolveToken($ref: TokenRefInput!) {
+      tokenByRef(ref: $ref) {
+        artworks { id title artists { id name slug } }
+      }
+    }`, {
+        ref: {
+            chainId: INDEXER_CHAIN_TO_CAIP[chain],
+            contractAddress: contract,
+            tokenId,
+        },
+    });
+    const artwork = data.tokenByRef?.artworks?.[0];
+    if (!artwork) {
+        return null;
     }
+    return {
+        artworkId: artwork.id,
+        title: artwork.title,
+        artists: (artwork.artists ?? []).map(toRasterArtist),
+    };
 }
 /**
- * Get the full Raster artwork summary suitable for the one-line resolve
- * message ("Snowfro — send/receive — 8977 tokens") and downstream UX.
+ * Resolve a `raster.art/artwork/{slug}` URL to its artwork (series) summary.
+ *
+ * One round trip via `artworkBySlug`. Returns `null` when the slug is
+ * unknown (Raster models not-found as a null query field, not an HTTP 404).
  */
-async function getArtworkSummary(artworkId) {
-    const data = await rasterFetch(`/artwork/${artworkId}`);
+async function resolveSlugToArtwork(slug) {
+    const data = await rasterQuery(`query ResolveSlug($slug: String!) {
+      artworkBySlug(slug: $slug) {
+        id
+        title
+        artists { id name slug }
+      }
+    }`, { slug });
+    const artwork = data.artworkBySlug;
+    if (!artwork) {
+        return null;
+    }
     return {
-        artworkId: data.id,
-        title: data.title,
-        artists: data.artists ?? [],
-        tokenCount: data.token_count,
-        editionSize: data.edition_size,
-        isEdition: data.is_edition,
-        hasOneOfOneTokens: data.has_one_of_one_tokens,
-        platforms: data.platforms ?? [],
-        contractAddresses: data.contract_addresses ?? [],
+        artworkId: artwork.id,
+        title: artwork.title,
+        artists: (artwork.artists ?? []).map(toRasterArtist),
     };
 }
 /**
- * Resolve an artist's wallet address to a Raster artist id via `/search`.
+ * Resolve a wallet address to the Raster artist who claims it.
  *
- * `/artist/{id}` does not accept raw addresses (404), so we bridge through
- * the multi-search endpoint and pick the artist hit whose `addresses` list
- * contains the input. Returns `null` when no artist matches.
+ * The `address` query carries artist associations directly (the old REST
+ * API needed a `/search` bridge). Returns `null` when no artist claims the
+ * address. Checksummed Ethereum input is normalized server-side.
  */
 async function resolveAddressToArtist(address) {
-    const normalized = address.trim().toLowerCase();
-    const data = await rasterFetch(`/search?query=${encodeURIComponent(address)}`);
-    for (const result of data.results ?? []) {
-        for (const hit of result.hits ?? []) {
-            const doc = hit.document;
-            if (doc.data_type !== 'artist') {
-                continue;
-            }
-            const addrs = (doc.addresses ?? []).map((a) => a.toLowerCase());
-            if (!addrs.includes(normalized)) {
-                continue;
-            }
-            const parsed = Number.parseInt(doc.data_pk, 10);
-            if (Number.isFinite(parsed)) {
-                return parsed;
-            }
-        }
-    }
-    return null;
+    const data = await rasterQuery(`query ResolveAddress($address: String!) {
+      address(address: $address) { artists { id name slug } }
+    }`, { address: address.trim() });
+    const artist = data.address?.artists?.[0];
+    return artist ? toRasterArtist(artist) : null;
 }
 /**
  * List tokens in a Raster artwork (series), one page at a time.
@@ -183,70 +198,83 @@ async function resolveAddressToArtist(address) {
  * warn-skip line instead of one per token.
  *
  * Pagination: pass the returned `nextCursor` back as `options.cursor`.
- * `nextCursor` is `null` on the final page. Raster signals end-of-stream by
- * returning `cursor === total_count`; that is normalized to `null` here.
+ * `nextCursor` is `null` on the final page. The API exposes no total count;
+ * the only way to learn a series' size is to walk it.
  */
 async function listArtworkTokens(artworkId, options = {}) {
-    const params = new URLSearchParams();
-    if (options.cursor !== undefined) {
-        params.set('cursor', String(options.cursor));
-    }
-    if (options.pageSize !== undefined) {
-        params.set('page_size', String(options.pageSize));
+    const data = await rasterQuery(`query ArtworkTokens($id: ID!, $first: Int, $after: String) {
+      artwork(id: $id) {
+        tokens(first: $first, after: $after) {
+          nodes { chainId contractAddress tokenId media { contentUrl contentType previewType } }
+          pageInfo { hasNextPage endCursor }
+        }
+      }
+    }`, { id: artworkId, first: options.pageSize ?? null, after: options.cursor ?? null });
+    if (!data.artwork) {
+        throw new Error(`Raster: artwork ${artworkId} not found.`);
     }
-    const qs = params.toString();
-    const path = `/artwork/${artworkId}/tokens${qs ? `?${qs}` : ''}`;
-    const data = await rasterFetch(path);
     const tokens = [];
     let skippedUnsupported = 0;
-    for (const raw of data.tokens ?? []) {
-        const chain = caipToIndexerChain(raw.chain_id);
-        if (!chain) {
+    for (const raw of data.artwork.tokens.nodes) {
+        const chain = caipToIndexerChain(raw.chainId);
+        if (!chain || !raw.contractAddress) {
             skippedUnsupported += 1;
             continue;
         }
         tokens.push({
-            caipChain: raw.chain_id,
             chain,
-            contractAddress: stripContractChainPrefix(raw.contract_address),
-            tokenId: raw.token_id,
+            contractAddress: raw.contractAddress,
+            tokenId: raw.tokenId,
+            mediaUrl: raw.media?.contentUrl ?? null,
+            // Prefer a real MIME (`contentType`) when Raster populates it; today it
+            // is usually empty, so fall back to the category-prefixed `previewType`.
+            mediaType: raw.media?.contentType || raw.media?.previewType || null,
         });
     }
-    const rawCursor = data.cursor;
-    const nextCursor = rawCursor === null || rawCursor >= data.total_count ? null : rawCursor;
+    const { hasNextPage, endCursor } = data.artwork.tokens.pageInfo;
     return {
         tokens,
-        totalCount: data.total_count,
-        nextCursor,
+        nextCursor: hasNextPage && endCursor ? endCursor : null,
         skippedUnsupported,
     };
 }
 /**
- * List an artist's full catalog as light artwork rows (id, title, token count,
- * edition flag, mint date). Use {@link getArtworkSummary} when full details
- * are needed for a specific row.
+ * List an artist's full catalog as light artwork rows (id + title — the
+ * API exposes no per-artwork token counts or mint dates yet).
  *
- * The endpoint returns the full catalog in a single response; no cursor is
- * exposed by Raster for this path.
+ * Walks the artist's `artworks` connection to the end so the caller sees
+ * the complete catalog, matching the old single-response REST behavior.
  */
 async function listArtistArtworks(artistId) {
-    const data = await rasterFetch(`/artist/${artistId}/artworks`);
-    return (data.artworks ?? []).map((row) => ({
-        artworkId: row.id,
-        title: row.title,
-        tokenCount: row.num_tokens ?? row.num_pieces ?? 0,
-        isEdition: row.is_edition,
-        mintDate: row.mint_date ?? null,
-    }));
+    const rows = [];
+    let cursor = null;
+    do {
+        const data = await rasterQuery(`query ArtistArtworks($id: ID!, $after: String) {
+        artist(id: $id) {
+          artworks(first: 100, after: $after) {
+            nodes { id title }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }`, { id: artistId, after: cursor });
+        if (!data.artist) {
+            throw new Error(`Raster: artist ${artistId} not found.`);
+        }
+        for (const node of data.artist.artworks.nodes) {
+            rows.push({ artworkId: node.id, title: node.title });
+        }
+        const { hasNextPage, endCursor } = data.artist.artworks.pageInfo;
+        cursor = hasNextPage && endCursor ? endCursor : null;
+    } while (cursor !== null);
+    return rows;
 }
 /**
  * Format a one-line summary for the resolved artwork.
  *
  * @example
- *   formatSummaryLine(summary) // "Snowfro — send/receive — 8977 tokens"
+ *   formatSummaryLine(summary) // "Snowfro — send/receive"
  */
 function formatSummaryLine(summary) {
     const artistNames = summary.artists.map((a) => a.name).join(', ') || 'Unknown artist';
-    const tokenWord = summary.tokenCount === 1 ? 'token' : 'tokens';
-    return `${artistNames} — ${summary.title} — ${summary.tokenCount} ${tokenWord}`;
+    return `${artistNames} — ${summary.title}`;
 }

package/docs/CONFIGURATION.md

@@ -116,6 +116,19 @@ Environment variable alternative:
 FEED_BASE_URLS=https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
 ```
 
+## find (Raster API)
+
+`ff-cli find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)). No configuration is required; two environment variables adjust the integration:
+
+```env
+# API key sent as the x-api-key header. The API currently answers without
+# one, but Raster's docs declare a key required — set this once enforced.
+RASTER_API_KEY=rk_your_key_here
+
+# Override the GraphQL endpoint (default: https://api.raster.art/graphql).
+RASTER_API_URL=https://api.raster.art/graphql
+```
+
 ## ff1Devices
 
 Configure devices you want to play content on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "CLI for building DP-1 playlists of digital art using AI (Claude, Grok, ChatGPT, Gemini)",
   "repository": {
     "type": "git",