@feralfile/cli 1.3.1 → 1.5.0

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

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

package/docs/CONFIGURATION.md

@@ -26,7 +26,8 @@ npm run dev -- config show
   - Used by orchestration to pick API, timeouts, and model identifier.
 
 - **defaultDuration** (number, seconds)
-  - Intended default per‑item display duration. Some flows pass an explicit duration; when omitted, utilities fall back to 10s.
+  - Default per‑item display duration for media without an intrinsic runtime (images, code-based works). Falls back to 10s when unset.
+  - Does NOT apply to video/audio items: with no explicit duration those are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) — the media plays its natural length.
 
 ## models
 
@@ -115,6 +116,19 @@ Environment variable alternative:
 FEED_BASE_URLS=https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
 ```
 
+## find (Raster API)
+
+`ff-cli find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)). No configuration is required; two environment variables adjust the integration:
+
+```env
+# API key sent as the x-api-key header. The API currently answers without
+# one, but Raster's docs declare a key required — set this once enforced.
+RASTER_API_KEY=rk_your_key_here
+
+# Override the GraphQL endpoint (default: https://api.raster.art/graphql).
+RASTER_API_URL=https://api.raster.art/graphql
+```
+
 ## ff1Devices
 
 Configure devices you want to play content on.

package/docs/FUNCTION_CALLING.md

@@ -75,12 +75,14 @@ Two options are available:
       "quantity": 2
     }
   ],
-  "playlistSettings": { "durationPerItem": 10, "preserveOrder": true, "title": "My Mix" }
+  "playlistSettings": { "preserveOrder": true, "title": "My Mix" }
 }
 ```
 
 This path bypasses the intent parser/orchestrator and calls utilities directly. Validation and sensible defaults are applied in `src/main.ts`.
 
+`playlistSettings.durationPerItem` is optional. Omit it for auto timing: video/audio items are emitted without `duration` and with `display.loop: false`, so a DP-1 player advances at end-of-stream (§4.1) and the media plays its natural length; static items fall back to `defaultDuration`. Set `durationPerItem` only to force a fixed display time on every item.
+
 2. AI‑orchestrated deterministic build (recommended for prompts): Use `chat` with `--verbose` to see tool calls. The orchestrator enforces complete requirement objects, then runs `verify_playlist` (structure only) before sending.
 
 ## Extending Functionality (OSS‑first)

package/docs/README.md

@@ -148,6 +148,7 @@ Notes:
   - Options: `-d, --device <name>`, `--skip-verify` (skip signature verification; not recommended)
 - `find <input>` – Resolve a marketplace URL, raw `chain:contract:tokenId`, or wallet address into a playable DP-1 playlist
   - Sources: Art Blocks, Objkt, fxhash, OpenSea, SuperRare, Feral File, Neort, Verse, raw on-chain coordinates, and wallet addresses
+  - OpenSea forms: `/assets/ethereum/{contract}/{tokenId}`, `/item/ethereum/{contract}/{tokenId}`, and `/collection/{slug}` (Ethereum collections; the slug is resolved from the public collection page, no API key needed)
   - Verse forms: `/items/ethereum/{contract}/{tokenId}` and `/series/{slug}`
   - Options: `-o, --output <path>`, `-l, --limit <n>`, `-p, --play`, `-d, --device <name>`, `--publish`, `-s, --server <index>`, `-y, --yes`, `--skip-verify`
 - `publish <file>` – Publish a playlist to a feed server (runs `verify` before upload and rejects unsigned or broken playlists)
@@ -343,7 +344,7 @@ Setup preserves existing devices when adding new ones. See selection rules and e
 
 - Max 20 items total across all requirements
 - Per-source caps enforced in utilities
-- Duration per item defaults to 10s (configurable)
+- Per-item timing: when no duration is given, video/audio items carry **no** `duration` and `display.loop: false`, so the player advances at end-of-stream (DP-1 §4.1) — the media plays its natural length. Static items use `defaultDuration` (10s unless configured). An explicit duration always wins.
 
 ## Links
 

package/package.json

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