r3plica 1.5.0 → 2.3.0

package/README.md

@@ -1,191 +1,290 @@
-# r3 — R3PLICA CLI
-
-Query the R3PLICA digital replicas catalog from your terminal. Search products, brands, collections, and finishes — built for AI agents, developers, and scripts.
-
-## Install
-
-```bash
-npm install -g r3plica
-```
-
-Requires Node.js 20+.
-
-## Quick Start
-
-```bash
-# Search products
-r3 product search "dining table"
-
-# List brands
-r3 brand list
-
-# Filter by brand and category
-r3 product list --brand "Cattelan Italia" --category table
-
-# Get product details
-r3 product get <mongo_id>
-
-# Pipe to jq
-r3 product list --limit 5 --json | jq '.[].name'
-```
-
-## Commands
-
-### Products
-
-```bash
-r3 product list [--brand X] [--category X] [--collection X] [--designer X] [--year X] [--limit N] [--page N]
-r3 product search <query> [--brand X] [--category X] [--designer X] [--year X] [--limit N]
-r3 product get <mongo_id>
-r3 product stats [--by category|brand|designer|year] [--brand X]
-r3 product compare <id1> <id2>
-```
-
-### Brands
-
-```bash
-r3 brand list [--country X] [--limit N]
-r3 brand search <query>
-```
-
-### Product Collections
-
-Product collections are furniture lines from a brand (e.g., "Tudor" by Cattelan Italia).
-
-```bash
-r3 product-collection list [--brand X] [--limit N] [--page N] [--sort X] [--order asc|desc]
-r3 product-collection search <query>
-```
-
-### Finish Collections
-
-Finish collections are sets of material finishes (shaders) — wood types, fabrics, metals, leathers — that can be applied to product parts.
-
-```bash
-r3 finish-collection list [--brand X] [--category X] [--limit N] [--page N]
-r3 finish-collection search <query>
-r3 finish-collection get <mongo_id>
-```
-
-### Configuration
-
-```bash
-r3 config show
-r3 config set api-url <url>
-```
-
-Default API URL: `https://api.r3plica.space/api/r3vault`. Override with `R3_API_URL` environment variable or `r3 config set`.
-
-## Output
-
-- **Terminal**: formatted table with headers and result count
-- **Piped**: JSON (automatic detection)
-- `--json`: force JSON output
-- `--pretty`: force table output
-- `--markdown`: force markdown table output
-
-```bash
-# Table output (terminal)
-$ r3 brand list --limit 3
-
-  ┌──────────────────┬───────────────────────────┬─────────────────┬────────────┐
-  │ ID               │ Name                      │ Country         │ Products   │
-  ├──────────────────┼───────────────────────────┼─────────────────┼────────────┤
-  │ 0a497f00-cc6f-45 │ Driade                    │ Italy           │ 29         │
-  │ 22b4a540-bcf2-4e │ We Are IB                 │ Italy           │ 37         │
-  │ ab368a13-6038-41 │ Emu                       │ Italy           │ 26         │
-  └──────────────────┴───────────────────────────┴─────────────────┴────────────┘
-  3 brands found
-
-# JSON output (piped or --json)
-$ r3 brand list --limit 1 --json | jq '.[0].name'
-"Driade"
-```
-
-## Use with AI Agents
-
-### Claude Code / CLAUDE.md
-
-Add to your project's `CLAUDE.md`:
-
-```markdown
-## R3PLICA Catalog
-
-The `r3` CLI queries the R3PLICA digital replicas catalog. Use it when the user
-asks about furniture, finishes, brands, or design products.
-
-- `r3 product search "query"` — search products by text
-- `r3 product list --brand X --category X` — filter products
-- `r3 product list --designer "Name"` — filter by designer
-- `r3 product get <id>` — product details with finish options
-- `r3 product stats --by brand` — catalog breakdown
-- `r3 product compare <id1> <id2>` — side-by-side comparison
-- `r3 brand list` — all available brands
-- `r3 finish-collection list --brand X` — available finish collections
-- Always use `--json` when processing results programmatically
-- Run `r3 --help` for full command reference
-```
-
-### MCP Server
-
-The package also includes an MCP server for auto-discovery in Claude Desktop, Cursor, and similar IDEs.
-
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "r3plica": {
-      "command": "r3-mcp"
-    }
-  }
-}
-```
-
-The MCP server exposes the same data through 10 tools: `product_list`, `product_search`, `product_get`, `brand_list`, `brand_search`, `product_collection_list`, `product_collection_search`, `finish_collection_list`, `finish_collection_search`, `finish_collection_get`.
-
-## Examples
-
-```bash
-# Find Italian brands
-r3 brand list --country Italy
-
-# Search chairs, limit to 5 results
-r3 product search "chair" --limit 5
-
-# Get all products from a brand
-r3 product list --brand "Driade"
-
-# Explore a product collection
-r3 product-collection search "Tudor"
-
-# Find products by designer
-r3 product list --designer "Philippe Starck"
-
-# Catalog stats
-r3 product stats --by brand
-r3 product stats --brand "Driade" --by designer
-
-# Compare two products
-r3 product compare <id1> <id2>
-
-# Find wood finishes
-r3 finish-collection list --category wood
-
-# Script: get all brand names
-r3 brand list --json | jq -r '.[].name'
-
-# Script: count products per brand
-r3 brand list --json | jq -r '.[].name' | while read brand; do
-  count=$(r3 product list --brand "$brand" --json 2>/dev/null | jq length)
-  echo "$brand: $count"
-done
-```
-
-## About R3PLICA
-
-[R3PLICA](https://r3plica.space) provides certified digital replicas of branded furniture, finishes, and materials to architects, interior designers, and visualization professionals. The catalog includes 60+ premium partner brands including Cattelan Italia, Driade, Poliform, and more.
-
-## License
-
-Proprietary - R3PLICA S.r.l.
+# r3 — R3PLICA CLI
+
+Query the R3PLICA digital replicas catalog from your terminal. Search products, brands, collections, and finishes — built for AI agents, developers, and scripts.
+
+## Install
+
+```bash
+npm install -g r3plica
+```
+
+Requires Node.js 20+.
+
+## Quick Start
+
+```bash
+# Search products
+r3 product search "dining table"
+
+# List brands
+r3 brand list
+
+# Filter by brand and category
+r3 product list --brand "Cattelan Italia" --category table
+
+# Get product details
+r3 product get <mongo_id>
+
+# Pipe to jq
+r3 product list --limit 5 --json | jq '.[].name'
+```
+
+## Commands
+
+### Products
+
+```bash
+r3 product list [--brand X] [--category X] [--collection X] [--designer X] [--year X] [--limit N] [--page N]
+r3 product search <query> [--brand X] [--category X] [--designer X] [--year X] [--limit N]
+r3 product get <mongo_id>
+r3 product stats [--by category|brand|designer|year] [--brand X]
+r3 product compare <id1> <id2>
+```
+
+### Brands
+
+```bash
+r3 brand list [--country X] [--limit N]
+r3 brand search <query>
+```
+
+### Product Collections
+
+Product collections are furniture lines from a brand (e.g., "Tudor" by Cattelan Italia).
+
+```bash
+r3 product-collection list [--brand X] [--limit N] [--page N] [--sort X] [--order asc|desc]
+r3 product-collection search <query>
+```
+
+### Finish Collections
+
+Finish collections are sets of material finishes (shaders) — wood types, fabrics, metals, leathers — that can be applied to product parts.
+
+```bash
+r3 finish-collection list [--brand X] [--category X] [--limit N] [--page N]
+r3 finish-collection search <query>
+r3 finish-collection get <mongo_id>
+```
+
+### Configuration
+
+```bash
+r3 config show
+r3 config set api-url <url>
+```
+
+Default API URL: `https://api.r3plica.space/api/r3vault`. Override with `R3_API_URL` environment variable or `r3 config set`.
+
+## Output
+
+- **Terminal**: formatted table with headers and result count
+- **Piped**: JSON (automatic detection)
+- `--json`: force JSON output
+- `--pretty`: force table output
+- `--markdown`: force markdown table output
+
+```bash
+# Table output (terminal)
+$ r3 brand list --limit 3
+
+  ┌──────────────────┬───────────────────────────┬─────────────────┬────────────┐
+  │ ID               │ Name                      │ Country         │ Products   │
+  ├──────────────────┼───────────────────────────┼─────────────────┼────────────┤
+  │ 0a497f00-cc6f-45 │ Driade                    │ Italy           │ 29         │
+  │ 22b4a540-bcf2-4e │ We Are IB                 │ Italy           │ 37         │
+  │ ab368a13-6038-41 │ Emu                       │ Italy           │ 26         │
+  └──────────────────┴───────────────────────────┴─────────────────┴────────────┘
+  3 brands found
+
+# JSON output (piped or --json)
+$ r3 brand list --limit 1 --json | jq '.[0].name'
+"Driade"
+```
+
+## Use with AI Agents
+
+### Claude Code / CLAUDE.md
+
+Add to your project's `CLAUDE.md`:
+
+```markdown
+## R3PLICA Catalog
+
+The `r3` CLI queries the R3PLICA digital replicas catalog. Use it when the user
+asks about furniture, finishes, brands, or design products.
+
+- `r3 product search "query"` — search products by text
+- `r3 product list --brand X --category X` — filter products
+- `r3 product list --designer "Name"` — filter by designer
+- `r3 product get <id>` — product details with finish options
+- `r3 product stats --by brand` — catalog breakdown
+- `r3 product compare <id1> <id2>` — side-by-side comparison
+- `r3 brand list` — all available brands
+- `r3 finish-collection list --brand X` — available finish collections
+- Always use `--json` when processing results programmatically
+- Run `r3 --help` for full command reference
+```
+
+### MCP Server
+
+The package also includes an MCP server for auto-discovery in Claude Desktop, Cursor, and similar IDEs.
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "r3plica": {
+      "command": "r3-mcp"
+    }
+  }
+}
+```
+
+The MCP server exposes the catalog through 13 tools — `product_list`, `product_search`, `product_get`, `product_stats`, `product_compare`, `brand_list`, `brand_get`, `brand_search`, `product_collection_list`, `product_collection_search`, `finish_collection_list`, `finish_collection_search`, `finish_collection_get` — plus 3 Unreal Engine tools (see below).
+
+## Remote MCP (no install)
+
+For users who want to access the R3PLICA catalog from Claude Desktop **without installing the full npm package**, the catalog half is also available as a remote MCP endpoint hosted on Cloudflare Workers. Claude Desktop doesn't natively accept URL-only configs yet, so we use the standard `mcp-remote` bridge that proxies a local stdio connection to the remote HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "R3PLICA": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.r3plica.space/sse"]
+    }
+  }
+}
+```
+
+Paste this into your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and restart Claude. The bridge is auto-fetched via `npx` on first connection — no manual install. The 13 catalog tools are immediately available.
+
+Requires Node.js 20+ on the user's machine (for `npx`). When Claude Desktop adds native HTTP MCP support (in roadmap from Anthropic), users will be able to switch to the simpler `{"url": ...}` form.
+
+Note: the **UE bridge tools** (`ue_spawn_product`, `ue_move_actor`, `ue_list_scene`, `ue_list_available_assets`, `ue_get_camera`) are NOT exposed remotely. They require localhost reachability to your Unreal Engine editor and are only available via the local stdio MCP server (this npm package).
+
+Landing page with install instructions: [mcp.r3plica.space](https://mcp.r3plica.space)
+
+### Deploying the Remote MCP (maintainers only)
+
+The remote server is deployed via Cloudflare Workers. Local development:
+
+```bash
+npm run remote:dev          # wrangler dev → http://localhost:8787
+npm run remote:deploy       # wrangler deploy → mcp.r3plica.space
+npm run remote:tail         # live logs from production
+```
+
+First-time setup:
+
+1. `wrangler login` — authenticate with the R3PLICA Cloudflare account
+2. (Optional) Create rate-limit KV namespace: `wrangler kv:namespace create RATE_LIMIT` and paste the returned id into `wrangler.toml`
+3. Update DNS: `mcp.r3plica.space` currently points to the old Digital Ocean droplet — replace the A record with a CNAME to `<your-workers-domain>.workers.dev` (or use Cloudflare's "Add Custom Domain" UI from the Workers dashboard)
+4. `wrangler deploy` — pushes the worker live
+
+## Unreal Engine bridge (v1.6+)
+
+The MCP server can drive a live Unreal Engine editor session to spawn and arrange R3PLICA products in a 3D scene. The AI assistant queries the catalog and places assets in the level, end-to-end in one conversation.
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `ue_spawn_product` | Spawn an asset by `product_id` (resolves path via template) or explicit `asset_path`. Returns an actor tag. |
+| `ue_move_actor` | Move/rotate a spawned actor by tag. |
+| `ue_list_scene` | List all R3PLICA actors in the active level. |
+
+### One-time UE setup
+
+1. **Enable plugins** in the Unreal project: *Remote Control API* and *Remote Control Web Interface* (Edit → Plugins). Restart the editor.
+2. **Confirm Remote Control is listening** on `http://localhost:30010` (default). Override with `Project Settings → Plugins → Remote Control` or with `-RCWebControlEnable -RCWebControlPort=30010` launch flags.
+3. **Create a helper Blueprint** `BP_R3MCPBridge` (Actor) with three custom functions exposed to the editor:
+   - `SpawnProduct(AssetPath: String, Location: Vector, Rotation: Rotator, Tag: String) → bool` — loads the asset via `LoadAsset` and calls `SpawnActor`, tagging the spawned actor with `Tag` (and adding the gameplay tag `R3Product`).
+   - `MoveActor(ActorTag: String, Location: Vector, Rotation: Rotator) → bool` — finds the actor by tag and sets its transform.
+   - `ListR3Actors() → String` — returns a JSON string listing actors tagged `R3Product` with `{tag, asset, location, rotation}`.
+   - (Optional) `DeleteActor(ActorTag: String) → bool`
+4. **Place** one `BP_R3MCPBridge` instance in the demo level.
+5. **Create a Remote Control Preset** `RCP_R3MCP` (Content Browser → Right-click → Remote Control → Remote Control Preset). Open it, drag the `BP_R3MCPBridge` actor in, and expose the four functions above.
+
+### Asset path convention
+
+The default template matches the R3PLICA project convention:
+
+```
+/Game/R3PLICA/{brand}/Products/{collection}/Meshes/{asset_name}.{asset_name}
+```
+
+Brand and collection segments preserve case (e.g. `Cantori/Products/Avantgarde/`). Names are sanitized to replace non-alphanumeric characters with underscores but no lowercasing is applied. Available template variables: `{brand}`, `{collection}`, `{asset_name}`, `{category}`.
+
+Override globally if needed:
+
+```bash
+r3 config set ue-asset-template "/Game/R3PLICA/{brand}/{asset_name}.{asset_name}"
+```
+
+Or pass `asset_path` explicitly to `ue_spawn_product` when the convention doesn't apply.
+
+### Config keys
+
+```bash
+r3 config set ue-host localhost          # default
+r3 config set ue-port 30010              # default
+r3 config set ue-preset RCP_R3MCP        # default
+r3 config set ue-asset-template "/Game/R3PLICA/{brand}/{asset_name}.{asset_name}"
+```
+
+Also overridable via `R3_UE_HOST`, `R3_UE_PORT`, `R3_UE_PRESET`, `R3_UE_ASSET_TEMPLATE` env vars.
+
+### Demo prompt
+
+> "Search for three Italian mid-century lounge chairs from the catalog, then arrange them around the origin facing inward, ~150 cm apart."
+
+Claude calls `product_search`, picks results, then issues three `ue_spawn_product` calls with the appropriate locations and rotations.
+
+## Examples
+
+```bash
+# Find Italian brands
+r3 brand list --country Italy
+
+# Search chairs, limit to 5 results
+r3 product search "chair" --limit 5
+
+# Get all products from a brand
+r3 product list --brand "Driade"
+
+# Explore a product collection
+r3 product-collection search "Tudor"
+
+# Find products by designer
+r3 product list --designer "Philippe Starck"
+
+# Catalog stats
+r3 product stats --by brand
+r3 product stats --brand "Driade" --by designer
+
+# Compare two products
+r3 product compare <id1> <id2>
+
+# Find wood finishes
+r3 finish-collection list --category wood
+
+# Script: get all brand names
+r3 brand list --json | jq -r '.[].name'
+
+# Script: count products per brand
+r3 brand list --json | jq -r '.[].name' | while read brand; do
+  count=$(r3 product list --brand "$brand" --json 2>/dev/null | jq length)
+  echo "$brand: $count"
+done
+```
+
+## About R3PLICA
+
+[R3PLICA](https://r3plica.space) provides certified digital replicas of branded furniture, finishes, and materials to architects, interior designers, and visualization professionals. The catalog includes 60+ premium partner brands including Cattelan Italia, Driade, Poliform, and more.
+
+## License
+
+Proprietary - R3PLICA S.r.l.

package/dist/cli/commands/config.js

@@ -3,7 +3,7 @@ export function registerConfigCommands(program) {
     const config = program.command("config").description("Manage CLI configuration");
     config
         .command("set <key> <value>")
-        .description("Set a config value (available keys: api-url)")
+        .description("Set a config value (keys: api-url, ue-host, ue-port, ue-preset, ue-asset-template)")
         .action((key, value) => {
         try {
             setConfigValue(key, value);

package/dist/cli/commands/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;IAEjF,MAAM;SACH,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,8CAA8C,CAAC;SAC3D,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,4BAA4B,CAAC;SACzC,MAAM,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;IAEjF,MAAM;SACH,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,oFAAoF,CAAC;SACjG,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,4BAA4B,CAAC;SACzC,MAAM,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/core/api.d.ts

@@ -47,3 +47,20 @@ export declare function listFinishCollections(opts: {
 }): Promise<any[]>;
 export declare function searchFinishCollections(query: string): Promise<any[]>;
 export declare function getFinishCollection(mongoId: string): Promise<any>;
+/**
+ * Look up a single individual finish by its mongo_id. Returns the finish
+ * enriched with its parent finish-collection identity. Designed for agents
+ * that need the EXACT asset_name + thumbnail_url for a specific finish (e.g.
+ * when composing a document) without re-fetching an entire collection.
+ *
+ * Note: "finish" here means a single individual finish (a row inside
+ * `finish_details[]`), NOT a product variant. R3PLICA reserves "variant" for
+ * product dimensional/additional variants.
+ */
+export declare function getFinish(finishMongoId: string): Promise<any>;
+/**
+ * Search individual finishes across all finish collections by name or
+ * asset_name. Optional `collection` filter narrows by collection name
+ * substring. Returns each match with parent collection identity attached.
+ */
+export declare function searchFinishes(query: string, collection?: string): Promise<any[]>;

package/dist/core/api.js

@@ -10,6 +10,24 @@ export class ApiError extends Error {
         this.name = "ApiError";
     }
 }
+/**
+ * Cloudflare Workers runtime detection — `navigator.userAgent === "Cloudflare-Workers"`
+ * is the canonical method (works even with nodejs_compat flag enabled).
+ *
+ * When running in Workers, we attach `cf.cacheTtl` / `cf.cacheEverything` to
+ * the fetch options. This routes the request through Cloudflare's edge cache:
+ * subsequent identical requests from anywhere in the world are served from
+ * the nearest CF data center without ever touching api.r3plica.space.
+ *
+ * Cache TTL is conservative (5 min) so catalog updates propagate within
+ * minutes. The catalog data itself changes only via the coda-sync-pipeline
+ * (hourly at most), so 5 min is plenty for staleness.
+ */
+function isCloudflareWorkers() {
+    const nav = globalThis.navigator;
+    return typeof nav !== "undefined" && nav?.userAgent === "Cloudflare-Workers";
+}
+const EDGE_CACHE_TTL_SECONDS = 300; // 5 minutes
 async function request(path, params = {}, timeoutMs = TIMEOUT_MS) {
     const baseUrl = getApiUrl();
     const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
@@ -19,15 +37,26 @@ async function request(path, params = {}, timeoutMs = TIMEOUT_MS) {
     }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    // Build fetch options — add CF edge cache hints when running in Workers.
+    // Outside Workers (CLI/stdio hub), the `cf` field is ignored.
+    const fetchOptions = {
+        signal: controller.signal,
+        headers: { "Accept": "application/json" },
+    };
+    if (isCloudflareWorkers()) {
+        fetchOptions.cf = {
+            cacheTtl: EDGE_CACHE_TTL_SECONDS,
+            cacheEverything: true,
+            // Cache key includes the full URL by default — query params naturally
+            // segment cache entries (per-filter caching).
+        };
+    }
     try {
-        const response = await fetch(url.toString(), {
-            signal: controller.signal,
-            headers: { "Accept": "application/json" },
-        });
+        const response = await fetch(url.toString(), fetchOptions);
         if (!response.ok) {
             throw new ApiError(`API returned ${response.status}: ${response.statusText}`, response.status);
         }
-        const data = await response.json();
+        const data = (await response.json());
         if (data.status === false) {
             throw new ApiError(data.message || "API returned an error");
         }
@@ -321,4 +350,51 @@ export async function getFinishCollection(mongoId) {
     }
     return collection;
 }
+/**
+ * Look up a single individual finish by its mongo_id. Returns the finish
+ * enriched with its parent finish-collection identity. Designed for agents
+ * that need the EXACT asset_name + thumbnail_url for a specific finish (e.g.
+ * when composing a document) without re-fetching an entire collection.
+ *
+ * Note: "finish" here means a single individual finish (a row inside
+ * `finish_details[]`), NOT a product variant. R3PLICA reserves "variant" for
+ * product dimensional/additional variants.
+ */
+export async function getFinish(finishMongoId) {
+    const all = await fetchAllFinishCollections();
+    for (const fc of all) {
+        const finish = fc.finish_details?.find((f) => f.mongo_id === finishMongoId);
+        if (finish) {
+            return {
+                ...finish,
+                collection: { mongo_id: fc.mongo_id, name: fc.name, asset_name: fc.asset_name },
+            };
+        }
+    }
+    throw new ApiError(`Finish "${finishMongoId}" not found`);
+}
+/**
+ * Search individual finishes across all finish collections by name or
+ * asset_name. Optional `collection` filter narrows by collection name
+ * substring. Returns each match with parent collection identity attached.
+ */
+export async function searchFinishes(query, collection) {
+    const all = await fetchAllFinishCollections();
+    const q = query.toLowerCase();
+    const colQ = collection?.toLowerCase();
+    const results = [];
+    for (const fc of all) {
+        if (colQ && !fc.name?.toLowerCase().includes(colQ))
+            continue;
+        const matches = fc.finish_details?.filter((f) => f.name?.toLowerCase().includes(q) ||
+            f.asset_name?.toLowerCase().includes(q)) || [];
+        for (const f of matches) {
+            results.push({
+                ...f,
+                collection: { mongo_id: fc.mongo_id, name: fc.name, asset_name: fc.asset_name },
+            });
+        }
+    }
+    return results;
+}
 //# sourceMappingURL=api.js.map