@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -0,0 +1,316 @@
+# Products Sub-API Reference
+
+Base: `https://merchantapi.googleapis.com/products/v1`
+
+## Resources
+
+### ProductInput (Write)
+
+Used to submit product data. Changes take several minutes to process.
+
+**Endpoints:**
+- `POST /accounts/{account}/productInputs:insert` - Insert product
+- `PATCH /accounts/{account}/productInputs/{productInput}` - Update product
+- `DELETE /accounts/{account}/productInputs/{productInput}` - Delete product
+
+All write operations require `dataSource` query parameter:
+```
+?dataSource=accounts/{account}/dataSources/{dataSourceId}
+```
+
+**ProductInput fields:**
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | Output | `accounts/{account}/productInputs/{id}` |
+| `product` | string | Output | Name of processed product |
+| `offerId` | string | Required, immutable | Your unique SKU/ID |
+| `contentLanguage` | string | Required, immutable | ISO 639-1 (e.g., `en`) |
+| `feedLabel` | string | Required, immutable | Max 20 chars, A-Z 0-9 hyphen underscore |
+| `legacyLocal` | boolean | Optional, immutable | Set true for local-only products |
+| `productAttributes` | object | Optional | All product attributes (see below) |
+| `customAttributes[]` | array | Optional | Max 2500 attrs, 102.4KB total |
+| `versionNumber` | int64 | Optional, immutable | Prevents out-of-order updates |
+
+### Product (Read-only)
+
+The processed product with status and validation results.
+
+**Endpoints:**
+- `GET /accounts/{account}/products/{product}` - Get single product
+- `GET /accounts/{account}/products` - List products (paginated)
+
+**Product fields include everything from ProductInput plus:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `productStatus` | object | Processing status, destination statuses, item-level issues |
+| `productStatus.destinationStatuses[]` | array | Per-destination approval status |
+| `productStatus.itemLevelIssues[]` | array | Validation warnings/errors |
+
+## ProductAttributes
+
+All typed product attributes live under `productAttributes`:
+
+### Identity
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Product name (max 150 chars) |
+| `description` | string | Product description (max 5000 chars) |
+| `link` | string | Landing page URL |
+| `canonicalLink` | string | Canonical URL |
+| `imageLink` | string | Primary image (min 100x100px) |
+| `additionalImageLinks[]` | string[] | Up to 10 additional images |
+| `brand` | string | Brand name |
+| `gtin` | string | Global Trade Item Number |
+| `mpn` | string | Manufacturer Part Number |
+| `identifierExists` | boolean | False if no GTIN/MPN/brand |
+
+### Classification
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `googleProductCategory` | string | Google taxonomy ID or path |
+| `productTypes[]` | string[] | Your own category hierarchy |
+| `channel` | enum | `ONLINE` or `LOCAL` |
+| `condition` | enum | `new`, `refurbished`, `used` |
+| `adult` | boolean | Adult content flag |
+| `ageGroup` | enum | `newborn`, `infant`, `toddler`, `kids`, `adult` |
+| `gender` | enum | `male`, `female`, `unisex` |
+
+### Pricing
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `price` | Price | Regular price |
+| `salePrice` | Price | Sale price |
+| `salePriceEffectiveDate` | Interval | When sale price applies |
+| `costOfGoodsSold` | Price | COGS for reporting |
+| `autoPricingMinPrice` | Price | Minimum for auto-pricing |
+| `installment` | Installment | Monthly payment info |
+| `subscriptionCost` | SubscriptionCost | Recurring charge |
+| `loyaltyPrograms[]` | LoyaltyProgram[] | Loyalty pricing |
+
+**Price object (Merchant API v1):**
+```json
+{
+  "amountMicros": "79990000",
+  "currencyCode": "USD"
+}
+```
+1 unit = 1,000,000 micros. $79.99 = `79990000`.
+
+**Installment object:**
+```json
+{
+  "months": "12",
+  "amount": { "amountMicros": "6660000", "currencyCode": "USD" },
+  "downpayment": { "amountMicros": "0", "currencyCode": "USD" },
+  "creditType": "finance"
+}
+```
+
+### Availability & Inventory
+
+| Field | Type | Values |
+|-------|------|--------|
+| `availability` | enum | `in_stock`, `out_of_stock`, `preorder`, `backorder` |
+| `availabilityDate` | Timestamp | When preorder/backorder becomes available |
+| `expirationDate` | Timestamp | Auto-deletion date (max 30 days) |
+| `sellOnGoogleQuantity` | int64 | Buy on Google quantity |
+
+### Shipping & Dimensions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `shipping[]` | Shipping[] | Per-country/region shipping overrides |
+| `shippingWeight` | Weight | Package weight |
+| `shippingLength` | Dimension | Package length |
+| `shippingWidth` | Dimension | Package width |
+| `shippingHeight` | Dimension | Package height |
+| `shippingLabel` | string | Maps to account-level shipping settings |
+| `transitTimeLabel` | string | Maps to transit time tables |
+| `freeShippingThreshold[]` | FreeShippingThreshold[] | Free shipping minimums |
+| `minHandlingTime` | int64 | Business days |
+| `maxHandlingTime` | int64 | Business days |
+
+**Shipping object:**
+```json
+{
+  "price": { "amountMicros": "5990000", "currencyCode": "USD" },
+  "country": "US",
+  "region": "CA",
+  "service": "Standard",
+  "minHandlingTime": "0",
+  "maxHandlingTime": "1",
+  "minTransitTime": "3",
+  "maxTransitTime": "7"
+}
+```
+
+### Physical Attributes
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `color` | string | Product color |
+| `material` | string | Material composition |
+| `pattern` | string | Design pattern |
+| `sizes[]` | string[] | Available sizes |
+| `sizeSystem` | enum | Sizing system (US, EU, UK, etc.) |
+| `sizeType` | enum | `regular`, `petite`, `plus`, `big_and_tall`, `maternity` |
+| `productHeight` | Dimension | Product height |
+| `productLength` | Dimension | Product length |
+| `productWidth` | Dimension | Product width |
+| `productWeight` | Weight | Product weight |
+| `itemGroupId` | string | Groups variants together |
+| `multipack` | int64 | Number of identical items in pack |
+| `isBundle` | boolean | Merchant-defined bundle |
+
+### Destinations & Ads
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `includedDestinations[]` | string[] | Opt-in destinations |
+| `excludedDestinations[]` | string[] | Opt-out destinations |
+| `adsRedirect` | string | Ads-specific redirect URL |
+| `adsLabels[]` | string[] | Campaign grouping labels |
+| `customLabel0` - `customLabel4` | string | Shopping campaign labels |
+| `promotionIds[]` | string[] | Associated promotion IDs |
+| `pause` | string | Set to `"ads"` to pause |
+
+### Structured Content
+
+```json
+{
+  "structuredTitle": {
+    "content": "AI-optimized product title",
+    "digitalSourceType": "trained_algorithmic_media"
+  },
+  "structuredDescription": {
+    "content": "AI-optimized description",
+    "digitalSourceType": "trained_algorithmic_media"
+  }
+}
+```
+
+### Tax (Content API only, auto-calculated in Merchant API)
+
+```json
+{
+  "taxes": [
+    {
+      "rate": 8.25,
+      "country": "US",
+      "region": "TX",
+      "taxShip": true
+    }
+  ]
+}
+```
+
+### Certifications
+
+```json
+{
+  "certifications": [
+    {
+      "certificationAuthority": "European_Commission",
+      "certificationName": "EPREL",
+      "certificationCode": "123456",
+      "certificationValue": "A+"
+    }
+  ]
+}
+```
+
+### Product Details & Highlights
+
+```json
+{
+  "productDetails": [
+    {
+      "sectionName": "Technical Specs",
+      "attributeName": "Battery Life",
+      "attributeValue": "30 hours"
+    }
+  ],
+  "productHighlights": [
+    "Active noise cancellation",
+    "30-hour battery life",
+    "Bluetooth 5.3"
+  ]
+}
+```
+
+## Insert Example (Full)
+
+```javascript
+const productInput = {
+  offerId: 'HEADPHONE-PRO-001',
+  contentLanguage: 'en',
+  feedLabel: 'US',
+  productAttributes: {
+    title: 'ProAudio X500 Wireless Headphones',
+    description: 'Premium noise-cancelling headphones with 30hr battery, Bluetooth 5.3, and Hi-Res audio support.',
+    link: 'https://store.example.com/proaudio-x500',
+    imageLink: 'https://cdn.example.com/images/x500-main.jpg',
+    additionalImageLinks: [
+      'https://cdn.example.com/images/x500-side.jpg',
+      'https://cdn.example.com/images/x500-case.jpg',
+    ],
+    availability: 'in_stock',
+    condition: 'new',
+    price: { amountMicros: '149990000', currencyCode: 'USD' },
+    salePrice: { amountMicros: '119990000', currencyCode: 'USD' },
+    brand: 'ProAudio',
+    gtin: '0123456789012',
+    googleProductCategory: 'Electronics > Audio > Headphones',
+    productTypes: ['Electronics', 'Audio', 'Wireless Headphones'],
+    channel: 'ONLINE',
+    color: 'Midnight Black',
+    sizes: ['One Size'],
+    itemGroupId: 'X500-GROUP',
+    shipping: [
+      {
+        price: { amountMicros: '0', currencyCode: 'USD' },
+        country: 'US',
+        service: 'Free Standard',
+        minTransitTime: '3',
+        maxTransitTime: '7',
+      },
+    ],
+    productHighlights: [
+      'Active noise cancellation with transparency mode',
+      '30-hour battery, 5-min quick charge for 3 hours',
+      'Bluetooth 5.3 with multipoint connection',
+    ],
+    customLabel0: 'electronics-sale',
+    customLabel1: 'high-margin',
+  },
+  customAttributes: [
+    { name: 'warranty_years', value: '2' },
+    { name: 'driver_size_mm', value: '40' },
+  ],
+};
+```
+
+## Pagination
+
+List responses include `nextPageToken`:
+
+```javascript
+let pageToken = '';
+const allProducts = [];
+
+do {
+  const url = new URL(`https://merchantapi.googleapis.com/products/v1/accounts/${MERCHANT_ID}/products`);
+  url.searchParams.set('pageSize', '250');
+  if (pageToken) url.searchParams.set('pageToken', pageToken);
+
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  const data = await res.json();
+  allProducts.push(...(data.products || []));
+  pageToken = data.nextPageToken || '';
+} while (pageToken);
+```

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

@@ -0,0 +1,201 @@
+# Promotions Sub-API Reference
+
+Base: `https://merchantapi.googleapis.com/promotions/v1`
+
+Manage promotional offers that display alongside your product listings on Google Shopping.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/accounts/{account}/promotions:insert` | Create promotion |
+| `GET` | `/accounts/{account}/promotions/{promotion}` | Get promotion |
+| `GET` | `/accounts/{account}/promotions` | List promotions |
+
+## Promotion Object
+
+```json
+{
+  "name": "accounts/123456/promotions/SUMMER_SALE_2024",
+  "promotionId": "SUMMER_SALE_2024",
+  "contentLanguage": "en",
+  "targetCountry": "US",
+  "redemptionChannel": ["ONLINE"],
+  "promotionStatus": {
+    "destinationStatuses": [
+      {
+        "reportingContext": "FREE_LISTINGS",
+        "status": "APPROVED"
+      }
+    ],
+    "itemLevelIssues": []
+  },
+  "attributes": {
+    "longTitle": "20% off all headphones - Summer Sale",
+    "promotionDisplayTimePeriod": {
+      "startTime": "2024-06-01T00:00:00Z",
+      "endTime": "2024-08-31T23:59:59Z"
+    },
+    "promotionEffectiveTimePeriod": {
+      "startTime": "2024-06-01T00:00:00Z",
+      "endTime": "2024-08-31T23:59:59Z"
+    },
+    "offerType": "GENERIC_CODE",
+    "genericRedemptionCode": "SUMMER20",
+    "percentOff": 20,
+    "couponValueType": "PERCENT_OFF",
+    "productApplicability": "SPECIFIC_PRODUCTS",
+    "productTypeInclusion": ["Electronics > Audio > Headphones"],
+    "storeApplicability": "ALL_STORES"
+  }
+}
+```
+
+## Key Fields
+
+### Identification
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `promotionId` | string | Required | Unique promotion identifier |
+| `contentLanguage` | string | Required | ISO 639-1 language code |
+| `targetCountry` | string | Required | CLDR territory code |
+| `redemptionChannel[]` | enum[] | Required | `ONLINE`, `IN_STORE`, or both |
+
+### Promotion Attributes
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `longTitle` | string | Promotion title (max 60 chars) |
+| `promotionDisplayTimePeriod` | Interval | When promotion is shown to users |
+| `promotionEffectiveTimePeriod` | Interval | When promotion can be redeemed |
+| `offerType` | enum | `NO_CODE`, `GENERIC_CODE`, `UNIQUE_CODE` (see below) |
+| `genericRedemptionCode` | string | Code for `GENERIC_CODE` type |
+| `couponValueType` | enum | Discount type (see below) |
+
+### Discount Types (`couponValueType`)
+
+| Value | Required Fields |
+|-------|-----------------|
+| `MONEY_OFF` | `moneyOffAmount` (Price object) |
+| `PERCENT_OFF` | `percentOff` (integer 1-100) |
+| `BUY_M_GET_N_MONEY_OFF` | `minimumPurchaseQuantity`, `getMoney`, `moneyOffAmount` |
+| `BUY_M_GET_N_PERCENT_OFF` | `minimumPurchaseQuantity`, `freeGiftValue`, `percentOff` |
+| `BUY_M_GET_MONEY_OFF` | `minimumPurchaseQuantity`, `moneyOffAmount` |
+| `BUY_M_GET_PERCENT_OFF` | `minimumPurchaseQuantity`, `percentOff` |
+| `FREE_GIFT` | `freeGiftDescription`, `freeGiftValue` (optional), `freeGiftItemId` (optional) |
+| `FREE_SHIPPING_STANDARD` | (no extra fields) |
+| `FREE_SHIPPING_OVERNIGHT` | (no extra fields) |
+| `FREE_SHIPPING_TWO_DAY` | (no extra fields) |
+
+### Offer Types
+
+| Value | Description |
+|-------|-------------|
+| `NO_CODE` | Automatic discount, no code needed |
+| `GENERIC_CODE` | Single code shared by all customers |
+| `UNIQUE_CODE` | Unique code per customer (requires file upload) |
+
+### Product Targeting
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `productApplicability` | enum | `ALL_PRODUCTS` or `SPECIFIC_PRODUCTS` |
+| `productTypeInclusion[]` | string[] | Product types to include |
+| `productTypeExclusion[]` | string[] | Product types to exclude |
+| `brandInclusion[]` | string[] | Brands to include |
+| `brandExclusion[]` | string[] | Brands to exclude |
+| `itemIdInclusion[]` | string[] | Specific offer IDs to include |
+| `itemIdExclusion[]` | string[] | Specific offer IDs to exclude |
+| `itemGroupIdInclusion[]` | string[] | Item group IDs to include |
+| `itemGroupIdExclusion[]` | string[] | Item group IDs to exclude |
+
+### Minimum Purchase
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `minimumPurchaseAmount` | Price | Minimum cart value |
+| `minimumPurchaseQuantity` | int64 | Minimum item count |
+| `limitQuantity` | int64 | Max uses per order |
+| `limitValue` | Price | Max discount per order |
+
+## Examples
+
+### Percentage Discount with Code
+
+```javascript
+const promotion = {
+  promotionId: 'SPRING_SALE_2024',
+  contentLanguage: 'en',
+  targetCountry: 'US',
+  redemptionChannel: ['ONLINE'],
+  attributes: {
+    longTitle: '15% off electronics with code SPRING15',
+    promotionDisplayTimePeriod: {
+      startTime: '2024-03-01T00:00:00Z',
+      endTime: '2024-03-31T23:59:59Z',
+    },
+    promotionEffectiveTimePeriod: {
+      startTime: '2024-03-01T00:00:00Z',
+      endTime: '2024-03-31T23:59:59Z',
+    },
+    offerType: 'GENERIC_CODE',
+    genericRedemptionCode: 'SPRING15',
+    couponValueType: 'PERCENT_OFF',
+    percentOff: 15,
+    productApplicability: 'SPECIFIC_PRODUCTS',
+    productTypeInclusion: ['Electronics'],
+  },
+};
+
+await fetch(
+  `https://merchantapi.googleapis.com/promotions/v1/accounts/${MERCHANT_ID}/promotions:insert`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(promotion),
+  }
+);
+```
+
+### Free Shipping (No Code)
+
+```javascript
+const promotion = {
+  promotionId: 'FREE_SHIP_50',
+  contentLanguage: 'en',
+  targetCountry: 'US',
+  redemptionChannel: ['ONLINE'],
+  attributes: {
+    longTitle: 'Free standard shipping on orders over $50',
+    promotionDisplayTimePeriod: {
+      startTime: '2024-01-01T00:00:00Z',
+      endTime: '2024-12-31T23:59:59Z',
+    },
+    promotionEffectiveTimePeriod: {
+      startTime: '2024-01-01T00:00:00Z',
+      endTime: '2024-12-31T23:59:59Z',
+    },
+    offerType: 'NO_CODE',
+    couponValueType: 'FREE_SHIPPING_STANDARD',
+    productApplicability: 'ALL_PRODUCTS',
+    minimumPurchaseAmount: { amountMicros: '50000000', currencyCode: 'USD' },
+  },
+};
+```
+
+### Linking Promotions to Products
+
+Add the `promotionIds` field to product inputs:
+
+```javascript
+const productInput = {
+  offerId: 'SKU-001',
+  contentLanguage: 'en',
+  feedLabel: 'US',
+  productAttributes: {
+    // ... other attributes
+    promotionIds: ['SPRING_SALE_2024', 'FREE_SHIP_50'],
+  },
+};
+```