within-sdk 1.0.0

package/dist/validate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * With.in MCP Auth SDK — Token Validation
+ *
+ * Validates tokens against With.in's JWKS endpoint.
+ * Caches the JWKS keys in memory with a 5-minute refresh interval.
+ *
+ * SYNC NOTE: vendor/lib/validate.ts intentionally diverges here — it adds
+ * `ngrok-skip-browser-warning` headers for local-dev only. Keep the
+ * published SDK clean of those.
+ */
+import type { WithinTokenClaims } from './types.js';
+export declare function validateWithinToken(token: string, jwksUrl: string): Promise<WithinTokenClaims | null>;
+export declare function extractBearerToken(authHeader?: string): string | null;
+/** Report to With.in that the vendor recognises this user as an existing customer.
+ *  Call this when a With.in token arrives and you find the user in your own DB.
+ *  With.in will mark the user as a subscriber (no conversion fee).
+ *
+ *  Pass `withinAccessToken` whenever it's available — the backend authenticates
+ *  the request by checking that token's claims match (email + vendor_slug).
+ *  Without it the call is rejected, so the vendorTokenValidator path (where
+ *  no With.in token exists) cannot drive conversions. That path is intentionally
+ *  niche today; broader auth (vendor shared secret) is planned. */
+export declare function reportConversion(authServerUrl: string, vendorSlug: string, email: string, withinAccessToken?: string): Promise<void>;
+/** Check whether the token holder is now a subscriber for this vendor.
+ *  Used to unstick users who paid seconds ago but whose cached access
+ *  token still says the trial is exhausted. Returns false on any error —
+ *  falling back to the normal trial-exhausted message is the safe default. */
+export declare function checkSubscriptionStatus(authServerUrl: string, token: string): Promise<boolean>;
+export interface ReportToolCallResult {
+    /** Backend returned 401 token_revoked — caller must block the tool call.
+     *  An access token's JWT signature stays valid until its 10-min TTL, so
+     *  local validation alone can't catch a dashboard-initiated revoke. The
+     *  /oauth/report roundtrip is the enforcement point. */
+    revoked: boolean;
+    /** Backend returned 429 tool_budget_exhausted — vendor has configured a
+     *  per-tool call budget and the user has hit it. Caller must block the
+     *  tool call so the vendor's handler does NOT run. The user can still
+     *  call other tools (budgets are per-tool, not global). */
+    budgetExhausted?: {
+        tool: string;
+        limit: number;
+    };
+}
+/** Report a tool call back to With.in for lead tracking and revocation
+ *  enforcement. `aiClient` — the MCP client name captured from the session's
+ *  `initialize` request (`clientInfo.name`). Lets the vendor and the user
+ *  see which agent (Claude Desktop, Cursor, ChatGPT, …) actually made
+ *  the call.
+ *
+ *  Returns `{ revoked: true }` when the backend reports the token has been
+ *  revoked since issuance. Network/server errors return `{ revoked: false }`
+ *  so reporting outages never block a tool call. */
+export declare function reportToolCall(authServerUrl: string, token: string, vendorSlug: string, toolName: string, aiClient?: string, toolArguments?: Record<string, unknown> | null): Promise<ReportToolCallResult>;

package/dist/validate.js

@@ -0,0 +1,139 @@
+/**
+ * With.in MCP Auth SDK — Token Validation
+ *
+ * Validates tokens against With.in's JWKS endpoint.
+ * Caches the JWKS keys in memory with a 5-minute refresh interval.
+ *
+ * SYNC NOTE: vendor/lib/validate.ts intentionally diverges here — it adds
+ * `ngrok-skip-browser-warning` headers for local-dev only. Keep the
+ * published SDK clean of those.
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+// Cache JWKS key set per URL
+const jwksCache = new Map();
+function getJwks(jwksUrl) {
+    let jwks = jwksCache.get(jwksUrl);
+    if (!jwks) {
+        jwks = createRemoteJWKSet(new URL(jwksUrl));
+        jwksCache.set(jwksUrl, jwks);
+    }
+    return jwks;
+}
+export async function validateWithinToken(token, jwksUrl) {
+    try {
+        const jwks = getJwks(jwksUrl);
+        const { payload } = await jwtVerify(token, jwks);
+        // Verify it's a With.in token
+        if (payload.token_type !== 'access' && payload.token_type !== 'identity') {
+            return null;
+        }
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+export function extractBearerToken(authHeader) {
+    if (!authHeader)
+        return null;
+    const match = authHeader.match(/^Bearer\s+(.+)$/i);
+    return match?.[1] ?? null;
+}
+/** Report to With.in that the vendor recognises this user as an existing customer.
+ *  Call this when a With.in token arrives and you find the user in your own DB.
+ *  With.in will mark the user as a subscriber (no conversion fee).
+ *
+ *  Pass `withinAccessToken` whenever it's available — the backend authenticates
+ *  the request by checking that token's claims match (email + vendor_slug).
+ *  Without it the call is rejected, so the vendorTokenValidator path (where
+ *  no With.in token exists) cannot drive conversions. That path is intentionally
+ *  niche today; broader auth (vendor shared secret) is planned. */
+export async function reportConversion(authServerUrl, vendorSlug, email, withinAccessToken) {
+    if (!withinAccessToken)
+        return; // No token, no auth → skip silently.
+    try {
+        await fetch(`${authServerUrl}/oauth/conversion`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${withinAccessToken}`,
+            },
+            body: JSON.stringify({ email, vendor_slug: vendorSlug }),
+        });
+    }
+    catch {
+        // Don't block auth if reporting fails
+    }
+}
+/** Check whether the token holder is now a subscriber for this vendor.
+ *  Used to unstick users who paid seconds ago but whose cached access
+ *  token still says the trial is exhausted. Returns false on any error —
+ *  falling back to the normal trial-exhausted message is the safe default. */
+export async function checkSubscriptionStatus(authServerUrl, token) {
+    // Hard-cap the live check so a slow or dead auth server doesn't stall the
+    // tool response. Claude will time out the tool call around ~30s; we fail
+    // fast at 3s and let the normal trial-ended message render.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3000);
+    try {
+        const res = await fetch(`${authServerUrl}/oauth/subscription-status`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return false;
+        const data = await res.json();
+        return data.subscriber === true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Report a tool call back to With.in for lead tracking and revocation
+ *  enforcement. `aiClient` — the MCP client name captured from the session's
+ *  `initialize` request (`clientInfo.name`). Lets the vendor and the user
+ *  see which agent (Claude Desktop, Cursor, ChatGPT, …) actually made
+ *  the call.
+ *
+ *  Returns `{ revoked: true }` when the backend reports the token has been
+ *  revoked since issuance. Network/server errors return `{ revoked: false }`
+ *  so reporting outages never block a tool call. */
+export async function reportToolCall(authServerUrl, token, vendorSlug, toolName, aiClient, toolArguments) {
+    try {
+        const res = await fetch(`${authServerUrl}/oauth/report`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                token,
+                tool_name: toolName,
+                vendor_slug: vendorSlug,
+                ai_client: aiClient,
+                tool_arguments: toolArguments ?? undefined,
+            }),
+        });
+        if (res.status === 401) {
+            try {
+                const body = (await res.json());
+                if (body?.error === 'token_revoked')
+                    return { revoked: true };
+            }
+            catch { }
+        }
+        if (res.status === 429) {
+            try {
+                const body = (await res.json());
+                if (body?.error === 'tool_budget_exhausted' && typeof body.tool === 'string' && typeof body.limit === 'number') {
+                    return { revoked: false, budgetExhausted: { tool: body.tool, limit: body.limit } };
+                }
+            }
+            catch { }
+        }
+    }
+    catch {
+        // Don't block tool calls if reporting fails
+    }
+    return { revoked: false };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "within-sdk",
+  "version": "1.0.0",
+  "description": "Within SDK for MCP analytics, workflow intelligence, and qualified opportunities.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "within",
+    "sdk",
+    "workflow",
+    "qualification"
+  ],
+  "license": "MIT",
+  "homepage": "https://getwith.in",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && rm -rf dist/thirdparty && cp -R src/thirdparty dist/thirdparty",
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test src/*.test.ts"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.11"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "~1.24.2",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}