@clawpify/skills 1.0.1

package/clawpify/references/subscriptions.md

@@ -0,0 +1,429 @@
+# Shopify Subscriptions
+
+Manage subscription contracts and billing via the GraphQL Admin API.
+
+## Overview
+
+Subscriptions enable recurring orders for products. Subscription contracts define the billing schedule, products, and delivery details.
+
+## List Subscription Contracts
+
+```graphql
+query ListSubscriptionContracts($first: Int!, $query: String) {
+  subscriptionContracts(first: $first, query: $query, sortKey: CREATED_AT, reverse: true) {
+    nodes {
+      id
+      status
+      createdAt
+      nextBillingDate
+      customer {
+        displayName
+        defaultEmailAddress {
+          emailAddress
+        }
+      }
+      deliveryPolicy {
+        interval
+        intervalCount
+      }
+      billingPolicy {
+        interval
+        intervalCount
+      }
+      lines(first: 5) {
+        nodes {
+          title
+          quantity
+          currentPrice {
+            amount
+            currencyCode
+          }
+        }
+      }
+    }
+  }
+}
+```
+Variables: `{ "first": 10 }`
+
+## Get Subscription Contract
+
+```graphql
+query GetSubscriptionContract($id: ID!) {
+  subscriptionContract(id: $id) {
+    id
+    status
+    createdAt
+    updatedAt
+    nextBillingDate
+    customer {
+      id
+      displayName
+    }
+    customerPaymentMethod {
+      id
+      instrument {
+        ... on CustomerCreditCard {
+          brand
+          lastDigits
+          expiryMonth
+          expiryYear
+        }
+      }
+    }
+    deliveryPolicy {
+      interval
+      intervalCount
+    }
+    billingPolicy {
+      interval
+      intervalCount
+      minCycles
+      maxCycles
+    }
+    deliveryPrice {
+      amount
+      currencyCode
+    }
+    lines(first: 10) {
+      nodes {
+        id
+        title
+        variantId
+        quantity
+        currentPrice {
+          amount
+          currencyCode
+        }
+        sellingPlanId
+        sellingPlanName
+      }
+    }
+    orders(first: 5) {
+      nodes {
+        id
+        name
+        createdAt
+      }
+    }
+  }
+}
+```
+Variables: `{ "id": "gid://shopify/SubscriptionContract/123" }`
+
+## Get Billing Cycles
+
+```graphql
+query GetBillingCycles($contractId: ID!, $first: Int!) {
+  subscriptionBillingCycles(contractId: $contractId, first: $first) {
+    nodes {
+      cycleIndex
+      cycleStartAt
+      cycleEndAt
+      status
+      skipped
+      billingAttemptExpectedDate
+    }
+  }
+}
+```
+Variables: `{ "contractId": "gid://shopify/SubscriptionContract/123", "first": 12 }`
+
+## Get Specific Billing Cycle
+
+```graphql
+query GetBillingCycle($billingCycleInput: SubscriptionBillingCycleInput!) {
+  subscriptionBillingCycle(billingCycleInput: $billingCycleInput) {
+    cycleIndex
+    cycleStartAt
+    cycleEndAt
+    status
+    skipped
+    billingAttemptExpectedDate
+    sourceContract {
+      id
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "billingCycleInput": {
+    "contractId": "gid://shopify/SubscriptionContract/123",
+    "selector": {
+      "index": 3
+    }
+  }
+}
+```
+
+## List Billing Attempts
+
+```graphql
+query ListBillingAttempts($first: Int!) {
+  subscriptionBillingAttempts(first: $first, sortKey: CREATED_AT, reverse: true) {
+    nodes {
+      id
+      createdAt
+      ready
+      errorMessage
+      subscriptionContract {
+        id
+      }
+      order {
+        id
+        name
+      }
+    }
+  }
+}
+```
+
+## Create Subscription Draft
+
+```graphql
+mutation CreateSubscriptionDraft($input: SubscriptionDraftInput!) {
+  subscriptionDraftCreate(input: $input) {
+    draft {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Update Subscription Draft
+
+```graphql
+mutation UpdateSubscriptionDraft($draftId: ID!, $input: SubscriptionDraftInput!) {
+  subscriptionDraftUpdate(draftId: $draftId, input: $input) {
+    draft {
+      id
+      status
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "draftId": "gid://shopify/SubscriptionDraft/123",
+  "input": {
+    "deliveryPolicy": {
+      "interval": "MONTH",
+      "intervalCount": 2
+    }
+  }
+}
+```
+
+## Add Line to Draft
+
+```graphql
+mutation AddLineToDraft($draftId: ID!, $input: SubscriptionLineInput!) {
+  subscriptionDraftLineAdd(draftId: $draftId, input: $input) {
+    draft {
+      id
+      lines(first: 10) {
+        nodes {
+          title
+          quantity
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "draftId": "gid://shopify/SubscriptionDraft/123",
+  "input": {
+    "productVariantId": "gid://shopify/ProductVariant/456",
+    "quantity": 1,
+    "currentPrice": {
+      "amount": "29.99",
+      "currencyCode": "USD"
+    }
+  }
+}
+```
+
+## Commit Draft (Activate)
+
+```graphql
+mutation CommitSubscriptionDraft($draftId: ID!) {
+  subscriptionDraftCommit(draftId: $draftId) {
+    contract {
+      id
+      status
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Pause Subscription
+
+```graphql
+mutation PauseSubscription($subscriptionContractId: ID!) {
+  subscriptionContractPause(subscriptionContractId: $subscriptionContractId) {
+    contract {
+      id
+      status
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Resume Subscription
+
+```graphql
+mutation ActivateSubscription($subscriptionContractId: ID!) {
+  subscriptionContractActivate(subscriptionContractId: $subscriptionContractId) {
+    contract {
+      id
+      status
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Cancel Subscription
+
+```graphql
+mutation CancelSubscription($subscriptionContractId: ID!) {
+  subscriptionContractCancel(subscriptionContractId: $subscriptionContractId) {
+    contract {
+      id
+      status
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Skip Billing Cycle
+
+```graphql
+mutation SkipBillingCycle($billingCycleInput: SubscriptionBillingCycleInput!) {
+  subscriptionBillingCycleSkip(billingCycleInput: $billingCycleInput) {
+    billingCycle {
+      cycleIndex
+      skipped
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "billingCycleInput": {
+    "contractId": "gid://shopify/SubscriptionContract/123",
+    "selector": {
+      "index": 5
+    }
+  }
+}
+```
+
+## Contract Status
+
+| Status | Description |
+|--------|-------------|
+| `ACTIVE` | Subscription is active |
+| `PAUSED` | Temporarily paused |
+| `CANCELLED` | Permanently cancelled |
+| `EXPIRED` | Reached max cycles |
+| `FAILED` | Billing failed |
+
+## Billing/Delivery Intervals
+
+| Interval | Description |
+|----------|-------------|
+| `DAY` | Daily |
+| `WEEK` | Weekly |
+| `MONTH` | Monthly |
+| `YEAR` | Yearly |
+
+## Billing Cycle Status
+
+| Status | Description |
+|--------|-------------|
+| `UNBILLED` | Not yet billed |
+| `BILLED` | Successfully billed |
+| `SKIPPED` | Skipped by customer/merchant |
+
+## Add Discount to Draft
+
+```graphql
+mutation AddDiscountToDraft($draftId: ID!, $input: SubscriptionManualDiscountInput!) {
+  subscriptionDraftDiscountAdd(draftId: $draftId, input: $input) {
+    draft {
+      id
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "draftId": "gid://shopify/SubscriptionDraft/123",
+  "input": {
+    "title": "Loyalty Discount",
+    "value": {
+      "percentage": 10
+    },
+    "recurringCycleLimit": 3
+  }
+}
+```
+
+## API Scopes Required
+
+- `read_own_subscription_contracts` - Read contracts
+- `write_own_subscription_contracts` - Manage contracts
+- `read_customer_payment_methods` - Read payment methods
+
+## Notes
+
+- Subscriptions require selling plans on products
+- Billing attempts are processed automatically
+- Customers can manage subscriptions via customer portal
+- Failed billing triggers retry logic
+- Drafts must be committed to create/update contracts
+- Skipped cycles don't charge the customer

package/clawpify/references/translations.md

@@ -0,0 +1,270 @@
+# Shopify Translations
+
+Manage translations for products, collections, pages, and other resources via the GraphQL Admin API.
+
+## Overview
+
+Shopify supports translating content into multiple locales. Each translatable field has a `digest` value used to register translations.
+
+## Get Translatable Resource
+
+```graphql
+query GetTranslatableResource($resourceId: ID!) {
+  translatableResource(resourceId: $resourceId) {
+    resourceId
+    translatableContent {
+      key
+      value
+      digest
+      locale
+    }
+    translations(locale: "fr") {
+      key
+      value
+      locale
+      outdated
+    }
+  }
+}
+```
+Variables: `{ "resourceId": "gid://shopify/Product/123" }`
+
+## List Translatable Resources
+
+```graphql
+query ListTranslatableResources($resourceType: TranslatableResourceType!, $first: Int!) {
+  translatableResources(resourceType: $resourceType, first: $first) {
+    nodes {
+      resourceId
+      translatableContent {
+        key
+        value
+        digest
+      }
+    }
+  }
+}
+```
+Variables: `{ "resourceType": "PRODUCT", "first": 10 }`
+
+## Get Resources by IDs
+
+```graphql
+query GetTranslatableResourcesByIds($resourceIds: [ID!]!, $first: Int!) {
+  translatableResourcesByIds(resourceIds: $resourceIds, first: $first) {
+    nodes {
+      resourceId
+      translatableContent {
+        key
+        value
+        digest
+      }
+      translations(locale: "es") {
+        key
+        value
+        outdated
+      }
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "resourceIds": ["gid://shopify/Product/123", "gid://shopify/Product/456"],
+  "first": 10
+}
+```
+
+## Register Translations
+
+```graphql
+mutation RegisterTranslations($resourceId: ID!, $translations: [TranslationInput!]!) {
+  translationsRegister(resourceId: $resourceId, translations: $translations) {
+    translations {
+      key
+      value
+      locale
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "resourceId": "gid://shopify/Product/123",
+  "translations": [
+    {
+      "key": "title",
+      "value": "Chandail d'été",
+      "locale": "fr",
+      "translatableContentDigest": "abc123digest"
+    },
+    {
+      "key": "body_html",
+      "value": "<p>Un chandail léger parfait pour l'été.</p>",
+      "locale": "fr",
+      "translatableContentDigest": "def456digest"
+    }
+  ]
+}
+```
+
+## Register Market-Specific Translations
+
+```graphql
+mutation RegisterMarketTranslations($resourceId: ID!, $translations: [TranslationInput!]!) {
+  translationsRegister(resourceId: $resourceId, translations: $translations) {
+    translations {
+      key
+      value
+      locale
+      market {
+        id
+        name
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "resourceId": "gid://shopify/Product/123",
+  "translations": [
+    {
+      "key": "title",
+      "value": "Summer Jumper",
+      "locale": "en-GB",
+      "translatableContentDigest": "abc123digest",
+      "marketId": "gid://shopify/Market/456"
+    }
+  ]
+}
+```
+
+## Remove Translations
+
+```graphql
+mutation RemoveTranslations($resourceId: ID!, $translationKeys: [String!]!, $locales: [String!]!) {
+  translationsRemove(resourceId: $resourceId, translationKeys: $translationKeys, locales: $locales) {
+    translations {
+      key
+      locale
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "resourceId": "gid://shopify/Product/123",
+  "translationKeys": ["title", "body_html"],
+  "locales": ["fr"]
+}
+```
+
+## Remove Market-Specific Translations
+
+```graphql
+mutation RemoveMarketTranslations($resourceId: ID!, $translationKeys: [String!]!, $locales: [String!]!, $marketIds: [ID!]) {
+  translationsRemove(resourceId: $resourceId, translationKeys: $translationKeys, locales: $locales, marketIds: $marketIds) {
+    translations {
+      key
+      locale
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Translatable Resource Types
+
+| Type | Description |
+|------|-------------|
+| `PRODUCT` | Products |
+| `PRODUCT_VARIANT` | Product variants |
+| `COLLECTION` | Collections |
+| `ONLINE_STORE_PAGE` | Pages |
+| `ONLINE_STORE_BLOG` | Blogs |
+| `ONLINE_STORE_ARTICLE` | Blog articles |
+| `ONLINE_STORE_MENU` | Navigation menus |
+| `EMAIL_TEMPLATE` | Email templates |
+| `SMS_TEMPLATE` | SMS templates |
+| `SHOP` | Shop settings |
+| `SHOP_POLICY` | Shop policies |
+| `LINK` | Navigation links |
+| `METAFIELD` | Metafields |
+| `METAOBJECT` | Metaobjects |
+| `FILTER` | Storefront filters |
+| `PAYMENT_GATEWAY` | Payment gateways |
+| `DELIVERY_METHOD_DEFINITION` | Shipping methods |
+
+## Common Translatable Keys by Resource
+
+### Products
+- `title` - Product title
+- `body_html` - Product description
+- `meta_title` - SEO title
+- `meta_description` - SEO description
+
+### Collections
+- `title` - Collection title
+- `body_html` - Collection description
+- `meta_title` - SEO title
+- `meta_description` - SEO description
+
+### Pages
+- `title` - Page title
+- `body_html` - Page content
+
+### Metafields
+- `value` - Metafield value (for string types)
+
+## Translation Workflow
+
+1. **Get translatable content** - Query the resource to get fields and digests
+2. **Translate content** - Prepare translations with the digest values
+3. **Register translations** - Submit translations via mutation
+4. **Verify** - Query to confirm translations are registered
+
+## Get Shop Locales
+
+```graphql
+query GetShopLocales {
+  shopLocales(published: true) {
+    locale
+    name
+    primary
+    published
+  }
+}
+```
+
+## API Scopes Required
+
+- `read_translations` - Read translations
+- `write_translations` - Create, update, delete translations
+- `read_locales` - Read shop locales
+- `write_locales` - Manage shop locales
+
+## Notes
+
+- Always use the `digest` value from `translatableContent` when registering translations
+- Translations marked as `outdated: true` need to be reviewed after the source content changed
+- Market-specific translations override locale translations for buyers in that market