@feralfile/cli 2.10.0 → 3.0.0

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

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaylistUrlLoadError = void 0;
 exports.isPlaylistSourceUrl = isPlaylistSourceUrl;
 exports.loadPlaylistSource = loadPlaylistSource;
+exports.buildMediaPlaySource = buildMediaPlaySource;
+exports.refusalForLoadFailure = refusalForLoadFailure;
+exports.checkWebPageUrl = checkWebPageUrl;
 exports.resolvePlaySource = resolvePlaySource;
 const http_1 = require("./http");
 const fs_1 = require("fs");
@@ -27,12 +31,87 @@ function isPlaylistSourceUrl(source) {
         return false;
     }
 }
+/**
+ * PlaylistUrlLoadError is a failure to load an http(s) URL as a playlist,
+ * tagged with how it failed so `resolvePlaySource` can tell a missing playlist
+ * from a URL that is simply not a playlist.
+ *
+ * - `status`: the server answered with a non-OK HTTP status (`status` is set).
+ * - `network`: no answer at all (DNS, refused connection, timeout); `code` is
+ *   the underlying system error code when fetch exposes one.
+ * - `read`: an OK answer whose body was cut off (timeout or dropped connection
+ *   mid-download). Nothing was learned about the URL, so it is not "not a
+ *   playlist" either.
+ * - `json`: an OK answer, read in full, that is not JSON. This is what every
+ *   ordinary web page and media file produces.
+ */
+class PlaylistUrlLoadError extends Error {
+    kind;
+    status;
+    code;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'PlaylistUrlLoadError';
+        this.kind = detail.kind;
+        this.status = detail.status;
+        this.code = detail.code;
+    }
+}
+exports.PlaylistUrlLoadError = PlaylistUrlLoadError;
+/**
+ * networkErrorCode digs the system error code (ENOTFOUND, ECONNREFUSED, …)
+ * out of a fetch failure. Node's fetch throws `TypeError('fetch failed')` and
+ * puts the real error on `cause`.
+ *
+ * @param {unknown} error - What fetch threw
+ * @returns {string | undefined} The code, when there is one
+ */
+function networkErrorCode(error) {
+    const cause = error?.cause;
+    return typeof cause?.code === 'string' ? cause.code : undefined;
+}
+/**
+ * loadPlaylistUrl fetches an http(s) URL and parses it as a playlist.
+ *
+ * @param {string} url - Trimmed http(s) URL
+ * @returns {Promise<LoadedPlaylist>} The parsed document
+ * @throws {PlaylistUrlLoadError} On any failure, tagged with its kind
+ */
+async function loadPlaylistUrl(url) {
+    let response;
+    try {
+        response = await (0, http_1.fetchWithTimeout)(url);
+    }
+    catch (error) {
+        throw new PlaylistUrlLoadError(`Could not reach ${url}: ${error.message}`, {
+            kind: 'network',
+            code: networkErrorCode(error),
+        });
+    }
+    if (!response.ok) {
+        throw new PlaylistUrlLoadError(`Failed to fetch playlist URL: ${response.status} ${response.statusText}`, { kind: 'status', status: response.status });
+    }
+    let playlistText;
+    try {
+        playlistText = await response.text();
+    }
+    catch (error) {
+        throw new PlaylistUrlLoadError(`Failed to read playlist response from ${url}: ${error.message}`, { kind: 'read' });
+    }
+    try {
+        return { playlist: JSON.parse(playlistText), source: url, sourceType: 'url' };
+    }
+    catch (error) {
+        throw new PlaylistUrlLoadError(`Invalid JSON from playlist URL ${url}: ${error.message}`, { kind: 'json' });
+    }
+}
 /**
  * Load a DP-1 playlist from a local file or hosted URL.
  *
  * @param {string} source - Playlist file path or URL
  * @returns {Promise<LoadedPlaylist>} Loaded playlist payload with source metadata
- * @throws {Error} When source is empty, cannot be loaded, or JSON is invalid
+ * @throws {Error} When source is empty, cannot be loaded, or JSON is invalid; a URL
+ *   failure is a PlaylistUrlLoadError
  */
 async function loadPlaylistSource(source) {
     const trimmedSource = source.trim();
@@ -40,27 +119,7 @@ async function loadPlaylistSource(source) {
         throw new Error('Playlist source is required');
     }
     if (isPlaylistSourceUrl(trimmedSource)) {
-        const response = await (0, http_1.fetchWithTimeout)(trimmedSource);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch playlist URL: ${response.status} ${response.statusText}`);
-        }
-        let playlistText;
-        try {
-            playlistText = await response.text();
-        }
-        catch (error) {
-            throw new Error(`Failed to read playlist response from ${trimmedSource}: ${error.message}`);
-        }
-        try {
-            return {
-                playlist: JSON.parse(playlistText),
-                source: trimmedSource,
-                sourceType: 'url',
-            };
-        }
-        catch (error) {
-            throw new Error(`Invalid JSON from playlist URL ${trimmedSource}: ${error.message}`);
-        }
+        return loadPlaylistUrl(trimmedSource);
     }
     let fileText;
     try {
@@ -80,25 +139,150 @@ async function loadPlaylistSource(source) {
         throw new Error(`Invalid JSON in ${trimmedSource}: ${error.message}`);
     }
 }
+/**
+ * buildMediaPlaySource wraps a URL in a synthesized single-item playlist, the
+ * shape `play` sends for a direct media file or web page.
+ *
+ * @param {string} url - Trimmed http(s) URL
+ * @param {Object} [options] - Item options
+ * @param {number} [options.duration] - Explicit display seconds; omit for auto timing
+ * @param {boolean} [options.asWebPage] - Time the item as a page whatever the URL looks like
+ * @param {string} [options.note] - Carried to the caller (see PlaySource.note)
+ * @returns {Promise<PlaySource>} A `media` play source
+ */
+async function buildMediaPlaySource(url, options = {}) {
+    const item = buildUrlItem(url, options.duration, { asWebPage: options.asWebPage });
+    const playlist = (await buildDP1Playlist({ items: [item], title: item.title }));
+    return options.note
+        ? { kind: 'media', playlist, source: url, note: options.note }
+        : { kind: 'media', playlist, source: url };
+}
+/**
+ * looksLikePlaylistUrl reports whether a URL names a JSON document by its
+ * path. A `.json` URL that fails to load is a broken playlist link, never a
+ * page someone meant to show on a wall.
+ *
+ * @param {string} url - http(s) URL
+ * @returns {boolean} True when the path ends in `.json`
+ */
+function looksLikePlaylistUrl(url) {
+    try {
+        return new URL(url).pathname.toLowerCase().endsWith('.json');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * refusalForLoadFailure returns the error `play` must stop with when a URL it
+ * tried to load is known not to exist, or null when it may still be sent.
+ *
+ * Wrapping a URL that does not exist sends the device an error page and
+ * reports "Playing", the silent wrong result an agent trusting exit codes
+ * cannot catch. These are refused:
+ * - HTTP 404 or 410: nothing is there.
+ * - DNS failure (ENOTFOUND): the host does not exist. A temporary resolver
+ *   failure (EAI_AGAIN) is not refused.
+ * - A `.json` URL that cannot be loaded or parsed: a broken playlist link.
+ * Real marketplace pages answer 200 to a command-line client (checked against
+ * OpenSea, Art Blocks, objkt, SuperRare, Feral File, Neort, Verse), so this
+ * rule is safe on discovery hosts too.
+ *
+ * @param {string} url - The URL that failed to load
+ * @param {unknown} failure - What loading threw
+ * @returns {Error | null} The refusal, or null
+ */
+function refusalForLoadFailure(url, failure) {
+    const loadFailure = failure;
+    if (loadFailure?.status === 404 || loadFailure?.status === 410) {
+        return new Error(`Nothing at ${url} (HTTP ${loadFailure.status}). Check the URL; nothing was sent to the device.`);
+    }
+    if (loadFailure?.code === 'ENOTFOUND') {
+        return new Error(`No such host for ${url}. Check the URL; nothing was sent to the device.`);
+    }
+    if (looksLikePlaylistUrl(url)) {
+        return new Error(`${url} looks like a playlist (.json) but could not be loaded: ${failure?.message}`);
+    }
+    return null;
+}
+/**
+ * noteForLoadFailure returns the line `play` prints when it sends a URL it
+ * could not read itself, or undefined when the URL was read in full and is
+ * simply not a playlist (an ordinary page or media file).
+ *
+ * @param {unknown} failure - What loading threw
+ * @returns {string | undefined} The note, if any
+ */
+function noteForLoadFailure(failure) {
+    const loadFailure = failure;
+    if (loadFailure?.kind === 'json') {
+        return undefined;
+    }
+    return `ff-cli could not read this URL itself (${failure?.message}); sending it to the device anyway.`;
+}
+/**
+ * checkWebPageUrl fetches a URL that `play --web` is about to send, refusing
+ * one that does not exist and returning a note when it could not be read.
+ *
+ * `--web` skips the playlist probe, so without this check a typo or a dead
+ * link handed to `--web` (the hint `play` prints for marketplace pages) would
+ * be cast as an error page with a successful exit. Only the status line is
+ * needed; the body is cancelled unread. The `.json` rule does not apply: the
+ * caller said this is a page.
+ *
+ * @param {string} url - Trimmed http(s) URL
+ * @returns {Promise<string | undefined>} A note when the URL could not be read
+ * @throws {Error} When the URL answers 404/410 or its host does not resolve
+ */
+async function checkWebPageUrl(url) {
+    let failure;
+    try {
+        const response = await (0, http_1.fetchWithTimeout)(url);
+        await response.body?.cancel().catch(() => undefined);
+        if (response.ok) {
+            return undefined;
+        }
+        failure = new PlaylistUrlLoadError(`HTTP ${response.status} ${response.statusText}`.trim(), {
+            kind: 'status',
+            status: response.status,
+        });
+    }
+    catch (error) {
+        failure = new PlaylistUrlLoadError(`Could not reach ${url}: ${error.message}`, {
+            kind: 'network',
+            code: networkErrorCode(error),
+        });
+    }
+    if (failure.status === 404 || failure.status === 410 || failure.code === 'ENOTFOUND') {
+        throw refusalForLoadFailure(url, failure);
+    }
+    return noteForLoadFailure(failure);
+}
 /**
  * Resolve a `play` command argument to a playable source.
  *
  * Files are always treated as playlists. URLs are tried as playlists first;
- * if loading fails (network, non-JSON, etc.), the URL is wrapped in a
- * synthesized single-item playlist so direct media URLs still work.
+ * a URL whose body is not a playlist (an ordinary web page, a video, an
+ * image) is wrapped in a synthesized single-item playlist so direct media
+ * URLs and web pages still work.
  *
  * The "URL → playlist or media" path uses throw-and-fallback because there
  * is no cheap way to distinguish a 200-OK media file from a malformed
- * playlist response without trying to parse it. Keeping the fallback
- * scoped to one helper means the play action no longer carries the
- * `loadedAsPlaylist` boolean dance.
+ * playlist response without trying to parse it.
+ *
+ * Not every failure falls back: a URL that does not exist is refused (see
+ * refusalForLoadFailure). Other failures (403 from bot protection, 5xx,
+ * timeouts, a body cut off mid-download) still fall back, with a `note`,
+ * because the device fetches media itself and often succeeds where a
+ * command-line client is refused.
  *
  * @param source - User-supplied path or URL
  * @param defaultDuration - Explicit duration (seconds) for the synthesized
  *   media item; omit for auto timing (video/audio URLs play their natural
  *   length per DP-1 §4.1, static media uses the configured default)
  * @returns Resolved playlist + metadata describing how it was loaded
- * @throws Error When `source` is empty, or is a non-URL file path that cannot be loaded
+ * @throws Error When `source` is empty, is a non-URL file path that cannot be loaded,
+ *   or is a URL that does not exist (see above)
  */
 async function resolvePlaySource(source, defaultDuration) {
     const trimmed = source.trim();
@@ -115,7 +299,7 @@ async function resolvePlaySource(source, defaultDuration) {
         };
     }
     try {
-        const loaded = await loadPlaylistSource(trimmed);
+        const loaded = await loadPlaylistUrl(trimmed);
         return {
             kind: 'playlist',
             playlist: loaded.playlist,
@@ -123,9 +307,14 @@ async function resolvePlaySource(source, defaultDuration) {
             source: loaded.source,
         };
     }
-    catch {
-        const item = buildUrlItem(trimmed, defaultDuration);
-        const playlist = (await buildDP1Playlist({ items: [item], title: item.title }));
-        return { kind: 'media', playlist, source: trimmed };
+    catch (error) {
+        const refusal = refusalForLoadFailure(trimmed, error);
+        if (refusal) {
+            throw refusal;
+        }
+        return buildMediaPlaySource(trimmed, {
+            duration: defaultDuration,
+            note: noteForLoadFailure(error),
+        });
     }
 }

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

@@ -3,12 +3,12 @@
  * Raster API client (api.raster.art — public GraphQL API).
  *
  * 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.
+ * (series) and artists (catalog) for `ff-cli find`, and fetches the full token
+ * rows the Raster token source (token-source-raster.ts) turns into DP-1 items.
  *
  * This module is pure data: it does not construct DP-1 items, send anything
- * to devices, or build playlists. The fulfiller layer (FF indexer) consumes
- * the `{ chain, contractAddress, tokenId }` shapes this module emits.
+ * to devices, or build playlists. Mapping a RasterToken to the vendor-neutral
+ * token shape happens in token-source-raster.ts.
  *
  * Chain filter: the FF indexer only supports Ethereum mainnet and Tezos
  * mainnet. Token lists are filtered here at the CAIP level and a
@@ -57,10 +57,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RasterUnreachableError = void 0;
+exports.RASTER_TOKEN_BATCH_SIZE = exports.TOKEN_FIELDS = exports.RasterUnreachableError = void 0;
+exports.rasterQuery = rasterQuery;
 exports.resolveTokenToArtwork = resolveTokenToArtwork;
 exports.resolveSlugToArtwork = resolveSlugToArtwork;
 exports.resolveAddressToArtist = resolveAddressToArtist;
+exports.buildTokenByRefBatchQuery = buildTokenByRefBatchQuery;
+exports.fetchTokensByRef = fetchTokensByRef;
+exports.fetchTokensOwned = fetchTokensOwned;
 exports.listArtworkTokens = listArtworkTokens;
 exports.listArtistArtworks = listArtistArtworks;
 exports.formatSummaryLine = formatSummaryLine;
@@ -241,6 +245,93 @@ async function resolveAddressToArtist(address) {
     const artist = data.address?.artists?.[0];
     return artist ? toRasterArtist(artist) : null;
 }
+/**
+ * TOKEN_FIELDS is the one selection every token-reading query shares, so the
+ * three entry points (by reference, by owner, by artwork) feed the same mapper.
+ */
+exports.TOKEN_FIELDS = `fragment TokenFields on Token {
+  chainId contractAddress tokenId tokenStandard name description
+  media { previewHash previewType contentUrl normalizedContentUrl contentType }
+  artworks { id slug title description platform { id name } artists { id name slug } }
+  artists { id name slug }
+}`;
+/**
+ * RASTER_TOKEN_BATCH_SIZE caps aliased `tokenByRef` lookups per request.
+ * 40 is the size probed on feral-file#3546 (one request, 2.9 s); larger
+ * batches are unmeasured, so raise it only with a new measurement.
+ */
+exports.RASTER_TOKEN_BATCH_SIZE = 40;
+/**
+ * buildTokenByRefBatchQuery builds one query with `count` aliased lookups.
+ *
+ * Refs travel as numbered variables (`$r0`…), never interpolated into the
+ * text, so token ids above 2^53 (every Feral File id) arrive as strings and
+ * no caller-supplied value can alter the document.
+ */
+function buildTokenByRefBatchQuery(count) {
+    const indices = Array.from({ length: count }, (_, i) => i);
+    const params = indices.map((i) => `$r${i}: TokenRefInput!`).join(', ');
+    const fields = indices.map((i) => `  t${i}: tokenByRef(ref: $r${i}) { ...TokenFields }`);
+    return `query TokensByRef(${params}) {\n${fields.join('\n')}\n}\n${exports.TOKEN_FIELDS}`;
+}
+/**
+ * fetchTokensByRef looks up one batch of coordinates in a single request.
+ *
+ * The result is aligned with the input; a token Raster does not cover, or one
+ * that was burned, is `null` (Raster answers null rather than an error).
+ * Batching across requests, progress, and per-batch failure handling belong to
+ * the caller, which is why more than RASTER_TOKEN_BATCH_SIZE refs is refused
+ * instead of split here.
+ *
+ * @throws RasterUnreachableError on network failure; Error on API failure
+ */
+async function fetchTokensByRef(refs) {
+    if (refs.length > exports.RASTER_TOKEN_BATCH_SIZE) {
+        throw new Error(`fetchTokensByRef takes at most ${exports.RASTER_TOKEN_BATCH_SIZE} refs per call.`);
+    }
+    if (refs.length === 0) {
+        return [];
+    }
+    const variables = {};
+    refs.forEach((ref, i) => {
+        variables[`r${i}`] = {
+            chainId: INDEXER_CHAIN_TO_CAIP[ref.chain],
+            contractAddress: ref.contractAddress,
+            tokenId: ref.tokenId,
+        };
+    });
+    const data = await rasterQuery(buildTokenByRefBatchQuery(refs.length), variables);
+    return refs.map((_, i) => data[`t${i}`] ?? null);
+}
+/**
+ * fetchTokensOwned reads one page of `address.tokensOwned`, the wallet walk.
+ *
+ * Raster resolves any well-formed address and returns an empty connection when
+ * it knows no holdings, so an empty page is an answer, not an error. Chain
+ * filtering is left to the caller, which owns the skipped-chain report.
+ */
+async function fetchTokensOwned(address, options) {
+    const data = await rasterQuery(`query TokensOwned($address: String!, $first: Int, $after: String) {
+      address(address: $address) {
+        tokensOwned(first: $first, after: $after) {
+          totalCount
+          nodes { token { ...TokenFields } }
+          pageInfo { hasNextPage endCursor }
+        }
+      }
+    }
+    ${exports.TOKEN_FIELDS}`, { address: address.trim(), first: options.first, after: options.after ?? null });
+    const owned = data.address?.tokensOwned;
+    if (!owned) {
+        return { tokens: [], nextCursor: null, totalCount: 0 };
+    }
+    const { hasNextPage, endCursor } = owned.pageInfo;
+    return {
+        tokens: owned.nodes.map((node) => node.token),
+        nextCursor: hasNextPage && endCursor ? endCursor : null,
+        totalCount: owned.totalCount,
+    };
+}
 /**
  * List tokens in a Raster artwork (series), one page at a time.
  *
@@ -257,11 +348,12 @@ async function listArtworkTokens(artworkId, options = {}) {
     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 } }
+          nodes { ...TokenFields }
           pageInfo { hasNextPage endCursor }
         }
       }
-    }`, { id: artworkId, first: options.pageSize ?? null, after: options.cursor ?? null });
+    }
+    ${exports.TOKEN_FIELDS}`, { id: artworkId, first: options.pageSize ?? null, after: options.cursor ?? null });
     if (!data.artwork) {
         throw new Error(`Raster: artwork ${artworkId} not found.`);
     }
@@ -277,12 +369,7 @@ async function listArtworkTokens(artworkId, options = {}) {
             chain,
             contractAddress: raw.contractAddress,
             tokenId: raw.tokenId,
-            mediaUrl: raw.media?.contentUrl ?? null,
-            // Prefer the real MIME (`contentType`); today it is usually empty, so we
-            // fall back to `previewType` as a last resort. NOTE: previewType only
-            // describes the preview encoding, not the work, so this fallback can
-            // misclassify (see the mediaType doc comment above). Tracked for revisit.
-            mediaType: raw.media?.contentType || raw.media?.previewType || null,
+            token: raw,
         });
     }
     const { hasNextPage, endCursor } = data.artwork.tokens.pageInfo;