**HyCom API**
A lightweight TypeScript client for the [HyCom](https://hycom.ir) public API. This package provides convenient functions to fetch authors, posts, tags, site statistics, and QR codes, handling all network requests internally.
---
## Features
* Fetch top authors by views
* Retrieve posts by author
* List popular tags
* Explore and search posts with pagination and sorting
* Get site-wide statistics
* Generate QR codes for any URL
---
## Installation
Install via npm or yarn:
```bash
npm install @persian-caesar/hycom-api
# or
yarn add @persian-caesar/hycom-api
```
---
## Quick Start
```ts
import {
topAuthors,
authorPosts,
getTags,
explore,
websiteInformation,
lastPosts,
qrCode
} from '@persian-caesar/hycom-api';
async function main() {
// 1. Get top 5 authors by view count
const authors = await topAuthors(5);
console.log('Top Authors:', authors);
// 2. Retrieve latest posts by a specific author
const postsByAuthor = await authorPosts('SobhanSRZA-1637', 10, 'newest');
console.log("John Doe's Posts:", postsByAuthor);
// 3. List 15 most popular tags
const tags = await getTags(15);
console.log('Tags:', tags);
// 4. Explore posts: page 2, sorted by most viewed, filtered by 'javascript'
const exploreResults = await explore('', 2, 12, 'most_viewed', 'javascript');
console.log('Explore Results:', exploreResults);
// 5. Fetch site information
const siteInfo = await websiteInformation();
console.log('Site Information:', siteInfo);
// 6. Get the 8 most recent posts
const recent = await lastPosts(8);
console.log('Recent Posts:', recent);
// 7. Generate a QR code for a URL
const qrBuffer = await qrCode('https://example.com');
// Save the QR buffer to disk in Node.js
import * as fs from 'fs';
fs.writeFileSync('qrcode.png', qrBuffer);
console.log('QR code saved!');
}
main().catch(console.error);
```
## Usage in JavaScript
If you're using plain JavaScript (CommonJS), import and use the library like this:
```js
const {
topAuthors,
authorPosts,
getTags,
explore,
websiteInformation,
lastPosts,
qrCode
} = require('@persian-caesar/hycom-api');
(async () => {
try {
// Example: fetch top 3 authors
const authors = await topAuthors(3);
console.log('Top 3 Authors:', authors);
// Fetch posts by author 'jane-doe-456'
const posts = await authorPosts('jane-doe-456', 5, 'most_viewed');
console.log("Jane Doe's Posts:", posts);
// List tags
const tags = await getTags(10);
console.log('Popular Tags:', tags);
// Explore articles with pagination
const exploreResults = await explore('javascript', 1, 8, 'recommended', 'nodejs');
console.log('Explore Results:', exploreResults);
// Site information
const info = await websiteInformation();
console.log('Site Info:', info);
// Last posts
const recent = await lastPosts(6);
console.log('Recent Posts:', recent);
// Generate QR code
const qrBuffer = await qrCode('https://example.com');
const fs = require('fs');
fs.writeFileSync('qrcode_js.png', qrBuffer);
console.log('QR code saved as qrcode_js.png');
} catch (error) {
console.error('Error:', error);
}
})();
```
---
## API Reference
| Function | Description | Parameters | Returns | |
| --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------- |
| `topAuthors(limit?)` | Fetches authors sorted by total views | `limit` (number, default `10`): number of authors to return (1–50) | `Author[]` | |
| `authorPosts(tag, limit?, sort?)` | Retrieves published posts by a given author | `tag` (string): display name and profile ID (e.g., "jane-doe-123")
`limit` (number, default `10`)
`sort` ("newest" | "most\_viewed", default "newest") | `Post[]` |
| `getTags(limit?)` | Returns tags with their associated post counts | `limit` (number, default `20`): number of tags (1–100) | `Tag[]` | |
| `explore(search?, page?, limit?, sort?, tag?)` | Paginated list of articles with filtering and sorting | `search` (string)
`page` (number, default `1`)
`limit` (number, default `12`)
`sort` ("recommended" | | |
| "newest" | | | | |
| "most\_viewed", default "newest")
`tag` (string) | `Post[]` | | | |
| `websiteInformation()` | Site statistics including last post, total views, posts, and authors | — | `SiteInformation` | |
| `lastPosts(limit?)` | Fetches the most recent published posts | `limit` (number, default `10`) | `Post[]` | |
| `qrCode(url)` | Generates a QR code image buffer for the specified URL | `url` (string): URL to encode | `Buffer` | |
---
## Types
All response data types are defined in `types.ts`. Key interfaces include:
* `Author`: metadata about an author (name, profile ID, views)
* `Post`: article information (title, summary, image, stats)
* `Tag`: tag slug and post count
* `WebSiteInformation`: overall site metrics
* `QrCodeResponse`: raw Base64 QR code string
---
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
---
⌨️ Built with ❤️ by **Persian-Caesar**. Don’t forget to ⭐️ the repo!
## Contact
