@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -0,0 +1,247 @@
+# Accounts Sub-API Reference
+
+Base: `https://merchantapi.googleapis.com/accounts/v1`
+
+## Account Management
+
+### Core Account Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/accounts/{account}` | Get account details |
+| `PATCH` | `/accounts/{account}` | Update account |
+| `DELETE` | `/accounts/{account}` | Delete account |
+| `GET` | `/accounts` | List all accounts |
+| `GET` | `/accounts/{parent}/subaccounts` | List sub-accounts |
+| `POST` | `/accounts:createAndConfigure` | Create and configure new account |
+| `POST` | `/accounts/{parent}/accounts:createTestAccount` | Create test account |
+
+### Account Object
+
+```json
+{
+  "name": "accounts/123456789",
+  "accountId": "123456789",
+  "accountName": "My Store",
+  "languageCode": "en",
+  "adultContent": false,
+  "timeZone": {
+    "id": "America/New_York"
+  },
+  "accountType": "STANDALONE"
+}
+```
+
+## Business Info
+
+Manage store business information (address, phone, customer service).
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/businessInfo` |
+| `PATCH` | `/accounts/{account}/businessInfo` |
+
+```json
+{
+  "name": "accounts/123456789/businessInfo",
+  "address": {
+    "regionCode": "US",
+    "postalCode": "10001",
+    "locality": "New York",
+    "administrativeArea": "NY",
+    "streetAddress": "123 Commerce St"
+  },
+  "phone": {
+    "number": "+12125551234"
+  },
+  "customerService": {
+    "uri": "https://example.com/support",
+    "email": "support@example.com",
+    "phone": {
+      "number": "+12125551234"
+    }
+  }
+}
+```
+
+## Business Identity
+
+Manage identity attributes (minority-owned, veteran-owned, etc.).
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/businessIdentity` |
+| `PATCH` | `/accounts/{account}/businessIdentity` |
+
+## Shipping Settings
+
+Configure account-level shipping rules.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/shippingSettings` |
+| `POST` | `/accounts/{account}/shippingSettings` |
+
+```json
+{
+  "name": "accounts/123456789/shippingSettings",
+  "services": [
+    {
+      "serviceName": "Standard Shipping",
+      "active": true,
+      "deliveryCountries": ["US"],
+      "currencyCode": "USD",
+      "deliveryTime": {
+        "minTransitDays": 3,
+        "maxTransitDays": 7,
+        "minHandlingDays": 0,
+        "maxHandlingDays": 1
+      },
+      "rateGroups": [
+        {
+          "applicableShippingLabels": [],
+          "singleValue": {
+            "flatRate": {
+              "amountMicros": "5990000",
+              "currencyCode": "USD"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Users
+
+Manage who can access the Merchant Center account.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/users/{user}` |
+| `GET` | `/accounts/{account}/users` |
+| `POST` | `/accounts/{account}/users` |
+| `PATCH` | `/accounts/{account}/users/{user}` |
+| `DELETE` | `/accounts/{account}/users/{user}` |
+
+```json
+{
+  "name": "accounts/123456789/users/user@example.com",
+  "emailAddress": "user@example.com",
+  "accessRights": ["STANDARD", "ADMIN"],
+  "state": "ACTIVE"
+}
+```
+
+**Access Rights:**
+- `STANDARD` - View and manage products
+- `ADMIN` - Full account control
+- `PERFORMANCE_REPORTING` - View reports only
+
+## Programs
+
+Manage enrollment in Google programs (Shopping Ads, Free Listings, etc.).
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/programs/{program}` |
+| `GET` | `/accounts/{account}/programs` |
+| `POST` | `/accounts/{account}/programs/{program}:enable` |
+| `POST` | `/accounts/{account}/programs/{program}:disable` |
+
+Common programs: `FREE_LISTINGS`, `SHOPPING_ADS`, `FREE_LOCAL_LISTINGS`, `LOCAL_INVENTORY_ADS`
+
+## Regions
+
+Define geographic regions for regional pricing and availability.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/regions/{region}` |
+| `GET` | `/accounts/{account}/regions` |
+| `POST` | `/accounts/{account}/regions` |
+| `PATCH` | `/accounts/{account}/regions/{region}` |
+| `DELETE` | `/accounts/{account}/regions/{region}` |
+| `POST` | `/accounts/{account}/regions:batchCreate` |
+| `POST` | `/accounts/{account}/regions:batchUpdate` |
+| `POST` | `/accounts/{account}/regions:batchDelete` |
+
+```json
+{
+  "name": "accounts/123456789/regions/northeast",
+  "displayName": "US Northeast",
+  "postalCodeArea": {
+    "regionCode": "US",
+    "postalCodes": [
+      { "begin": "10000", "end": "14999" },
+      { "begin": "06000", "end": "06999" }
+    ]
+  }
+}
+```
+
+## Online Return Policies
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/onlineReturnPolicies/{policy}` |
+| `GET` | `/accounts/{account}/onlineReturnPolicies` |
+| `POST` | `/accounts/{account}/onlineReturnPolicies` |
+| `DELETE` | `/accounts/{account}/onlineReturnPolicies/{policy}` |
+
+## Homepage
+
+Claim and manage your store homepage URL.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/homepage` |
+| `PATCH` | `/accounts/{account}/homepage` |
+| `POST` | `/accounts/{account}/homepage:claim` |
+| `POST` | `/accounts/{account}/homepage:unclaim` |
+
+## Terms of Service
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/termsOfService/{tos}` |
+| `GET` | `/termsOfService:retrieveLatest` |
+| `POST` | `/termsOfService/{tos}:accept` |
+| `GET` | `/accounts/{account}/termsOfServiceAgreementStates/{state}` |
+
+## Autofeed Settings
+
+Enable Google to auto-crawl your site for product data.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/autofeedSettings` |
+| `PATCH` | `/accounts/{account}/autofeedSettings` |
+
+```json
+{
+  "name": "accounts/123456789/autofeedSettings",
+  "enableProducts": true
+}
+```
+
+## Developer Registration
+
+Link your GCP project to Merchant Center.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/developerRegistration` |
+| `POST` | `/accounts/{account}/developerRegistration:registerGcp` |
+| `POST` | `/accounts/{account}/developerRegistration:unregisterGcp` |
+
+## Account Issues
+
+List problems affecting your account.
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/accounts/{account}/issues` |
+
+Returns validation issues, policy violations, and suggested fixes.

package/src/skills/google-merchant-api/references/content-api-legacy.md

@@ -0,0 +1,216 @@
+# Content API for Shopping v2.1 (Legacy Reference)
+
+**Sunset date: August 18, 2026.** Use the Merchant API for new integrations.
+
+Base: `https://shoppingcontent.googleapis.com/content/v2.1`
+
+## Products
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/{merchantId}/products` | Insert product |
+| `PATCH` | `/{merchantId}/products/{productId}` | Update product |
+| `DELETE` | `/{merchantId}/products/{productId}` | Delete product |
+| `GET` | `/{merchantId}/products/{productId}` | Get product |
+| `GET` | `/{merchantId}/products` | List products |
+| `POST` | `/products/batch` | Batch operations |
+
+**Product ID format:** `channel:contentLanguage:targetCountry:offerId`
+Example: `online:en:US:SKU-001`
+
+### Insert Product
+
+```javascript
+const product = {
+  offerId: 'SKU-001',
+  title: 'Premium Wireless Headphones',
+  description: 'Noise-cancelling Bluetooth headphones',
+  link: 'https://example.com/headphones',
+  imageLink: 'https://example.com/images/headphones.jpg',
+  contentLanguage: 'en',
+  targetCountry: 'US',
+  channel: 'online',
+  availability: 'in stock',
+  condition: 'new',
+  price: { value: '79.99', currency: 'USD' },
+  brand: 'AudioBrand',
+  gtin: '0123456789012',
+  googleProductCategory: 'Electronics > Audio > Headphones',
+};
+
+const response = await fetch(
+  `https://shoppingcontent.googleapis.com/content/v2.1/${MERCHANT_ID}/products`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(product),
+  }
+);
+```
+
+### Custom Batch
+
+```javascript
+const batchRequest = {
+  entries: [
+    {
+      batchId: 1,
+      merchantId: MERCHANT_ID,
+      method: 'insert',
+      product: {
+        offerId: 'SKU-001',
+        title: 'Product 1',
+        // ...
+      },
+    },
+    {
+      batchId: 2,
+      merchantId: MERCHANT_ID,
+      method: 'insert',
+      product: {
+        offerId: 'SKU-002',
+        title: 'Product 2',
+        // ...
+      },
+    },
+  ],
+};
+
+const response = await fetch(
+  `https://shoppingcontent.googleapis.com/content/v2.1/products/batch`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(batchRequest),
+  }
+);
+```
+
+## Product Statuses
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/{merchantId}/productstatuses/{productId}` |
+| `GET` | `/{merchantId}/productstatuses` |
+| `POST` | `/productstatuses/batch` |
+
+```json
+{
+  "productId": "online:en:US:SKU-001",
+  "title": "Premium Headphones",
+  "destinationStatuses": [
+    {
+      "destination": "SurfacesAcrossGoogle",
+      "status": "approved",
+      "approvedCountries": ["US"],
+      "pendingCountries": [],
+      "disapprovedCountries": []
+    }
+  ],
+  "itemLevelIssues": [
+    {
+      "code": "missing_recommended_attribute",
+      "servability": "unaffected",
+      "description": "Missing product highlight",
+      "detail": "Add product highlights for better visibility",
+      "attributeName": "product_highlight"
+    }
+  ]
+}
+```
+
+## Accounts
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/{merchantId}/accounts/{accountId}` |
+| `GET` | `/{merchantId}/accounts` |
+| `POST` | `/{merchantId}/accounts` |
+| `PATCH` | `/{merchantId}/accounts/{accountId}` |
+| `DELETE` | `/{merchantId}/accounts/{accountId}` |
+
+## Datafeeds
+
+| Method | Endpoint |
+|--------|----------|
+| `GET` | `/{merchantId}/datafeeds/{datafeedId}` |
+| `GET` | `/{merchantId}/datafeeds` |
+| `POST` | `/{merchantId}/datafeeds` |
+| `PATCH` | `/{merchantId}/datafeeds/{datafeedId}` |
+| `DELETE` | `/{merchantId}/datafeeds/{datafeedId}` |
+| `POST` | `/{merchantId}/datafeeds/{datafeedId}/fetchNow` |
+
+```json
+{
+  "id": "123456789",
+  "name": "Daily Product Feed",
+  "contentType": "products",
+  "fileName": "products.xml",
+  "fetchSchedule": {
+    "fetchUrl": "https://example.com/feeds/products.xml",
+    "hour": 6,
+    "timeZone": "America/New_York",
+    "dayOfMonth": 0,
+    "weekday": "monday",
+    "paused": false
+  },
+  "format": {
+    "fileEncoding": "utf-8",
+    "quotingMode": "none"
+  },
+  "targets": [
+    {
+      "language": "en",
+      "country": "US",
+      "includedDestinations": ["SurfacesAcrossGoogle", "ShoppingAds"]
+    }
+  ]
+}
+```
+
+## Price Object (Content API)
+
+```json
+{
+  "value": "79.99",
+  "currency": "USD"
+}
+```
+
+`value` is a decimal string. `currency` is ISO 4217.
+
+## Key Enums
+
+**availability:** `in stock`, `out of stock`, `preorder`, `backorder`
+(Note: spaces, not underscores — unlike Merchant API)
+
+**condition:** `new`, `refurbished`, `used`
+
+**channel:** `online`, `local`
+(Note: lowercase strings — unlike Merchant API enums)
+
+## Pagination
+
+List endpoints support `maxResults` and `pageToken`:
+
+```
+GET /{merchantId}/products?maxResults=250&pageToken=abc123
+```
+
+## Error Format
+
+```json
+{
+  "error": {
+    "errors": [
+      {
+        "domain": "content.ContentErrorDomain",
+        "reason": "not_found",
+        "message": "product not found"
+      }
+    ],
+    "code": 404,
+    "message": "product not found"
+  }
+}
+```

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

@@ -0,0 +1,233 @@
+# Data Sources Sub-API Reference
+
+Base: `https://merchantapi.googleapis.com/datasources/v1`
+
+Manage how product data flows into Merchant Center — via API, file uploads, or automatic crawling.
+
+## Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/accounts/{account}/dataSources` | Create data source |
+| `GET` | `/accounts/{account}/dataSources/{dataSource}` | Get data source |
+| `GET` | `/accounts/{account}/dataSources` | List data sources |
+| `PATCH` | `/accounts/{account}/dataSources/{dataSource}` | Update data source |
+| `DELETE` | `/accounts/{account}/dataSources/{dataSource}` | Delete data source |
+| `POST` | `/accounts/{account}/dataSources/{dataSource}:fetch` | Trigger file fetch |
+| `GET` | `/accounts/{account}/dataSources/{dataSource}/fileUploads/{fileUpload}` | Get file upload status |
+
+## Data Source Types
+
+### Primary API Data Source
+
+Products inserted directly via `productInputs:insert`.
+
+```json
+{
+  "displayName": "My API Feed",
+  "primaryProductDataSource": {
+    "channel": "ONLINE_PRODUCTS",
+    "contentLanguage": "en",
+    "feedLabel": "US"
+  }
+}
+```
+
+### Primary File Data Source
+
+Products loaded from a file (URL fetch or direct upload).
+
+```json
+{
+  "displayName": "Daily Product Feed",
+  "primaryProductDataSource": {
+    "channel": "ONLINE_PRODUCTS",
+    "contentLanguage": "en",
+    "feedLabel": "US"
+  },
+  "fileInput": {
+    "fetchSettings": {
+      "enabled": true,
+      "fetchUri": "https://example.com/feeds/products.xml",
+      "timeOfDay": { "hours": 6, "minutes": 0 },
+      "dayOfMonth": 0,
+      "timeZone": "America/New_York",
+      "frequency": "DAILY"
+    },
+    "fileName": "products.xml",
+    "fileInputType": "FETCH"
+  }
+}
+```
+
+### Supplemental API Data Source
+
+Adds/overrides attributes on products from a primary source.
+
+```json
+{
+  "displayName": "Price Overrides",
+  "supplementalProductDataSource": {
+    "referencingPrimaryDataSources": [
+      "accounts/123456/dataSources/primary-feed-id"
+    ]
+  }
+}
+```
+
+### Supplemental File Data Source
+
+```json
+{
+  "displayName": "Weekly Sale Prices",
+  "supplementalProductDataSource": {
+    "referencingPrimaryDataSources": [
+      "accounts/123456/dataSources/primary-feed-id"
+    ]
+  },
+  "fileInput": {
+    "fetchSettings": {
+      "enabled": true,
+      "fetchUri": "https://example.com/feeds/sale-prices.tsv",
+      "frequency": "WEEKLY",
+      "dayOfWeek": "MONDAY",
+      "timeOfDay": { "hours": 3, "minutes": 0 },
+      "timeZone": "America/New_York"
+    },
+    "fileName": "sale-prices.tsv",
+    "fileInputType": "FETCH"
+  }
+}
+```
+
+## Channel Types
+
+| Channel | Description |
+|---------|-------------|
+| `ONLINE_PRODUCTS` | Online product listings |
+| `LOCAL_PRODUCTS` | Local/in-store product listings |
+| `PRODUCTS` | Both online and local |
+
+## Fetch Frequency
+
+| Value | Description |
+|-------|-------------|
+| `DAILY` | Every day at specified time |
+| `WEEKLY` | Specified day + time each week |
+| `MONTHLY` | Specified day of month + time |
+
+## File Input Types
+
+| Type | Description |
+|------|-------------|
+| `FETCH` | Google fetches from your URL on schedule |
+| `GOOGLE_SHEETS` | Data from a Google Sheet |
+| `UPLOAD` | Direct file upload via SFTP or Merchant Center UI |
+
+## Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Resource name (output only) |
+| `dataSourceId` | string | Numeric ID (output only) |
+| `displayName` | string | Human-readable name |
+| `primaryProductDataSource` | object | Config for primary data source |
+| `supplementalProductDataSource` | object | Config for supplemental source |
+| `fileInput` | object | File-based fetch/upload settings |
+| `input` | enum | `API`, `FILE`, `UI`, `AUTOFEED` (output only) |
+
+## Common Workflows
+
+### Create Primary API Feed and Insert Products
+
+```javascript
+// Step 1: Create the data source
+const dsResponse = await fetch(
+  `https://merchantapi.googleapis.com/datasources/v1/accounts/${MERCHANT_ID}/dataSources`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      displayName: 'Product API Feed',
+      primaryProductDataSource: {
+        channel: 'ONLINE_PRODUCTS',
+        contentLanguage: 'en',
+        feedLabel: 'US',
+      },
+    }),
+  }
+);
+const dataSource = await dsResponse.json();
+const dataSourceName = dataSource.name; // accounts/123456/dataSources/789
+
+// Step 2: Insert products referencing this data source
+await fetch(
+  `https://merchantapi.googleapis.com/products/v1/accounts/${MERCHANT_ID}/productInputs:insert?dataSource=${dataSourceName}`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      offerId: 'SKU-001',
+      contentLanguage: 'en',
+      feedLabel: 'US',
+      productAttributes: {
+        title: 'My Product',
+        // ... other attributes
+      },
+    }),
+  }
+);
+```
+
+### Create Supplemental Feed for Sale Prices
+
+```javascript
+// Supplemental feed overrides specific attributes
+const dsResponse = await fetch(
+  `https://merchantapi.googleapis.com/datasources/v1/accounts/${MERCHANT_ID}/dataSources`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      displayName: 'Sale Price Overrides',
+      supplementalProductDataSource: {
+        referencingPrimaryDataSources: [primaryDataSourceName],
+      },
+    }),
+  }
+);
+const supplementalDS = await dsResponse.json();
+
+// Insert supplemental data (only the fields you want to override)
+await fetch(
+  `https://merchantapi.googleapis.com/products/v1/accounts/${MERCHANT_ID}/productInputs:insert?dataSource=${supplementalDS.name}`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      offerId: 'SKU-001',
+      contentLanguage: 'en',
+      feedLabel: 'US',
+      productAttributes: {
+        salePrice: { amountMicros: '59990000', currencyCode: 'USD' },
+        salePriceEffectiveDate: {
+          startTime: '2024-12-01T00:00:00Z',
+          endTime: '2024-12-31T23:59:59Z',
+        },
+      },
+    }),
+  }
+);
+```
+
+### Trigger Manual File Fetch
+
+```javascript
+await fetch(
+  `https://merchantapi.googleapis.com/datasources/v1/accounts/${MERCHANT_ID}/dataSources/${DATA_SOURCE_ID}:fetch`,
+  {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}` },
+  }
+);
+```