@polar-sh/sdk 0.30.0 → 0.32.0

package/src/mcp-server/prompts.ts

@@ -0,0 +1,110 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
+import {
+  objectOutputType,
+  ZodOptional,
+  ZodType,
+  ZodTypeAny,
+  ZodTypeDef,
+} from "zod";
+import { PolarCore } from "../core.js";
+import { ConsoleLogger } from "./console-logger.js";
+import { MCPScope } from "./scopes.js";
+
+// '@modelcontextprotocol/sdk' currently does not export this type
+export type PromptArgsRawShape = {
+  [k: string]:
+    | ZodType<string, ZodTypeDef, string>
+    | ZodOptional<ZodType<string, ZodTypeDef, string>>;
+};
+
+export type PromptDefinition<
+  Args extends undefined | PromptArgsRawShape = undefined,
+> = Args extends PromptArgsRawShape ? {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args: Args;
+    prompt: (
+      client: PolarCore,
+      args: objectOutputType<Args, ZodTypeAny>,
+      extra: RequestHandlerExtra,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  }
+  : {
+    name: string;
+    description?: string;
+    scopes?: MCPScope[];
+    args?: undefined;
+    prompt: (
+      client: PolarCore,
+      extra: RequestHandlerExtra,
+    ) => GetPromptResult | Promise<GetPromptResult>;
+  };
+
+// Optional function to assist with formatting prompt results
+export async function formatResult(value: string): Promise<GetPromptResult> {
+  return {
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: value,
+        },
+      },
+    ],
+  };
+}
+
+export function createRegisterPrompt(
+  logger: ConsoleLogger,
+  server: McpServer,
+  sdk: PolarCore,
+  allowedScopes: Set<MCPScope>,
+): <A extends PromptArgsRawShape | undefined>(
+  prompt: PromptDefinition<A>,
+) => void {
+  return <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ): void => {
+    const scopes = prompt.scopes ?? [];
+    if (!scopes.every((s: MCPScope) => allowedScopes.has(s))) {
+      return;
+    }
+
+    if (prompt.args) {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(sdk, args, ctx),
+        );
+      } else {
+        server.prompt(
+          prompt.name,
+          prompt.args,
+          async (args, ctx) => prompt.prompt(sdk, args, ctx),
+        );
+      }
+    } else {
+      if (prompt.description) {
+        server.prompt(
+          prompt.name,
+          prompt.description,
+          async (ctx) => prompt.prompt(sdk, ctx),
+        );
+      } else {
+        server.prompt(prompt.name, async (ctx) => prompt.prompt(sdk, ctx));
+      }
+    }
+
+    logger.debug("Registered prompt", { name: prompt.name });
+  };
+}

package/src/mcp-server/resources.ts

@@ -46,6 +46,7 @@ export type ResourceTemplateDefinition = {
   read: ReadResourceTemplateCallback;
 };
 
+// Optional function to assist with formatting resource results
 export async function formatResult(
   value: unknown,
   uri: URL,

package/src/mcp-server/server.ts

@@ -6,6 +6,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PolarCore } from "../core.js";
 import { SDKOptions } from "../lib/config.js";
 import type { ConsoleLogger } from "./console-logger.js";
+import { createRegisterPrompt } from "./prompts.js";
 import {
   createRegisterResource,
   createRegisterResourceTemplate,
@@ -48,7 +49,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "Polar",
-    version: "0.30.0",
+    version: "0.32.0",
   });
 
   const client = new PolarCore({
@@ -74,7 +75,8 @@ export function createMCPServer(deps: {
     client,
     scopes,
   );
-  const register = { tool, resource, resourceTemplate };
+  const prompt = createRegisterPrompt(deps.logger, server, client, scopes);
+  const register = { tool, resource, resourceTemplate, prompt };
   void register; // suppress unused warnings
 
   tool(tool$subscriptionsList);

package/src/mcp-server/tools/customersCreate.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersCreate: ToolDefinition<typeof args> = {
-  name: "customers_create",
+  name: "customers-create",
   description: `Create Customer
 
 Create a customer.

package/src/mcp-server/tools/customersDelete.ts

@@ -11,12 +11,22 @@ const args = {
 };
 
 export const tool$customersDelete: ToolDefinition<typeof args> = {
-  name: "customers_delete",
+  name: "customers-delete",
   description: `Delete Customer
 
 Delete a customer.
 
-Immediately cancels any active subscriptions and revokes any active benefits.
+This action cannot be undone and will immediately:
+- Cancel any active subscriptions for the customer
+- Revoke all their benefits
+- Clear any \`external_id\`
+
+Use it only in the context of deleting a user within your
+own service. Otherwise, use more granular API endpoints to cancel
+a specific subscription or revoke certain benefits.
+
+Note: The customers information will nonetheless be retained for historic
+orders and subscriptions.
 
 **Scopes**: \`customers:write\``,
   scopes: ["write", "customers"],

package/src/mcp-server/tools/customersDeleteExternal.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersDeleteExternal: ToolDefinition<typeof args> = {
-  name: "customers_delete-external",
+  name: "customers-delete-external",
   description: `Delete Customer by External ID
 
 Delete a customer by external ID.

package/src/mcp-server/tools/customersGet.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersGet: ToolDefinition<typeof args> = {
-  name: "customers_get",
+  name: "customers-get",
   description: `Get Customer
 
 Get a customer by ID.

package/src/mcp-server/tools/customersGetExternal.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersGetExternal: ToolDefinition<typeof args> = {
-  name: "customers_get-external",
+  name: "customers-get-external",
   description: `Get Customer by External ID
 
 Get a customer by external ID.

package/src/mcp-server/tools/customersGetState.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersGetState: ToolDefinition<typeof args> = {
-  name: "customers_get-state",
+  name: "customers-get-state",
   description: `Get Customer State
 
 Get a customer state by ID.

package/src/mcp-server/tools/customersGetStateExternal.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersGetStateExternal: ToolDefinition<typeof args> = {
-  name: "customers_get-state-external",
+  name: "customers-get-state-external",
   description: `Get Customer State by External ID
 
 Get a customer state by external ID.

package/src/mcp-server/tools/customersList.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersList: ToolDefinition<typeof args> = {
-  name: "customers_list",
+  name: "customers-list",
   description: `List Customers
 
 List customers.

package/src/mcp-server/tools/customersUpdate.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersUpdate: ToolDefinition<typeof args> = {
-  name: "customers_update",
+  name: "customers-update",
   description: `Update Customer
 
 Update a customer.

package/src/mcp-server/tools/customersUpdateExternal.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$customersUpdateExternal: ToolDefinition<typeof args> = {
-  name: "customers_update-external",
+  name: "customers-update-external",
   description: `Update Customer by External ID
 
 Update a customer by external ID.

package/src/mcp-server/tools/metricsGet.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$metricsGet: ToolDefinition<typeof args> = {
-  name: "metrics_get",
+  name: "metrics-get",
   description: `Get Metrics
 
 Get metrics about your orders and subscriptions.

package/src/mcp-server/tools/metricsLimits.ts

@@ -6,7 +6,7 @@ import { metricsLimits } from "../../funcs/metricsLimits.js";
 import { formatResult, ToolDefinition } from "../tools.js";
 
 export const tool$metricsLimits: ToolDefinition = {
-  name: "metrics_limits",
+  name: "metrics-limits",
   description: `Get Metrics Limits
 
 Get the interval limits for the metrics endpoint.

package/src/mcp-server/tools/ordersGet.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$ordersGet: ToolDefinition<typeof args> = {
-  name: "orders_get",
+  name: "orders-get",
   description: `Get Order
 
 Get an order by ID.

package/src/mcp-server/tools/ordersInvoice.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$ordersInvoice: ToolDefinition<typeof args> = {
-  name: "orders_invoice",
+  name: "orders-invoice",
   description: `Get Order Invoice
 
 Get an order's invoice data.

package/src/mcp-server/tools/ordersList.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$ordersList: ToolDefinition<typeof args> = {
-  name: "orders_list",
+  name: "orders-list",
   description: `List Orders
 
 List orders.

package/src/mcp-server/tools/productsCreate.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$productsCreate: ToolDefinition<typeof args> = {
-  name: "products_create",
+  name: "products-create",
   description: `Create Product
 
 Create a product.

package/src/mcp-server/tools/productsGet.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$productsGet: ToolDefinition<typeof args> = {
-  name: "products_get",
+  name: "products-get",
   description: `Get Product
 
 Get a product by ID.

package/src/mcp-server/tools/productsList.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$productsList: ToolDefinition<typeof args> = {
-  name: "products_list",
+  name: "products-list",
   description: `List Products
 
 List products.

package/src/mcp-server/tools/productsUpdate.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$productsUpdate: ToolDefinition<typeof args> = {
-  name: "products_update",
+  name: "products-update",
   description: `Update Product
 
 Update a product.

package/src/mcp-server/tools/productsUpdateBenefits.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$productsUpdateBenefits: ToolDefinition<typeof args> = {
-  name: "products_update-benefits",
+  name: "products-update-benefits",
   description: `Update Product Benefits
 
 Update benefits granted by a product.

package/src/mcp-server/tools/subscriptionsExport.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$subscriptionsExport: ToolDefinition<typeof args> = {
-  name: "subscriptions_export",
+  name: "subscriptions-export",
   description: `Export Subscriptions
 
 Export subscriptions as a CSV file.

package/src/mcp-server/tools/subscriptionsGet.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$subscriptionsGet: ToolDefinition<typeof args> = {
-  name: "subscriptions_get",
+  name: "subscriptions-get",
   description: `Get Subscription
 
 Get a subscription by ID.

package/src/mcp-server/tools/subscriptionsList.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$subscriptionsList: ToolDefinition<typeof args> = {
-  name: "subscriptions_list",
+  name: "subscriptions-list",
   description: `List Subscriptions
 
 List subscriptions.

package/src/mcp-server/tools/subscriptionsRevoke.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$subscriptionsRevoke: ToolDefinition<typeof args> = {
-  name: "subscriptions_revoke",
+  name: "subscriptions-revoke",
   description: `Revoke Subscription
 
 Revoke a subscription, i.e cancel immediately.

package/src/mcp-server/tools/subscriptionsUpdate.ts

@@ -11,7 +11,7 @@ const args = {
 };
 
 export const tool$subscriptionsUpdate: ToolDefinition<typeof args> = {
-  name: "subscriptions_update",
+  name: "subscriptions-update",
   description: `Update Subscription
 
 Update a subscription.

package/src/mcp-server/tools.ts

@@ -34,6 +34,7 @@ export type ToolDefinition<Args extends undefined | ZodRawShape = undefined> =
       ) => CallToolResult | Promise<CallToolResult>;
     };
 
+// Optional function to assist with formatting tool results
 export async function formatResult(
   value: unknown,
   init: { response?: Response | undefined },
@@ -102,6 +103,10 @@ export function createRegisterTool(
     }
 
     const toolScopes = tool.scopes ?? [];
+    if (allowedScopes.size > 0 && toolScopes.length === 0) {
+      return;
+    }
+
     if (!toolScopes.every((s) => allowedScopes.has(s))) {
       return;
     }

package/src/models/components/benefitgithubrepositorycreateproperties.ts

@@ -12,7 +12,7 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 /**
  * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
  */
-export const Permission = {
+export const BenefitGitHubRepositoryCreatePropertiesPermission = {
   Pull: "pull",
   Triage: "triage",
   Push: "push",
@@ -22,7 +22,9 @@ export const Permission = {
 /**
  * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
  */
-export type Permission = ClosedEnum<typeof Permission>;
+export type BenefitGitHubRepositoryCreatePropertiesPermission = ClosedEnum<
+  typeof BenefitGitHubRepositoryCreatePropertiesPermission
+>;
 
 /**
  * Properties to create a benefit of type `github_repository`.
@@ -39,26 +41,30 @@ export type BenefitGitHubRepositoryCreateProperties = {
   /**
    * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
    */
-  permission: Permission;
+  permission: BenefitGitHubRepositoryCreatePropertiesPermission;
 };
 
 /** @internal */
-export const Permission$inboundSchema: z.ZodNativeEnum<typeof Permission> = z
-  .nativeEnum(Permission);
+export const BenefitGitHubRepositoryCreatePropertiesPermission$inboundSchema:
+  z.ZodNativeEnum<typeof BenefitGitHubRepositoryCreatePropertiesPermission> = z
+    .nativeEnum(BenefitGitHubRepositoryCreatePropertiesPermission);
 
 /** @internal */
-export const Permission$outboundSchema: z.ZodNativeEnum<typeof Permission> =
-  Permission$inboundSchema;
+export const BenefitGitHubRepositoryCreatePropertiesPermission$outboundSchema:
+  z.ZodNativeEnum<typeof BenefitGitHubRepositoryCreatePropertiesPermission> =
+    BenefitGitHubRepositoryCreatePropertiesPermission$inboundSchema;
 
 /**
  * @internal
  * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
  */
-export namespace Permission$ {
-  /** @deprecated use `Permission$inboundSchema` instead. */
-  export const inboundSchema = Permission$inboundSchema;
-  /** @deprecated use `Permission$outboundSchema` instead. */
-  export const outboundSchema = Permission$outboundSchema;
+export namespace BenefitGitHubRepositoryCreatePropertiesPermission$ {
+  /** @deprecated use `BenefitGitHubRepositoryCreatePropertiesPermission$inboundSchema` instead. */
+  export const inboundSchema =
+    BenefitGitHubRepositoryCreatePropertiesPermission$inboundSchema;
+  /** @deprecated use `BenefitGitHubRepositoryCreatePropertiesPermission$outboundSchema` instead. */
+  export const outboundSchema =
+    BenefitGitHubRepositoryCreatePropertiesPermission$outboundSchema;
 }
 
 /** @internal */
@@ -69,7 +75,7 @@ export const BenefitGitHubRepositoryCreateProperties$inboundSchema: z.ZodType<
 > = z.object({
   repository_owner: z.string(),
   repository_name: z.string(),
-  permission: Permission$inboundSchema,
+  permission: BenefitGitHubRepositoryCreatePropertiesPermission$inboundSchema,
 }).transform((v) => {
   return remap$(v, {
     "repository_owner": "repositoryOwner",
@@ -92,7 +98,7 @@ export const BenefitGitHubRepositoryCreateProperties$outboundSchema: z.ZodType<
 > = z.object({
   repositoryOwner: z.string(),
   repositoryName: z.string(),
-  permission: Permission$outboundSchema,
+  permission: BenefitGitHubRepositoryCreatePropertiesPermission$outboundSchema,
 }).transform((v) => {
   return remap$(v, {
     repositoryOwner: "repository_owner",

package/src/models/components/benefitgithubrepositoryproperties.ts

@@ -12,7 +12,7 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 /**
  * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
  */
-export const BenefitGitHubRepositoryPropertiesPermission = {
+export const Permission = {
   Pull: "pull",
   Triage: "triage",
   Push: "push",
@@ -22,9 +22,7 @@ export const BenefitGitHubRepositoryPropertiesPermission = {
 /**
  * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
  */
-export type BenefitGitHubRepositoryPropertiesPermission = ClosedEnum<
-  typeof BenefitGitHubRepositoryPropertiesPermission
->;
+export type Permission = ClosedEnum<typeof Permission>;
 
 /**
  * Properties for a benefit of type `github_repository`.
@@ -41,7 +39,7 @@ export type BenefitGitHubRepositoryProperties = {
   /**
    * The permission level to grant. Read more about roles and their permissions on [GitHub documentation](https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role).
    */
-  permission: BenefitGitHubRepositoryPropertiesPermission;
+  permission: Permission;
   /**
    * @deprecated field: This will be removed in a future release, please migrate away from it as soon as possible.
    */
@@ -49,26 +47,22 @@ export type BenefitGitHubRepositoryProperties = {
 };
 
 /** @internal */
-export const BenefitGitHubRepositoryPropertiesPermission$inboundSchema:
-  z.ZodNativeEnum<typeof BenefitGitHubRepositoryPropertiesPermission> = z
-    .nativeEnum(BenefitGitHubRepositoryPropertiesPermission);
+export const Permission$inboundSchema: z.ZodNativeEnum<typeof Permission> = z
+  .nativeEnum(Permission);
 
 /** @internal */
-export const BenefitGitHubRepositoryPropertiesPermission$outboundSchema:
-  z.ZodNativeEnum<typeof BenefitGitHubRepositoryPropertiesPermission> =
-    BenefitGitHubRepositoryPropertiesPermission$inboundSchema;
+export const Permission$outboundSchema: z.ZodNativeEnum<typeof Permission> =
+  Permission$inboundSchema;
 
 /**
  * @internal
  * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
  */
-export namespace BenefitGitHubRepositoryPropertiesPermission$ {
-  /** @deprecated use `BenefitGitHubRepositoryPropertiesPermission$inboundSchema` instead. */
-  export const inboundSchema =
-    BenefitGitHubRepositoryPropertiesPermission$inboundSchema;
-  /** @deprecated use `BenefitGitHubRepositoryPropertiesPermission$outboundSchema` instead. */
-  export const outboundSchema =
-    BenefitGitHubRepositoryPropertiesPermission$outboundSchema;
+export namespace Permission$ {
+  /** @deprecated use `Permission$inboundSchema` instead. */
+  export const inboundSchema = Permission$inboundSchema;
+  /** @deprecated use `Permission$outboundSchema` instead. */
+  export const outboundSchema = Permission$outboundSchema;
 }
 
 /** @internal */
@@ -79,7 +73,7 @@ export const BenefitGitHubRepositoryProperties$inboundSchema: z.ZodType<
 > = z.object({
   repository_owner: z.string(),
   repository_name: z.string(),
-  permission: BenefitGitHubRepositoryPropertiesPermission$inboundSchema,
+  permission: Permission$inboundSchema,
   repository_id: z.nullable(z.string()).optional(),
 }).transform((v) => {
   return remap$(v, {
@@ -105,7 +99,7 @@ export const BenefitGitHubRepositoryProperties$outboundSchema: z.ZodType<
 > = z.object({
   repositoryOwner: z.string(),
   repositoryName: z.string(),
-  permission: BenefitGitHubRepositoryPropertiesPermission$outboundSchema,
+  permission: Permission$outboundSchema,
   repositoryId: z.nullable(z.string()).optional(),
 }).transform((v) => {
   return remap$(v, {