SDK Reference
The main client for interacting with the Simplist API.
Method Signature
SimplistClient(options?: SimplistClientOptions): SimplistClient| Property | Type | Description | Default |
|---|---|---|---|
apiKey | string | API key for authentication (auto-detected from SIMPLIST_API_KEY env var) | - |
baseUrl | string | Base URL for the API | https://api.simplist.blog |
apiVersion | string | API version to use (e.g., '1', '2'). Automatically adds /v{version}/ prefix to all requests | 1 |
path | string | Global path for article URLs (e.g., 'blog', 'articles') | - |
timeout | number | Request timeout in milliseconds | 10000 |
retries | number | Number of retry attempts for failed requests | 3 |
retryDelay | number | Delay between retries in milliseconds | 1000 |
import { SimplistClient } from "@simplist.blog/sdk"
const client = new SimplistClient({
apiKey: process.env.SIMPLIST_API_KEY,
apiVersion: '1', // Use API v1 (default)
path: 'blog', // Articles will be at yoursite.com/blog/article-slug
timeout: 5000,
retries: 2
})
// Or for future v2 API
const v2Client = new SimplistClient({
apiKey: process.env.SIMPLIST_API_KEY,
apiVersion: '2' // Use API v2
})Test the API connection and validate your API key.
Method Signature
async ping(): Promise<{ status: 'ok', timestamp: string }>const result = await client.ping()
console.log(result.status) // 'ok'
console.log(result.timestamp) // '2025-12-09T10:30:00Z'Use cases:
- Health checks in monitoring systems
- Validating API key before making requests
- Testing API connectivity
The SimplistClient exposes 4 resource modules:
Access the Articles API for fetching and managing articles.
client.articles.list()
client.articles.get('article-slug')See Articles API for full documentation.
Access project information and statistics.
client.project.get()
client.project.getStats()See Project API for full documentation.
Track page views and get analytics data.
client.analytics.track({ slug: 'article-slug' })
client.analytics.getStats({ days: 7 })See Analytics API for full documentation.
Generate sitemaps, RSS feeds, and structured data.
client.seo.getSitemap('https://yourblog.com', 'xml')
client.seo.getRssFeed('https://yourblog.com', 20)See SEO API for full documentation.
import { SimplistClient } from "@simplist.blog/sdk"
// Initialize client
const client = new SimplistClient({
apiKey: process.env.SIMPLIST_API_KEY,
path: 'blog'
})
// Test connection
try {
const health = await client.ping()
console.log('✓ API connection successful')
// Fetch articles
const { data: articles } = await client.articles.list({ limit: 5 })
console.log(`✓ Found ${articles.length} articles`)
// Get project stats
const { project, stats } = await client.project.get()
console.log(`✓ Project: ${project.name}`)
console.log(`✓ Total views: ${stats.totalViews}`)
} catch (error) {
console.error('✗ Error:', error.message)
}All methods can throw SimplistApiError for API errors:
import { SimplistClient, SimplistApiError } from "@simplist.blog/sdk"
// Uses SIMPLIST_API_KEY from environment variables
const client = new SimplistClient()
try {
await client.ping()
} catch (error) {
if (error instanceof SimplistApiError) {
console.error(`API Error [${error.statusCode}]:`, error.message)
console.error(`Details: ${error.details}`)
} else {
console.error(`Network Error: ${error}`)
}
}See Error Handling for more information.
Quick Help
The API key is required. You can pass it via the apiKey option or set the SIMPLIST_API_KEY environment variable. The client will throw an error if no key is found.
Yes, you can create multiple SimplistClient instances with different configurations. This is useful for managing multiple projects or different API keys.
The default timeout is 10 seconds (10000ms). You can customize it by passing the timeout option when creating the client. Max timeout is 60 seconds.