@jclvsh/iris 0.23.1 → 0.24.0

package/README.md

@@ -76,6 +76,7 @@ iris campaigns --help
 | billing       | `b`    | plans                                                         | 1     |
 | channels      | `ch`   | accounts, availability, send                                  | 3     |
 | credits       | `cr`   | balance, buy                                                  | 2     |
+| affiliate     | —      | (status, link, sign-ups, and commission totals)               | 1     |
 | responder     | `r`    | status, configure, activity, show, pause, resume, triggers list, triggers add, triggers update, triggers remove, triggers posts | 11 |
 
 ## MCP Server Configuration
@@ -127,6 +128,19 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
+## Hosted Endpoint
+
+Clients that connect to a remote MCP server can use the hosted endpoint instead of this package:
+
+```
+https://api.iris-ai.dev/mcp
+```
+
+- Transport: MCP streamable HTTP, `POST` only.
+- Registry: listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.JCLVSH/iris`.
+- Auth: `Authorization: Bearer is_live_...` (the same API key; its scopes apply). `initialize` and `tools/list` answer without a key, so a client can read the tool list before signing up; calling a tool needs the key.
+- Tools: a subset of this package. Credits, API key, webhook, and affiliate tools are only available through the npm package. The class of each hosted tool is listed at https://www.iris-ai.dev/docs#mcp-hosted.
+
 ## Available Tools
 
 ### Campaigns
@@ -298,6 +312,14 @@ Add to `.cursor/mcp.json`:
 | ------------------- | --------------------------------- |
 | `get_billing_plans` | List available subscription plans |
 
+### Affiliate
+
+| Tool            | Description                                                                              |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| `get_affiliate` | Your affiliate status, link, sign-ups, and commission totals, with the terms (stdio only) |
+
+CLI: `iris affiliate`.
+
 ### API Keys
 
 | Tool                  | Description                                       |

package/dist/cli.js

@@ -18,6 +18,7 @@ import { registerBillingCommands } from "./commands/billing.js";
 import { registerChannelCommands } from "./commands/channels.js";
 import { registerCreditCommands } from "./commands/credits.js";
 import { registerResponderCommands } from "./commands/responder.js";
+import { registerAffiliateCommands } from "./commands/affiliate.js";
 const program = new Command()
     .name("iris")
     .description("iris CLI - manage campaigns, contacts, messages, and outreach")
@@ -52,6 +53,7 @@ try {
     registerChannelCommands(program, client);
     registerCreditCommands(program, client);
     registerResponderCommands(program, client);
+    registerAffiliateCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

package/dist/commands/affiliate.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { IrisClient } from "../client.js";
+export declare function registerAffiliateCommands(program: Command, client: IrisClient): void;

package/dist/commands/affiliate.js

@@ -0,0 +1,15 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerAffiliateCommands(program, client) {
+    program
+        .command("affiliate")
+        .description("your affiliate status, link, sign-ups, and commission totals")
+        .action(async () => {
+        try {
+            const result = await client.get("/affiliate");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/hosted-transport.d.ts

@@ -8,3 +8,22 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * opens an event stream that never ends).
  */
 export declare function serveStatelessMcp(server: McpServer, request: Request): Promise<Response>;
+/**
+ * True when a JSON-RPC payload (one message or a batch) only asks who the server is and which
+ * tools it has. A host may answer these without a key, so an agent or a directory can see what
+ * the server does before signing up. Every message must be on the list: one tool call in a
+ * batch makes the whole payload need a key.
+ */
+export declare function isDiscoveryPayload(payload: unknown): boolean;
+/**
+ * True when the request's body is a discovery payload. Reads a clone, so the request can still
+ * be served afterwards, and stops at MAX_DISCOVERY_BODY_BYTES: a larger body, or a chunked one
+ * with no Content-Length, is never buffered whole.
+ */
+export declare function isDiscoveryRequest(request: Request): Promise<boolean>;
+/**
+ * The API client for a keyless discovery server: it has no key, so every use throws. Listing
+ * tools never touches the client; a tool call that reached this server would fail here, before
+ * any REST request.
+ */
+export declare function keylessClient<Client extends object>(): Client;

package/dist/hosted-transport.js

@@ -15,3 +15,70 @@ export async function serveStatelessMcp(server, request) {
     await server.connect(transport);
     return transport.handleRequest(request);
 }
+/** JSON-RPC methods that describe the server and change nothing. */
+const DISCOVERY_METHODS = new Set(["initialize", "notifications/initialized", "ping", "tools/list"]);
+/** A handshake is three messages; a longer keyless batch is not a handshake. */
+const MAX_DISCOVERY_BATCH = 10;
+/**
+ * True when a JSON-RPC payload (one message or a batch) only asks who the server is and which
+ * tools it has. A host may answer these without a key, so an agent or a directory can see what
+ * the server does before signing up. Every message must be on the list: one tool call in a
+ * batch makes the whole payload need a key.
+ */
+export function isDiscoveryPayload(payload) {
+    const messages = Array.isArray(payload) ? payload : [payload];
+    if (messages.length === 0 || messages.length > MAX_DISCOVERY_BATCH)
+        return false;
+    return messages.every((message) => {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const method = message.method;
+        return typeof method === "string" && DISCOVERY_METHODS.has(method);
+    });
+}
+/** A handshake fits in a few hundred bytes; a keyless body past this is not one. */
+const MAX_DISCOVERY_BODY_BYTES = 16_384;
+/**
+ * True when the request's body is a discovery payload. Reads a clone, so the request can still
+ * be served afterwards, and stops at MAX_DISCOVERY_BODY_BYTES: a larger body, or a chunked one
+ * with no Content-Length, is never buffered whole.
+ */
+export async function isDiscoveryRequest(request) {
+    const stream = request.clone().body;
+    if (!stream)
+        return false;
+    const reader = stream.getReader();
+    const bytes = new Uint8Array(MAX_DISCOVERY_BODY_BYTES);
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (size + value.byteLength > MAX_DISCOVERY_BODY_BYTES) {
+                // Not awaited: cancelling one side of a cloned body only settles once the other
+                // side is cancelled too, and the caller is about to answer without reading it.
+                void reader.cancel().catch(() => undefined);
+                return false;
+            }
+            bytes.set(value, size);
+            size += value.byteLength;
+        }
+        return isDiscoveryPayload(JSON.parse(new TextDecoder().decode(bytes.subarray(0, size))));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The API client for a keyless discovery server: it has no key, so every use throws. Listing
+ * tools never touches the client; a tool call that reached this server would fail here, before
+ * any REST request.
+ */
+export function keylessClient() {
+    return new Proxy({}, {
+        get(_target, property) {
+            throw new Error(`an api key is required (client.${String(property)} was used without one)`);
+        },
+    });
+}

package/dist/hosted.d.ts

@@ -8,3 +8,12 @@ export interface HostedMcpOptions {
 }
 /** One hosted MCP request: a per-request client and server over the stateless transport. */
 export declare function handleHostedMcpRequest(request: Request, options: HostedMcpOptions): Promise<Response>;
+/**
+ * One keyless discovery request (initialize, tools/list): the same hosted server and tool list,
+ * built on a client that cannot make a REST call. The host checks the request with
+ * isDiscoveryRequest first; anything else needs a key and goes to handleHostedMcpRequest.
+ */
+export declare function handleHostedMcpDiscovery(request: Request, options: {
+    version: string;
+}): Promise<Response>;
+export { isDiscoveryPayload, isDiscoveryRequest } from "./hosted-transport.js";

package/dist/hosted.js

@@ -1,5 +1,5 @@
 import { IrisClient } from "./client.js";
-import { serveStatelessMcp } from "./hosted-transport.js";
+import { keylessClient, serveStatelessMcp } from "./hosted-transport.js";
 import { createIrisServer } from "./server.js";
 /** One hosted MCP request: a per-request client and server over the stateless transport. */
 export function handleHostedMcpRequest(request, options) {
@@ -7,3 +7,17 @@ export function handleHostedMcpRequest(request, options) {
     const server = createIrisServer({ client, version: options.version, profile: "hosted" });
     return serveStatelessMcp(server, request);
 }
+/**
+ * One keyless discovery request (initialize, tools/list): the same hosted server and tool list,
+ * built on a client that cannot make a REST call. The host checks the request with
+ * isDiscoveryRequest first; anything else needs a key and goes to handleHostedMcpRequest.
+ */
+export function handleHostedMcpDiscovery(request, options) {
+    const server = createIrisServer({
+        client: keylessClient(),
+        version: options.version,
+        profile: "hosted",
+    });
+    return serveStatelessMcp(server, request);
+}
+export { isDiscoveryPayload, isDiscoveryRequest } from "./hosted-transport.js";

package/dist/server.js

@@ -18,6 +18,7 @@ import { registerUsageTools } from "./tools/usage.js";
 import { registerAutopilotTools } from "./tools/autopilot.js";
 import { registerResponderTools } from "./tools/responder.js";
 import { registerAudienceTools } from "./tools/audiences.js";
+import { registerAffiliateTools } from "./tools/affiliate.js";
 export function createIrisServer({ client, version, profile }) {
     const server = new McpServer({ name: "iris", version });
     const registrar = createPolicyRegistrar(server, TOOL_POLICY, profile);
@@ -36,6 +37,7 @@ export function createIrisServer({ client, version, profile }) {
     registerAgentCreditTools(registrar, client);
     registerUsageTools(registrar, client);
     registerAutopilotTools(registrar, client);
+    registerAffiliateTools(registrar, client);
     registerResponderTools(registrar, client);
     registerAudienceTools(registrar, client);
     return server;

package/dist/tool-policy.d.ts

@@ -1,9 +1,9 @@
 import { type PolicyTable, type ToolClass, type ToolPolicy, type ToolProfile } from "./policy.js";
 export type { ToolClass, ToolPolicy, ToolProfile };
-export declare const TOOL_CATEGORIES: readonly ["campaigns", "contacts", "conversations", "messages", "channels", "discovery", "audiences", "autopilot", "responder", "ai", "analytics", "notifications", "usage", "billing", "credits", "API keys", "webhooks"];
+export declare const TOOL_CATEGORIES: readonly ["campaigns", "contacts", "conversations", "messages", "channels", "discovery", "audiences", "autopilot", "responder", "ai", "analytics", "notifications", "usage", "billing", "credits", "affiliate", "API keys", "webhooks"];
 export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
 export declare const TOOL_POLICY: PolicyTable<ToolCategory>;
-export declare const toolPolicy: (name: string) => ToolPolicy<"campaigns" | "contacts" | "usage" | "messages" | "conversations" | "discovery" | "ai" | "webhooks" | "notifications" | "analytics" | "billing" | "channels" | "credits" | "responder" | "audiences" | "autopilot" | "API keys">;
+export declare const toolPolicy: (name: string) => ToolPolicy<"campaigns" | "contacts" | "usage" | "messages" | "conversations" | "discovery" | "ai" | "webhooks" | "notifications" | "analytics" | "billing" | "channels" | "credits" | "responder" | "affiliate" | "audiences" | "autopilot" | "API keys">;
 export declare const isToolEnabled: (name: string, profile: ToolProfile) => boolean;
 export declare const toolAnnotations: (name: string) => {
     readOnlyHint: boolean;

package/dist/tool-policy.js

@@ -15,6 +15,7 @@ export const TOOL_CATEGORIES = [
     "usage",
     "billing",
     "credits",
+    "affiliate",
     "API keys",
     "webhooks",
 ];
@@ -126,6 +127,8 @@ export const TOOL_POLICY = {
     get_usage: hosted("usage", "read"),
     get_changelog: hosted("usage", "read"),
     get_billing_plans: hosted("billing", "read"),
+    // affiliate program (hosted tool set is frozen: npm package only)
+    get_affiliate: localOnly("affiliate", "read"),
     // credits (agent payments: never hosted)
     get_credit_balance: localOnly("credits", "read"),
     purchase_credit_pack: localOnly("credits", "sensitive"),

package/dist/tools/affiliate.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { IrisClient } from "../client.js";
+export declare function registerAffiliateTools(server: McpServer, client: IrisClient): void;

package/dist/tools/affiliate.js

@@ -0,0 +1,12 @@
+import { formatMcpError } from "../cli-utils.js";
+export function registerAffiliateTools(server, client) {
+    server.tool("get_affiliate", 'the user\'s affiliate status ("none" if they have not applied), code and link, sign-up count, commission totals in US cents (in the hold, payable, paid out), and the program terms. read-only; applying is done in the app at /settings/affiliate. requires read scope.', {}, async () => {
+        try {
+            const result = await client.get("/affiliate");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.23.1",
+	"version": "0.24.0",
 	"mcpName": "io.github.JCLVSH/iris",
 	"description": "MCP server for the Iris API",
 	"repository": {