@biggora/claude-plugins 1.1.1 → 1.2.2

package/src/skills/google-merchant-api/references/reports.md

@@ -0,0 +1,240 @@
+# Reports Sub-API Reference
+
+Base: `https://merchantapi.googleapis.com/reports/v1`
+
+Query performance data, competitive insights, and market benchmarks using a SQL-like language.
+
+## Endpoint
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/accounts/{account}/reports:search` | Execute a report query |
+
+## Query Language
+
+Reports use Merchant Center Query Language (MCQL):
+
+```sql
+SELECT
+  field1,
+  field2,
+  metric1,
+  metric2
+FROM table_name
+WHERE condition1 AND condition2
+ORDER BY metric1 DESC
+LIMIT 100
+```
+
+## Available Tables
+
+### Performance Tables
+
+| Table | Description |
+|-------|-------------|
+| `product_performance_view` | Product-level clicks, impressions, CTR, conversions |
+| `non_product_performance_view` | Website traffic analytics (non-product pages) |
+
+### Competitive Tables
+
+| Table | Description |
+|-------|-------------|
+| `price_competitiveness_product_view` | Your prices vs. benchmark prices |
+| `price_insights_product_view` | Pricing optimization suggestions |
+| `competitive_visibility_competitor_view` | Market share analysis |
+| `competitive_visibility_benchmark_view` | Category benchmarks |
+| `competitive_visibility_top_merchant_view` | Top merchants in category |
+
+### Best Sellers Tables
+
+| Table | Description |
+|-------|-------------|
+| `best_sellers_product_cluster_view` | Top-selling product clusters |
+| `best_sellers_brand_view` | Top-selling brands |
+
+### Product Status Tables
+
+| Table | Description |
+|-------|-------------|
+| `product_view` | Product data and status information |
+
+## Common Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `metrics.clicks` | Total clicks |
+| `metrics.impressions` | Total impressions |
+| `metrics.ctr` | Click-through rate |
+| `metrics.conversions` | Total conversions |
+| `metrics.conversionValue` | Total conversion value |
+| `metrics.orders` | Total orders |
+
+## Common Segments
+
+| Segment | Description |
+|---------|-------------|
+| `segments.date` | Date (YYYY-MM-DD) |
+| `segments.offerId` | Product offer ID |
+| `segments.title` | Product title |
+| `segments.brand` | Product brand |
+| `segments.categoryL1` - `categoryL5` | Category levels |
+| `segments.productTypeL1` - `productTypeL5` | Product type levels |
+| `segments.customLabel0` - `customLabel4` | Custom labels |
+| `segments.program` | Program (SHOPPING_ADS, FREE_LISTINGS, etc.) |
+
+## Query Examples
+
+### Product Performance by Date
+
+```json
+{
+  "query": "SELECT segments.date, segments.offerId, segments.title, metrics.clicks, metrics.impressions, metrics.ctr FROM product_performance_view WHERE segments.date BETWEEN '2024-01-01' AND '2024-01-31' ORDER BY metrics.clicks DESC LIMIT 50"
+}
+```
+
+### Top Products by Conversions
+
+```json
+{
+  "query": "SELECT segments.offerId, segments.title, segments.brand, metrics.conversions, metrics.conversionValue FROM product_performance_view WHERE segments.date BETWEEN '2024-01-01' AND '2024-03-31' AND segments.program = 'SHOPPING_ADS' ORDER BY metrics.conversions DESC LIMIT 20"
+}
+```
+
+### Price Competitiveness
+
+```json
+{
+  "query": "SELECT segments.offerId, segments.title, metrics.benchmarkPrice, metrics.price FROM price_competitiveness_product_view WHERE segments.date = '2024-01-15' ORDER BY segments.offerId"
+}
+```
+
+### Brand Performance
+
+```json
+{
+  "query": "SELECT segments.brand, metrics.clicks, metrics.impressions, metrics.ctr FROM product_performance_view WHERE segments.date BETWEEN '2024-01-01' AND '2024-01-31' ORDER BY metrics.clicks DESC LIMIT 10"
+}
+```
+
+## Response Format
+
+```json
+{
+  "results": [
+    {
+      "productPerformanceView": {
+        "date": { "year": 2024, "month": 1, "day": 15 },
+        "offerId": "SKU-001",
+        "title": "Premium Headphones",
+        "clicks": "142",
+        "impressions": "5230",
+        "ctr": 0.0272
+      }
+    }
+  ],
+  "nextPageToken": "abc123"
+}
+```
+
+## Pagination
+
+Reports support pagination via `pageSize` and `pageToken` in the request body:
+
+```json
+{
+  "query": "SELECT ... FROM ...",
+  "pageSize": 1000,
+  "pageToken": "abc123"
+}
+```
+
+Default page size varies by table. Max is typically 1000 rows per page.
+
+## Code Example
+
+```javascript
+async function getProductPerformance(merchantId, token, startDate, endDate) {
+  const results = [];
+  let pageToken = '';
+
+  do {
+    const body = {
+      query: `
+        SELECT
+          segments.offerId,
+          segments.title,
+          metrics.clicks,
+          metrics.impressions,
+          metrics.ctr,
+          metrics.conversions
+        FROM product_performance_view
+        WHERE segments.date BETWEEN '${startDate}' AND '${endDate}'
+        ORDER BY metrics.clicks DESC
+      `,
+      pageSize: 1000,
+    };
+    if (pageToken) body.pageToken = pageToken;
+
+    const response = await fetch(
+      `https://merchantapi.googleapis.com/reports/v1/accounts/${merchantId}/reports:search`,
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      }
+    );
+
+    const data = await response.json();
+    results.push(...(data.results || []));
+    pageToken = data.nextPageToken || '';
+  } while (pageToken);
+
+  return results;
+}
+```
+
+```python
+import requests
+
+def get_product_performance(merchant_id, token, start_date, end_date):
+    results = []
+    page_token = ''
+
+    while True:
+        body = {
+            'query': f"""
+                SELECT
+                    segments.offerId,
+                    segments.title,
+                    metrics.clicks,
+                    metrics.impressions,
+                    metrics.ctr,
+                    metrics.conversions
+                FROM product_performance_view
+                WHERE segments.date BETWEEN '{start_date}' AND '{end_date}'
+                ORDER BY metrics.clicks DESC
+            """,
+            'pageSize': 1000,
+        }
+        if page_token:
+            body['pageToken'] = page_token
+
+        response = requests.post(
+            f'https://merchantapi.googleapis.com/reports/v1/accounts/{merchant_id}/reports:search',
+            headers={
+                'Authorization': f'Bearer {token}',
+                'Content-Type': 'application/json',
+            },
+            json=body,
+        )
+        data = response.json()
+        results.extend(data.get('results', []))
+        page_token = data.get('nextPageToken', '')
+        if not page_token:
+            break
+
+    return results
+```

package/src/skills/lv-aggregators-api/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: lv-aggregators-api
+description: >
+  Use this skill whenever the user wants to work with Latvian price comparison / aggregator
+  platforms, specifically Salidzini.lv or KurPirkt.lv. Triggers include: creating or generating
+  XML product feeds, integrating an e-commerce store with Latvian aggregators, exporting product
+  catalogs for salidzini or kurpirkt, validating XML feed format, debugging feed errors,
+  setting up product data export for Latvian price comparison sites, or any mention of
+  "salidzini", "kurpirkt", "cenu salīdzināšana", "preču eksports", "XML feed Latvia",
+  "Latvian marketplace integration", or "price aggregator feed". Also use when the user mentions
+  e-commerce product feeds for the Latvian market, product data export in LV context, or wants
+  to list products on Latvian comparison shopping engines, even without naming a specific platform.
+---
+
+# Latvian Price Aggregator APIs
+
+Generate and manage XML product feeds for Latvia's two major price comparison platforms: **Salidzini.lv** and **KurPirkt.lv**.
+
+## Platform Overview
+
+| Aspect | Salidzini.lv | KurPirkt.lv |
+|--------|-------------|-------------|
+| Daily visitors | ~47,000 | 30,000-45,000 |
+| Monthly visitors | ~1.3 million | N/A |
+| Listed shops | N/A | 1,200+ |
+| Feed format | XML (UTF-8) | XML (UTF-8) |
+| Feed update | At least daily | Regular (daily recommended) |
+| Contact | Web form on shops_info.php | kurpirkt@kurpirkt.lv / +371 26533032 |
+| Registration | Online form | Email application |
+
+Both platforms use similar XML feed formats with minor differences in field names and requirements. If a shop targets both platforms, a single feed generator can produce both formats with minimal adjustments.
+
+## Quick Start
+
+To integrate with either platform:
+
+1. **Generate an XML feed** from your product database (see format details in reference files)
+2. **Host the feed** at a public URL (e.g., `https://yourshop.lv/export/salidzini.xml`)
+3. **Auto-update** the feed at least once daily via a scheduled script/cron job
+4. **Place the aggregator's banner** on your shop's homepage
+5. **Submit your application** through the platform's registration process
+6. **Validate** your feed using the platform's validator (Salidzini provides one at their shops_info page)
+
+## Feed Format Comparison
+
+Both platforms use `<root>` as the root element and `<item>` for each product. The key differences:
+
+| Field | Salidzini.lv | KurPirkt.lv | Notes |
+|-------|-------------|-------------|-------|
+| Product name | `<name>` (required) | `<name>` (required) | Max 200 chars on Salidzini |
+| Product URL | `<link>` (required) | `<link>` (required) | Max 500 chars, full URL |
+| Price | `<price>` (required) | `<price>` (required) | EUR, dot decimal separator |
+| Image | `<image>` | `<image>` | White bg, no logos/watermarks |
+| Brand | `<brand>` | `<manufacturer>` | **Different tag name** |
+| Category | `<category_full>` | `<category_full>` | Hierarchy with `>>` (Salidzini) or `>` (KurPirkt) |
+| Category link | `<category_link>` | `<category_link>` | Optional on KurPirkt |
+| Stock | `<in_stock>` | `<in_stock>` | Numeric quantity |
+| Used/refurbished | `<used>` | `<used>` | Value `1` for used items |
+| Delivery cost | `<delivery_latvija>` | `<delivery_cost_riga>` | **Different tag name & scope** |
+| Delivery days | `<delivery_days_latvija>` | N/A | Salidzini only |
+| In-store pickup days | `<delivery_days_shop>` | N/A | Salidzini only |
+| Service fee | `<service_fee>` | N/A | Salidzini only |
+| Model | `<model>` | N/A | Salidzini only |
+| Color | `<color>` | N/A | Salidzini only |
+| MPN | `<mpn>` | N/A | Salidzini only |
+| EAN/GTIN | `<ean>` | N/A | Salidzini only |
+| Adult content | `<adult>` | N/A | `yes`/`no`, required for adult shops |
+| OTC medicine | `<over_the_counter_medicine>` | N/A | Salidzini only, value `1` |
+
+## Reference Files
+
+For detailed per-platform documentation, field specifications, code examples, and validation rules:
+
+- **`references/salidzini.md`** - Complete Salidzini.lv feed specification, all fields, rules, and examples
+- **`references/kurpirkt.md`** - Complete KurPirkt.lv feed specification and registration process
+- **`references/integration-guide.md`** - Code examples for generating feeds in Node.js, PHP, Python; dual-feed strategy; validation; scheduling
+
+Read the relevant reference file when you need detailed field-level documentation or implementation code.
+
+## Common Rules (Both Platforms)
+
+### Pricing
+- All prices in **EUR with VAT** included
+- Use **dot** (`.`) as decimal separator
+- Price must be the final price a consumer pays (excluding delivery)
+- Include any additional fees in the price
+
+### Product Names
+- Include brand/manufacturer, model, and product code
+- Keep names concise and descriptive
+- No promotional text ("Free shipping", "Best price", "Sale", etc.)
+- No vague phrases ("Best choice", "Highest quality", "Buy now")
+
+### Images
+- Must show the actual product appearance
+- **White background**, no frames
+- No shop logos, prices, watermarks, or promotional overlays
+- No text like "In stock", "Gift", "0% credit"
+- If no product image available, leave the `<image>` tag empty
+- Salidzini: min 500x500px recommended, max 16MB
+
+### Prohibited Content
+- Alcohol and tobacco products (Salidzini)
+- Products with delivery times exceeding 30 days (Salidzini)
+- Duplicate product entries
+- Products not available for purchase/delivery in Latvia
+
+### Feed Technical Requirements
+- **UTF-8 encoding** (declared in XML header)
+- Feed response time must be under **5 minutes** (Salidzini)
+- Host at a stable public URL on your registered domain
+- Auto-generate and update at least daily
+- CDATA sections supported: `<name><![CDATA[Product Name]]></name>`