@yawlabs/lemonsqueezy-mcp 0.5.0 → 0.6.1

package/README.md

@@ -174,9 +174,9 @@ All configuration is via environment variables. Only `LEMONSQUEEZY_API_KEY` (or
 | --- | --- |
 | `LEMONSQUEEZY_API_KEY` | LemonSqueezy API token. |
 | `LEMONSQUEEZY_API_KEY_COMMAND` | Command whose stdout produces the API key. Overrides `LEMONSQUEEZY_API_KEY`. Output is cached for 1 hour. Use this to pull short-lived credentials from a vault (`op read`, `gcloud secrets versions access`, etc.) without writing them to env vars. |
-| `LEMONSQUEEZY_ALLOWED_STORE_IDS` | Comma-separated allowlist of store IDs. When set, tools that receive a `storeId` input reject calls to any other store. Note: operations that don't take an explicit `storeId` (e.g. `ls_refund_order`) are not gated by this — pair with `LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS`. |
+| `LEMONSQUEEZY_ALLOWED_STORE_IDS` | Comma-separated allowlist of store IDs. When set: (1) any tool whose input includes a `storeId` rejects calls to a non-allowed store; (2) tools that *accept* a `storeId` filter (e.g. `ls_list_orders`, `ls_list_subscriptions`) require it — calls without one are blocked so a missing filter cannot return data from every store the API key can see. Tools with no `storeId` field at all (e.g. `ls_refund_order`, `ls_list_stores`) are not gated by this — pair with `LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS` and `LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT`. |
 | `LEMONSQUEEZY_MAX_REFUND_AMOUNT_CENTS` | Rejects `ls_refund_order` and `ls_refund_subscription_invoice` calls above this amount. |
-| `LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT` | Max destructive tool calls per 60-second rolling window. In-process limit — per MCP server instance, not global. |
+| `LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT` | Max destructive tool calls per 60-second rolling window. In-process limit — per MCP server instance, not global; each `npx` cold start resets the window. Counts include `ls_update_license_key` calls that set `disabled: true`. |
 | `LEMONSQUEEZY_LOG=json` | Emit one JSON log line to stderr per tool and HTTP call. Destructive calls are tagged `audit: true` and include their inputs. |
 
 ### Logging format
@@ -214,6 +214,23 @@ npm test                  # full unit + handler suite
 npm run test:integration  # requires LEMONSQUEEZY_TEST_API_KEY + LEMONSQUEEZY_TEST_STORE_ID
 ```
 
+## Releasing
+
+Releases are cut locally — there is no CI pipeline. From a clean checkout of `main`:
+
+```bash
+./release.sh 0.6.0
+```
+
+The script lints, tests, builds, bumps the version, commits and tags, pushes to `origin`, publishes to npm, and creates a GitHub release. Each step is idempotent — re-running with the same version after a partial failure resumes from where it stopped.
+
+One-time setup on the release machine:
+
+```bash
+npm login --auth-type=web   # publisher of @yawlabs/lemonsqueezy-mcp
+gh auth login               # GitHub CLI for the release-creation step
+```
+
 ## License
 
 MIT

package/dist/index.js

@@ -30176,6 +30176,24 @@ function checkDestructiveRateLimit(now = Date.now()) {
   }
   destructiveTimestamps.push(now);
 }
+function isStoreAllowlistActive() {
+  return loadOptions().allowedStoreIds !== null;
+}
+function checkStoreScopedToolInput(toolAcceptsStoreId, input) {
+  if (!toolAcceptsStoreId) return;
+  const raw = input.storeId;
+  if (raw !== void 0 && raw !== null && raw !== "") {
+    checkStoreAllowed(String(raw));
+    return;
+  }
+  if (isStoreAllowlistActive()) {
+    throw new GuardrailError("storeId is required when LEMONSQUEEZY_ALLOWED_STORE_IDS is set");
+  }
+}
+function isDestructiveCall(tool, input) {
+  if (typeof tool.isDestructive === "function") return tool.isDestructive(input);
+  return tool.annotations?.destructiveHint === true;
+}
 
 // src/logger.ts
 function isEnabled() {
@@ -30186,6 +30204,25 @@ function logEvent(entry) {
   try {
     const line = JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), ...entry });
     process.stderr.write(`${line}
+`);
+    return;
+  } catch {
+  }
+  try {
+    const fallback = JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      event: entry.event,
+      tool: entry.tool,
+      method: entry.method,
+      path: entry.path,
+      status: entry.status,
+      latency_ms: entry.latency_ms,
+      request_id: entry.request_id,
+      audit: entry.audit,
+      error: entry.error,
+      log_error: "inputs_not_serializable"
+    });
+    process.stderr.write(`${fallback}
 `);
   } catch {
   }
@@ -30326,6 +30363,9 @@ async function loadApiKey() {
 
 // src/api.ts
 var BASE_URL = "https://api.lemonsqueezy.com/v1";
+function encodePath(segment) {
+  return encodeURIComponent(String(segment));
+}
 function buildQuery(params) {
   if (!params) return "";
   const parts = [];
@@ -30362,7 +30402,7 @@ async function apiRequest(method, path, body) {
     headers["Content-Type"] = "application/vnd.api+json";
     fetchBody = JSON.stringify(body);
   }
-  const url2 = path.startsWith("http") ? path : `${BASE_URL}${path}`;
+  const url2 = `${BASE_URL}${path}`;
   const idempotent = method === "GET" || method === "DELETE";
   let res;
   try {
@@ -30430,7 +30470,8 @@ async function apiRequest(method, path, body) {
   if (res.status === 204) {
     return { ok: true, status: res.status, requestId };
   }
-  const data = await res.json();
+  const bodyText = await res.text();
+  const data = bodyText.trim() ? JSON.parse(bodyText) : void 0;
   return { ok: true, status: res.status, data, requestId };
 }
 async function licenseRequest(path, body) {
@@ -30518,13 +30559,14 @@ async function licenseRequest(path, body) {
     latency_ms,
     request_id: requestId
   });
-  const data = await res.json();
+  const bodyText = await res.text();
+  const data = bodyText.trim() ? JSON.parse(bodyText) : void 0;
   return { ok: true, status: res.status, data, requestId };
 }
 function getHandler(endpoint, idField) {
   return async (input) => {
     const query = buildQuery({ include: input.include?.split(",") });
-    return apiGet(`${endpoint}/${input[idField]}${query}`);
+    return apiGet(`${endpoint}/${encodePath(input[idField])}${query}`);
   };
 }
 function listHandler(endpoint, filterMap = {}) {
@@ -30662,13 +30704,11 @@ var checkoutTools = [
       const checkoutData = {};
       if (input.email !== void 0) checkoutData.email = input.email;
       if (input.name !== void 0) checkoutData.name = input.name;
-      if (input.billingAddressCountry !== void 0)
-        checkoutData.billing_address = { country: input.billingAddressCountry };
-      if (input.billingAddressZip !== void 0) {
-        checkoutData.billing_address = {
-          ...checkoutData.billing_address || {},
-          zip: input.billingAddressZip
-        };
+      if (input.billingAddressCountry !== void 0 || input.billingAddressZip !== void 0) {
+        const billingAddress = {};
+        if (input.billingAddressCountry !== void 0) billingAddress.country = input.billingAddressCountry;
+        if (input.billingAddressZip !== void 0) billingAddress.zip = input.billingAddressZip;
+        checkoutData.billing_address = billingAddress;
       }
       if (input.taxNumber !== void 0) checkoutData.tax_number = input.taxNumber;
       if (input.discountCode !== void 0) checkoutData.discount_code = input.discountCode;
@@ -30774,6 +30814,12 @@ var customerTools = [
       idempotentHint: true,
       openWorldHint: true
     },
+    // Setting status to "archived" via this tool is the same operation as
+    // ls_archive_customer and must engage the same rate limiter / audit log;
+    // otherwise the dedicated archive tool's destructive flag becomes a side
+    // channel anyone can route around. Other field edits (name, email,
+    // address) stay on the regular path.
+    isDestructive: (input) => input.status === "archived",
     inputSchema: external_exports3.object({
       customerId: external_exports3.string().max(1e4).describe("The customer ID to update"),
       name: external_exports3.string().max(1e4).optional().describe("New name"),
@@ -30791,7 +30837,7 @@ var customerTools = [
       if (input.region !== void 0) attributes.region = input.region;
       if (input.country !== void 0) attributes.country = input.country;
       if (input.status !== void 0) attributes.status = input.status;
-      return apiPatch(`/customers/${input.customerId}`, {
+      return apiPatch(`/customers/${encodePath(input.customerId)}`, {
         data: {
           type: "customers",
           id: input.customerId,
@@ -30806,7 +30852,7 @@ var customerTools = [
     annotations: {
       title: "Archive customer",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -30814,7 +30860,7 @@ var customerTools = [
       customerId: external_exports3.string().max(1e4).describe("The customer ID to archive")
     }),
     handler: async (input) => {
-      return apiPatch(`/customers/${input.customerId}`, {
+      return apiPatch(`/customers/${encodePath(input.customerId)}`, {
         data: {
           type: "customers",
           id: input.customerId,
@@ -30972,7 +31018,7 @@ var discountTools = [
       discountId: external_exports3.string().max(1e4).describe("The discount ID to delete")
     }),
     handler: async (input) => {
-      return apiDelete(`/discounts/${input.discountId}`);
+      return apiDelete(`/discounts/${encodePath(input.discountId)}`);
     }
   }
 ];
@@ -31103,7 +31149,7 @@ var licenseKeyTools = [
   },
   {
     name: "ls_update_license_key",
-    description: "Update a license key's activation limit, expiry date, or disabled status.",
+    description: "Update a license key's activation limit, expiry date, or disabled status. Setting `disabled: true` revokes customer access and is treated as destructive (rate-limited and audited).",
     annotations: {
       title: "Update license key",
       readOnlyHint: false,
@@ -31111,18 +31157,23 @@ var licenseKeyTools = [
       idempotentHint: true,
       openWorldHint: true
     },
+    // Disabling a license key revokes a customer's access. Tag the call as
+    // destructive only when `disabled: true` so the rate limiter and audit log
+    // engage on revocation, while benign edits (expiry, activation limit) stay
+    // on the regular path.
+    isDestructive: (input) => input.disabled === true,
     inputSchema: external_exports3.object({
       licenseKeyId: external_exports3.string().max(1e4).describe("The license key ID to update"),
       activationLimit: external_exports3.number().int().min(0).optional().describe("Maximum number of activations allowed (0 = unlimited)"),
       disabled: external_exports3.boolean().optional().describe("Set to true to disable this license key"),
-      expiresAt: external_exports3.string().max(1e4).optional().describe("Expiry date (ISO 8601 format). Set to null to remove expiry.")
+      expiresAt: external_exports3.string().max(1e4).nullable().optional().describe("Expiry date (ISO 8601 format). Set to null to remove expiry.")
     }),
     handler: async (input) => {
       const attributes = {};
       if (input.activationLimit !== void 0) attributes.activation_limit = input.activationLimit;
       if (input.disabled !== void 0) attributes.disabled = input.disabled;
       if (input.expiresAt !== void 0) attributes.expires_at = input.expiresAt;
-      return apiPatch(`/license-keys/${input.licenseKeyId}`, {
+      return apiPatch(`/license-keys/${encodePath(input.licenseKeyId)}`, {
         data: {
           type: "license-keys",
           id: input.licenseKeyId,
@@ -31312,7 +31363,7 @@ var orderTools = [
       if (input.notes !== void 0) params.set("notes", input.notes);
       if (input.locale !== void 0) params.set("locale", input.locale);
       const qs = params.toString();
-      return apiPost(`/orders/${input.orderId}/generate-invoice${qs ? `?${qs}` : ""}`);
+      return apiPost(`/orders/${encodePath(input.orderId)}/generate-invoice${qs ? `?${qs}` : ""}`);
     }
   },
   {
@@ -31331,7 +31382,7 @@ var orderTools = [
     }),
     handler: async (input) => {
       checkRefundAmount(input.amount);
-      return apiPost(`/orders/${input.orderId}/refund`, {
+      return apiPost(`/orders/${encodePath(input.orderId)}/refund`, {
         data: { type: "orders", id: input.orderId, attributes: { amount: input.amount } }
       });
     }
@@ -31531,7 +31582,9 @@ var subscriptionInvoiceTools = [
       if (input.notes !== void 0) params.set("notes", input.notes);
       if (input.locale !== void 0) params.set("locale", input.locale);
       const qs = params.toString();
-      return apiPost(`/subscription-invoices/${input.subscriptionInvoiceId}/generate-invoice${qs ? `?${qs}` : ""}`);
+      return apiPost(
+        `/subscription-invoices/${encodePath(input.subscriptionInvoiceId)}/generate-invoice${qs ? `?${qs}` : ""}`
+      );
     }
   },
   {
@@ -31550,7 +31603,7 @@ var subscriptionInvoiceTools = [
     }),
     handler: async (input) => {
       checkRefundAmount(input.amount);
-      return apiPost(`/subscription-invoices/${input.subscriptionInvoiceId}/refund`, {
+      return apiPost(`/subscription-invoices/${encodePath(input.subscriptionInvoiceId)}/refund`, {
         data: {
           type: "subscription-invoices",
           id: input.subscriptionInvoiceId,
@@ -31604,7 +31657,7 @@ var subscriptionItemTools = [
     annotations: {
       title: "Update subscription item",
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: true,
       openWorldHint: true
     },
@@ -31613,7 +31666,7 @@ var subscriptionItemTools = [
       quantity: external_exports3.number().int().min(1).describe("New quantity for the subscription item")
     }),
     handler: async (input) => {
-      return apiPatch(`/subscription-items/${input.subscriptionItemId}`, {
+      return apiPatch(`/subscription-items/${encodePath(input.subscriptionItemId)}`, {
         data: {
           type: "subscription-items",
           id: input.subscriptionItemId,
@@ -31636,7 +31689,7 @@ var subscriptionItemTools = [
       subscriptionItemId: external_exports3.string().max(1e4).describe("The subscription item ID")
     }),
     handler: async (input) => {
-      return apiGet(`/subscription-items/${input.subscriptionItemId}/current-usage`);
+      return apiGet(`/subscription-items/${encodePath(input.subscriptionItemId)}/current-usage`);
     }
   }
 ];
@@ -31705,9 +31758,20 @@ var subscriptionTools = [
       idempotentHint: true,
       openWorldHint: true
     },
+    // A pause (void/free) or plan switch is the customer-impacting subset of
+    // this tool's surface; treat those calls as destructive so they engage
+    // the rate limiter and audit log. Intentional exclusions, all of which
+    // either reverse a destructive action or are billing-neutral:
+    //   - pause === "resume"        un-pause, restoring access
+    //   - cancelled === false       un-cancel before expiry, restoring access
+    //   - billingAnchor             changes anchor day, no immediate charge
+    //   - trialEndsAt               extending or ending a trial
+    //   - invoiceImmediately        toggle on the next prorated edit
+    //   - disableProrations         toggle on plan-change behavior
+    isDestructive: (input) => typeof input.pause === "string" && input.pause !== "resume" || typeof input.variantId === "string",
     inputSchema: external_exports3.object({
       subscriptionId: external_exports3.string().max(1e4).describe("The subscription ID to update"),
-      variantId: external_exports3.string().max(1e4).optional().describe("New variant ID for plan switching"),
+      variantId: external_exports3.string().max(1e4).regex(/^[1-9]\d*$/, "variantId must be a positive integer string (e.g. '12345')").optional().describe("New variant ID for plan switching"),
       pause: external_exports3.enum(["void", "free", "resume"]).optional().describe("Pause mode: 'void' (pause, skip billing), 'free' (pause, keep access free), or 'resume' to unpause"),
       cancelled: external_exports3.literal(false).optional().describe(
         "Set to false to un-cancel a subscription before it expires. To cancel, use ls_cancel_subscription instead."
@@ -31726,7 +31790,7 @@ var subscriptionTools = [
       if (input.invoiceImmediately !== void 0) attributes.invoice_immediately = input.invoiceImmediately;
       if (input.disableProrations !== void 0) attributes.disable_prorations = input.disableProrations;
       if (input.trialEndsAt !== void 0) attributes.trial_ends_at = input.trialEndsAt;
-      return apiPatch(`/subscriptions/${input.subscriptionId}`, {
+      return apiPatch(`/subscriptions/${encodePath(input.subscriptionId)}`, {
         data: {
           type: "subscriptions",
           id: input.subscriptionId,
@@ -31749,7 +31813,7 @@ var subscriptionTools = [
       subscriptionId: external_exports3.string().max(1e4).describe("The subscription ID to cancel")
     }),
     handler: async (input) => {
-      return apiDelete(`/subscriptions/${input.subscriptionId}`);
+      return apiDelete(`/subscriptions/${encodePath(input.subscriptionId)}`);
     }
   }
 ];
@@ -31796,7 +31860,10 @@ var usageRecordTools = [
     annotations: {
       title: "Create usage record",
       readOnlyHint: false,
-      destructiveHint: false,
+      // Usage records feed the meter that determines the customer's bill --
+      // 'increment' adds to current usage, 'set' overwrites it. Either mode
+      // moves real money, so engage the rate limiter and audit log.
+      destructiveHint: true,
       idempotentHint: false,
       openWorldHint: true
     },
@@ -31973,7 +32040,7 @@ var webhookTools = [
       if (input.url !== void 0) attributes.url = input.url;
       if (input.events !== void 0) attributes.events = input.events;
       if (input.secret !== void 0) attributes.secret = input.secret;
-      return apiPatch(`/webhooks/${input.webhookId}`, {
+      return apiPatch(`/webhooks/${encodePath(input.webhookId)}`, {
         data: {
           type: "webhooks",
           id: input.webhookId,
@@ -31996,13 +32063,13 @@ var webhookTools = [
       webhookId: external_exports3.string().max(1e4).describe("The webhook ID to delete")
     }),
     handler: async (input) => {
-      return apiDelete(`/webhooks/${input.webhookId}`);
+      return apiDelete(`/webhooks/${encodePath(input.webhookId)}`);
     }
   }
 ];
 
 // src/index.ts
-var version2 = true ? "0.5.0" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.6.1" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -32036,18 +32103,18 @@ var server = new McpServer({
   version: version2
 });
 for (const tool of allTools) {
-  const isDestructive = tool.annotations?.destructiveHint === true;
+  const toolAcceptsStoreId = "storeId" in tool.inputSchema.shape;
   server.tool(
     tool.name,
     tool.description,
     tool.inputSchema.shape,
     tool.annotations,
     async (input) => {
+      const isDestructive = isDestructiveCall(tool, input);
       const start = Date.now();
       try {
         if (isDestructive) checkDestructiveRateLimit();
-        const storeId = input.storeId;
-        if (typeof storeId === "string") checkStoreAllowed(storeId);
+        checkStoreScopedToolInput(toolAcceptsStoreId, input);
         const result = await tool.handler(input);
         const response = result;
         const latency_ms = Date.now() - start;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/lemonsqueezy-mcp",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "LemonSqueezy MCP server for managing your store from AI assistants",
   "license": "MIT",
   "author": "YawLabs <contact@yaw.sh>",
@@ -31,11 +31,10 @@
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "test": "npm run build && node --test dist/**/*.test.js",
-    "test:ci": "npm run test",
     "test:integration": "npm run build && node --test dist/integration/*.test.js",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
-    "prepublishOnly": "npm run build && node --test dist/**/*.test.js"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {},
   "overrides": {
@@ -50,6 +49,6 @@
     "zod": "^4.3.6"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }