docs(examples): add webhook example; fix MCP README placeholders; improve example docs

README.md

@@ -128,21 +128,21 @@ Create a `.cursor/mcp.json` file in your project root with the following content
 
 </details>
 
-You can also run MCP servers as a standalone binary with no additional dependencies. You must pull these binaries from available Github releases:
+You can also run MCP servers as a standalone binary with no additional dependencies. Download the binaries from the Polar SDK GitHub releases:
 
 ```bash
 curl -L -o mcp-server \
-    https://github.com/{org}/{repo}/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
+    https://github.com/polarsource/polar-js/releases/download/{tag}/mcp-server-bun-darwin-arm64 && \
 chmod +x mcp-server
 ```
 
-If the repo is a private repo you must add your Github PAT to download a release `-H "Authorization: Bearer {GITHUB_PAT}"`.
+Replace `{tag}` with the desired release tag. See available tags at https://github.com/polarsource/polar-js/releases. If the repo is private, add your GitHub PAT header: `-H "Authorization: Bearer {GITHUB_PAT}"`.
 
 
 ```json
 {
   "mcpServers": {
-    "Todos": {
+    "Polar": {
       "command": "./DOWNLOAD/PATH/mcp-server",
       "args": [
         "start"

examples/README.md

@@ -18,14 +18,17 @@ This directory contains example scripts demonstrating how to use the @polar-sh/s
 
 ## Running the Examples
 
-To run an example file from the examples directory:
+To run an example from this directory:
 
 ```bash
-npm run build && npx tsx example.ts
+npm run build && npx tsx organizationsList.example.ts
 ```
 
+Available examples:
+- organizationsList.example.ts — lists organizations using the SDK
+- webhookExpress.example.ts — minimal Express server validating Polar webhooks
+
 ## Creating new examples
 
 Duplicate an existing example file, they won't be overwritten by the generation process.
 
-

examples/package.json

@@ -5,14 +5,18 @@
   "scripts": {
     "build:parent": "cd .. && npm i && npm run build && cd -",
     "build:examples": "npm i",
-    "build": "npm run build:parent && npm run build:examples"
+    "build": "npm run build:parent && npm run build:examples",
+    "start:orgs": "npm run build && npx tsx organizationsList.example.ts",
+    "start:webhooks": "npm run build && npx tsx webhookExpress.example.ts"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "dotenv": "^16.4.5",
-    "tsx": "^4.19.2"
+    "tsx": "^4.19.2",
+    "express": "^4.21.2",
+    "@types/express": "^4.17.21"
   },
   "dependencies": {
     "@polar-sh/sdk": "file:.."
   }
-}
+}

examples/webhookExpress.example.ts

@@ -0,0 +1,44 @@
+/*
+ * Example: Minimal Express server validating Polar webhooks
+ *
+ * To run from the examples directory:
+ *   npm run build && npx tsx webhookExpress.example.ts
+ */
+
+import dotenv from "dotenv";
+dotenv.config();
+
+import express, { Request, Response } from "express";
+import { validateEvent, WebhookVerificationError } from "@polar-sh/sdk/webhooks";
+
+const app = express();
+
+// Use raw body for signature verification
+app.post("/webhook", express.raw({ type: "application/json" }), (req: Request, res: Response) => {
+  try {
+    const secret = process.env["POLAR_WEBHOOK_SECRET"] ?? "";
+    if (!secret) {
+      console.warn("POLAR_WEBHOOK_SECRET is not set; refusing to validate requests.");
+      return res.status(500).send("");
+    }
+
+    const event = validateEvent(req.body, req.headers as Record<string, string>, secret);
+
+    // TODO: Handle the event by type if desired
+    console.log("Received webhook:", event.type);
+
+    return res.status(202).send("");
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) {
+      return res.status(403).send("");
+    }
+    console.error(error);
+    return res.status(500).send("");
+  }
+});
+
+const port = Number(process.env["PORT"] ?? 3000);
+app.listen(port, () => {
+  console.log(`Webhook server listening on http://localhost:${port}`);
+});
+