@clawpify/skills 1.0.1

package/clawpify/references/webhooks.md

@@ -0,0 +1,400 @@
+# Shopify Webhooks
+
+Subscribe to event notifications via the GraphQL Admin API.
+
+## Overview
+
+Webhooks push real-time notifications to your app when events occur in a Shopify store, eliminating the need for polling.
+
+## List Webhook Subscriptions
+
+```graphql
+query ListWebhooks($first: Int!) {
+  webhookSubscriptions(first: $first) {
+    nodes {
+      id
+      topic
+      endpoint {
+        ... on WebhookHttpEndpoint {
+          callbackUrl
+        }
+        ... on WebhookPubSubEndpoint {
+          pubSubProject
+          pubSubTopic
+        }
+        ... on WebhookEventBridgeEndpoint {
+          arn
+        }
+      }
+      format
+      createdAt
+    }
+  }
+}
+```
+Variables: `{ "first": 50 }`
+
+## Get Webhook Subscription
+
+```graphql
+query GetWebhook($id: ID!) {
+  webhookSubscription(id: $id) {
+    id
+    topic
+    endpoint {
+      ... on WebhookHttpEndpoint {
+        callbackUrl
+      }
+    }
+    format
+    includeFields
+    metafieldNamespaces
+    filter
+    createdAt
+    updatedAt
+  }
+}
+```
+Variables: `{ "id": "gid://shopify/WebhookSubscription/123" }`
+
+## Get Webhooks Count
+
+```graphql
+query GetWebhooksCount {
+  webhookSubscriptionsCount {
+    count
+  }
+}
+```
+
+## Create HTTP Webhook
+
+```graphql
+mutation CreateWebhook($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      topic
+      endpoint {
+        ... on WebhookHttpEndpoint {
+          callbackUrl
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "ORDERS_CREATE",
+  "webhookSubscription": {
+    "callbackUrl": "https://myapp.example.com/webhooks/orders",
+    "format": "JSON"
+  }
+}
+```
+
+## Create Webhook with Filters
+
+```graphql
+mutation CreateFilteredWebhook($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      topic
+      filter
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "ORDERS_CREATE",
+  "webhookSubscription": {
+    "callbackUrl": "https://myapp.example.com/webhooks/orders",
+    "format": "JSON",
+    "filter": "total_price:>=100.00"
+  }
+}
+```
+
+## Create Webhook with Field Selection
+
+```graphql
+mutation CreateWebhookWithFields($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      includeFields
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "PRODUCTS_UPDATE",
+  "webhookSubscription": {
+    "callbackUrl": "https://myapp.example.com/webhooks/products",
+    "format": "JSON",
+    "includeFields": ["id", "title", "variants"]
+  }
+}
+```
+
+## Create Webhook with Metafields
+
+```graphql
+mutation CreateWebhookWithMetafields($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      metafieldNamespaces
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "PRODUCTS_UPDATE",
+  "webhookSubscription": {
+    "callbackUrl": "https://myapp.example.com/webhooks/products",
+    "format": "JSON",
+    "metafieldNamespaces": ["custom", "my_app"]
+  }
+}
+```
+
+## Create Google Pub/Sub Webhook
+
+```graphql
+mutation CreatePubSubWebhook($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      endpoint {
+        ... on WebhookPubSubEndpoint {
+          pubSubProject
+          pubSubTopic
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "ORDERS_CREATE",
+  "webhookSubscription": {
+    "pubSubProject": "my-gcp-project",
+    "pubSubTopic": "shopify-orders",
+    "format": "JSON"
+  }
+}
+```
+
+## Create AWS EventBridge Webhook
+
+```graphql
+mutation CreateEventBridgeWebhook($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      endpoint {
+        ... on WebhookEventBridgeEndpoint {
+          arn
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "topic": "ORDERS_CREATE",
+  "webhookSubscription": {
+    "arn": "arn:aws:events:us-east-1:123456789:event-source/aws.partner/shopify.com/12345/my-source",
+    "format": "JSON"
+  }
+}
+```
+
+## Update Webhook
+
+```graphql
+mutation UpdateWebhook($id: ID!, $webhookSubscription: WebhookSubscriptionInput!) {
+  webhookSubscriptionUpdate(id: $id, webhookSubscription: $webhookSubscription) {
+    webhookSubscription {
+      id
+      endpoint {
+        ... on WebhookHttpEndpoint {
+          callbackUrl
+        }
+      }
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+Variables:
+```json
+{
+  "id": "gid://shopify/WebhookSubscription/123",
+  "webhookSubscription": {
+    "callbackUrl": "https://myapp.example.com/webhooks/orders/v2"
+  }
+}
+```
+
+## Delete Webhook
+
+> REQUIRES PERMISSION: Deleting a webhook subscription permanently stops event notifications and may break integrations or automated workflows. Always ask the user for explicit confirmation, show the webhook topic and endpoint, and wait for approval before executing this operation.
+
+```graphql
+mutation DeleteWebhook($id: ID!) {
+  webhookSubscriptionDelete(id: $id) {
+    deletedWebhookSubscriptionId
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+## Common Webhook Topics
+
+### Orders
+| Topic | Event |
+|-------|-------|
+| `ORDERS_CREATE` | New order placed |
+| `ORDERS_UPDATED` | Order modified |
+| `ORDERS_CANCELLED` | Order cancelled |
+| `ORDERS_FULFILLED` | Order fulfilled |
+| `ORDERS_PAID` | Order paid |
+
+### Products
+| Topic | Event |
+|-------|-------|
+| `PRODUCTS_CREATE` | Product created |
+| `PRODUCTS_UPDATE` | Product updated |
+| `PRODUCTS_DELETE` | Product deleted |
+
+### Customers
+| Topic | Event |
+|-------|-------|
+| `CUSTOMERS_CREATE` | Customer created |
+| `CUSTOMERS_UPDATE` | Customer updated |
+| `CUSTOMERS_DELETE` | Customer deleted |
+
+### Inventory
+| Topic | Event |
+|-------|-------|
+| `INVENTORY_LEVELS_UPDATE` | Inventory changed |
+
+### Fulfillment
+| Topic | Event |
+|-------|-------|
+| `FULFILLMENTS_CREATE` | Fulfillment created |
+| `FULFILLMENTS_UPDATE` | Fulfillment updated |
+
+### Refunds
+| Topic | Event |
+|-------|-------|
+| `REFUNDS_CREATE` | Refund processed |
+
+### App
+| Topic | Event |
+|-------|-------|
+| `APP_UNINSTALLED` | App uninstalled |
+| `APP_SUBSCRIPTIONS_UPDATE` | Subscription changed |
+
+## Webhook Formats
+
+| Format | Description |
+|--------|-------------|
+| `JSON` | JSON payload |
+| `XML` | XML payload |
+
+## Filter Syntax Examples
+
+```
+# Orders over $100
+total_price:>=100.00
+
+# Specific customer
+customer_id:123456
+
+# Products with tag
+tags:sale
+
+# Combined filters
+total_price:>=50.00 AND financial_status:paid
+```
+
+## API Scopes Required
+
+Different topics require different scopes:
+
+| Topic | Required Scope |
+|-------|----------------|
+| `ORDERS_*` | `read_orders` |
+| `PRODUCTS_*` | `read_products` |
+| `CUSTOMERS_*` | `read_customers` |
+| `INVENTORY_*` | `read_inventory` |
+
+## Notes
+
+- App-specific webhooks in `shopify.app.toml` are preferred for most apps
+- API-created webhooks are shop-scoped, not app-scoped
+- Webhooks retry failed deliveries with exponential backoff
+- Verify webhook signatures for security
+- Maximum 3 attempts before webhook is marked failed
+- Webhook API version is set at app level, not per subscription
+
+## Dangerous Operations in This Skill
+
+The following operations require explicit user permission before execution:
+
+| Operation | Impact | Reversible |
+|-----------|--------|------------|
+| `webhookSubscriptionDelete` | Permanently stops event notifications, may break integrations | Yes (can recreate, but data in transit is lost) |
+
+Permission Protocol: Before executing `webhookSubscriptionDelete`:
+1. Show the webhook ID and subscription topic
+2. Display the endpoint/callback URL or destination
+3. Explain that event notifications will stop immediately
+4. Warn about potential impact on integrations and automation
+5. Wait for explicit user confirmation with "yes", "confirm", or "proceed"

package/dist/agent.d.ts

@@ -0,0 +1,18 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { ShopifyClient } from "./shopify";
+export declare class ShopifyAgent {
+    private anthropic;
+    private shopify;
+    private skillContent;
+    private model;
+    constructor(config: {
+        shopify: ShopifyClient;
+        skillContent: string;
+        model?: string;
+    });
+    chat(userMessage: string, conversationHistory?: Anthropic.MessageParam[]): Promise<{
+        response: string;
+        history: Anthropic.MessageParam[];
+    }>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAsB1C,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE;QAClB,OAAO,EAAE,aAAa,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB;IAOK,IAAI,CACR,WAAW,EAAE,MAAM,EACnB,mBAAmB,GAAE,SAAS,CAAC,YAAY,EAAO,GACjD,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,CAAC,YAAY,EAAE,CAAA;KAAE,CAAC;CAyFpE"}

package/dist/agent.js

@@ -0,0 +1,100 @@
+// src/agent.ts
+import Anthropic from "@anthropic-ai/sdk";
+var SHOPIFY_GRAPHQL_TOOL = {
+  name: "shopify_graphql",
+  description: "Execute a GraphQL query against the Shopify Admin API. Use this to interact with products, orders, customers, inventory, and other Shopify resources.",
+  input_schema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "The GraphQL query or mutation to execute"
+      },
+      variables: {
+        type: "object",
+        description: "Optional variables for the GraphQL query"
+      }
+    },
+    required: ["query"]
+  }
+};
+
+class ShopifyAgent {
+  anthropic;
+  shopify;
+  skillContent;
+  model;
+  constructor(config) {
+    this.anthropic = new Anthropic;
+    this.shopify = config.shopify;
+    this.skillContent = config.skillContent;
+    this.model = config.model ?? "claude-sonnet-4-5";
+  }
+  async chat(userMessage, conversationHistory = []) {
+    const systemPrompt = `You are a helpful Shopify assistant that can query and manage a Shopify store using the GraphQL Admin API.
+
+${this.skillContent}
+
+When the user asks about products, orders, customers, or any Shopify data, use the shopify_graphql tool to fetch or modify the data. Always explain what you're doing and present results clearly.`;
+    const messages = [
+      ...conversationHistory,
+      { role: "user", content: userMessage }
+    ];
+    let response = await this.anthropic.messages.create({
+      model: this.model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      tools: [SHOPIFY_GRAPHQL_TOOL],
+      messages
+    });
+    const assistantMessages = [];
+    while (response.stop_reason === "tool_use") {
+      const toolUseBlocks = response.content.filter((block) => block.type === "tool_use");
+      assistantMessages.push(...response.content);
+      const toolResults = [];
+      for (const toolUse of toolUseBlocks) {
+        if (toolUse.name === "shopify_graphql") {
+          const input = toolUse.input;
+          try {
+            const result = await this.shopify.graphql(input.query, input.variables);
+            toolResults.push({
+              type: "tool_result",
+              tool_use_id: toolUse.id,
+              content: JSON.stringify(result, null, 2)
+            });
+          } catch (error) {
+            toolResults.push({
+              type: "tool_result",
+              tool_use_id: toolUse.id,
+              content: `Error: ${error instanceof Error ? error.message : String(error)}`,
+              is_error: true
+            });
+          }
+        }
+      }
+      messages.push({ role: "assistant", content: assistantMessages.slice() });
+      messages.push({ role: "user", content: toolResults });
+      assistantMessages.length = 0;
+      response = await this.anthropic.messages.create({
+        model: this.model,
+        max_tokens: 4096,
+        system: systemPrompt,
+        tools: [SHOPIFY_GRAPHQL_TOOL],
+        messages
+      });
+    }
+    const textBlocks = response.content.filter((block) => block.type === "text");
+    const finalResponse = textBlocks.map((b) => b.text).join(`
+`);
+    const updatedHistory = [
+      ...messages,
+      { role: "assistant", content: response.content }
+    ];
+    return { response: finalResponse, history: updatedHistory };
+  }
+}
+export {
+  ShopifyAgent
+};
+
+export { ShopifyAgent };

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shopify OAuth Client Credentials
+ * For apps installed on stores you own (server-to-server)
+ */
+export interface AccessTokenResponse {
+    accessToken: string;
+    scope: string;
+    expiresIn: number;
+}
+export interface ClientCredentialsConfig {
+    storeUrl: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Get an access token using the Client Credentials grant.
+ * Token expires in 24 hours and must be refreshed with the same request.
+ *
+ * @see https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant
+ */
+export declare function getAccessToken(config: ClientCredentialsConfig): Promise<AccessTokenResponse>;
+/**
+ * Create a Shopify client config from environment variables.
+ * Supports two authentication methods:
+ * 1. Direct access token (SHOPIFY_ACCESS_TOKEN) - uses token directly
+ * 2. Client credentials (SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET) - fetches token via OAuth
+ */
+export declare function createAuthenticatedConfig(): Promise<{
+    storeUrl: string;
+    accessToken: string;
+    scope?: string;
+    expiresIn?: number;
+}>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAoC9B;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAkCD"}

package/dist/auth.js

@@ -0,0 +1,58 @@
+// src/auth.ts
+async function getAccessToken(config) {
+  const storeUrl = config.storeUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+  const response = await fetch(`https://${storeUrl}/admin/oauth/access_token`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: config.clientId,
+      client_secret: config.clientSecret
+    })
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`OAuth error (${response.status}): ${text}`);
+  }
+  const data = await response.json();
+  return {
+    accessToken: data.access_token,
+    scope: data.scope,
+    expiresIn: data.expires_in
+  };
+}
+async function createAuthenticatedConfig() {
+  const storeUrl = process.env.SHOPIFY_STORE_URL;
+  const directToken = process.env.SHOPIFY_ACCESS_TOKEN;
+  const clientId = process.env.SHOPIFY_CLIENT_ID;
+  const clientSecret = process.env.SHOPIFY_CLIENT_SECRET;
+  if (!storeUrl) {
+    throw new Error("Missing required environment variable: SHOPIFY_STORE_URL");
+  }
+  if (directToken) {
+    return {
+      storeUrl,
+      accessToken: directToken
+    };
+  }
+  if (clientId && clientSecret) {
+    const token = await getAccessToken({ storeUrl, clientId, clientSecret });
+    return {
+      storeUrl,
+      accessToken: token.accessToken,
+      scope: token.scope,
+      expiresIn: token.expiresIn
+    };
+  }
+  throw new Error(`Missing authentication credentials. Provide either:
+` + `  - SHOPIFY_ACCESS_TOKEN (direct token), or
+` + "  - SHOPIFY_CLIENT_ID and SHOPIFY_CLIENT_SECRET (OAuth client credentials)");
+}
+export {
+  getAccessToken,
+  createAuthenticatedConfig
+};
+
+export { getAccessToken, createAuthenticatedConfig };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Clawpify - Shopify Agent SDK
+ *
+ * Query and manage Shopify stores via GraphQL Admin API with AI agents.
+ *
+ * @example
+ * ```ts
+ * import { ShopifyClient } from "clawpify";
+ *
+ * const client = new ShopifyClient({
+ *   storeUrl: "my-store.myshopify.com",
+ *   accessToken: "shpat_xxxxx",
+ * });
+ *
+ * const { data } = await client.graphql(`{
+ *   products(first: 5) {
+ *     nodes { id title }
+ *   }
+ * }`);
+ * ```
+ *
+ * @example Using the AI agent (requires @anthropic-ai/sdk)
+ * ```ts
+ * import { ShopifyClient } from "clawpify";
+ * import { ShopifyAgent } from "clawpify/agent";
+ * import { loadSkills } from "clawpify/skills";
+ *
+ * const client = new ShopifyClient({ storeUrl, accessToken });
+ * const skills = await loadSkills();
+ * const agent = new ShopifyAgent({ shopify: client, skillContent: skills });
+ *
+ * const result = await agent.chat("List my products");
+ * console.log(result.response);
+ * ```
+ */
+export { ShopifyClient, createShopifyClient } from "./shopify";
+export { createAuthenticatedConfig, getAccessToken, type AccessTokenResponse, type ClientCredentialsConfig, } from "./auth";
+export { ShopifyAgent } from "./agent";
+export { loadSkills } from "./skills";
+export type { ShopifyClientConfig, GraphQLResponse } from "./shopify";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGtC,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  ShopifyAgent
+} from "./agent.js";
+import {
+  ShopifyClient,
+  createShopifyClient
+} from "./shopify.js";
+import {
+  createAuthenticatedConfig,
+  getAccessToken
+} from "./auth.js";
+import {
+  loadSkills
+} from "./skills.js";
+export {
+  loadSkills,
+  getAccessToken,
+  createShopifyClient,
+  createAuthenticatedConfig,
+  ShopifyClient,
+  ShopifyAgent
+};

package/dist/mcp-server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":""}