@yawlabs/vend-mcp 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+# @yawlabs/vend-mcp
+
+Payments for MCP servers. Add license key gating and usage metering in two lines of code.
+
+```
+npm install @yawlabs/vend-mcp
+```
+
+## Quick Start
+
+```ts
+import { vendAuth } from '@yawlabs/vend-mcp';
+
+const guard = vendAuth({
+  apiKey: process.env.VEND_API_KEY!,
+  gates: {
+    search: 'free',
+    execute: 'pro',
+    deploy: 'business',
+  },
+});
+
+// In your tool handler:
+if (!(await guard.canAccess('execute'))) {
+  return { content: [{ type: 'text', text: guard.upgradeMessage('execute') }] };
+}
+
+guard.recordUsage('execute');
+// ... run the tool
+```
+
+## How It Works
+
+1. Customers purchase a license key at your project's checkout page on [vend.sh](https://vend.sh)
+2. They set `VEND_LICENSE_KEY` in their MCP client config
+3. Your server uses `vendAuth` to gate tools by tier and track usage
+
+The SDK validates the key against the Vend API, caches the result, and lets you gate any tool to any tier.
+
+## API Reference
+
+### `vendAuth(options): VendGuard`
+
+Creates a guard instance. Validation is lazy — no API calls until the first `canAccess()` or `validate()`.
+
+```ts
+const guard = vendAuth({
+  // Required
+  apiKey: 'vend_xxx',                    // Your project API key from the dashboard
+  gates: { search: 'free', run: 'pro' }, // Tool name → minimum tier
+
+  // Optional
+  licenseKey: 'VEND-XXXX-...',           // Override (default: process.env.VEND_LICENSE_KEY)
+  cacheTtl: 300,                         // Seconds to cache successful validations (default: 300)
+  errorCacheTtl: 30,                     // Seconds to cache failed validations (default: 30)
+
+  // Observability hooks (all optional)
+  onValidate: (result, fromCache) => {},
+  onActivate: (result) => {},
+  onUsage: (toolName, success) => {},
+  onError: (operation, error) => {},
+});
+```
+
+### `guard.canAccess(toolName): Promise<boolean>`
+
+Check if the current key can access a tool. Calls `validate()` internally (cached).
+
+```ts
+if (!(await guard.canAccess('deploy'))) {
+  return { content: [{ type: 'text', text: guard.upgradeMessage('deploy') }] };
+}
+```
+
+### `guard.validate(): Promise<ValidationResult>`
+
+Validate the license key against the Vend API. Results are cached per the TTL settings.
+
+```ts
+const result = await guard.validate();
+// {
+//   valid: true,
+//   tier: 'pro',
+//   tierName: 'Pro',
+//   toolGates: { search: true, execute: true },
+//   requestLimit: 10000,
+//   activationsRemaining: 4,
+// }
+```
+
+On failure, `reason` tells you why:
+
+| Reason | Meaning |
+|--------|---------|
+| `no_license_key` | No key provided |
+| `invalid_key_format` | Key doesn't match `VEND-XXXX-XXXX-XXXX-XXXX` |
+| `invalid_api_key` | Your project API key is wrong |
+| `key_not_found` | Key doesn't exist or doesn't belong to your project |
+| `key_inactive` / `key_expired` / `key_revoked` | Key is no longer valid |
+| `network_error` | Couldn't reach vend.sh (falls back to cache if available) |
+| `validation_failed` | Other API error |
+
+### `guard.recordUsage(toolName): Promise<boolean>`
+
+Record a tool invocation. Returns `true` if recorded, `false` on failure. Safe to fire-and-forget:
+
+```ts
+// Fire-and-forget (won't block your handler)
+guard.recordUsage('search');
+
+// Or await for confirmation
+const ok = await guard.recordUsage('search');
+```
+
+### `guard.activate(instanceName, instanceId): Promise<ActivationResult>`
+
+Activate the key for a specific MCP client instance. Call this once on startup.
+
+```ts
+const result = await guard.activate('claude-desktop', crypto.randomUUID());
+if (!result.activated) {
+  console.error(`Activation failed: ${result.reason}`);
+  // reason: 'activation_limit_reached' | 'key_not_found' | 'key_inactive' | ...
+}
+```
+
+### `guard.tier: TierGate`
+
+The current customer's tier (after validation). One of: `'free'`, `'starter'`, `'pro'`, `'business'`, `'enterprise'`.
+
+### `guard.upgradeMessage(toolName): string`
+
+A human-readable message explaining why a tool is gated and how to upgrade.
+
+### `guard.licenseKey = 'VEND-...'`
+
+Update the license key at runtime. Clears the cache.
+
+### `createToolGuard(guard)`
+
+Auto-gate and track usage for an MCP `CallToolRequest` handler:
+
+```ts
+import { vendAuth, createToolGuard } from '@yawlabs/vend-mcp';
+
+const guard = vendAuth({ apiKey: '...', gates: { search: 'free', run: 'pro' } });
+const gated = createToolGuard(guard);
+
+server.setRequestHandler(
+  CallToolRequestSchema,
+  gated(async (request) => {
+    // This only runs if the key has access to request.params.name
+    // Usage is recorded automatically on success
+    return { content: [{ type: 'text', text: 'result' }] };
+  }),
+);
+```
+
+## Tiers
+
+Tiers are ordered. A `pro` key can access `free` and `starter` tools.
+
+| Tier | Level |
+|------|-------|
+| `free` | 0 |
+| `starter` | 1 |
+| `pro` | 2 |
+| `business` | 3 |
+| `enterprise` | 4 |
+
+## Observability
+
+Hook into every SDK operation for logging, metrics, or alerting:
+
+```ts
+const guard = vendAuth({
+  apiKey: process.env.VEND_API_KEY!,
+  gates: { search: 'free', execute: 'pro' },
+  onValidate: (result, fromCache) => {
+    console.log(`[vend] validate: valid=${result.valid} tier=${result.tier} cache=${fromCache}`);
+  },
+  onActivate: (result) => {
+    if (!result.activated) console.warn(`[vend] activation failed: ${result.reason}`);
+  },
+  onUsage: (toolName, success) => {
+    metrics.increment('vend.usage', { tool: toolName, ok: String(success) });
+  },
+  onError: (operation, error) => {
+    console.error(`[vend] ${operation} error:`, error);
+    sentry.captureException(error);
+  },
+});
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VEND_LICENSE_KEY` | Customer's license key (set by the end user) |
+| `VEND_API_URL` | Override the API URL (default: `https://vend.sh`) |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+export type TierGate = 'free' | 'starter' | 'pro' | 'business' | 'enterprise';
+export type ValidationReason = 'no_license_key' | 'invalid_key_format' | 'invalid_api_key' | 'key_not_found' | 'key_inactive' | 'key_expired' | 'key_revoked' | 'validation_failed' | 'network_error';
+export type ActivationReason = 'no_license_key' | 'invalid_key_format' | 'invalid_api_key' | 'key_not_found' | 'key_inactive' | 'activation_limit_reached' | 'activation_failed' | 'network_error';
+export interface VendAuthOptions {
+    /** Your project's API key from the Vend dashboard */
+    apiKey: string;
+    /** The customer's license key (usually from env: VEND_LICENSE_KEY) */
+    licenseKey?: string;
+    /** Map of tool names to minimum required tier */
+    gates: Record<string, TierGate>;
+    /** Cache TTL in seconds for successful validations (default: 300 = 5 min) */
+    cacheTtl?: number;
+    /** Cache TTL in seconds for failed validations (default: 30) */
+    errorCacheTtl?: number;
+    /** Called after every validation attempt (cached or not) */
+    onValidate?: (result: ValidationResult, fromCache: boolean) => void;
+    /** Called after every activation attempt */
+    onActivate?: (result: ActivationResult) => void;
+    /** Called after every usage recording attempt */
+    onUsage?: (toolName: string, success: boolean) => void;
+    /** Called on any network or API error */
+    onError?: (operation: 'validate' | 'activate' | 'usage', error: unknown) => void;
+}
+export interface ValidationResult {
+    valid: boolean;
+    tier?: TierGate;
+    tierName?: string;
+    toolGates?: Record<string, boolean> | null;
+    requestLimit?: number | null;
+    activationsRemaining?: number | null;
+    reason?: ValidationReason;
+}
+export interface ActivationResult {
+    activated: boolean;
+    reason?: ActivationReason;
+}
+export declare class VendGuard {
+    private apiKey;
+    private _licenseKey;
+    private gates;
+    private successCacheTtl;
+    private errorCacheTtl;
+    private cached;
+    private cachedAt;
+    private hooks;
+    constructor(opts: VendAuthOptions);
+    /** Update the license key (clears cache) */
+    set licenseKey(key: string);
+    /** Validate the license key against the Vend API (cached) */
+    validate(): Promise<ValidationResult>;
+    /** Check if a tool is accessible at the current tier */
+    canAccess(toolName: string): Promise<boolean>;
+    /** Get the current customer's tier (after validate() has been called) */
+    get tier(): TierGate;
+    /** Get the required tier for a tool */
+    requiredTier(toolName: string): TierGate;
+    /** Get a human-readable upgrade message for a denied tool */
+    upgradeMessage(toolName: string): string;
+    /**
+     * Record a tool invocation.
+     * Returns true if the usage was recorded, false on failure.
+     * Safe to fire-and-forget (errors are swallowed) or await for confirmation.
+     */
+    recordUsage(toolName: string): Promise<boolean>;
+    /**
+     * Activate the license key for this MCP client instance.
+     * Returns an object with `activated` boolean and an optional `reason` on failure.
+     */
+    activate(instanceName: string, instanceId: string): Promise<ActivationResult>;
+}
+/**
+ * Create a Vend guard for your MCP server.
+ * Validates lazily on first canAccess() call, not at construction time.
+ *
+ * @example
+ * ```ts
+ * import { vendAuth } from '@vend/mcp';
+ *
+ * const guard = vendAuth({
+ *   apiKey: process.env.VEND_API_KEY!,
+ *   gates: { 'search': 'free', 'execute': 'pro' },
+ *   onValidate: (result, fromCache) => {
+ *     console.log(`[vend] validate: ${result.valid} (cache: ${fromCache})`);
+ *   },
+ *   onError: (op, err) => {
+ *     console.error(`[vend] ${op} error:`, err);
+ *   },
+ * });
+ *
+ * // In your tool handler:
+ * if (!await guard.canAccess('execute')) {
+ *   return { content: [{ type: 'text', text: guard.upgradeMessage('execute') }] };
+ * }
+ * guard.recordUsage('execute');
+ * ```
+ */
+export declare function vendAuth(opts: VendAuthOptions): VendGuard;
+/**
+ * Create a tool handler wrapper that auto-gates and tracks usage.
+ * Usage is recorded only when the handler completes without throwing.
+ * If the handler throws, the error propagates and no usage is recorded.
+ *
+ * @example
+ * ```ts
+ * import { vendAuth, createToolGuard } from '@vend/mcp';
+ *
+ * const guard = vendAuth({ apiKey: '...', gates: { 'search': 'free', 'execute': 'pro' } });
+ * const gated = createToolGuard(guard);
+ *
+ * server.setRequestHandler(CallToolRequestSchema, gated(async (request) => {
+ *   return { content: [{ type: 'text', text: 'result' }] };
+ * }));
+ * ```
+ */
+export declare function createToolGuard(guard: VendGuard): <T extends {
+    params: {
+        name: string;
+    };
+}>(handler: (request: T) => Promise<any>) => (request: T) => Promise<any>;

package/dist/index.js

@@ -0,0 +1,292 @@
+const VEND_API_URL = process.env.VEND_API_URL || 'https://vend.sh';
+// Key format: VEND-XXXX-XXXX-XXXX-XXXX (chars: A-Z excluding I,O + 2-9)
+const KEY_PATTERN = /^VEND-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/;
+// --- Tier ordering ---
+const TIER_ORDER = {
+    free: 0,
+    starter: 1,
+    pro: 2,
+    business: 3,
+    enterprise: 4,
+};
+function tierMeetsMinimum(actual, required) {
+    return TIER_ORDER[actual] >= TIER_ORDER[required];
+}
+// --- Status → reason mapping ---
+function reasonFromStatus(status, body) {
+    if (status === 401)
+        return 'invalid_api_key';
+    if (status === 404)
+        return 'key_not_found';
+    if (body?.error?.startsWith('key_'))
+        return body.error;
+    return 'validation_failed';
+}
+function activationReasonFromStatus(status, body) {
+    if (status === 401)
+        return 'invalid_api_key';
+    if (status === 404)
+        return 'key_not_found';
+    if (body?.error === 'key_inactive')
+        return 'key_inactive';
+    if (body?.error === 'activation_limit_reached')
+        return 'activation_limit_reached';
+    return 'activation_failed';
+}
+// --- VendGuard ---
+export class VendGuard {
+    apiKey;
+    _licenseKey;
+    gates;
+    successCacheTtl;
+    errorCacheTtl;
+    cached = null;
+    cachedAt = 0;
+    hooks;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this._licenseKey = opts.licenseKey || process.env.VEND_LICENSE_KEY || '';
+        this.gates = opts.gates;
+        this.successCacheTtl = (opts.cacheTtl ?? 300) * 1000;
+        this.errorCacheTtl = (opts.errorCacheTtl ?? 30) * 1000;
+        this.hooks = {
+            onValidate: opts.onValidate,
+            onActivate: opts.onActivate,
+            onUsage: opts.onUsage,
+            onError: opts.onError,
+        };
+    }
+    /** Update the license key (clears cache) */
+    set licenseKey(key) {
+        this._licenseKey = key;
+        this.cached = null;
+        this.cachedAt = 0;
+    }
+    /** Validate the license key against the Vend API (cached) */
+    async validate() {
+        const ttl = this.cached?.valid ? this.successCacheTtl : this.errorCacheTtl;
+        if (this.cached && Date.now() - this.cachedAt < ttl) {
+            this.hooks.onValidate?.(this.cached, true);
+            return this.cached;
+        }
+        if (!this._licenseKey) {
+            this.cached = { valid: false, tier: 'free', reason: 'no_license_key' };
+            this.cachedAt = Date.now();
+            this.hooks.onValidate?.(this.cached, false);
+            return this.cached;
+        }
+        if (!KEY_PATTERN.test(this._licenseKey)) {
+            this.cached = { valid: false, tier: 'free', reason: 'invalid_key_format' };
+            this.cachedAt = Date.now();
+            this.hooks.onValidate?.(this.cached, false);
+            return this.cached;
+        }
+        try {
+            const res = await fetch(`${VEND_API_URL}/api/v1/keys/validate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-vend-api-key': this.apiKey,
+                },
+                body: JSON.stringify({ key: this._licenseKey }),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                this.cached = {
+                    valid: false,
+                    tier: 'free',
+                    reason: reasonFromStatus(res.status, body),
+                };
+            }
+            else {
+                this.cached = (await res.json());
+            }
+        }
+        catch (err) {
+            this.hooks.onError?.('validate', err);
+            // On network error, use previous successful cache if available
+            if (this.cached?.valid) {
+                this.hooks.onValidate?.(this.cached, true);
+                return this.cached;
+            }
+            this.cached = { valid: false, tier: 'free', reason: 'network_error' };
+        }
+        this.cachedAt = Date.now();
+        this.hooks.onValidate?.(this.cached, false);
+        return this.cached;
+    }
+    /** Check if a tool is accessible at the current tier */
+    async canAccess(toolName) {
+        const result = await this.validate();
+        const requiredTier = this.gates[toolName];
+        // If no gate defined, allow by default
+        if (!requiredTier)
+            return true;
+        // If key is invalid, only allow free-tier tools
+        if (!result.valid)
+            return requiredTier === 'free';
+        return tierMeetsMinimum(result.tier, requiredTier);
+    }
+    /** Get the current customer's tier (after validate() has been called) */
+    get tier() {
+        return this.cached?.tier ?? 'free';
+    }
+    /** Get the required tier for a tool */
+    requiredTier(toolName) {
+        return this.gates[toolName] ?? 'free';
+    }
+    /** Get a human-readable upgrade message for a denied tool */
+    upgradeMessage(toolName) {
+        const required = this.gates[toolName];
+        if (!required)
+            return 'This tool requires a valid license key.';
+        return `This tool requires the ${required} tier. Upgrade your license at your project's checkout page.`;
+    }
+    /**
+     * Record a tool invocation.
+     * Returns true if the usage was recorded, false on failure.
+     * Safe to fire-and-forget (errors are swallowed) or await for confirmation.
+     */
+    recordUsage(toolName) {
+        if (!this._licenseKey)
+            return Promise.resolve(false);
+        return fetch(`${VEND_API_URL}/api/v1/usage`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-vend-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                license_key: this._licenseKey,
+                tool_name: toolName,
+            }),
+        })
+            .then((res) => {
+            const ok = res.ok;
+            this.hooks.onUsage?.(toolName, ok);
+            return ok;
+        })
+            .catch((err) => {
+            this.hooks.onError?.('usage', err);
+            this.hooks.onUsage?.(toolName, false);
+            return false;
+        });
+    }
+    /**
+     * Activate the license key for this MCP client instance.
+     * Returns an object with `activated` boolean and an optional `reason` on failure.
+     */
+    async activate(instanceName, instanceId) {
+        if (!this._licenseKey) {
+            const result = { activated: false, reason: 'no_license_key' };
+            this.hooks.onActivate?.(result);
+            return result;
+        }
+        if (!KEY_PATTERN.test(this._licenseKey)) {
+            const result = { activated: false, reason: 'invalid_key_format' };
+            this.hooks.onActivate?.(result);
+            return result;
+        }
+        try {
+            const res = await fetch(`${VEND_API_URL}/api/v1/keys/activate`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-vend-api-key': this.apiKey,
+                },
+                body: JSON.stringify({
+                    key: this._licenseKey,
+                    instance_name: instanceName,
+                    instance_id: instanceId,
+                }),
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => ({}));
+                const result = {
+                    activated: false,
+                    reason: activationReasonFromStatus(res.status, body),
+                };
+                this.hooks.onActivate?.(result);
+                return result;
+            }
+            const result = { activated: true };
+            this.hooks.onActivate?.(result);
+            return result;
+        }
+        catch (err) {
+            this.hooks.onError?.('activate', err);
+            const result = { activated: false, reason: 'network_error' };
+            this.hooks.onActivate?.(result);
+            return result;
+        }
+    }
+}
+// --- Main export ---
+/**
+ * Create a Vend guard for your MCP server.
+ * Validates lazily on first canAccess() call, not at construction time.
+ *
+ * @example
+ * ```ts
+ * import { vendAuth } from '@vend/mcp';
+ *
+ * const guard = vendAuth({
+ *   apiKey: process.env.VEND_API_KEY!,
+ *   gates: { 'search': 'free', 'execute': 'pro' },
+ *   onValidate: (result, fromCache) => {
+ *     console.log(`[vend] validate: ${result.valid} (cache: ${fromCache})`);
+ *   },
+ *   onError: (op, err) => {
+ *     console.error(`[vend] ${op} error:`, err);
+ *   },
+ * });
+ *
+ * // In your tool handler:
+ * if (!await guard.canAccess('execute')) {
+ *   return { content: [{ type: 'text', text: guard.upgradeMessage('execute') }] };
+ * }
+ * guard.recordUsage('execute');
+ * ```
+ */
+export function vendAuth(opts) {
+    return new VendGuard(opts);
+}
+/**
+ * Create a tool handler wrapper that auto-gates and tracks usage.
+ * Usage is recorded only when the handler completes without throwing.
+ * If the handler throws, the error propagates and no usage is recorded.
+ *
+ * @example
+ * ```ts
+ * import { vendAuth, createToolGuard } from '@vend/mcp';
+ *
+ * const guard = vendAuth({ apiKey: '...', gates: { 'search': 'free', 'execute': 'pro' } });
+ * const gated = createToolGuard(guard);
+ *
+ * server.setRequestHandler(CallToolRequestSchema, gated(async (request) => {
+ *   return { content: [{ type: 'text', text: 'result' }] };
+ * }));
+ * ```
+ */
+export function createToolGuard(guard) {
+    return function gated(handler) {
+        return async (request) => {
+            const toolName = request.params.name;
+            const allowed = await guard.canAccess(toolName);
+            if (!allowed) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: guard.upgradeMessage(toolName),
+                        },
+                    ],
+                };
+            }
+            // Execute handler first, then record usage on success
+            const result = await handler(request);
+            guard.recordUsage(toolName);
+            return result;
+        };
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@yawlabs/vend-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Vend SDK for MCP servers — license key gating and usage metering in two lines",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "payments", "license-keys", "monetization", "vend"],
+  "author": "Yaw Labs <contact@yaw.sh>",
+  "license": "MIT",
+  "homepage": "https://vend.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/YawLabs/vend.git",
+    "directory": "packages/mcp"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  }
+}