purchase_list

Instructions

Implementation Reference

• src/tools/purchases.ts:125-143 (handler)

  The _handleTool method handles the 'purchase_list' case (lines 127-143). It calls this.api.getPurchases() with limit (capped at 1000), offset, startdate, enddate, customerId, and appName args, then returns the result as JSON text content.

  private async _handleTool(name: string, args: any) {
    switch (name) {
      case 'purchase_list':
        console.error(`Fetching purchases with params:`, args);
        const purchases = await this.api.getPurchases({
          limit: Math.min(args.limit || 100, 1000),  // Cap at 1000
          offset: args.offset,
          startdate: args.startdate,
          enddate: args.enddate,
          customerId: args.customerId,
          appName: args.appName
        });
        console.error(`Retrieved ${purchases.rows?.length || 0} purchases`);
        return {
          content: [{
            type: "text",
            text: JSON.stringify(purchases, null, 2)
          }]
        };

• src/tools/purchases.ts:96-122 (handler)

  The public handleTool method handles app switching if using master key and appName is provided, then delegates to _handleTool.

  async handleTool(name: string, args: any) {
    const appInfo = this.api.getCurrentAppInfo();
    
    // If using master key and appName is provided, temporarily switch app
    if (appInfo.usingMasterKey && args.appName) {
      const currentApp = appInfo.appName;
      
      // Switch to the requested app
      this.api.switchApp('dummy-api-key', args.appName);
      
      try {
        // Execute the tool with the requested app
        const result = await this._handleTool(name, args);
        
        // Switch back to the original app
        this.api.switchApp('dummy-api-key', currentApp);
        
        return result;
      } catch (error) {
        // Make sure to switch back even if there's an error
        this.api.switchApp('dummy-api-key', currentApp);
        throw error;
      }
    }
    
    return this._handleTool(name, args);
  }

• src/tools/purchases.ts:33-64 (schema)

  The inputSchema for purchase_list defines properties: limit (number), offset (number), startdate (string), enddate (string), customerId (string), and optionally appName (string) when using master key.

  inputSchema: {
    type: "object",
    properties: {
      limit: { 
        type: "number", 
        description: "Maximum number of purchases to return (default: 100, max: 1000)" 
      },
      offset: { 
        type: "number", 
        description: "Number of purchases to skip for pagination" 
      },
      startdate: { 
        type: "string", 
        description: "Filter purchases after this date (ISO format, e.g. 2024-01-01)" 
      },
      enddate: { 
        type: "string", 
        description: "Filter purchases before this date (ISO format, e.g. 2024-12-31)" 
      },
      customerId: { 
        type: "string", 
        description: "Filter purchases by customer ID" 
      },
      ...(appNameRequired ? {
        appName: {
          type: "string",
          description: "Name of the app to fetch data from. Required when using master key."
        }
      } : {})
    },
    required: appNameRequired ? ["appName"] : undefined
  }

• src/tools/purchases.ts:23-41 (registration)

  The tool is registered inside the getTools() method (returned as part of an array). The name is 'purchase_list' with a description listing capabilities like pagination, date filtering, and customer filtering.

      return [
        {
          name: "purchase_list",
          description: `List purchases from your Iaptic account.
  - Returns a paginated list of purchases
  - Use limit and offset for pagination (default: 100 per page)
  - Filter by date range using startdate and enddate (ISO format)
  - Filter by customerId to see purchases from a specific customer
  - Results include purchase status, product info, and transaction details
  - Results are ordered by purchase date (newest first)${appNameRequired ? '\n- Requires appName parameter when using master key' : ''}`,
          inputSchema: {
            type: "object",
            properties: {
              limit: { 
                type: "number", 
                description: "Maximum number of purchases to return (default: 100, max: 1000)" 
              },
              offset: { 
                type: "number", 

• src/iaptic-api.ts:181-188 (helper)

  The getPurchases method on IapticAPI makes the actual HTTP GET request to '/purchases' endpoint, passing pagination and filter params. This is the underlying API call that the purchase_list handler invokes.

  async getPurchases(params?: ListParams & { customerId?: string }) {
    const defaultParams = {
      limit: 100,  // Reasonable default limit
      ...params
    };
    const response = await this.client.get('/purchases', { params: defaultParams });
    return response.data;
  }