--- name: clari-sdk-patterns description: | Production-ready Clari API client patterns in Python and TypeScript. Use when building reusable Clari clients, implementing export pipelines, or wrapping the Clari v4 API for team use. Trigger with phrases like "clari API patterns", "clari client wrapper", "clari Python client", "clari TypeScript client". allowed-tools: Read, Write, Edit version: 1.0.0 license: MIT author: Jeremy Longshore tags: [saas, revenue-intelligence, forecasting, clari] compatible-with: claude-code --- # Clari SDK Patterns ## Overview Clari has no official SDK -- build typed wrappers around the v4 REST API. These patterns cover the Export API for forecasts, job polling, and data transformation pipelines. ## Prerequisites - Completed `clari-install-auth` setup - Python 3.10+ (primary) or TypeScript 5+ ## Instructions ### Step 1: Python Client ```python # clari_client.py import os import time import requests from dataclasses import dataclass, field from typing import Optional @dataclass class ClariConfig: api_key: str base_url: str = "https://api.clari.com/v4" poll_interval: int = 5 max_poll_attempts: int = 60 class ClariClient: def __init__(self, config: Optional[ClariConfig] = None): self.config = config or ClariConfig( api_key=os.environ["CLARI_API_KEY"] ) self.session = requests.Session() self.session.headers.update({ "apikey": self.config.api_key, "Content-Type": "text/plain", }) def list_forecasts(self) -> list[dict]: resp = self.session.get(f"{self.config.base_url}/export/forecast/list") resp.raise_for_status() return resp.json()["forecasts"] def export_forecast( self, forecast_name: str, time_period: str, types: list[str] = None, currency: str = "USD", export_format: str = "JSON", ) -> dict: payload = { "timePeriod": time_period, "typesToExport": types or [ "forecast", "quota", "forecast_updated", "adjustment", "crm_total", "crm_closed" ], "currency": currency, "schedule": "NONE", "includeHistorical": False, "exportFormat": export_format, } resp = self.session.post( f"{self.config.base_url}/export/forecast/{forecast_name}", json=payload, ) resp.raise_for_status() return resp.json() def wait_for_job(self, job_id: str) -> dict: for attempt in range(self.config.max_poll_attempts): resp = self.session.get( f"{self.config.base_url}/export/jobs/{job_id}", ) resp.raise_for_status() status = resp.json() if status["status"] == "COMPLETED": return status if status["status"] == "FAILED": raise ClariExportError(f"Job {job_id} failed: {status}") time.sleep(self.config.poll_interval) raise ClariExportError(f"Job {job_id} timed out after {self.config.max_poll_attempts} attempts") def download_export(self, download_url: str) -> dict: resp = requests.get(download_url) resp.raise_for_status() return resp.json() def export_and_download( self, forecast_name: str, time_period: str ) -> dict: job = self.export_forecast(forecast_name, time_period) completed = self.wait_for_job(job["jobId"]) return self.download_export(completed["downloadUrl"]) class ClariExportError(Exception): pass ``` ### Step 2: TypeScript Client ```typescript // clari-client.ts interface ClariConfig { apiKey: string; baseUrl?: string; pollIntervalMs?: number; maxPollAttempts?: number; } interface ForecastExport { entries: ForecastEntry[]; } interface ForecastEntry { ownerName: string; ownerEmail: string; forecastAmount: number; quotaAmount: number; crmTotal: number; crmClosed: number; adjustmentAmount: number; timePeriod: string; } class ClariClient { private apiKey: string; private baseUrl: string; private pollIntervalMs: number; private maxPollAttempts: number; constructor(config: ClariConfig) { this.apiKey = config.apiKey; this.baseUrl = config.baseUrl ?? "https://api.clari.com/v4"; this.pollIntervalMs = config.pollIntervalMs ?? 5000; this.maxPollAttempts = config.maxPollAttempts ?? 60; } private async request(path: string, options?: RequestInit): Promise { const response = await fetch(`${this.baseUrl}${path}`, { ...options, headers: { apikey: this.apiKey, "Content-Type": "text/plain", ...options?.headers, }, }); if (!response.ok) { throw new Error(`Clari API ${response.status}: ${await response.text()}`); } return response.json(); } async listForecasts(): Promise<{ forecasts: any[] }> { return this.request("/export/forecast/list"); } async exportForecast(forecastName: string, timePeriod: string): Promise { return this.request(`/export/forecast/${forecastName}`, { method: "POST", body: JSON.stringify({ timePeriod, typesToExport: ["forecast", "quota", "crm_total", "crm_closed"], currency: "USD", schedule: "NONE", includeHistorical: false, exportFormat: "JSON", }), }); } async exportAndDownload( forecastName: string, timePeriod: string ): Promise { const job = await this.exportForecast(forecastName, timePeriod); const completed = await this.waitForJob(job.jobId); const resp = await fetch(completed.downloadUrl); return resp.json(); } private async waitForJob(jobId: string): Promise { for (let i = 0; i < this.maxPollAttempts; i++) { const status = await this.request(`/export/jobs/${jobId}`); if (status.status === "COMPLETED") return status; if (status.status === "FAILED") throw new Error(`Job failed: ${jobId}`); await new Promise((r) => setTimeout(r, this.pollIntervalMs)); } throw new Error(`Job ${jobId} timed out`); } } ``` ## Error Handling | Status | Meaning | Action | |--------|---------|--------| | 401 | Invalid API key | Regenerate token | | 403 | Insufficient permissions | Admin must grant API access | | 404 | Wrong forecast name | List forecasts first | | 429 | Rate limited | Back off and retry | ## Resources - [Clari API Reference](https://developer.clari.com/documentation/external_spec) - [Clari Community API Guide](https://community.clari.com/product-q-a-6/clari-api-all-you-need-to-know-556) ## Next Steps Apply patterns in `clari-core-workflow-a` for forecast export pipelines. --- Source attribution: Jeremy Longshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 SkillsHub Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: Jeremy Longshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills Attribution basis: Original repository namespace preserved by package mirror Fields of work: Data & Analytics, Marketing, Sales Roles: Data Analyst, Growth Marketer, Marketing Analyst, Product Marketer, Sales Engineer Specialties: API Tools: Clari Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: ef2037a76c56999d8b9601b5c4cb437c10198f8ec8aecd79ac669b358b812e8b Metadata reviewed: 2026-10-27 This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.