@yawlabs/lemonsqueezy-mcp 0.9.2 → 0.10.0

package/README.md

@@ -100,7 +100,7 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
-## Tools (61)
+## Tools (64)
 
 ### Users
 - `ls_get_user` — Get the authenticated user
@@ -201,9 +201,16 @@ Add to `claude_desktop_config.json`:
 - `ls_validate_license` — Validate a license key (no API key required)
 - `ls_deactivate_license` — Deactivate a license key instance (no API key required)
 
+### Webhook sink (optional)
+Bridge to a separate [@yawlabs/lemonsqueezy-webhook-sink](https://github.com/YawLabs/lemonsqueezy-webhook-sink) process so the agent can reconcile against webhooks that actually fired. Tools are always registered; if `LEMONSQUEEZY_SINK_URL` / `LEMONSQUEEZY_SINK_ADMIN_TOKEN` are unset, calls return a clear "not configured" error.
+
+- `ls_sink_events_list` — List webhook events the sink has received (filter by `since` / `type` / `limit`)
+- `ls_sink_event_mark_processed` — Mark a sink event as processed by your consumer (idempotent)
+- `ls_sink_stats` — Get total events, unprocessed count, and last-received timestamp
+
 ## Features
 
-- **Full API coverage** — All 17 LemonSqueezy API resources with 61 tools
+- **Full API coverage** — All 17 LemonSqueezy API resources with 61 tools, plus 3 bridge tools to an optional [@yawlabs/lemonsqueezy-webhook-sink](https://github.com/YawLabs/lemonsqueezy-webhook-sink) for webhook reconciliation
 - **JSON:API support** — Filtering, pagination, and relationship inclusion on all list/get operations
 - **Zero runtime dependencies** — Single bundled file for instant `npx` startup
 - **License API** — Activate, validate, and deactivate license keys without an API key
@@ -228,6 +235,8 @@ All configuration is via environment variables. Only `LEMONSQUEEZY_API_KEY` (or
 | `LEMONSQUEEZY_DISABLE_CLASSES` | Comma-separated list of [authority classes](#authority-classes) to refuse outright. Any tool whose class is listed returns a `guardrail_block` before the API call is attempted. Example: `LEMONSQUEEZY_DISABLE_CLASSES=money,recurring,pii` lets an agent run reads but blocks refunds, subscription changes, and customer-record access. Unknown class names throw at server startup. |
 | `LEMONSQUEEZY_RATE_LIMIT_PER_CLASS` | Per-class rolling rate limits, comma-separated. Each entry is `class:N`, `class:N/m`, or `class:N/h` (bare numbers default to per-minute). Example: `money:2/h,recurring:5/h,key:10/m`. Composes with `LEMONSQUEEZY_DESTRUCTIVE_RATE_LIMIT` — both must pass. In-process per server instance. |
 | `LEMONSQUEEZY_LOG` | Structured-log verbosity to stderr. Set to `all` (or legacy `json`) to log every tool and HTTP call, `audit` to log only destructive-call audit entries plus errors (recommended for production), `error` to log only failures. Unset: no logs. Destructive calls are tagged `audit: true` and include their inputs. |
+| `LEMONSQUEEZY_SINK_URL` | Base URL of an optional [@yawlabs/lemonsqueezy-webhook-sink](https://github.com/YawLabs/lemonsqueezy-webhook-sink) instance (e.g. `https://webhooks.example.com`). Trailing slashes are stripped. Enables the `ls_sink_*` reconciliation tools below. Unset: the tools are still registered but return a "not configured" error when called. |
+| `LEMONSQUEEZY_SINK_ADMIN_TOKEN` | Bearer token for the sink's admin endpoints. Must match the sink's `WEBHOOK_SINK_ADMIN_TOKEN`. Required when `LEMONSQUEEZY_SINK_URL` is set; if the sink itself was started without an admin token, its admin endpoints return 404 and `ls_sink_*` calls surface that diagnostically. |
 
 ### Logging format
 

package/dist/index.js

@@ -31825,6 +31825,165 @@ var productTools = [
   }
 ];
 
+// src/tools/sink.ts
+var SINK_REPO_URL = "https://github.com/YawLabs/lemonsqueezy-webhook-sink";
+var FETCH_TIMEOUT_MS = 1e4;
+function loadSinkConfig() {
+  const rawUrl = process.env.LEMONSQUEEZY_SINK_URL;
+  const token = process.env.LEMONSQUEEZY_SINK_ADMIN_TOKEN;
+  if (!rawUrl || !token) {
+    const missing = [];
+    if (!rawUrl) missing.push("LEMONSQUEEZY_SINK_URL");
+    if (!token) missing.push("LEMONSQUEEZY_SINK_ADMIN_TOKEN");
+    return {
+      ok: false,
+      error: `Sink not configured: ${missing.join(", ")} must be set. See ${SINK_REPO_URL} for setup.`
+    };
+  }
+  return { url: rawUrl.replace(/\/+$/, ""), token };
+}
+function isToolHandlerResponse(value) {
+  return "ok" in value;
+}
+function buildSinkPath(path, params) {
+  const parts = [];
+  for (const [k, v] of Object.entries(params)) {
+    if (v === void 0 || v === null) continue;
+    const s = String(v);
+    if (s === "") continue;
+    parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(s)}`);
+  }
+  const qs = parts.length > 0 ? `?${parts.join("&")}` : "";
+  return `${path}${qs}`;
+}
+async function sinkRequest(config2, method, pathAndQuery) {
+  const url2 = `${config2.url}${pathAndQuery}`;
+  let res;
+  try {
+    res = await fetch(url2, {
+      method,
+      headers: {
+        Authorization: `Bearer ${config2.token}`,
+        Accept: "application/json"
+      },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const isTimeout = err instanceof Error && (err.name === "TimeoutError" || /timeout/i.test(message));
+    return {
+      ok: false,
+      error: isTimeout ? `Sink request timed out after ${Math.round(FETCH_TIMEOUT_MS / 1e3)}s (${config2.url})` : `Sink unreachable: ${message} (${config2.url})`
+    };
+  }
+  if (!res.ok) {
+    let body = "";
+    try {
+      body = await res.text();
+    } catch {
+    }
+    let detail = body;
+    try {
+      const parsed = JSON.parse(body);
+      if (parsed.error) detail = parsed.error;
+    } catch {
+    }
+    if (res.status === 401) {
+      return {
+        ok: false,
+        error: `Sink rejected admin token (401): ${detail || "unauthorized"}. Verify LEMONSQUEEZY_SINK_ADMIN_TOKEN matches the sink's WEBHOOK_SINK_ADMIN_TOKEN.`
+      };
+    }
+    if (res.status === 404) {
+      return {
+        ok: false,
+        error: `Sink admin endpoint not found (404): ${detail || "not found"}. The sink may have been started without WEBHOOK_SINK_ADMIN_TOKEN set, which disables admin endpoints.`
+      };
+    }
+    return {
+      ok: false,
+      error: `Sink returned ${res.status}: ${detail || res.statusText}`
+    };
+  }
+  const text = await res.text();
+  if (!text.trim()) return { ok: true, data: {} };
+  try {
+    return { ok: true, data: JSON.parse(text) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `Sink returned invalid JSON: ${message}` };
+  }
+}
+var sinkTools = [
+  {
+    name: "ls_sink_events_list",
+    authorityClass: "read",
+    description: "List webhook events the sink has received, optionally filtered. Use `since` (received_at timestamp, exclusive) to checkpoint. Requires the sink at LEMONSQUEEZY_SINK_URL with LEMONSQUEEZY_SINK_ADMIN_TOKEN.",
+    annotations: {
+      title: "List sink webhook events",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      since: external_exports3.number().int().min(0).optional().describe(
+        "Exclusive lower bound on received_at (Unix ms). Pass the highest received_at you have to checkpoint."
+      ),
+      type: external_exports3.string().max(200).optional().describe("Filter by event_name (e.g. 'order_created')."),
+      limit: external_exports3.number().int().min(1).max(1e3).optional().describe("Maximum number of events to return.")
+    }),
+    handler: async (input) => {
+      const config2 = loadSinkConfig();
+      if (isToolHandlerResponse(config2)) return config2;
+      const path = buildSinkPath("/events", {
+        since: input.since,
+        type: input.type,
+        limit: input.limit
+      });
+      return sinkRequest(config2, "GET", path);
+    }
+  },
+  {
+    name: "ls_sink_event_mark_processed",
+    authorityClass: "mutate",
+    description: "Mark a sink event as processed by your consumer. Idempotent.",
+    annotations: {
+      title: "Mark sink event processed",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({
+      id: external_exports3.number().int().min(1).describe("The sink event ID (positive integer, as returned by ls_sink_events_list).")
+    }),
+    handler: async (input) => {
+      const config2 = loadSinkConfig();
+      if (isToolHandlerResponse(config2)) return config2;
+      return sinkRequest(config2, "POST", `/events/${encodeURIComponent(String(input.id))}/processed`);
+    }
+  },
+  {
+    name: "ls_sink_stats",
+    authorityClass: "read",
+    description: "Get sink totals: total events, unprocessed count, last-received timestamp.",
+    annotations: {
+      title: "Get sink stats",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: external_exports3.object({}),
+    handler: async () => {
+      const config2 = loadSinkConfig();
+      if (isToolHandlerResponse(config2)) return config2;
+      return sinkRequest(config2, "GET", "/stats");
+    }
+  }
+];
+
 // src/tools/stores.ts
 var storeTools = [
   {
@@ -32617,7 +32776,7 @@ function readAuditLogResource(uri) {
 }
 
 // src/index.ts
-var version2 = true ? "0.9.2" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.10.0" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version") {
   console.log(version2);
@@ -32644,7 +32803,8 @@ var allTools = [
   ...checkoutTools,
   ...webhookTools,
   ...licenseTools,
-  ...affiliateTools
+  ...affiliateTools,
+  ...sinkTools
 ];
 var server = new McpServer({
   name: "@yawlabs/lemonsqueezy-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/lemonsqueezy-mcp",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "mcpName": "io.github.YawLabs/lemonsqueezy-mcp",
   "description": "LemonSqueezy MCP server for managing your store from AI assistants",
   "license": "MIT",