purchase

Instructions

Implementation Reference

• src/tools/billing.ts:72-104 (handler)

  The main tool handler for 'purchase'. Registers the tool with server.registerTool, defines input schema (package enum: pkg_100, pkg_500, pkg_2000, pkg_10000), validates auth, calls api.purchase(args.package), and returns the Stripe Checkout URL.

    // --- purchase ---
    server.registerTool(
      "purchase",
      {
        description: `Purchase pipeline check credits. Returns a Stripe Checkout URL that the user must open in a browser to complete payment.
  
  The AI cannot complete the payment. Tell the user to open the URL in their browser, complete the Stripe checkout, and then confirm they've paid. Credits are added to the account automatically once Stripe confirms payment.
  
  After purchase, use get_balance to verify credits have been added.`,
        inputSchema: {
          package: z
            .enum(["pkg_100", "pkg_500", "pkg_2000", "pkg_10000"])
            .describe(
              "Package to purchase: pkg_100 ($9, 100 credits), pkg_500 ($39, 500 credits), pkg_2000 ($99, 2000 credits), pkg_10000 ($399, 10000 credits)"
            ),
        },
      },
      async (args) => {
        if (!api.hasApiKey) return authError();
  
        try {
          const result = await api.purchase(args.package);
          return successResult({
            ...result,
            _note:
              "The user must open this URL in a browser to complete payment. Credits are added automatically after Stripe confirms payment.",
          });
        } catch (err) {
          if (err instanceof ApiRequestError) return apiErrorToResult(err);
          return errorResult(err instanceof Error ? err.message : "Unknown error");
        }
      }
    );

• src/tools/billing.ts:72-87 (schema)

  Input schema for the purchase tool. Uses Zod to define a 'package' parameter as an enum of four package IDs (pkg_100, pkg_500, pkg_2000, pkg_10000) with descriptions including prices and credit counts.

    // --- purchase ---
    server.registerTool(
      "purchase",
      {
        description: `Purchase pipeline check credits. Returns a Stripe Checkout URL that the user must open in a browser to complete payment.
  
  The AI cannot complete the payment. Tell the user to open the URL in their browser, complete the Stripe checkout, and then confirm they've paid. Credits are added to the account automatically once Stripe confirms payment.
  
  After purchase, use get_balance to verify credits have been added.`,
        inputSchema: {
          package: z
            .enum(["pkg_100", "pkg_500", "pkg_2000", "pkg_10000"])
            .describe(
              "Package to purchase: pkg_100 ($9, 100 credits), pkg_500 ($39, 500 credits), pkg_2000 ($99, 2000 credits), pkg_10000 ($399, 10000 credits)"
            ),
        },

• src/api.ts:195-199 (helper)

  The api.purchase() method in the UnphurlAPI class. Makes an HTTP POST request to /v1/purchase with the package ID in the request body and returns a PurchaseResponse containing the checkout_url.

  async purchase(packageId: string): Promise<PurchaseResponse> {
    return this.doRequest<PurchaseResponse>("POST", "/v1/purchase", {
      package: packageId,
    });
  }

• src/types.ts:185-192 (schema)

  TypeScript interface PurchaseResponse defining the return type: checkout_url (string) and package details (id, credits, price).

  export interface PurchaseResponse {
    checkout_url: string;
    package: {
      id: string;
      credits: number;
      price: string;
    };
  }

• src/index.ts:38-38 (registration)

  Registration call: registerBillingTools(server, api) in the main server entry point which registers get_balance, get_pricing, and purchase tools.

  registerBillingTools(server, api); // get_balance, get_pricing, purchase