@feralfile/cli 1.3.1 → 1.5.0

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

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * OpenSea marketplace resolver.
+ *
+ * OpenSea collection URLs (`opensea.io/collection/{slug}`) point to a series,
+ * not a token. OpenSea's REST API requires an API key, so this resolver reads
+ * the public collection page instead: the server-rendered HTML embeds the
+ * first page of collection items as relay-style JSON where each item carries
+ * `"chain":{"identifier":...},"contractAddress":"0x...","tokenId":"..."`
+ * adjacently. One extracted (contract, tokenId) pair is enough — the standard
+ * Raster reverse-lookup then enumerates the rest of the series like any other
+ * marketplace.
+ *
+ * Extraction invariants (what must not change):
+ * - Match only the adjacent `contractAddress` + `tokenId` pattern. The page
+ *   also embeds payment-token contracts (WETH etc.) in other JSON shapes that
+ *   never carry an adjacent tokenId, so adjacency is the noise filter.
+ * - The most frequent contract among matches wins (collection items dominate
+ *   any stray adjacency), and its lowest tokenId is the deterministic seed.
+ * - tokenIds are compared as BigInt: ERC-721 ids can exceed Number range.
+ *
+ * Trade-off: scraping page HTML is less stable than a documented API, but the
+ * alternative (requiring every user to provision an OpenSea API key) defeats
+ * the paste-a-URL UX. Errors below name the fallback (`/item/` token URL) so
+ * a layout change degrades to a one-step workaround, not a dead end.
+ */
+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.resolveOpenSeaCollection = resolveOpenSeaCollection;
+const logger = __importStar(require("../logger"));
+const user_agent_1 = require("./user-agent");
+/**
+ * One embedded collection item: chain identifier, contract, tokenId. The
+ * `[^{}]*` keeps the chain object match from swallowing unrelated JSON when
+ * OpenSea reorders fields inside `chain`.
+ */
+const ITEM_PATTERN = /"chain":\{"identifier":"([a-z0-9_-]+)"[^{}]*\},"contractAddress":"(0x[a-fA-F0-9]{40})","tokenId":"(\d+)"/g;
+const FALLBACK_HINT = 'Paste a specific token URL (opensea.io/item/ethereum/{contract}/{tokenId}) ' +
+    'or use `ethereum:{contract}:{tokenId}`.';
+/**
+ * Resolve an OpenSea collection slug to its contract address + the lowest
+ * tokenId visible on the collection page (a representative seed for the
+ * Raster series lookup).
+ *
+ * @throws When the page cannot be fetched, embeds no recognizable items
+ *   (layout change or empty collection), or the collection is not on
+ *   Ethereum mainnet (outside FF indexer coverage).
+ */
+async function resolveOpenSeaCollection(slug) {
+    logger.debug(`[OpenSea] Resolving collection slug "${slug}"`);
+    const response = await fetch(`https://opensea.io/collection/${encodeURIComponent(slug)}`, {
+        headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'text/html' },
+    });
+    if (!response.ok) {
+        throw new Error(`OpenSea collection page returned ${response.status} ${response.statusText}. ` + FALLBACK_HINT);
+    }
+    const html = await response.text();
+    // Tally (contract → tokenIds) per chain so the dominant-contract rule and
+    // the ethereum-only guard can both give precise errors.
+    const byContract = new Map();
+    for (const match of html.matchAll(ITEM_PATTERN)) {
+        const [, chain, contract, tokenId] = match;
+        const key = contract.toLowerCase();
+        const entry = byContract.get(key) ?? { chain, tokenIds: [] };
+        entry.tokenIds.push(BigInt(tokenId));
+        byContract.set(key, entry);
+    }
+    if (byContract.size === 0) {
+        throw new Error(`OpenSea: no items found on the collection page for "${slug}". ` +
+            'The collection may be empty, or the page layout changed. ' +
+            FALLBACK_HINT);
+    }
+    let best = null;
+    for (const [contract, entry] of byContract) {
+        if (!best || entry.tokenIds.length > best.tokenIds.length) {
+            best = { contract, ...entry };
+        }
+    }
+    // byContract.size > 0 guarantees best is set; the check keeps TS honest.
+    if (!best) {
+        throw new Error(`OpenSea: no items found for "${slug}". ${FALLBACK_HINT}`);
+    }
+    if (best.chain !== 'ethereum') {
+        throw new Error(`OpenSea collection "${slug}" is on ${best.chain} — ff-cli covers Ethereum and ` +
+            'Tezos mainnet only. Paste an Ethereum-chain source instead.');
+    }
+    const seed = best.tokenIds.reduce((min, id) => (id < min ? id : min));
+    logger.debug(`[OpenSea] Resolved "${slug}" → ${best.contract} (seed tokenId ${seed}, ` +
+        `${best.tokenIds.length} items sampled)`);
+    return { chain: 'ethereum', contract: best.contract, tokenId: seed.toString() };
+}

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

@@ -2,8 +2,72 @@
  * Playlist Builder Utilities
  * Core functions for building and validating DP1 playlists
  */
-const { getPlaylistConfig } = require('../config');
+const { getPlaylistConfig, getConfig } = require('../config');
 const { signPlaylist } = require('./playlist-signer');
+/**
+ * isTimeBasedMedia reports whether an item's media has an intrinsic runtime
+ * (video or audio) per DP-1 §4.1 "time-based sources".
+ *
+ * Two signals are consulted because neither is reliable alone: indexer
+ * `display.mime_type` is authoritative when present but is defaulted to
+ * 'image/png' upstream when missing, and URL extensions only cover direct
+ * media links. Either signal saying video/audio wins.
+ *
+ * @param {string} [mimeType] - MIME type reported by the indexer, if any
+ * @param {string} [sourceUrl] - Item source URL, used as an extension fallback
+ * @returns {boolean} True when the media is video or audio
+ */
+function isTimeBasedMedia(mimeType, sourceUrl) {
+    const candidates = [String(mimeType || '').toLowerCase(), detectMimeType(sourceUrl)];
+    return candidates.some((mime) => mime.startsWith('video/') || mime.startsWith('audio/'));
+}
+/**
+ * applyItemTiming sets a DP1 item's playback timing per DP-1 §4.1.
+ *
+ * Invariant this function owns: an explicit numeric `duration` always wins
+ * and is stamped as-is. When `duration` is undefined/null ("auto"), a
+ * time-based source (video/audio) gets NO duration and `display.loop: false`,
+ * so a conformant player MUST advance at end-of-stream — the media plays its
+ * natural length. Static and code-based sources fall back to the configured
+ * `defaultDuration` because they have no intrinsic runtime to play out.
+ *
+ * Do not re-introduce an unconditional duration here: stamping a default on
+ * video items silently truncates or pads them (the bug this fixed).
+ *
+ * @param {Object} item - DP1 playlist item (mutated in place)
+ * @param {Object} mediaHints - Media signals for the time-based check
+ * @param {string} [mediaHints.mimeType] - Indexer-reported MIME type
+ * @param {string} [mediaHints.sourceUrl] - Item source URL
+ * @param {number} [duration] - Explicit display seconds; omit for auto
+ * @returns {Object} The same item, for chaining
+ */
+function applyItemTiming(item, mediaHints = {}, duration) {
+    if (typeof duration === 'number') {
+        item.duration = duration;
+        return item;
+    }
+    if (isTimeBasedMedia(mediaHints.mimeType, mediaHints.sourceUrl)) {
+        item.display = { ...(item.display || {}), loop: false };
+        return item;
+    }
+    item.duration = getDefaultStaticDuration();
+    return item;
+}
+/**
+ * getDefaultStaticDuration returns the configured per-item display seconds
+ * for media without an intrinsic runtime. Falls back to 10 when config is
+ * unavailable (e.g. unit tests without a config file).
+ *
+ * @returns {number} Display duration in seconds
+ */
+function getDefaultStaticDuration() {
+    try {
+        return getConfig().defaultDuration || 10;
+    }
+    catch (_error) {
+        return 10;
+    }
+}
 /**
  * Convert a string to a URL-friendly slug
  *
@@ -31,14 +95,16 @@ function slugify(value) {
  * Convert single NFT token info to DP1 playlist item
  *
  * @param {Object} tokenInfo - Token information from NFT indexer
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
+ *   (video/audio play natural length per DP-1 §4.1, static media uses the
+ *   configured default — see applyItemTiming)
  * @returns {Object} DP1 playlist item
  * @throws {Error} When token data is missing or source is a data URI
  * @example
  * const item = convertTokenToDP1ItemSingle(tokenInfo, 10);
  * // Returns: { title, source, duration, license, provenance, ... }
  */
-function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
+function convertTokenToDP1ItemSingle(tokenInfo, duration) {
     const { token } = tokenInfo;
     if (!token) {
         throw new Error('Invalid token info: missing token data');
@@ -75,7 +141,6 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
         id: itemId,
         title: token.name || `Token #${token.tokenId}`,
         source: sourceUrl,
-        duration: duration,
         license: 'token', // NFTs are token-gated by default
         created: new Date().toISOString(),
         provenance: {
@@ -102,7 +167,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
     if ((token.animation_url || token.animationUrl) && (token.image?.url || token.image)) {
         dp1Item.ref = token.image?.url || token.image;
     }
-    return dp1Item;
+    return applyItemTiming(dp1Item, { mimeType: token.image?.mimeType, sourceUrl }, duration);
 }
 /**
  * Convert NFT token info(s) to DP1 playlist item(s)
@@ -111,7 +176,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
  * For collections, returns a map of token key to DP1 item.
  *
  * @param {Object|Array} tokenInfo - Token information (single object or map of tokens)
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Object} Map of token key to DP1 playlist item, or single item
  * @example
  * // Single token
@@ -120,7 +185,7 @@ function convertTokenToDP1ItemSingle(tokenInfo, duration = 10) {
  * // Multiple tokens
  * const items = convertTokenToDP1Item({ token1: info1, token2: info2 }, 10);
  */
-function convertTokenToDP1Item(tokenInfo, duration = 10) {
+function convertTokenToDP1Item(tokenInfo, duration) {
     // Handle array or map of tokens
     if (typeof tokenInfo === 'object' && !tokenInfo.token) {
         const results = {};
@@ -163,12 +228,12 @@ function convertTokenToDP1Item(tokenInfo, duration = 10) {
  * Excludes items with data URIs in their source field.
  *
  * @param {Array} tokensInfo - Array of token information
- * @param {number} duration - Display duration in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
  * @returns {Array} Array of DP1 playlist items
  * @example
  * const items = convertTokensToDP1Items(tokensInfoArray, 10);
  */
-function convertTokensToDP1Items(tokensInfo, duration = 10) {
+function convertTokensToDP1Items(tokensInfo, duration) {
     return tokensInfo
         .filter((info) => info.success && info.token)
         .map((info) => {
@@ -313,7 +378,10 @@ async function buildDP1Playlist(paramsOrItems, options = {}) {
                 margin: 0,
             },
             license: 'token',
-            duration: 10,
+            // No defaults.duration: items that should be timed carry an explicit
+            // duration already, and a playlist-level default would make conformant
+            // players time-cut items that intentionally omit duration to play
+            // their natural length (DP-1 §4.1 end-of-stream advance).
         },
     };
     // Always include slug (auto-generated when missing)
@@ -384,11 +452,14 @@ function validateDP1Playlist(playlist) {
             else if (typeof item.source !== 'string') {
                 errors.push(`Item ${index}: Field "source" must be a string (URI)`);
             }
-            if (item.duration === undefined || item.duration === null) {
-                errors.push(`Item ${index}: Missing required field "duration"`);
-            }
-            else if (typeof item.duration !== 'number' || item.duration < 1) {
-                errors.push(`Item ${index}: Field "duration" must be a number >= 1`);
+            // Duration is OPTIONAL per the DP-1 v1.1.0 schema (PlaylistItem requires
+            // only `source`; duration has `minimum: 0`). Absent duration is meaningful:
+            // time-based sources advance at end-of-stream (§4.1). Do not tighten this
+            // back to required — it would reject spec-valid playlists.
+            if (item.duration !== undefined && item.duration !== null) {
+                if (typeof item.duration !== 'number' || item.duration < 0) {
+                    errors.push(`Item ${index}: Field "duration" must be a number >= 0`);
+                }
             }
             if (!item.license) {
                 errors.push(`Item ${index}: Missing required field "license"`);
@@ -461,12 +532,13 @@ function detectMimeType(url) {
  * Build a single DP1 playlist item from a URL
  *
  * @param {string} url - Media URL
- * @param {number} duration - Duration per item in seconds
+ * @param {number} [duration] - Explicit display seconds; omit for auto timing
+ *   (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
  * @returns {Object} DP1 playlist item
  */
-function buildUrlItem(url, duration = 10, options = {}) {
+function buildUrlItem(url, duration, options = {}) {
     const sourceUrl = String(url || '').trim();
     if (!sourceUrl) {
         throw new Error('URL is required to build a playlist item');
@@ -496,7 +568,6 @@ function buildUrlItem(url, duration = 10, options = {}) {
         id: itemId,
         title,
         source: sourceUrl,
-        duration: duration,
         license: 'open',
         created: new Date().toISOString(),
         provenance: {
@@ -509,7 +580,7 @@ function buildUrlItem(url, duration = 10, options = {}) {
             margin: 0,
         },
     };
-    return item;
+    return applyItemTiming(item, { sourceUrl }, duration);
 }
 module.exports = {
     convertTokenToDP1Item,
@@ -519,5 +590,7 @@ module.exports = {
     buildDP1Playlist,
     validateDP1Playlist,
     detectMimeType,
+    isTimeBasedMedia,
+    applyItemTiming,
     buildUrlItem,
 };

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

@@ -93,7 +93,9 @@ async function loadPlaylistSource(source) {
  * `loadedAsPlaylist` boolean dance.
  *
  * @param source - User-supplied path or URL
- * @param defaultDuration - Duration (seconds) for the synthesized media item
+ * @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
  */