@clawpify/skills 1.0.4 → 1.0.6

package/clawpify/SKILL.md

@@ -1,134 +1,36 @@
 ---
 name: clawpify
 description: Query and manage Shopify stores via GraphQL Admin API. Use for products, orders, customers, inventory, discounts, and all Shopify data operations.
-dependencies:
-  - Tool: shopify_graphql (from MCP server or custom function)
 ---
 
 # Shopify GraphQL Admin API
 
-A comprehensive skill for interacting with Shopify's GraphQL Admin API. This skill enables Claude to query and manage all aspects of Shopify store data.
-
-## When to Use This Skill
-
-Use this skill when the user asks about:
-- Products (list, search, create, update, delete)
-- Orders (view, cancel, fulfill)
-- Customers (list, create, update)
-- Inventory (check levels, adjust quantities)
-- Discounts (create codes, manage promotions)
-- Any other Shopify store operations
-
-## Critical Operations Requiring Permission
-
-IMPORTANT: Before executing any of the following operations, you MUST ask for explicit user permission:
-
-- Refunds: Create refunds (permanent financial transactions)
-- Order Cancellations: Cancel orders (may trigger refunds)
-- Gift Card Deactivation: Permanently disable gift cards
-- Inventory Adjustments: Modify stock levels
-- Product Deletions: Permanently remove products
-- Discount Activations: Change pricing for customers
-
-Always show what will be changed and wait for user confirmation.
-
 ## How to Use
 
-1. Use the `shopify_graphql` tool to execute queries
-2. Check for `errors` (GraphQL issues) and `userErrors` (validation issues)
-3. Use pagination with `first`/`after` for large result sets
+1. Use `load_skill_reference` to load the relevant reference FIRST
+2. Use `shopify_graphql` to execute queries based on the loaded reference
+3. Check for `errors` and `userErrors` in responses
 4. Format all IDs as: `gid://shopify/Resource/123`
 
-## Available References
-
-For detailed patterns and examples, refer to the reference documents:
-- products.md - Products and variants management
-- orders.md - Order operations
-- customers.md - Customer management
-- inventory.md - Inventory and locations
-- discounts.md - Discount codes and promotions
-- collections.md - Product collections
-- fulfillments.md - Order fulfillment and shipping
-- refunds.md - Process refunds
-- draft-orders.md - Draft order creation
-- gift-cards.md - Gift card management
-- webhooks.md - Event subscriptions
-- locations.md - Store locations
-- marketing.md - Marketing activities
-- markets.md - Multi-market setup
-- menus.md - Navigation menus
-- metafields.md - Custom data fields
-- pages.md - Store pages
-- blogs.md - Blog management
-- files.md - File uploads
-- shipping.md - Shipping configuration
-- shop.md - Store information
-- subscriptions.md - Subscription management
-- translations.md - Content translations
-- segments.md - Customer segments
-- bulk-operations.md - Bulk data operations
-
-## Quick Examples
-
-### List Recent Orders
-```graphql
-query {
-  orders(first: 10, sortKey: CREATED_AT, reverse: true) {
-    nodes {
-      id
-      name
-      totalPriceSet {
-        shopMoney { amount currencyCode }
-      }
-      customer { displayName }
-    }
-  }
-}
-```
-
-### Search Products
-```graphql
-query {
-  products(first: 10, query: "title:*shirt* AND status:ACTIVE") {
-    nodes {
-      id
-      title
-      status
-    }
-  }
-}
-```
+## Critical Operations Requiring Permission
 
-### Check Inventory
-```graphql
-query GetInventory($id: ID!) {
-  inventoryItem(id: $id) {
-    id
-    inventoryLevels(first: 5) {
-      nodes {
-        quantities(names: ["available"]) {
-          name
-          quantity
-        }
-        location { name }
-      }
-    }
-  }
-}
-```
+IMPORTANT: Before executing any of the following, you MUST ask for explicit user permission:
 
-## Error Handling
+- Refunds, order cancellations, gift card deactivation
+- Inventory adjustments, product deletions, discount activations
 
-Always check responses:
-- `errors` array = GraphQL syntax issues
-- `userErrors` in mutations = validation problems
+Always show what will be changed and wait for confirmation.
 
-## Best Practices
+## Available References
 
-1. Request only needed fields to optimize response size
-2. Use pagination for lists that may grow
-3. Check userErrors in all mutation responses
-4. Ask permission before dangerous operations
-5. Format results clearly for the user
-6. Use bulk operations for large data exports/imports
-7. Handle rate limits with exponential backoff
+Load the reference for your domain using `load_skill_reference` before writing queries:
+
+**Store**: [shop](reference/shop.md) | [locations](reference/locations.md) | [markets](reference/markets.md)
+**Catalog**: [products](reference/products.md) | [collections](reference/collections.md) | [inventory](reference/inventory.md)
+**Sales**: [orders](reference/orders.md) | [draft-orders](reference/draft-orders.md) | [fulfillments](reference/fulfillments.md) | [refunds](reference/refunds.md)
+**Customers**: [customers](reference/customers.md) | [segments](reference/segments.md) | [gift-cards](reference/gift-cards.md)
+**Pricing**: [discounts](reference/discounts.md) | [subscriptions](reference/subscriptions.md)
+**Content**: [pages](reference/pages.md) | [blogs](reference/blogs.md) | [menus](reference/menus.md) | [translations](reference/translations.md) | [files](reference/files.md)
+**Custom data**: [metafields](reference/metafields.md)
+**Automation**: [webhooks](reference/webhooks.md) | [bulk-operations](reference/bulk-operations.md)
+**Growth**: [marketing](reference/marketing.md) | [shipping](reference/shipping.md)

package/dist/agent.d.ts

@@ -1,18 +1,148 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { ShopifyClient } from "./shopify";
+import type { MemoryStore } from "./memory";
+/** Accumulated token usage and estimated cost for a single chat() call. */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    /** Estimated USD cost based on the configured pricing. */
+    totalCost: number;
+}
+/** Per-model pricing in USD per million tokens. */
+export interface ModelPricing {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    cacheWritePerMillion: number;
+    cacheReadPerMillion: number;
+}
+/** A user-provided tool + handler that extends the agent's capabilities. */
+export interface AgentPlugin {
+    tool: Anthropic.Tool;
+    handler: (input: Record<string, any>) => Promise<string>;
+}
+/** Lifecycle hooks for observability and custom behavior. */
+export interface AgentHooks {
+    /** Fires before a chat request is processed. */
+    onRequest?: (message: string, history: Anthropic.MessageParam[]) => void | Promise<void>;
+    /** Fires before each Anthropic API call (including retries in the loop). */
+    onApiCall?: (params: {
+        model: string;
+        messages: Anthropic.MessageParam[];
+        tools: Anthropic.Tool[];
+    }) => void | Promise<void>;
+    /** Fires before a tool handler is executed. */
+    onToolCall?: (toolName: string, input: Record<string, any>) => void | Promise<void>;
+    /** Fires after a tool handler returns. */
+    onToolResult?: (toolName: string, result: string, isError: boolean) => void | Promise<void>;
+    /** Fires after the final text response is assembled. */
+    onResponse?: (response: string, usage: TokenUsage) => void | Promise<void>;
+    /** Fires when an error is caught during the chat loop. */
+    onError?: (error: Error) => void | Promise<void>;
+}
+/** Extended thinking configuration. */
+export interface ThinkingConfig {
+    /** Token budget for thinking. Must be >= 1024. */
+    budgetTokens: number;
+}
+/** Full configuration accepted by the ShopifyAgent constructor. */
+export interface AgentConfig {
+    shopify: ShopifyClient;
+    skillContent: string;
+    model?: string;
+    /** Override the default system instruction sent to the model. */
+    systemInstruction?: string;
+    /** Override default Claude Sonnet pricing. */
+    pricing?: ModelPricing;
+    /** Register plugins at construction time. */
+    plugins?: AgentPlugin[];
+    /** Lifecycle hooks for observability. */
+    hooks?: AgentHooks;
+    /** Enable extended thinking so the model plans before executing. */
+    thinking?: ThinkingConfig;
+    /** Maximum tool-use loop iterations before the agent stops. Defaults to 20. */
+    maxIterations?: number;
+    /** Persistent memory store for conversation history across sessions. */
+    memory?: MemoryStore;
+}
+/** Return value of a single chat() invocation. */
+export interface ChatResult {
+    response: string;
+    history: Anthropic.MessageParam[];
+    usage: TokenUsage;
+    /** Concatenated thinking text when extended thinking is enabled. */
+    thinking?: string;
+    /** Number of tool-use loop iterations used in this call. */
+    iterationsUsed: number;
+}
+/** Events yielded by chatStream(). */
+export type StreamEvent = {
+    type: "thinking";
+    text: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_call";
+    name: string;
+    input: Record<string, any>;
+} | {
+    type: "tool_result";
+    name: string;
+    result: string;
+    isError: boolean;
+} | {
+    type: "done";
+    response: string;
+    thinking?: string;
+    usage: TokenUsage;
+    iterationsUsed: number;
+    history: Anthropic.MessageParam[];
+};
+export declare const DEFAULT_SYSTEM_INSTRUCTION = "You're Clawpify. You help run a Shopify store. The merchant texts you to get stuff done";
 export declare class ShopifyAgent {
     private anthropic;
     private shopify;
     private skillContent;
+    private systemInstruction;
     private model;
-    constructor(config: {
-        shopify: ShopifyClient;
-        skillContent: string;
-        model?: string;
-    });
-    chat(userMessage: string, conversationHistory?: Anthropic.MessageParam[]): Promise<{
-        response: string;
-        history: Anthropic.MessageParam[];
-    }>;
+    private pricing;
+    private plugins;
+    private hooks;
+    private thinkingConfig;
+    private maxIterations;
+    private memory;
+    constructor(config: AgentConfig);
+    /** Register a plugin at runtime. Throws if a tool with the same name already exists. */
+    registerPlugin(plugin: AgentPlugin): void;
+    /** Build the system prompt array with prompt caching. */
+    private buildSystemPrompt;
+    /** Build the tools list with cache_control on the last tool. */
+    private buildTools;
+    /** Compute max_tokens accounting for thinking budget. */
+    private getMaxTokens;
+    /** Build optional thinking param for the API call. */
+    private getThinkingParam;
+    /** Execute a single tool call by name. Returns content and error flag. */
+    private executeTool;
+    /** Process all tool_use blocks from a response, returning tool results. */
+    private processToolCalls;
+    /**
+     * Send a message and get a complete response (non-streaming).
+     * Runs the agentic tool-use loop until the model produces a final text response.
+     */
+    chat(userMessage: string, conversationHistory?: Anthropic.MessageParam[]): Promise<ChatResult>;
+    /**
+     * Send a message and stream the response as typed events.
+     * Same agentic loop as chat() but yields incremental text/thinking deltas.
+     */
+    chatStream(userMessage: string, conversationHistory?: Anthropic.MessageParam[]): AsyncGenerator<StreamEvent>;
+    /**
+     * Chat with automatic session memory.
+     * Loads conversation history from the memory store, runs chat(), and saves
+     * the updated history back. Requires a MemoryStore to be configured.
+     */
+    chatWithMemory(sessionId: string, userMessage: string): Promise<ChatResult>;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}