@feralfile/cli 1.1.1 → 1.2.0

package/dist/src/intent-parser/index.js

@@ -121,6 +121,9 @@ REQUIREMENT TYPES (BUILD)
     - "tokens 1, 2, 3 from contract 0x123" → build_playlist with tokenIds: ["1", "2", "3"]
     - "100 items from ethereum contract 0xABC" → build_playlist with quantity: 100, NO tokenIds
     - "50 random tokens from tezos contract KT1..." → build_playlist with quantity: 50, NO tokenIds
+- feral_file_artwork: { type, artworkId } for Feral File artwork URLs or public artwork ids.
+  • USE THIS only for feralfile.com/exhibitions/artwork URLs or explicit Feral File public artwork ids
+  • Do not use this for ordinary blockchain contract prompts
 - query_address: { type, ownerAddress: 0x…|tz…|domain.eth|domain.tez, quantity?: number | "all" }
   • USE THIS for owner/wallet addresses WITHOUT the word "contract"
   • Patterns: "N items from [address]", "NFTs from [address]", "tokens owned by [address]"
@@ -153,6 +156,10 @@ EXAMPLES (build_playlist - contract addresses)
 - "100 random tokens from tezos contract KT1abc" → \`build_playlist\` { blockchain: "tezos", contractAddress: "KT1abc", quantity: 100 }
 - "get 50 from contract 0xDEF" → \`build_playlist\` { blockchain: "ethereum", contractAddress: "0xDEF", quantity: 50 }
 
+EXAMPLES (feral_file_artwork - public artwork URLs)
+- "build a playlist from https://feralfile.com/exhibitions/artwork/abc123" → \`feral_file_artwork\` { artworkId: "abc123" }
+- "play Feral File artwork f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf" → \`feral_file_artwork\` { artworkId: "f0240e04d64717e319584957f6a83954b029254ad1260b6320472ea8c0c5b1cf" }
+
 EXAMPLES (fetch_feed)
 - "Pick 3 artworks from Social Codes and 2 from a2p. Mix them up." → \`fetch_feed\` { playlistName: "Social Codes", quantity: 3 } + \`fetch_feed\` { playlistName: "a2p", quantity: 2 }, and set \`playlistSettings.preserveOrder\` = false
 
@@ -266,20 +273,20 @@ const intentParserFunctionSchemas = [
         type: 'function',
         function: {
             name: 'parse_requirements',
-            description: 'Parse validated and complete requirements. Only call this when you have all required information for each requirement: blockchain, contract address, token IDs, and source.',
+            description: 'Parse validated and complete requirements. Only call this when you have all required information for each requirement, such as blockchain/contract/token IDs, Feral File artwork id, feed playlist name, or owner address.',
             parameters: {
                 type: 'object',
                 properties: {
                     requirements: {
                         type: 'array',
-                        description: 'Array of parsed requirements. Each can be either build_playlist (specific NFTs), fetch_feed (feed playlist), or query_address (all NFTs from address)',
+                        description: 'Array of parsed requirements. Each can be build_playlist (specific NFTs), feral_file_artwork (Feral File public artwork id or URL), fetch_feed (feed playlist), or query_address (all NFTs from address)',
                         items: {
                             type: 'object',
                             properties: {
                                 type: {
                                     type: 'string',
-                                    enum: ['build_playlist', 'fetch_feed', 'query_address'],
-                                    description: 'Type of requirement: build_playlist (specific NFTs), fetch_feed (feed playlist), or query_address (all NFTs from address)',
+                                    enum: ['build_playlist', 'feral_file_artwork', 'fetch_feed', 'query_address'],
+                                    description: 'Type of requirement: build_playlist (specific NFTs), feral_file_artwork (Feral File artwork), fetch_feed (feed playlist), or query_address (all NFTs from address)',
                                 },
                                 blockchain: {
                                     type: 'string',
@@ -296,6 +303,10 @@ const intentParserFunctionSchemas = [
                                         type: 'string',
                                     },
                                 },
+                                artworkId: {
+                                    type: 'string',
+                                    description: 'Feral File public artwork id or artwork URL - only for feral_file_artwork type',
+                                },
                                 ownerAddress: {
                                     type: 'string',
                                     description: 'Owner wallet address (0x... for Ethereum, tz... for Tezos) - only for query_address type',
@@ -1067,7 +1078,7 @@ async function processIntentParserRequest(userRequest, options = {}) {
                 const { confirmPlaylistForSending } = await Promise.resolve().then(() => __importStar(require('../utilities/playlist-send')));
                 // Validate and confirm the playlist.
                 // args.deviceName may be null/undefined/"null" when the model omits it;
-                // fall back to the CLI --device flag so `ff1 chat --device kitchen` works.
+                // fall back to the CLI --device flag so `ff-cli chat --device kitchen` works.
                 const resolvedDeviceName = args.deviceName && args.deviceName !== 'null' ? args.deviceName : defaultDeviceName;
                 const confirmation = await confirmPlaylistForSending(args.filePath, resolvedDeviceName);
                 if (!confirmation.success) {

package/dist/src/intent-parser/utils.js

@@ -51,6 +51,11 @@ function applyConstraints(params, config) {
                 throw new Error(`Requirement ${index + 1}: playlistName is required for fetch_feed`);
             }
         }
+        else if (r.type === 'feral_file_artwork') {
+            if (!r.artworkId) {
+                throw new Error(`Requirement ${index + 1}: artworkId is required for feral_file_artwork`);
+            }
+        }
         else {
             throw new Error(`Requirement ${index + 1}: invalid type "${r.type}"`);
         }
@@ -79,9 +84,9 @@ function applyConstraints(params, config) {
     });
     // Note: No cap needed - registry system handles large playlists efficiently
     // Full items are stored in memory, only IDs are sent to AI model
-    const hasAllQuantity = params.requirements.some((r) => r.quantity === 'all');
+    const hasAllQuantity = params.requirements.some((r) => 'quantity' in r && r.quantity === 'all');
     const totalRequested = params.requirements.reduce((sum, r) => {
-        if (typeof r.quantity === 'number') {
+        if ('quantity' in r && typeof r.quantity === 'number') {
             return sum + r.quantity;
         }
         return sum;

package/dist/src/main.js

@@ -44,6 +44,7 @@ exports.SEND_SHORTCUT_PATTERN = void 0;
 exports.resolveSendShortcutDevice = resolveSendShortcutDevice;
 exports.resolveEffectiveDeviceName = resolveEffectiveDeviceName;
 exports.resolveSendPlaylistDeviceName = resolveSendPlaylistDeviceName;
+exports.sendPreparedPlaylistToDevice = sendPreparedPlaylistToDevice;
 exports.validateRequirements = validateRequirements;
 exports.applyPlaylistDefaults = applyPlaylistDefaults;
 exports.buildPlaylistDirect = buildPlaylistDirect;
@@ -106,6 +107,36 @@ function resolveSendPlaylistDeviceName(intentDeviceName, cliDeviceName) {
         : intentDeviceName;
     return resolveEffectiveDeviceName(sanitized, cliDeviceName);
 }
+/**
+ * Verify a playlist for device delivery and send it using the supplied transport.
+ *
+ * This helper keeps the send branches in `buildPlaylist` testable without
+ * duplicating the verification and transport wiring in tests.
+ */
+async function sendPreparedPlaylistToDevice(playlist, deps) {
+    const verificationResult = await deps.verifyPlaylist(playlist);
+    if (!verificationResult.valid) {
+        return {
+            success: false,
+            error: verificationResult.error || 'Failed to verify playlist before sending',
+            playlist: null,
+        };
+    }
+    const sendResult = await deps.sendToDevice(playlist, deps.resolveDeviceName());
+    if (sendResult.success) {
+        return {
+            success: true,
+            playlist,
+            deviceName: sendResult.deviceName,
+            device: sendResult.device,
+        };
+    }
+    return {
+        success: false,
+        error: sendResult.error || 'Failed to send playlist',
+        playlist: null,
+    };
+}
 /**
  * Validate and apply constraints to requirements
  *
@@ -129,6 +160,12 @@ function validateRequirements(requirements) {
                 quantity,
             };
         }
+        if (req.type === 'feral_file_artwork') {
+            if (!req.artworkId) {
+                throw new Error(`Requirement ${index + 1}: artworkId is required for feral_file_artwork`);
+            }
+            return req;
+        }
         // Query address requirement
         if (req.type === 'query_address') {
             // Query all NFTs from an owner address
@@ -249,6 +286,7 @@ async function buildPlaylist(userRequest, options = {}) {
         if (sendMatch) {
             const deviceName = sendMatch[1]?.trim() || defaultDeviceName;
             const { confirmPlaylistForSending } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-send')));
+            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
             const confirmation = await confirmPlaylistForSending(outputPath, deviceName);
             if (!confirmation.success) {
                 if (confirmation.message) {
@@ -261,7 +299,11 @@ async function buildPlaylist(userRequest, options = {}) {
                     playlist: null,
                 };
             }
-            const sendResult = await utilities.sendToDevice(confirmation.playlist, confirmation.deviceName);
+            const sendResult = await sendPreparedPlaylistToDevice(confirmation.playlist, {
+                verifyPlaylist,
+                sendToDevice: utilities.sendToDevice,
+                resolveDeviceName: () => confirmation.deviceName,
+            });
             if (sendResult.success) {
                 console.log(chalk_1.default.green('\nPlaylist sent'));
                 if (sendResult.deviceName) {
@@ -270,7 +312,7 @@ async function buildPlaylist(userRequest, options = {}) {
                 console.log();
                 return {
                     success: true,
-                    playlist: confirmation.playlist,
+                    playlist: sendResult.playlist,
                     action: 'send_playlist',
                 };
             }
@@ -348,23 +390,15 @@ async function buildPlaylist(userRequest, options = {}) {
             // Handle playlist sending directly
             const sendParams = params;
             const utilities = getUtilities();
+            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
             console.log();
             console.log(chalk_1.default.cyan('Sending to device'));
-            const sendResult = await utilities.sendToDevice(sendParams.playlist, resolveSendPlaylistDeviceName(sendParams.deviceName, defaultDeviceName));
-            if (sendResult.success) {
-                console.log(chalk_1.default.green('\nPlaylist sent'));
-                if (sendResult.deviceName) {
-                    console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
-                }
-                console.log();
-                return {
-                    success: true,
-                    playlist: sendParams.playlist,
-                    action: 'send_playlist',
-                };
-            }
-            else {
-                // Send failed - return error without showing the playlist summary
+            const sendResult = await sendPreparedPlaylistToDevice(sendParams.playlist, {
+                verifyPlaylist,
+                sendToDevice: utilities.sendToDevice,
+                resolveDeviceName: () => resolveSendPlaylistDeviceName(sendParams.deviceName, defaultDeviceName),
+            });
+            if (!sendResult.success) {
                 console.log();
                 console.error(chalk_1.default.red('Send failed'));
                 if (sendResult.error) {
@@ -377,6 +411,16 @@ async function buildPlaylist(userRequest, options = {}) {
                     action: 'send_playlist',
                 };
             }
+            console.log(chalk_1.default.green('\nPlaylist sent'));
+            if (sendResult.deviceName) {
+                console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
+            }
+            console.log();
+            return {
+                success: true,
+                playlist: sendResult.playlist,
+                action: 'send_playlist',
+            };
         }
         // Check if this is a publish_playlist action
         if (params && params.action === 'publish_playlist') {

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

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Art Blocks marketplace resolver.
+ *
+ * AB collection URLs (`artblocks.io/collection/{slug}`) point to a series,
+ * not a token. Their public Hasura GraphQL at `artblocks-mainnet.hasura.app`
+ * resolves the slug to a contract + a representative tokenId in one call.
+ * From there, the standard Raster reverse-lookup enumerates the rest of the
+ * series like any other marketplace.
+ *
+ * AB does not publish a first-party MCP server as of 2026-05-17, so the
+ * direct GraphQL path is the right shape.
+ */
+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.resolveArtBlocksCollection = resolveArtBlocksCollection;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+const AB_GRAPHQL = 'https://artblocks-mainnet.hasura.app/v1/graphql';
+/**
+ * Resolve an Art Blocks collection slug to its contract address + the first
+ * minted tokenId in the series.
+ *
+ * @throws When the slug is unknown, the project has no minted tokens, or
+ *   the GraphQL call fails.
+ */
+async function resolveArtBlocksCollection(slug) {
+    logger.debug(`[AB] Resolving collection slug "${slug}"`);
+    const query = 'query ($slug: String!) {' +
+        '  projects_metadata(where: { slug: { _eq: $slug } }, limit: 1) {' +
+        '    contract_address' +
+        '    tokens(limit: 1, order_by: { invocation: asc }) { token_id }' +
+        '  }' +
+        '}';
+    const response = await fetch(AB_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(`Art Blocks GraphQL ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (data.errors && data.errors.length > 0) {
+        throw new Error(`Art Blocks GraphQL errors: ${data.errors.map((e) => e.message).join('; ')}`);
+    }
+    const project = data.data?.projects_metadata?.[0];
+    if (!project) {
+        throw new Error(`Art Blocks: no project found for slug "${slug}". ` +
+            'Check the URL — slugs come from artblocks.io/collection/{slug}. ' +
+            'AB Engine collaborations may live on a different subgraph and are not covered here yet.');
+    }
+    const firstToken = project.tokens?.[0];
+    if (!firstToken) {
+        throw new Error(`Art Blocks: project "${slug}" has no minted tokens yet. ` +
+            'Paste a specific token URL once at least one edition is minted.');
+    }
+    return {
+        chain: 'ethereum',
+        contract: project.contract_address.toLowerCase(),
+        tokenId: firstToken.token_id,
+    };
+}

package/dist/src/utilities/feral-file-artwork.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Feral File public artwork API helpers.
+ *
+ * The exhibition API is the source of truth for public artwork IDs, including
+ * swapped artwork IDs where the public URL id differs from the on-chain token
+ * id. The CLI should consume the identity fields returned by the artwork
+ * endpoint instead of reconstructing contract identity from exhibition internals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFeralFileArtwork = resolveFeralFileArtwork;
+exports.parseFeralFileArtworkId = parseFeralFileArtworkId;
+const user_agent_1 = require("./user-agent");
+/**
+ * resolveFeralFileArtwork resolves a public Feral File artwork id into indexer
+ * token coordinates using the self-describing artwork API response.
+ *
+ * @param artworkId - Public artwork id from Feral File.
+ * @param fetchImpl - Fetch implementation, injected by tests.
+ * @returns Token coordinates suitable for ff-indexer-v2 lookup.
+ */
+async function resolveFeralFileArtwork(artworkId, fetchImpl = fetch) {
+    const normalizedArtworkId = artworkId.trim();
+    if (!normalizedArtworkId) {
+        throw new Error('Feral File artwork id is required');
+    }
+    const url = `https://feralfile.com/api/artworks/${encodeURIComponent(normalizedArtworkId)}`;
+    const response = await fetchImpl(url, {
+        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
+    });
+    const body = (await response.json());
+    if (!response.ok) {
+        throw new Error(body.error?.message || `Feral File artwork lookup failed (${response.status})`);
+    }
+    const artwork = body.result;
+    if (!artwork) {
+        throw new Error('Feral File artwork lookup returned no result');
+    }
+    const chain = normalizeFeralFileChain(artwork.chain);
+    const contractAddress = stringField(artwork.contractAddress, 'contractAddress');
+    const tokenId = stringField(artwork.tokenID, 'tokenID');
+    return { chain, contractAddress, tokenId };
+}
+/**
+ * parseFeralFileArtworkId extracts the public artwork id from supported Feral
+ * File artwork URLs. Non-URL strings are treated as raw artwork ids so
+ * structured build inputs can pass the id directly.
+ *
+ * @param input - Feral File artwork URL or raw public artwork id.
+ * @returns Public artwork id.
+ */
+function parseFeralFileArtworkId(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error('Feral File artwork id is required');
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+    const host = parsed.hostname.replace(/^www\./, '').toLowerCase();
+    if (host !== 'feralfile.com') {
+        throw new Error(`Unsupported Feral File artwork URL host: ${parsed.hostname}`);
+    }
+    const match = parsed.pathname.match(/^\/exhibitions\/artwork\/([^/]+)\/?$/);
+    if (!match) {
+        throw new Error('Unsupported Feral File artwork URL path');
+    }
+    return decodeURIComponent(match[1]);
+}
+function normalizeFeralFileChain(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Feral File artwork is missing chain');
+    }
+    const normalized = value.toLowerCase();
+    if (normalized === 'ethereum' || normalized === 'tezos') {
+        return normalized;
+    }
+    throw new Error(`Unsupported Feral File artwork chain: ${value}`);
+}
+function stringField(value, fieldName) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Feral File artwork is missing ${fieldName}`);
+    }
+    return value;
+}

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

@@ -0,0 +1,115 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFeralFileToken = resolveFeralFileToken;
+/**
+ * Feral File marketplace resolver.
+ *
+ * Both artwork and series URLs go through the self-describing
+ * `/api/artworks/{id}` endpoint (one GET returning chain, contract, and the
+ * on-chain tokenID — including the swapped tokenID case where the public
+ * URL id differs from the on-chain id). Series URLs add one extra hop:
+ * resolve the series slug, then look up its first artwork, then hand that
+ * artwork id to `resolveFeralFileArtwork`. The exhibition's contract list is
+ * not consulted — exhibitions can host multiple series across multiple
+ * contracts, so picking-first would silently route a Tezos series to an
+ * Ethereum sibling contract on the same exhibition.
+ *
+ * Show URLs are rejected: a single exhibition spans multiple series, which
+ * is wider than v1 supports.
+ */
+const logger = __importStar(require("../logger"));
+const feral_file_artwork_1 = require("./feral-file-artwork");
+const user_agent_1 = require("./user-agent");
+const FF_API_BASE = 'https://feralfile.com/api';
+async function ffFetch(path) {
+    const url = `${FF_API_BASE}${path}`;
+    logger.debug(`[FF API] GET ${url}`);
+    const response = await fetch(url, {
+        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Feral File API ${response.status} ${response.statusText} for ${path}: ${body.slice(0, 200)}`);
+    }
+    return (await response.json());
+}
+/**
+ * Resolve a parsed Feral File URL to on-chain token coordinates. For series
+ * URLs we return one representative token; the Raster reverse-lookup in the
+ * caller resolves to the series and enumerates the rest.
+ */
+async function resolveFeralFileToken(parsed) {
+    switch (parsed.urlKind) {
+        case 'artwork':
+            return resolveFromArtworkID(parsed.identifier);
+        case 'series':
+            return resolveFromSeriesSlug(parsed.identifier);
+        case 'show':
+            throw new Error('Feral File `/exhibitions/shows/{slug}` URLs span multiple series; not supported in v1. ' +
+                'Paste a specific series (`/exhibitions/series/{slug}`) or artwork URL.');
+    }
+}
+async function resolveFromArtworkID(publicArtworkId) {
+    // /api/artworks/{id} returns chain + contractAddress + on-chain tokenID
+    // directly, including the swapped-id case where URL id != on-chain id.
+    const { chain, contractAddress, tokenId } = await (0, feral_file_artwork_1.resolveFeralFileArtwork)(publicArtworkId);
+    return {
+        chain,
+        contract: chain === 'ethereum' ? contractAddress.toLowerCase() : contractAddress,
+        tokenId,
+    };
+}
+async function resolveFromSeriesSlug(slug) {
+    const series = await ffFetch(`/series?slug=${encodeURIComponent(slug)}`);
+    if (!series.result || series.result.length === 0) {
+        throw new Error(`Feral File: no series found for slug "${slug}".`);
+    }
+    // Slug collisions across exhibitions are documented in ff-exhibition#3039.
+    // Take the first record; the user can pass the artwork URL directly to disambiguate.
+    if (series.result.length > 1) {
+        logger.warn(`[FF API] Slug "${slug}" matched ${series.result.length} series across exhibitions; ` +
+            'taking the first. Pass /exhibitions/artwork/{tokenId} to disambiguate.');
+    }
+    const picked = series.result[0];
+    const artworks = await ffFetch(`/artworks?seriesID=${encodeURIComponent(picked.id)}`);
+    if (!artworks.result || artworks.result.length === 0) {
+        throw new Error(`Feral File: series "${slug}" has no artworks.`);
+    }
+    // Hand the representative artwork's public id to the canonical resolver so
+    // we get the right (chain, contract, on-chain tokenID) for THIS series —
+    // not whatever picking-first off the exhibition's contract list returned.
+    return resolveFromArtworkID(artworks.result[0].id);
+}

package/dist/src/utilities/ff1-device.js

@@ -117,13 +117,13 @@ function isTransientDeviceNetworkError(error) {
  * @example
  * // Send to first device
  * const result = await sendPlaylistToDevice({
- *   playlist: { version: '1.0.0', title: 'My Collection', items: [...] }
+ *   playlist: { version: '1.1.0', title: 'My Collection', items: [...] }
  * });
  *
  * @example
  * // Send to specific device by name
  * const result = await sendPlaylistToDevice({
- *   playlist: { version: '1.0.0', title: 'My Collection', items: [...] },
+ *   playlist: { version: '1.1.0', title: 'My Collection', items: [...] },
  *   deviceName: 'Living Room Display'
  * });
  */
@@ -204,7 +204,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                 success: false,
                 error: `Could not reach device "${deviceLabel}" at ${device.host}`,
                 details: 'Check that the device is powered on and reachable on your network. ' +
-                    'If the device IP changed (e.g. after a factory reset), run: ff1 setup',
+                    'If the device IP changed (e.g. after a factory reset), run: ff-cli setup',
             };
         }
         // Check response status
@@ -239,7 +239,7 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                 success: false,
                 error: `Could not reach device "${deviceLabel}" at ${device.host}`,
                 details: 'Check that the device is powered on and reachable on your network. ' +
-                    'If the device IP changed (e.g. after a factory reset), run: ff1 setup',
+                    'If the device IP changed (e.g. after a factory reset), run: ff-cli setup',
             };
         }
         return {

package/dist/src/utilities/functions.js

@@ -41,7 +41,7 @@ const ff1Device = require('./ff1-device');
 const domainResolver = require('./domain-resolver');
 const logger = require('../logger');
 /**
- * Build DP1 v1.0.0 compliant playlist
+ * Build DP1 v1.1.0 compliant playlist
  *
  * This is the actual implementation called by AI orchestrator's function calling.
  * Uses core playlist-builder utilities.