Agent skill

maintainx-cost-tuning

Optimize MaintainX API usage for cost efficiency. Use when managing API costs, optimizing request volume, or implementing cost-effective integration patterns with MaintainX. Trigger with phrases like "maintainx cost", "maintainx billing", "reduce maintainx usage", "maintainx api costs", "maintainx optimization".

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/maintainx-cost-tuning

SKILL.md

MaintainX Cost Tuning

Overview

Optimize your MaintainX API usage for cost efficiency while maintaining functionality.

Prerequisites

  • MaintainX integration deployed
  • API usage monitoring in place
  • Understanding of pricing tiers

Cost Optimization Strategies

Strategy Savings Potential Implementation Effort
Caching 40-60% Low
Batch operations 20-30% Medium
Webhook over polling 50-70% Medium
Smart pagination 10-20% Low
Request deduplication 15-25% Low

Instructions

Step 1: API Usage Tracking

typescript
// src/monitoring/api-usage.ts

interface UsageMetric {
  endpoint: string;
  method: string;
  timestamp: Date;
  responseSize: number;
  cached: boolean;
}

class ApiUsageTracker {
  private metrics: UsageMetric[] = [];
  private dailyUsage: Map<string, number> = new Map();

  track(metric: Omit<UsageMetric, 'timestamp'>): void {
    this.metrics.push({
      ...metric,
      timestamp: new Date(),
    });

    // Update daily counter
    const today = new Date().toISOString().split('T')[0];
    const key = `${today}:${metric.endpoint}`;
    this.dailyUsage.set(key, (this.dailyUsage.get(key) || 0) + 1);
  }

  getUsageReport(days = 7): any {
    const now = Date.now();
    const cutoff = now - days * 24 * 60 * 60 * 1000;

    const recentMetrics = this.metrics.filter(
      m => m.timestamp.getTime() > cutoff
    );

    // Group by endpoint
    const byEndpoint: Record<string, number> = {};
    recentMetrics.forEach(m => {
      byEndpoint[m.endpoint] = (byEndpoint[m.endpoint] || 0) + 1;
    });

    // Calculate cache hit rate
    const cacheHits = recentMetrics.filter(m => m.cached).length;
    const cacheHitRate = recentMetrics.length > 0
      ? cacheHits / recentMetrics.length
      : 0;

    // Identify optimization opportunities
    const opportunities = this.identifyOpportunities(byEndpoint, cacheHitRate);

    return {
      period: `${days} days`,
      totalRequests: recentMetrics.length,
      byEndpoint,
      cacheHitRate: `${(cacheHitRate * 100).toFixed(1)}%`,
      estimatedSavings: this.calculateSavings(recentMetrics),
      opportunities,
    };
  }

  private identifyOpportunities(
    byEndpoint: Record<string, number>,
    cacheHitRate: number
  ): string[] {
    const opportunities: string[] = [];

    // High-frequency endpoints that could be cached
    Object.entries(byEndpoint).forEach(([endpoint, count]) => {
      if (count > 1000 && !endpoint.includes('create')) {
        opportunities.push(
          `High volume on ${endpoint} (${count} requests) - consider caching`
        );
      }
    });

    // Low cache hit rate
    if (cacheHitRate < 0.3) {
      opportunities.push(
        `Low cache hit rate (${(cacheHitRate * 100).toFixed(1)}%) - improve caching strategy`
      );
    }

    return opportunities;
  }

  private calculateSavings(metrics: UsageMetric[]): string {
    const totalRequests = metrics.length;
    const cachedRequests = metrics.filter(m => m.cached).length;

    // Estimate cost per request (varies by plan)
    const costPerRequest = 0.001;  // Example: $0.001 per request

    const savedRequests = cachedRequests;
    const savings = savedRequests * costPerRequest;

    return `$${savings.toFixed(2)} saved from ${savedRequests} cached requests`;
  }
}

export const usageTracker = new ApiUsageTracker();

Step 2: Smart Caching Strategy

typescript
// src/cache/smart-cache.ts

interface CacheStrategy {
  ttlSeconds: number;
  staleWhileRevalidate: boolean;
  priority: 'high' | 'medium' | 'low';
}

const cacheStrategies: Record<string, CacheStrategy> = {
  // Static data - cache longer
  'locations': { ttlSeconds: 3600, staleWhileRevalidate: true, priority: 'low' },
  'users': { ttlSeconds: 1800, staleWhileRevalidate: true, priority: 'low' },
  'assets': { ttlSeconds: 900, staleWhileRevalidate: true, priority: 'medium' },

  // Dynamic data - cache shorter
  'workorders:list': { ttlSeconds: 60, staleWhileRevalidate: true, priority: 'high' },
  'workorders:single': { ttlSeconds: 300, staleWhileRevalidate: true, priority: 'medium' },
};

class SmartCache {
  private cache: CacheManager;

  async getOrFetch<T>(
    key: string,
    fetchFn: () => Promise<T>,
    strategyKey: string
  ): Promise<T> {
    const strategy = cacheStrategies[strategyKey] || {
      ttlSeconds: 300,
      staleWhileRevalidate: false,
      priority: 'medium',
    };

    // Try cache first
    const cached = await this.cache.get<T>(key);

    if (cached) {
      usageTracker.track({
        endpoint: strategyKey,
        method: 'GET',
        responseSize: 0,
        cached: true,
      });

      // Stale-while-revalidate: return cached, refresh in background
      if (strategy.staleWhileRevalidate) {
        this.revalidateInBackground(key, fetchFn, strategy);
      }

      return cached;
    }

    // Fetch fresh data
    const data = await fetchFn();

    usageTracker.track({
      endpoint: strategyKey,
      method: 'GET',
      responseSize: JSON.stringify(data).length,
      cached: false,
    });

    // Cache the result
    await this.cache.set(key, data, strategy.ttlSeconds);

    return data;
  }

  private async revalidateInBackground<T>(
    key: string,
    fetchFn: () => Promise<T>,
    strategy: CacheStrategy
  ): Promise<void> {
    // Don't await - runs in background
    fetchFn()
      .then(data => this.cache.set(key, data, strategy.ttlSeconds))
      .catch(err => console.error('Background revalidation failed:', err));
  }
}

Step 3: Webhook-Based Updates

typescript
// src/sync/webhook-sync.ts

// Instead of polling, use webhooks to stay in sync
class WebhookBasedSync {
  private localCache: Map<string, any> = new Map();

  constructor() {
    // Initialize cache from MaintainX on startup
    this.initializeCache();

    // Register webhook handlers
    this.registerWebhookHandlers();
  }

  private async initializeCache(): Promise<void> {
    console.log('Initializing local cache from MaintainX...');

    // One-time full sync
    const workOrders = await getAllWorkOrders(client, { status: 'OPEN' });
    workOrders.forEach(wo => this.localCache.set(`workorder:${wo.id}`, wo));

    console.log(`Cached ${workOrders.length} work orders`);
  }

  private registerWebhookHandlers(): void {
    // Update cache from webhooks instead of polling
    on('workorder.created', async (event) => {
      this.localCache.set(`workorder:${event.data.id}`, event.data);
    });

    on('workorder.updated', async (event) => {
      this.localCache.set(`workorder:${event.data.id}`, event.data);
    });

    on('workorder.deleted', async (event) => {
      this.localCache.delete(`workorder:${event.data.id}`);
    });
  }

  // Get data from cache - no API call needed
  getWorkOrder(id: string): WorkOrder | undefined {
    return this.localCache.get(`workorder:${id}`);
  }

  // Only call API when data doesn't exist locally
  async getWorkOrderWithFallback(id: string): Promise<WorkOrder> {
    const cached = this.localCache.get(`workorder:${id}`);
    if (cached) return cached;

    // Fallback to API
    const workOrder = await client.getWorkOrder(id);
    this.localCache.set(`workorder:${id}`, workOrder);
    return workOrder;
  }
}

// Cost comparison:
// Polling every 30 seconds = 2,880 requests/day = $2.88/day (at $0.001/request)
// Webhooks = ~100 events/day = $0.10/day (at $0.001/request)
// Savings = 96.5%

Step 4: Request Batching

typescript
// src/optimization/batch-requests.ts

// Instead of individual requests, batch where possible
class BatchRequestManager {
  private pendingWorkOrderIds: Set<string> = new Set();
  private batchTimeout: NodeJS.Timeout | null = null;
  private batchResolvers: Map<string, (wo: WorkOrder) => void> = new Map();

  async getWorkOrder(id: string): Promise<WorkOrder> {
    return new Promise((resolve) => {
      this.pendingWorkOrderIds.add(id);
      this.batchResolvers.set(id, resolve);

      // Schedule batch execution
      if (!this.batchTimeout) {
        this.batchTimeout = setTimeout(() => this.executeBatch(), 50);
      }
    });
  }

  private async executeBatch(): Promise<void> {
    const ids = Array.from(this.pendingWorkOrderIds);
    this.pendingWorkOrderIds.clear();
    this.batchTimeout = null;

    if (ids.length === 0) return;

    console.log(`Batching ${ids.length} work order requests`);

    // Fetch all at once (if API supports batch endpoint)
    // Otherwise, parallel fetch with rate limiting
    const workOrders = await Promise.all(
      ids.map(id => client.getWorkOrder(id))
    );

    // Resolve individual promises
    workOrders.forEach((wo, i) => {
      const resolver = this.batchResolvers.get(ids[i]);
      if (resolver) {
        resolver(wo);
        this.batchResolvers.delete(ids[i]);
      }
    });

    // Cost savings: 10 individual requests -> 1 batch = 90% reduction
  }
}

Step 5: Efficient Data Fetching

typescript
// src/optimization/efficient-fetch.ts

// Only fetch what you need
async function fetchMinimalWorkOrderData(
  client: MaintainXClient,
  params: WorkOrderQueryParams
): Promise<WorkOrderSummary[]> {
  const response = await client.getWorkOrders({
    ...params,
    // Request only necessary fields if API supports field selection
    // fields: ['id', 'title', 'status', 'priority', 'dueDate'],
    limit: params.limit || 50,  // Don't over-fetch
  });

  // Transform to minimal objects
  return response.workOrders.map(wo => ({
    id: wo.id,
    title: wo.title,
    status: wo.status,
    priority: wo.priority,
    dueDate: wo.dueDate,
  }));
}

// Pagination with early termination
async function fetchUntilCondition(
  client: MaintainXClient,
  condition: (wo: WorkOrder) => boolean,
  params: WorkOrderQueryParams = {}
): Promise<WorkOrder[]> {
  const results: WorkOrder[] = [];
  let cursor: string | undefined;

  do {
    const response = await client.getWorkOrders({ ...params, cursor, limit: 100 });

    for (const wo of response.workOrders) {
      if (condition(wo)) {
        results.push(wo);
      } else {
        // Early termination - don't fetch more pages
        return results;
      }
    }

    cursor = response.nextCursor || undefined;
  } while (cursor && results.length < 1000);  // Safety limit

  return results;
}

Step 6: Cost Dashboard

typescript
// src/monitoring/cost-dashboard.ts

interface CostReport {
  period: string;
  totalRequests: number;
  estimatedCost: number;
  byEndpoint: Record<string, { count: number; cost: number }>;
  recommendations: string[];
}

function generateCostReport(days = 30): CostReport {
  const usage = usageTracker.getUsageReport(days);

  // Cost per request (adjust based on your plan)
  const costPerRequest = 0.001;

  const byEndpoint: Record<string, { count: number; cost: number }> = {};
  Object.entries(usage.byEndpoint).forEach(([endpoint, count]) => {
    byEndpoint[endpoint] = {
      count: count as number,
      cost: (count as number) * costPerRequest,
    };
  });

  // Sort by cost descending
  const sortedEndpoints = Object.entries(byEndpoint)
    .sort((a, b) => b[1].cost - a[1].cost);

  const recommendations: string[] = [];

  // Top cost endpoint
  if (sortedEndpoints.length > 0) {
    const [topEndpoint, topUsage] = sortedEndpoints[0];
    recommendations.push(
      `Highest cost: ${topEndpoint} ($${topUsage.cost.toFixed(2)}) - ` +
      `Consider caching or webhooks`
    );
  }

  // Low cache hit rate
  const cacheHitRate = parseFloat(usage.cacheHitRate);
  if (cacheHitRate < 50) {
    const potentialSavings = usage.totalRequests * 0.5 * costPerRequest;
    recommendations.push(
      `Cache hit rate is ${cacheHitRate.toFixed(0)}% - ` +
      `Improving to 50% could save $${potentialSavings.toFixed(2)}`
    );
  }

  return {
    period: `${days} days`,
    totalRequests: usage.totalRequests,
    estimatedCost: usage.totalRequests * costPerRequest,
    byEndpoint,
    recommendations,
  };
}

Output

  • API usage tracking implemented
  • Smart caching strategy
  • Webhook-based sync instead of polling
  • Request batching
  • Cost dashboard and reports

Cost Savings Summary

Optimization Before After Savings
Caching 10,000/day 4,000/day 60%
Webhooks vs polling 2,880/day 100/day 97%
Batching 500/day 100/day 80%
Total estimate 13,380/day 4,200/day 69%

Resources

Next Steps

For architecture patterns, see maintainx-reference-architecture.

Didn't find tool you were looking for?

Be as detailed as possible for better results