@open-neko/plugin-shopify 0.1.0

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC"}

package/dist/shopify-client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Thin HTTP wrapper for Shopify's Admin REST API. All network calls
+ * go through `fetchImpl` for testability — the production runtime
+ * uses globalThis.fetch; tests inject a stub.
+ *
+ * Shopify's API is per-store; the storeDomain in the config is the
+ * canonical *.myshopify.com host (NOT the custom storefront domain
+ * the operator may have configured for shoppers).
+ *
+ * Pinned API version: Shopify rotates quarterly. We default to
+ * "2026-01" — operators can override via SHOPIFY_API_VERSION when
+ * Shopify deprecates that version.
+ */
+export declare const DEFAULT_API_VERSION = "2026-01";
+export interface ShopifyClientConfig {
+    /** Canonical *.myshopify.com domain — no scheme. */
+    storeDomain: string;
+    accessToken: string;
+    apiVersion?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ShopifyOrderSummary {
+    id: number;
+    name: string;
+    order_number: number;
+    email: string | null;
+    financial_status: string | null;
+    fulfillment_status: string | null;
+    total_price: string;
+    currency: string;
+    created_at: string;
+    updated_at: string;
+    tags: string;
+    note: string | null;
+}
+export interface ShopifyOrderDetail extends ShopifyOrderSummary {
+    customer: {
+        id: number;
+        email: string | null;
+        first_name: string | null;
+        last_name: string | null;
+    } | null;
+    line_items: Array<{
+        id: number;
+        title: string;
+        quantity: number;
+        sku: string | null;
+        price: string;
+    }>;
+    shipping_address: Record<string, unknown> | null;
+    billing_address: Record<string, unknown> | null;
+    refunds: Array<Record<string, unknown>>;
+}
+export interface ListOrdersParams {
+    /** ISO timestamp lower bound on created_at. */
+    createdAtMin?: string;
+    /** ISO timestamp upper bound on created_at. */
+    createdAtMax?: string;
+    /** "any" | "authorized" | "pending" | "paid" | "partially_paid" | "refunded" | "voided" | "partially_refunded" | "unpaid" */
+    financialStatus?: string;
+    /** "shipped" | "partial" | "unshipped" | "any" | "unfulfilled" */
+    fulfillmentStatus?: string;
+    /** 1-250 (Shopify max). Default 50. */
+    limit?: number;
+    /** "open" | "closed" | "cancelled" | "any". Default "open". */
+    status?: string;
+}
+export interface UpdateOrderNoteParams {
+    orderId: number;
+    note: string;
+    /** When true, append " — <note>" to the existing note instead of replacing. */
+    append?: boolean;
+    /** Optional tags to add (comma-joined). */
+    addTags?: string[];
+}
+export declare class ShopifyClient {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly apiVersion;
+    constructor(cfg: ShopifyClientConfig);
+    private url;
+    private headers;
+    listOrders(params?: ListOrdersParams): Promise<{
+        orders: ShopifyOrderSummary[];
+    }>;
+    getOrder(orderId: number): Promise<{
+        order: ShopifyOrderDetail;
+    }>;
+    /**
+     * Append-or-replace the note + optionally add tags. Shopify's PUT
+     * order endpoint is field-by-field PATCH semantics: only the keys
+     * you pass change.
+     */
+    updateOrderNote(params: UpdateOrderNoteParams): Promise<{
+        order: ShopifyOrderDetail;
+    }>;
+}
+//# sourceMappingURL=shopify-client.d.ts.map

package/dist/shopify-client.d.ts.map

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

package/dist/shopify-client.js

@@ -0,0 +1,113 @@
+/**
+ * Thin HTTP wrapper for Shopify's Admin REST API. All network calls
+ * go through `fetchImpl` for testability — the production runtime
+ * uses globalThis.fetch; tests inject a stub.
+ *
+ * Shopify's API is per-store; the storeDomain in the config is the
+ * canonical *.myshopify.com host (NOT the custom storefront domain
+ * the operator may have configured for shoppers).
+ *
+ * Pinned API version: Shopify rotates quarterly. We default to
+ * "2026-01" — operators can override via SHOPIFY_API_VERSION when
+ * Shopify deprecates that version.
+ */
+export const DEFAULT_API_VERSION = "2026-01";
+export class ShopifyClient {
+    cfg;
+    fetchImpl;
+    apiVersion;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch;
+        this.apiVersion = cfg.apiVersion ?? DEFAULT_API_VERSION;
+    }
+    url(path) {
+        return `https://${this.cfg.storeDomain}/admin/api/${this.apiVersion}/${path}`;
+    }
+    headers(extra = {}) {
+        return {
+            "X-Shopify-Access-Token": this.cfg.accessToken,
+            Accept: "application/json",
+            ...extra,
+        };
+    }
+    async listOrders(params = {}) {
+        const u = new URL(this.url("orders.json"));
+        u.searchParams.set("limit", String(clampInt(params.limit ?? 50, 1, 250)));
+        u.searchParams.set("status", params.status ?? "open");
+        if (params.financialStatus)
+            u.searchParams.set("financial_status", params.financialStatus);
+        if (params.fulfillmentStatus)
+            u.searchParams.set("fulfillment_status", params.fulfillmentStatus);
+        if (params.createdAtMin)
+            u.searchParams.set("created_at_min", params.createdAtMin);
+        if (params.createdAtMax)
+            u.searchParams.set("created_at_max", params.createdAtMax);
+        const res = await this.fetchImpl(u.toString(), { headers: this.headers() });
+        if (!res.ok)
+            throw await shopifyError(res, "list_shopify_orders");
+        return (await res.json());
+    }
+    async getOrder(orderId) {
+        const res = await this.fetchImpl(this.url(`orders/${orderId}.json`), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw await shopifyError(res, "get_shopify_order");
+        return (await res.json());
+    }
+    /**
+     * Append-or-replace the note + optionally add tags. Shopify's PUT
+     * order endpoint is field-by-field PATCH semantics: only the keys
+     * you pass change.
+     */
+    async updateOrderNote(params) {
+        let nextNote = params.note;
+        let nextTags;
+        if (params.append || params.addTags?.length) {
+            // Need the current state to append safely. Fetch once.
+            const current = await this.getOrder(params.orderId);
+            if (params.append) {
+                const existing = current.order.note ?? "";
+                nextNote = existing ? `${existing} — ${params.note}` : params.note;
+            }
+            if (params.addTags?.length) {
+                const existingTags = (current.order.tags ?? "")
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                const merged = new Set(existingTags);
+                for (const t of params.addTags)
+                    merged.add(t);
+                nextTags = [...merged].join(", ");
+            }
+        }
+        const body = { id: params.orderId, note: nextNote };
+        if (nextTags !== undefined)
+            body.tags = nextTags;
+        const res = await this.fetchImpl(this.url(`orders/${params.orderId}.json`), {
+            method: "PUT",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify({ order: body }),
+        });
+        if (!res.ok)
+            throw await shopifyError(res, "update_shopify_order_note");
+        return (await res.json());
+    }
+}
+function clampInt(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}
+async function shopifyError(res, action) {
+    let body = "";
+    try {
+        body = await res.text();
+    }
+    catch {
+        /* ignore */
+    }
+    return new Error(`${action} failed (HTTP ${res.status}): ${body || res.statusText}`);
+}
+//# sourceMappingURL=shopify-client.js.map

package/dist/shopify-client.js.map

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

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@open-neko/plugin-shopify",
+  "version": "0.1.0",
+  "description": "Shopify Admin API connector for OpenNeko — list orders, fetch order detail, and update internal order notes against an operator's store. Three sandboxed actions: list_shopify_orders, get_shopify_order, update_shopify_order_note. Network egress limited to the operator's *.myshopify.com host.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-neko/plugins.git",
+    "directory": "packages/shopify"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "skill"
+  ],
+  "openneko": {
+    "runner": "./dist/run.js",
+    "skill": "./skill",
+    "permissions": {
+      "network": [
+        "*.myshopify.com"
+      ],
+      "env": [
+        {
+          "key": "SHOPIFY_STORE_DOMAIN",
+          "required": true,
+          "secret": false,
+          "description": "Your store's permanent myshopify.com subdomain — e.g. acme.myshopify.com. Use the .myshopify.com domain even if you've configured a custom storefront domain; the Admin API only honors the canonical one."
+        },
+        {
+          "key": "SHOPIFY_ACCESS_TOKEN",
+          "required": true,
+          "secret": true,
+          "description": "Shopify Admin API access token (starts with shpat_). Create at admin → Settings → Apps and sales channels → Develop apps → Create an app → Configuration → Admin API access scopes. Needs read_orders + write_orders. Token is shown ONCE on install — copy it immediately."
+        },
+        {
+          "key": "SHOPIFY_API_VERSION",
+          "required": false,
+          "secret": false,
+          "description": "Shopify Admin API version to pin (defaults to 2026-01). Shopify rotates quarterly; pin a stable version to avoid surprise breakage."
+        }
+      ]
+    },
+    "capabilities": {
+      "action": {
+        "kinds": [
+          {
+            "kind": "list_shopify_orders",
+            "description": "List recent orders, optionally filtered by financialStatus, fulfillmentStatus, or a date range (createdAtMin/createdAtMax).",
+            "default_mode": "auto",
+            "example": {
+              "financialStatus": "paid",
+              "createdAtMin": "2026-05-01T00:00:00Z",
+              "limit": 20
+            }
+          },
+          {
+            "kind": "get_shopify_order",
+            "description": "Fetch full detail for one order by id — line items, customer, addresses, refunds, tags.",
+            "default_mode": "auto",
+            "example": {
+              "orderId": 1234567890
+            }
+          },
+          {
+            "kind": "update_shopify_order_note",
+            "description": "Set or append the internal note on an order (user-visible in Shopify admin only; not customer-facing).",
+            "default_mode": "ask",
+            "example": {
+              "orderId": 1234567890,
+              "note": "Flagged for review by ops.",
+              "append": true
+            }
+          }
+        ]
+      }
+    }
+  },
+  "dependencies": {
+    "@open-neko/plugin-types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: shopify
+description: Patterns for the @open-neko/plugin-shopify actions — when to use list_shopify_orders vs get_shopify_order, how to filter for a specific operations question, and how to log internal context via update_shopify_order_note. Use whenever the operator's question is about orders flowing through their Shopify store (revenue checks, fulfillment status, customer service follow-ups, ops tagging). Assumes SHOPIFY_STORE_DOMAIN and SHOPIFY_ACCESS_TOKEN are configured.
+license: Apache-2.0
+metadata:
+  authoredBy: open-neko
+  pairsWith: "@open-neko/plugin-shopify"
+---
+
+# Shopify patterns
+
+Shopify is OpenNeko's reference ecommerce connector. Most operator
+questions fall into one of three shapes:
+
+| Operator says | Right action | Why |
+|---|---|---|
+| "What's happened in the last hour?" | `list_shopify_orders` with `createdAtMin` set to T-1h | Bounded read, server-side filter |
+| "Pull up order #1234" | `get_shopify_order` with the parsed number | Single-record fetch, full detail |
+| "Mark this order as 'priority shipping' and tell ops we noticed" | `update_shopify_order_note` with `append: true` and `addTags: ["priority"]` | One write, preserves prior state |
+
+## Identifying an order from operator input
+
+Operators usually paste either:
+
+- `#1234` — Shopify's display name. The numeric part after `#` is
+  `order_number`, NOT `id`. The plugin's actions need `id` (the
+  internal numeric identifier).
+- `https://acme.myshopify.com/admin/orders/4567890123456` — the
+  number in the URL IS `id`. Use it directly.
+- A bare integer the operator says is "order 4567890123456" — same.
+
+If the operator gives you `#1234`, run a `list_shopify_orders` with
+no filter and `limit: 50`, then match against `order_number`. Don't
+guess.
+
+## `list_shopify_orders` patterns
+
+### Filter server-side, always
+
+Default `status: "open"` keeps you off completed/archived orders.
+Override only when the operator's question explicitly includes
+them ("how many cancellations did we get yesterday?" → `status:
+"cancelled"`).
+
+Three commonly useful filter combos:
+
+- **"What's stuck?"** → `fulfillmentStatus: "unfulfilled"`, `financialStatus: "paid"`
+- **"What needs payment chasing?"** → `financialStatus: "pending"`
+- **"What landed today?"** → `createdAtMin` set to today's midnight in the store's timezone
+
+### Page size
+
+Default 50; cap at 250 (Shopify's max per call). Bigger pages are
+slower and ALL of the payload comes through the agent's context. For
+"show me the last 10" requests, set `limit: 10`.
+
+### Time zones matter
+
+Shopify returns ISO timestamps in UTC. The operator usually thinks
+in their own timezone. If the question is "what happened today?",
+the agent should convert the operator's local "today" to a UTC
+ISO range before passing to `createdAtMin`/`createdAtMax`. Don't
+ask Shopify to filter on a calendar day in the wrong timezone.
+
+## `update_shopify_order_note` patterns
+
+This is the only write action in this plugin, and it's deliberately
+low-blast-radius: the `note` field is operator-visible inside the
+Shopify admin only, never customer-facing.
+
+### Always prefer `append: true` for ops logging
+
+```
+note: "OpenNeko revenue-drop watcher pinged @amit at 14:03"
+append: true
+```
+
+Operators rely on the note as a running log. Replacing it wipes
+their history. The only time to omit `append` is when the operator
+explicitly says "replace the note with…".
+
+### Pair with tags for filterable ops state
+
+```
+addTags: ["needs-review", "noticed-by-openneko"]
+```
+
+Tags ARE searchable in Shopify admin's order list, notes aren't.
+Adding a tag like `"noticed-by-openneko"` lets the operator pull
+"show me everything OpenNeko flagged this week" later.
+
+## Failure modes the operator should see
+
+- **`401 Unauthorized`** — `SHOPIFY_ACCESS_TOKEN` expired or scope
+  insufficient. Prompt the operator to regenerate the token with
+  read_orders + write_orders.
+- **`404 Not Found`** on an order id — usually the operator gave you
+  the `order_number` (#1234) instead of the `id`. Re-run `list` to
+  resolve.
+- **`429 Too Many Requests`** — Shopify rate limits per app per
+  store (2 req/sec leaky bucket on REST). Back off; if the operator
+  is waiting, surface the Retry-After header so they know how long.
+- **`Invalid SHOPIFY_STORE_DOMAIN`** — the plugin rejects domains
+  that aren't `*.myshopify.com`. Custom storefront domains don't
+  work on the Admin API.
+
+## What this skill is NOT for
+
+- Storefront product browsing — that's the public Storefront API,
+  a different scope set, and this connector doesn't enable it.
+- Customer-facing email — Shopify can send transactional emails;
+  this connector doesn't trigger them. Use the operator's
+  email/Gmail connector for that.
+- Bulk migrations — Shopify's REST API caps you at ~2 req/sec.
+  For >1000 changes, point the operator at Shopify's bulk operations
+  GraphQL endpoint, not this plugin.