diff --git a/README.md b/README.md index f719565..8ca3f3b 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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'; @@ -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' @@ -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'); @@ -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")
`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[]` | | | | -| `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
`limit` (number, default `10`)
`page` (number, default `1`) | `Post[]` | | | `qrCode(url)` | Generates a QR code image buffer for the specified URL | `url` (string): URL to encode | `Buffer` | | --- @@ -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 --- diff --git a/package.json b/package.json index b42b657..0d52606 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/src/HyCom.ts b/src/HyCom.ts index 236ffe7..65cee9f 100644 --- a/src/HyCom.ts +++ b/src/HyCom.ts @@ -2,11 +2,9 @@ import { AuthorPostsResponse, ExploreResponse, ExploreSortParametr, - LastPostsResponse, QrCodeResponse, - SearchPostsResponse, SiteInformation, - SiteInformationResponse, + WebSiteInformationResponse, SortParametr, TagsResponse, TopAuthorResponse @@ -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": [ { @@ -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", @@ -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(); @@ -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; @@ -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 { @@ -317,13 +260,12 @@ async function qrCode(url: string) { } export { - topAuthor, + topAuthors, authorPosts, getTags, explore, - siteInformation, + websiteInformation, lastPosts, - searchPosts, qrCode } /** diff --git a/src/types.ts b/src/types.ts index 1f36ec0..6575149 100644 --- a/src/types.ts +++ b/src/types.ts @@ -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: {