{"_id":"@circles-market/catalog","name":"@circles-market/catalog","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@circles-market/catalog","version":"0.1.0","private":false,"type":"module","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.cjs","import":"./dist/index.js"}},"sideEffects":false,"scripts":{"build":"tsup src/index.ts --dts --format esm,cjs --sourcemap","clean":"rm -rf dist","typecheck":"tsc -p tsconfig.json --noEmit","demo":"tsx examples/demo.ts"},"dependencies":{"@circles-market/core":"0.1.0"},"devDependencies":{"tsup":"^8.3.0","typescript":"^5.6.3","tsx":"^4.16.2"},"_id":"@circles-market/catalog@0.1.0","gitHead":"2bfca7a6816434444613f8ca4349e796179480b5","description":"Read-only access to aggregated operator catalogs (no auth).","_nodeVersion":"24.8.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-PCPF38cNoguflCmOIrPBIgGwvMUFBJ0ORjMaxfdN1rrqcxnLW5lhzmzhk12mryY981Yx1LtyCIrje9k0ZIruGw==","shasum":"69fbcea6f3672ecafbea845315590a46ebd44005","tarball":"https://registry.npmjs.org/@circles-market/catalog/-/catalog-0.1.0.tgz","fileCount":13,"unpackedSize":60991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAK2vadPGrarLZhSsGKzwjS6uQYw3irgMuHIyTiEb1BIAiEAnw0IMbzUT78VuZMzvT0KBucRPAqxFIS4K4C3HULPniE="}]},"_npmUser":{"name":"jaensen","email":"daniel@djanz.de"},"directories":{},"maintainers":[{"name":"jaensen","email":"daniel@djanz.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/catalog_0.1.0_1768922730703_0.21291816210907188"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-20T15:25:30.614Z","0.1.0":"2026-01-20T15:25:30.850Z","modified":"2026-01-20T15:25:31.083Z"},"maintainers":[{"name":"jaensen","email":"daniel@djanz.de"}],"description":"Read-only access to aggregated operator catalogs (no auth).","readme":"# @circles-market/catalog\n\nRead-only access to aggregated operator catalogs (no auth).\n\n## Install\n\n```bash\npnpm add @circles-market/catalog\n```\n\n## Quickstart\n\n```ts\nimport { CatalogClientImpl } from \"@circles-market/catalog\";\n\nasync function fetchFirstPage(marketApiBase: string, operator: string, sellers: string[]) {\n  const catalog = new CatalogClientImpl(marketApiBase);\n\n  const page = await catalog.fetchCatalogPage({\n    operator,\n    avatars: sellers,\n    chainId: 100,\n    pageSize: 50,\n  });\n\n  return page.items;\n}\n```\n\n## Demo app\n\nA minimal runnable demo is included. It fetches the first catalog page and prints a compact summary.\n\nRun it either from the monorepo root or from this package directory (requires Node 18+ for global fetch):\n\n```bash\n# Set your environment values (run these in your shell)\nexport MARKET_API_BASE=\"https://market-api.aboutcircles.com/market/\"\nexport OPERATOR=\"0x31d5d15c558fbfbbbe604c9c11eb42c9afbf5140\"\n\n# Optional: comma-separated list of seller/avatar addresses to filter\nexport SELLERS=\"0xde374ece6fa50e781e81aac78e811b33d16912c7\"\n\n# Option B) From the package directory (no workspace flags):\n# (run these commands inside packages/circles-market-catalog)\npnpm install\npnpm demo\n```\n\nIf you omit SELLERS, the demo will request whatever the operator returns by default. The script exits with a helpful message if required env vars are missing.\n\n## Quickstart (lookup by seller + sku)\n\n```ts\nimport { CatalogClientImpl } from \"@circles-market/catalog\";\n\nasync function fetchSellerSku(marketApiBase: string, operator: string, seller: string, sku: string) {\n  const catalog = new CatalogClientImpl(marketApiBase);\n\n  const item = await catalog\n    .forOperator(operator)\n    .fetchProductForSellerAndSku(seller, sku, { chainId: 100, maxPages: 10 });\n\n  return item;\n}\n```\n\n## Reference\n\n### Concepts\n\n* `operator`: operator address serving the aggregation endpoint\n* `avatars`: seller/avatar addresses to include\n* pagination:\n  * cursor-based (`X-Next-Cursor` / `cursor`)\n  * sometimes Link header (`rel=\"next\"`)\n  * status `416`: out-of-range / no more pages\n\n### API and return values\n\n* `fetchCatalogPage(query)` → `CatalogPage`\n* `forOperator(operator).fetchCatalogPage(queryWithoutOperator)` → `CatalogPage`\n* `forOperator(operator).fetchSellerCatalog(seller, opts?)` → `AggregatedCatalogItem[]`\n* `forOperator(operator).fetchProductForSellerAndSku(seller, sku, opts?)` → `AggregatedCatalogItem | null`\n\n### Types\n\n#### `CatalogPage`\nFields:\n- `catalog`: `AggregatedCatalog | null` (backend may omit)\n- `items`: `AggregatedCatalogItem[]`\n- `nextCursor`: cursor string or `null`\n- `nextLink`: next URL or `null`\n- `status`: HTTP status code\n\n#### `AggregatedCatalogItem`\nFields:\n- `seller`: seller/avatar address\n- `productCid`: IPFS CID of product JSON-LD\n- `publishedAt`: numeric timestamp (backend-defined unit)\n- `linkKeccak`: link identifier/hash\n- `indexInChunk`: position inside aggregation chunk\n- `product`: `SchemaOrgProductLite`\n\n#### `SchemaOrgProductLite`\nFields:\n- `sku`, `name`: primary fields for checkout\n- `description?`, `image?`, `url?`, `brand?`, `mpn?`, `gtin13?`, `category?`\n- `offers`: `SchemaOrgOfferLite[]` (price/currency/availability/etc.)\n\n## Runtime notes\n\n* Requires global `fetch`.\n* There’s an internal 10s memoization cache for pages to avoid spamming the same URL.\n\n## Related packages\n\n* `@circles-market/cart` uses SKUs + sellers from catalog results\n* `@circles-market/sdk` gives you catalog + cart + orders in one client\n","readmeFilename":"README.md","_rev":"1-b45ed1605b0c0eae678fc597229bb722"}