Skip to content

1.1.0 #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 22, 2025
Merged

1.1.0 #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 13 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,23 +31,22 @@ yarn add @persian-caesar/hycom-api

```ts
import {
topAuthor,
topAuthors,
authorPosts,
getTags,
explore,
siteInformation,
websiteInformation,
lastPosts,
searchPosts,
qrCode
} from '@persian-caesar/hycom-api';

async function main() {
// 1. Get top 5 authors by view count
const authors = await topAuthor(5);
const authors = await topAuthors(5);
console.log('Top Authors:', authors);

// 2. Retrieve latest posts by a specific author
const postsByAuthor = await authorPosts('john-doe', 10, 'newest');
const postsByAuthor = await authorPosts('SobhanSRZA-1637', 10, 'newest');
console.log("John Doe's Posts:", postsByAuthor);

// 3. List 15 most popular tags
Expand All @@ -59,18 +58,14 @@ async function main() {
console.log('Explore Results:', exploreResults);

// 5. Fetch site information
const siteInfo = await siteInformation();
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. Search posts by keyword
const searchResults = await searchPosts('nodejs', 10, 1);
console.log('Search Results:', searchResults);

// 8. Generate a QR code for a URL
// 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';
Expand All @@ -87,20 +82,19 @@ If you're using plain JavaScript (CommonJS), import and use the library like thi

```js
const {
topAuthor,
topAuthors,
authorPosts,
getTags,
explore,
siteInformation,
websiteInformation,
lastPosts,
searchPosts,
qrCode
} = require('@persian-caesar/hycom-api');

(async () => {
try {
// Example: fetch top 3 authors
const authors = await topAuthor(3);
const authors = await topAuthors(3);
console.log('Top 3 Authors:', authors);

// Fetch posts by author 'jane-doe-456'
Expand All @@ -116,17 +110,13 @@ const {
console.log('Explore Results:', exploreResults);

// Site information
const info = await siteInformation();
const info = await websiteInformation();
console.log('Site Info:', info);

// Last posts
const recent = await lastPosts(6);
console.log('Recent Posts:', recent);

// Search posts
const search = await searchPosts('api', 5, 1);
console.log('Search Results:', search);

// Generate QR code
const qrBuffer = await qrCode('https://example.com');
const fs = require('fs');
Expand All @@ -144,15 +134,14 @@ const {

| Function | Description | Parameters | Returns | |
| --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------- |
| `topAuthor(limit?)` | Fetches authors sorted by total views | `limit` (number, default `10`): number of authors to return (1–50) | `Author[]` | |
| `topAuthors(limit?)` | Fetches authors sorted by total views | `limit` (number, default `10`): number of authors to return (1–50) | `Author[]` | |
| `authorPosts(name, limit?, sort?)` | Retrieves published posts by a given author | `name` (string): display name and profile ID (e.g., "jane-doe-123")<br>`limit` (number, default `10`)<br>`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)<br>`page` (number, default `1`)<br>`limit` (number, default `12`)<br>`sort` ("recommended" | | |
| "newest" | | | | |
| "most\_viewed", default "newest")<br>`tag` (string) | `Post[]` | | | |
| `siteInformation()` | Site statistics including last post, total views, posts, and authors | — | `SiteInformation` | |
| `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[]` | |
| `searchPosts(query, limit?, page?)` | Searches posts by title, tags, or author | `query` (string): search term<br>`limit` (number, default `10`)<br>`page` (number, default `1`) | `Post[]` | |
| `qrCode(url)` | Generates a QR code image buffer for the specified URL | `url` (string): URL to encode | `Buffer` | |

---
Expand All @@ -164,7 +153,7 @@ 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
* `SiteInformation`: overall site metrics
* `WebSiteInformation`: overall site metrics
* `QrCodeResponse`: raw Base64 QR code string

---
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@persian-caesar/hycom-api",
"version": "1.0.1",
"version": "1.1.0",
"description": "A package for easy using hycom.ir api service.",
"main": "dist/index.js",
"types": "dist/index.d.ts",
Expand Down
78 changes: 10 additions & 68 deletions src/HyCom.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,9 @@ import {
AuthorPostsResponse,
ExploreResponse,
ExploreSortParametr,
LastPostsResponse,
QrCodeResponse,
SearchPostsResponse,
SiteInformation,
SiteInformationResponse,
WebSiteInformationResponse,
SortParametr,
TagsResponse,
TopAuthorResponse
Expand All @@ -30,7 +28,7 @@ import {
"description": "Returns top authors sorted by total views"
},
{
"endpoint": "/api/author-posts/\u003Cdisplay_name\u003E/",
"endpoint": "/api/author-posts/{display_name}/",
"method": "GET",
"parameters": [
{
Expand Down Expand Up @@ -109,44 +107,6 @@ import {
"parameters": [],
"description": "Returns site statistics including last post, total views, total posts, and total authors"
},
{
"endpoint": "/api/last-posts/",
"method": "GET",
"parameters": [
{
"name": "limit",
"type": "integer",
"default": 10,
"description": "Number of posts to return (1-50)"
}
],
"description": "Returns the most recent published posts"
},
{
"endpoint": "/api/search-posts/",
"method": "GET",
"parameters": [
{
"name": "q",
"type": "string",
"required": true,
"description": "Search query for title, tags, or author"
},
{
"name": "limit",
"type": "integer",
"default": 10,
"description": "Number of posts per page (1-50)"
},
{
"name": "page",
"type": "integer",
"default": 1,
"description": "Page number for pagination"
}
],
"description": "Searches published posts by query"
},
{
"endpoint": "/api/qr-code/",
"method": "GET",
Expand Down Expand Up @@ -180,7 +140,7 @@ const hycom = {
*
* @param limit Number of authors to return. (1-50)
*/
async function topAuthor(limit: number = 10) {
async function topAuthors(limit: number = 10) {
try {
const response = await fetch(hycom.url + hycom.topAuthor + `?limit=${limit}`);
const data: TopAuthorResponse = await response.json();
Expand Down Expand Up @@ -248,14 +208,15 @@ async function explore(search: string = "", page: number = 1, limit: number = 12
/**
* Returns site statistics including last post, total views, total posts, and total authors.
*/
async function siteInformation() {
async function websiteInformation() {
try {
const now = Date.now();
const response = await fetch(hycom.url + hycom.siteInformation);
const data: SiteInformationResponse = await response.json();
const data: WebSiteInformationResponse = await response.json();
const siteInfo = data.data as any as SiteInformation;

siteInfo.ping = Date.now() - now;
siteInfo.last_post = (await lastPosts(1))![0];
return siteInfo;
} catch {
return null;
Expand All @@ -269,26 +230,8 @@ async function siteInformation() {
*/
async function lastPosts(limit: number = 10) {
try {
const response = await fetch(hycom.url + hycom.lastPosts + `?limit=${limit}`);
const data: LastPostsResponse = await response.json();

return data.data;
} catch {
return null;
}
}

/**
* Searches published posts by query.
*
* @param query Search query for title, tags, or author.
* @param limit Number of posts per page. (1-50)
* @param page Page number for pagination.
*/
async function searchPosts(query: string, limit: number = 10, page: number = 1) {
try {
const response = await fetch(hycom.url + hycom.searchPosts + `?q=${query}&limit=${limit}&page=${page}`);
const data: SearchPostsResponse = await response.json();
const response = await fetch(hycom.url + hycom.explore + `?page=1&limit=${limit}&sort=newest`);
const data: ExploreResponse = await response.json();

return data.data;
} catch {
Expand Down Expand Up @@ -317,13 +260,12 @@ async function qrCode(url: string) {
}

export {
topAuthor,
topAuthors,
authorPosts,
getTags,
explore,
siteInformation,
websiteInformation,
lastPosts,
searchPosts,
qrCode
}
/**
Expand Down
26 changes: 4 additions & 22 deletions src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,41 +46,23 @@ export interface ExploreResponse {
}

export interface SiteInformation {
last_post: {
title: string;
url: string;
created_at: string;
},
last_post: Post,
ping: number;
total_tags: number;
total_views: number;
total_posts: number;
total_authors: number;
}
export interface SiteInformationResponse {
export interface WebSiteInformationResponse {
success: boolean;
data: {
last_post: {
title: string;
url: string;
created_at: string;
},
ping: string;
total_tags: number;
total_views: number;
total_posts: number;
total_authors: number;
}
}

export interface LastPostsResponse {
success: boolean;
data: Post[];
}

export interface SearchPostsResponse {
success: boolean;
data: Post[];
}

export interface QrCodeResponse {
success: boolean;
data: {
Expand Down