Client API Reference

Client API Reference

Every method below lives on the object returned by createClient(config).

listArticles

listArticles(params?: ListArticlesParams): Promise<RankHikerArticleSummary[]>

Returns an array of article summaries, sorted by publishedAt descending. Defaults to status: 'published' and limit: 50 (server-side). Each summary includes the full HTML content but omits tableOfContents, faq, and keyTakeaways.

const posts = await rh.listArticles({ limit: 10 });
for (const post of posts) {
  console.log(post.title, post.slug);
}

listArticlesRaw

listArticlesRaw(params?: ListArticlesParams): Promise<ListArticlesResponse>

Same as listArticles, but returns the full envelope { articles, syncedAt }. Use it for incremental sync when you want the server's syncedAt timestamp.

const { articles, syncedAt } = await rh.listArticlesRaw({ since: lastSync });
saveCursor(syncedAt);

getArticleBySlug

getArticleBySlug(slug: string, params?: GetArticleParams): Promise<RankHikerArticle | null>

Fetches one full article by slug, including tableOfContents, faq, keyTakeaways, views, and wordCount. Returns null when the article is not found (HTTP 404). Other failures throw a RankHikerError. Throws immediately if slug is empty. Defaults to status: 'published'.

const post = await rh.getArticleBySlug('my-slug');
if (!post) {
  // 404: render a not-found page
} else {
  console.log(post.title, post.wordCount, post.tableOfContents.length);
}

getArticleById

getArticleById(id: string): Promise<RankHikerArticleSummary | null>

Fetches one article by its id. There is no id-based endpoint, so this is implemented as a list filter (it lists articles and finds the matching id). It returns a RankHikerArticleSummary (no toc/faq/keyTakeaways) or null. Prefer getArticleBySlug when you have the slug, since it is a single direct lookup and returns the full article.

const post = await rh.getArticleById('665f0c...');

request

request<T>(path: string, query?: Record<string, unknown>): Promise<T>

Low-level GET escape hatch. It builds the URL from baseUrl + path, drops undefined, null, and empty-string query values, attaches the X-API-Key header, parses the JSON response, and throws a RankHikerError on any non-2xx status. Most callers should use the typed methods above; reach for request only for advanced needs.

const data = await rh.request<ListArticlesResponse>('/api/articles/export', { limit: 5 });