@feralfile/cli 1.1.4 → 1.3.0

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

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Neort (neort.io) resolver.
+ *
+ * Neort is an off-chain platform for code-based / generative art. Pieces are
+ * referenced by an opaque id (e.g. `ce3lvgkn70rlpj69ccc0`) and do NOT have
+ * on-chain coordinates, so the find flow bypasses Raster + FF indexer for
+ * Neort items and builds the DP-1 entry directly from Neort's API response
+ * using the off-chain `provenance.offChainURI` shape.
+ *
+ * Asset / thumbnail URLs are constructed by stitching CloudFront paths with
+ * fields from the API response (per Ryota / Neort, 2026-05-21):
+ *   - artwork:   https://d32h66pp7fue57.cloudfront.net/artPreview/{resourceFileName}
+ *   - thumbnail: https://d32h66pp7fue57.cloudfront.net/artThumb/{thumbFileName-or-selectedThumbFileName}
+ *
+ * Field nuances observed across real responses:
+ *   - `thumbFileName` and `selectedThumbFileName` are mutually exclusive in
+ *     practice; one is populated, the other empty. Prefer
+ *     `selectedThumbFileName` (newer field) and fall back to `thumbFileName`.
+ *   - `resourceFileName` is empty for static-image pieces (`resourceType: 3`),
+ *     where the thumbnail IS the artwork — fall back to the thumb URL when
+ *     resourceFileName is missing so static-image pieces still build.
+ *   - Unknown ids return HTTP 200 with `id: ""` (an empty stub), not a 404 —
+ *     reject when `id` is empty.
+ */
+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.resolveNeortArt = resolveNeortArt;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+const NEORT_API_BASE = 'https://api.neort.io/v1';
+const NEORT_CDN_BASE = 'https://d32h66pp7fue57.cloudfront.net';
+/**
+ * Resolve a Neort art id to a playable asset URL plus title/artist metadata.
+ *
+ * @throws When the id is unknown, the art is private, or no playable asset
+ *   can be constructed from the response.
+ */
+async function resolveNeortArt(id) {
+    logger.debug(`[neort] Resolving art id "${id}"`);
+    const response = await fetch(`${NEORT_API_BASE}/art/${encodeURIComponent(id)}`, {
+        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Neort API ${response.status} ${response.statusText} for art id "${id}".`);
+    }
+    const data = (await response.json());
+    if (!data.id) {
+        throw new Error(`Neort: no art found for id "${id}". Check the URL — ids come from neort.io/art/{id}.`);
+    }
+    if (!data.isPublic) {
+        throw new Error(`Neort: art "${id}" (${data.title || 'untitled'}) is not public.`);
+    }
+    const thumbFile = data.selectedThumbFileName || data.thumbFileName;
+    const thumbnailUrl = thumbFile ? `${NEORT_CDN_BASE}/artThumb/${thumbFile}` : null;
+    const assetUrl = data.resourceFileName
+        ? `${NEORT_CDN_BASE}/artPreview/${data.resourceFileName}`
+        : thumbnailUrl;
+    if (!assetUrl) {
+        throw new Error(`Neort: art "${id}" has no playable asset (resourceFileName and thumbnail are both empty).`);
+    }
+    return {
+        id: data.id,
+        title: data.title || `Neort ${data.id}`,
+        description: data.description || '',
+        artistName: data.user?.name ?? '',
+        assetUrl,
+        thumbnailUrl,
+    };
+}

package/dist/src/utilities/nft-indexer.js

@@ -180,7 +180,10 @@ async function queryTokens(params = {}) {
         });
         if (!response.ok) {
             const errorBody = await response.text();
-            logger.error('[NFT Indexer] HTTP error response:', {
+            // Inside queryTokens — caller (queryTokenDataFromIndexer) falls back
+            // to the trigger-indexing path when this returns/throws. Demoting to
+            // debug so transient 502s don't flood stderr during recoverable runs.
+            logger.debug('[NFT Indexer] HTTP error response:', {
                 status: response.status,
                 body: errorBody.substring(0, 500),
             });
@@ -188,7 +191,7 @@ async function queryTokens(params = {}) {
         }
         const result = await response.json();
         if (result.errors) {
-            logger.error('[NFT Indexer] GraphQL errors:', result.errors);
+            logger.debug('[NFT Indexer] GraphQL errors:', result.errors);
             throw new Error(`GraphQL errors: ${result.errors.map((e) => e.message).join(', ')}`);
         }
         // v2 API wraps tokens in { items: [...], total: N }
@@ -197,7 +200,7 @@ async function queryTokens(params = {}) {
         return tokens;
     }
     catch (error) {
-        logger.error('[NFT Indexer] Failed to query tokens:', error.message);
+        logger.debug('[NFT Indexer] Failed to query tokens:', error.message);
         throw error;
     }
 }
@@ -215,7 +218,7 @@ async function queryTokenDataFromIndexer(tokenCID) {
         return tokens[0] || null;
     }
     catch (error) {
-        logger.error('[NFT Indexer] Failed to query token data:', error.message);
+        logger.debug('[NFT Indexer] Failed to query token data:', error.message);
         return null;
     }
 }
@@ -520,7 +523,7 @@ async function getNFTTokenInfoSingle(params, duration = 10, options = {}) {
             // Trigger background indexing workflow
             const indexResult = await triggerIndexingAsync(chain, contractAddress, tokenId);
             if (!indexResult.success) {
-                logger.error(`[NFT Indexer] Failed to trigger indexing:`, indexResult.error);
+                logger.debug(`[NFT Indexer] Failed to trigger indexing:`, indexResult.error);
                 return {
                     success: false,
                     error: `Token not found and indexing failed: ${indexResult.error}`,
@@ -532,7 +535,7 @@ async function getNFTTokenInfoSingle(params, duration = 10, options = {}) {
             // Poll for job completion (queue-backed jobs use job_id / jobStatus)
             const pollResult = await pollForJobCompletion(indexResult.job_id, options.jobPoll ?? {});
             if (!pollResult.success) {
-                logger.error('[NFT Indexer] Job polling failed:', pollResult.error);
+                logger.debug('[NFT Indexer] Job polling failed:', pollResult.error);
                 return {
                     success: false,
                     error: `Indexing job failed: ${pollResult.error}`,
@@ -575,7 +578,7 @@ async function getNFTTokenInfoSingle(params, duration = 10, options = {}) {
         return convertToDP1Item(tokenData, duration);
     }
     catch (error) {
-        logger.error(`[NFT Indexer] Error fetching token:`, error.message);
+        logger.debug(`[NFT Indexer] Error fetching token:`, error.message);
         return {
             success: false,
             error: error.message,
@@ -601,7 +604,7 @@ async function getNFTTokenInfoBatch(tokens, duration = 10) {
         const batch = tokens.slice(i, i + concurrency);
         logger.info(`[NFT Indexer] Processing batch ${Math.floor(i / concurrency) + 1}/${Math.ceil(tokens.length / concurrency)} (${batch.length} tokens)`);
         const batchResults = await Promise.all(batch.map((token, idx) => getNFTTokenInfoSingle(token, duration).catch((error) => {
-            logger.error(`[NFT Indexer] Token ${idx + 1} in batch failed:`, error.message);
+            logger.debug(`[NFT Indexer] Token ${idx + 1} in batch failed:`, error.message);
             return {
                 success: false,
                 error: error.message,
@@ -713,7 +716,7 @@ async function triggerIndexingAsync(chain, contractAddress, tokenId) {
         };
     }
     catch (error) {
-        logger.error('[NFT Indexer] Async indexing error:', error.message);
+        logger.debug('[NFT Indexer] Async indexing error:', error.message);
         return {
             success: false,
             error: error.message,
@@ -761,7 +764,7 @@ async function queryJobStatus(jobId) {
         };
     }
     catch (error) {
-        logger.error('[NFT Indexer] Failed to query job status:', error.message);
+        logger.debug('[NFT Indexer] Failed to query job status:', error.message);
         return {
             success: false,
             error: error.message,
@@ -799,9 +802,14 @@ async function pollForJobCompletion(jobId, options = {}) {
             pollCount += 1;
             logger.debug(`[NFT Indexer] Poll #${pollCount}: status = ${status}`);
             const normalized = typeof status === 'string' ? status.toLowerCase() : '';
-            if (normalized === 'completed') {
+            // Indexer terminal-success states: both `completed` (older) and
+            // `succeeded` (current pgmq convention) appear in the wild. Accepting
+            // both prevents the CLI from polling-to-timeout on freshly-triggered
+            // tokens, which was masking as "No tokens could be indexed" on the
+            // first encounter while the underlying job had already finished.
+            if (normalized === 'completed' || normalized === 'succeeded') {
                 const elapsedMs = Date.now() - startTime;
-                logger.info(`[NFT Indexer] ✓ Job completed after ${pollCount} polls (${elapsedMs}ms)`);
+                logger.info(`[NFT Indexer] ✓ Job ${normalized} after ${pollCount} polls (${elapsedMs}ms)`);
                 return {
                     success: true,
                     completed: true,
@@ -834,7 +842,7 @@ async function pollForJobCompletion(jobId, options = {}) {
         }
     }
     catch (error) {
-        logger.error('[NFT Indexer] Error during job polling:', error.message);
+        logger.debug('[NFT Indexer] Error during job polling:', error.message);
         return {
             success: false,
             error: error.message,
@@ -882,7 +890,7 @@ async function pollForMediaAssets(tokenCID, options = {}) {
         }
     }
     catch (error) {
-        logger.error('[NFT Indexer] Error during media assets polling:', error.message);
+        logger.debug('[NFT Indexer] Error during media assets polling:', error.message);
         return null;
     }
 }

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

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Objkt marketplace resolver.
+ *
+ * Objkt URLs accept either a raw KT1 contract address OR a short collection
+ * alias (e.g. `objkt.com/tokens/hicetnunc/111068` where `hicetnunc` maps to
+ * `KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton`). The alias-to-contract mapping
+ * lives in their public GraphQL `fa.path` field.
+ *
+ * The URL parser stays sync; this module owns the one async call needed
+ * when an alias segment is detected.
+ */
+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.resolveObjktAlias = resolveObjktAlias;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+const OBJKT_GRAPHQL = 'https://data.objkt.com/v3/graphql';
+/**
+ * Resolve an Objkt URL alias to its KT1 contract address.
+ *
+ * @throws When the alias is not registered on Objkt, or the GraphQL call fails.
+ */
+async function resolveObjktAlias(alias) {
+    logger.debug(`[Objkt] Resolving alias "${alias}"`);
+    const query = 'query ($path: String!) { fa(where: { path: { _eq: $path } }) { contract } }';
+    const response = await fetch(OBJKT_GRAPHQL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
+        body: JSON.stringify({ query, variables: { path: alias } }),
+    });
+    if (!response.ok) {
+        throw new Error(`Objkt GraphQL ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (data.errors && data.errors.length > 0) {
+        throw new Error(`Objkt GraphQL errors: ${data.errors.map((e) => e.message).join('; ')}`);
+    }
+    const contract = data.data?.fa?.[0]?.contract;
+    if (!contract) {
+        throw new Error(`Objkt: alias "${alias}" did not resolve to a contract. ` +
+            'If this is a real collection, paste the URL using its KT1 contract address instead.');
+    }
+    return contract;
+}

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

@@ -1,37 +1,4 @@
 "use strict";
-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;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -39,13 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishPlaylist = publishPlaylist;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = __importDefault(require("fs"));
+const playlist_verifier_1 = require("./playlist-verifier");
 /**
- * Publish a validated playlist to a DP-1 feed server
+ * Publish a verified playlist to a DP-1 feed server
  *
  * Flow:
  * 1. Read and parse playlist file
- * 2. Parse / structure validation via validatePlaylist (same as `validate`; not cryptographic verify)
- * 3. If valid, send the original playlist to feed server
+ * 2. Verify the playlist signature before upload
+ * 3. If valid, send the verified playlist to feed server
  * 4. Return result with playlist ID or error
  *
  * @param {string} filePath - Path to playlist JSON file
@@ -80,14 +48,13 @@ async function publishPlaylist(filePath, feedServerUrl, apiKey) {
                 error: `Invalid JSON in playlist file: ${filePath}`,
             };
         }
-        // Step 2: Parse / structure validation (use `verify` CLI for signature checks)
-        const { validatePlaylist } = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
-        const validationResult = await validatePlaylist(playlist);
-        if (!validationResult.valid) {
+        // Step 2: Verify signature integrity before publishing.
+        const deliveryResult = await (0, playlist_verifier_1.verifyPlaylist)(playlist);
+        if (!deliveryResult.valid) {
             return {
                 success: false,
-                error: `Playlist validation failed: ${validationResult.error}`,
-                message: validationResult.details?.map((d) => `  • ${d.path}: ${d.message}`).join('\n'),
+                error: `Playlist verification failed: ${deliveryResult.error}`,
+                message: deliveryResult.details?.map((d) => `  • ${d.path}: ${d.message}`).join('\n'),
             };
         }
         // Step 3: Send validated playlist to feed server

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

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Raster API client (kit.raster.art)
+ *
+ * Resolves on-chain coordinates and artist addresses into Raster `artwork_id`
+ * (series) and `artist_id` (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
+ * to devices, or build playlists. The fulfiller layer (FF indexer) consumes
+ * the `{ chain, contractAddress, tokenId }` shapes this module emits.
+ *
+ * Chain filter: the FF indexer only supports Ethereum mainnet and Tezos
+ * 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.
+ */
+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.RasterNotFoundError = void 0;
+exports.resolveTokenToArtwork = resolveTokenToArtwork;
+exports.getArtworkSummary = getArtworkSummary;
+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';
+// 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.
+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;
+}
+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).
+ */
+class RasterNotFoundError extends Error {
+    notFound = true;
+    constructor(path) {
+        super(`Raster: not found (${path})`);
+        this.name = 'RasterNotFoundError';
+    }
+}
+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' },
+    });
+    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)}`);
+    }
+    return (await response.json());
+}
+/**
+ * Resolve a token's on-chain coordinates to its Raster artwork (series) id.
+ *
+ * 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.
+ */
+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;
+    }
+}
+/**
+ * Get the full Raster artwork summary suitable for the one-line resolve
+ * message ("Snowfro — send/receive — 8977 tokens") and downstream UX.
+ */
+async function getArtworkSummary(artworkId) {
+    const data = await rasterFetch(`/artwork/${artworkId}`);
+    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 ?? [],
+    };
+}
+/**
+ * Resolve an artist's wallet address to a Raster artist id via `/search`.
+ *
+ * `/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.
+ */
+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;
+}
+/**
+ * List tokens in a Raster artwork (series), one page at a time.
+ *
+ * Filters out tokens whose chain is not supported by the FF indexer
+ * (anything other than `eip155:1` or `tezos:NetXdQprcVkpaWU`) and reports
+ * the count via `skippedUnsupported` so the caller can print a single
+ * 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.
+ */
+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 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) {
+            skippedUnsupported += 1;
+            continue;
+        }
+        tokens.push({
+            caipChain: raw.chain_id,
+            chain,
+            contractAddress: stripContractChainPrefix(raw.contract_address),
+            tokenId: raw.token_id,
+        });
+    }
+    const rawCursor = data.cursor;
+    const nextCursor = rawCursor === null || rawCursor >= data.total_count ? null : rawCursor;
+    return {
+        tokens,
+        totalCount: data.total_count,
+        nextCursor,
+        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.
+ *
+ * The endpoint returns the full catalog in a single response; no cursor is
+ * exposed by Raster for this path.
+ */
+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,
+    }));
+}
+/**
+ * Format a one-line summary for the resolved artwork.
+ *
+ * @example
+ *   formatSummaryLine(summary) // "Snowfro — send/receive — 8977 tokens"
+ */
+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}`;
+}

package/dist/src/utilities/user-agent.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Outbound HTTP User-Agent for ff-cli.
+ *
+ * Set on every fetch to third-party APIs (Raster, Objkt, fxhash, AB, Feral
+ * File, Neort) so partners can distinguish CLI traffic from their own
+ * frontend/backend traffic in logs. Without it, all Node-side fetches blend
+ * into a generic default UA and partners can't attribute load or behavior
+ * back to the CLI when something looks unusual.
+ *
+ * Format: `ff-cli/<version>` — version is read from package.json at compile
+ * time via the bundler's JSON import support (`resolveJsonModule`).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_AGENT = void 0;
+const package_json_1 = __importDefault(require("../../package.json"));
+exports.USER_AGENT = `ff-cli/${package_json_1.default.version}`;

package/docs/CONFIGURATION.md

@@ -60,10 +60,12 @@ Optional settings used where headless/browser‑like behavior is needed.
 
 Used for signing DP‑1 playlists.
 
-- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`.
+- `playlist.privateKey` (string, Ed25519 private key in hex or base64): Used by the `sign` command to create DP-1 v1.1.0 multi-signatures. The `verify` command may derive the matching public key from this value (or `PLAYLIST_PRIVATE_KEY`) when you omit `--public-key`; **dp1-js applies that derived key only when verifying legacy flat `signature` strings**, not when checking `signatures[]` envelopes. If that derivation fails, `verify` prints a warning on stderr and continues without derived key material. The derived public key is emitted as PEM so Node can decode it without ambiguity. Hex may include or omit the `0x` prefix. You can also set this via `PLAYLIST_PRIVATE_KEY` in `.env`. `play` verifies playlists before delivery and only auto-signs the synthesized media URL fallback when signing is configured. `send` and `publish` verify before delivery or upload and reject unsigned or broken playlists.
 
   **Signing and key encoding:** Signing paths (`sign`, deterministic `build` when configured, and `-k/--key` overrides) pass the private key string through to **`dp1-js`** (`SignMultiEd25519`) without an extra decoding step in ff-cli. `dp1-js` recognizes **hex** (optional `0x`) or **base64** encodings of the PKCS#8 DER blob produced by the OpenSSL examples below, then loads the key for Ed25519. Use those formats; ff-cli does not add a separate normalizer ahead of the library.
+
 - `playlist.role` (string): DP-1 signing role that travels with the private key. Defaults to `agent` if omitted. You can also set this via `PLAYLIST_ROLE` in `.env`. Guided `ff-cli setup`, `config validate`, and `sign --role` only accept the usual DP-1 signing roles (`agent`, `feed`, `curator`, `institution`, `licensor`).
+
 ### Generate an Ed25519 private key
 
 You can generate a key locally. The CLI accepts either base64 (preferred) or hex