docs: document API for supported calendars, currency and countdown ev…

…ent (#23)

* v1.4.3

* docs: document API for supported calendars, currency and countdown event

api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api",
-  "version": "1.3.2",
+  "version": "1.4.3",
   "main": "./src/index.ts",
   "scripts": {
     "start": "node dist/index.js",
@@ -17,7 +17,7 @@
   "dependencies": {
     "dotenv": "^16.4.5",
     "express": "^4.21.1",
-    "world-clockify": "^1.3.3"
+    "world-clockify": "^1.4.3"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",

api/src/controllers/timezone.controller.ts

@@ -6,6 +6,10 @@ import {
   convertTimeZone,
   calculateDuration,
   formatDateInTimeZone,
+  getSupportedCrrency,
+  getSupportedCalendar,
+  formatDateForLocale,
+  getCountdownToEvent,
 } from 'world-clockify';
 
 export const fetchCurrentTimeInZone = async (req: Request, res: Response) => {
@@ -34,6 +38,26 @@ export const fetchSupportedTimezones = async (_req: Request, res: Response) => {
   }
 };
 
+export const fetchSupportedCrrency = async (req: Request, res: Response) => {
+  try {
+    const crrencies = getSupportedCrrency();
+    res.status(200).json({ crrencies });
+  } catch (error) {
+    console.error('Error fetching supported currencies:', error);
+    res.status(500).json({ message: 'Internal server error' });
+  }
+};
+
+export const fetchSupportedCalendar = async (req: Request, res: Response) => {
+  try {
+    const calendar = getSupportedCalendar();
+    res.status(200).json({ calendar });
+  } catch (error) {
+    console.error('Error fetching supported calendar:', error);
+    res.status(500).json({ message: 'Internal server error' });
+  }
+};
+
 export const fetchConvertedTime = async (req: Request, res: Response) => {
   const { date, fromZone, toZone } = req.query;
 
@@ -96,7 +120,7 @@ export const formatDateInTimezone = (req: Request, res: Response) => {
       typeof format === 'string'
     ) {
       const formattedDate = formatDateInTimeZone(date, fromZone, toZone, format);
-      res.json({ formattedDate });
+      res.status(200).json({ formattedDate });
     } else {
       res.status(400).json({ message: 'Invalid parameters' });
     }
@@ -105,3 +129,35 @@ export const formatDateInTimezone = (req: Request, res: Response) => {
     res.status(500).json({ message: 'Internal server error' });
   }
 };
+
+export const formatDateLocale = async (req: Request, res: Response) => {
+  const { dateStr, locale, timezone } = req.query;
+
+  try {
+    if (typeof dateStr === 'string' && typeof locale === 'string' && typeof timezone === 'string') {
+      const formatDateLocale = formatDateForLocale(dateStr, locale, timezone);
+      res.status(200).json({ formatDateLocale });
+    } else {
+      res.status(400).json({ message: 'Invalid parameters' });
+    }
+  } catch (error) {
+    console.error('Error formatting date for local:', error);
+    res.status(500).json({ message: 'Internal server error' });
+  }
+};
+
+export const countDownToEvent = async (req: Request, res: Response) => {
+  const { eventDate, eventTimezone } = req.query;
+
+  try {
+    if (typeof eventDate === 'string' && typeof eventTimezone === 'string') {
+      const countdown = getCountdownToEvent(eventDate, eventTimezone);
+      res.status(200).json({ countdown });
+    } else {
+      res.status(400).json({ message: 'Invalid parameters' });
+    }
+  } catch (error) {
+    console.error('Error getting countdown to event:', error);
+    res.status(500).json({ message: 'Internal server error' });
+  }
+};

api/src/routes/timezone.routes.ts

@@ -6,15 +6,23 @@ import {
   fetchTimeDifference,
   calculateDurationBetweenDates,
   formatDateInTimezone,
+  formatDateLocale,
+  fetchSupportedCrrency,
+  fetchSupportedCalendar,
+  countDownToEvent,
 } from '../controllers/timezone.controller';
 
 const router = express.Router();
 
 router.get('/currenttime', fetchCurrentTimeInZone);
 router.get('/supportedtimezone', fetchSupportedTimezones);
+router.get('/currency', fetchSupportedCrrency);
+router.get('/calendar', fetchSupportedCalendar);
 router.get('/converttimezone', fetchConvertedTime);
 router.get('/timedifference', fetchTimeDifference);
 router.get('/calculateduration', calculateDurationBetweenDates);
 router.get('/formattimezone', formatDateInTimezone);
+router.get('/formatdatelocale', formatDateLocale);
+router.get('/countdownevent', countDownToEvent);
 
 export default router;

docs/api/Introduction.md

@@ -2,7 +2,7 @@ Let’s explore why a user might prefer to use the API endpoints instead of inst
 
 ## Note
 
-Our base URl for the API is `https://world-clockify.com/api/v1/` and all the endpoints are relative to this base URL.
+Our base URl for the API is `https://world-clockify-api.onrender.com/api/v1` and all the endpoints are relative to this base URL.
 
 ## 1. Serverless/Lightweight Client Applications
 

docs/api/fetchSupportedCalendar.md

@@ -0,0 +1,42 @@
+# Get List of Supported Calendar
+
+Fetch the list of all supported calendar.
+
+## Endpoint
+
+```http
+GET /calendar
+```
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/calendar
+```
+
+## Example Response
+
+```json
+{
+  "calendar": [
+    "buddhist",
+    "chinese",
+    "coptic",
+    "dangi",
+    "ethioaa",
+    "ethiopic",
+    "gregory",
+    "hebrew",
+    "indian",
+    "islamic",
+    "islamic-civil",
+    "islamic-rgsa",
+    "islamic-tbla",
+    "islamic-umalqura",
+    "iso8601",
+    "japanese",
+    "persian",
+    "roc"
+  ]
+}
+```

docs/api/fetchSupportedCurrency.md

@@ -0,0 +1,55 @@
+# Get List of Supported Currencies
+
+Fetch the list of all supported currencies.
+
+## Endpoint
+
+```http
+GET /currency
+```
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/currency
+```
+
+## Example Response
+
+```json
+ {
+  "crrencies": [
+    "AED",
+    "AFN",
+    "ALL",
+    "AMD",
+    "ANG",
+    "AOA",
+    "ARS",
+    "AUD",
+    "AWG",
+    "AZN",
+    "BAM",
+    "BBD",
+    "BDT",
+    "BGN",
+    "BHD",
+    "BIF",
+    "BMD",
+    "BND",
+    "BOB",
+    "BRL",
+    "BSD",
+    "BTN",
+    "BWP",
+    "BYN",
+    "BZD",
+    "CAD",
+    "CDF",
+    "CHF",
+    "CLP",
+    "CNY",
+    ... more currencies
+  ]
+}
+```

docs/api/formatDateInLocale.md

@@ -0,0 +1,37 @@
+# 6. Format Date for locale
+
+Format a date/time string according to a locale (e.g. 'en-us', 'fr').
+
+## Endpoint
+
+```http
+GET /formatdatelocale
+```
+
+## Query Parameters
+
+- dateStr (string) - The date/time in ISO format (e.g., "2024-10-17T10:30:00").
+- locale (string) – The locale to format the date/time (e.g., "en-us").
+- timezone (string) – The timezone of the original date/time (e.g., "America/New_York").
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/formatdatelocale?dateStr=2024-10-18T12:00:00&locale=en-us&timezone=Europe/Paris
+```
+
+## Example Response
+
+```json
+{
+  "formatDateLocale": "October 18, 2024 at 12:00 PM GMT+2"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid parameters"
+}
+```

docs/api/getCountdownToEvent.md

@@ -0,0 +1,37 @@
+# Get Count Down To Event
+
+This endpoint returns the count down to the event.
+
+## Endpoint
+
+```bash
+GET /countdownevent
+```
+
+## Query Parameters
+
+- eventDate (string) - The date/time in ISO format (e.g., "2024-10-17T10:30:00").
+- eventTimezone (string) – The timezone of the original event date/time (e.g., "America/New_York").
+
+## Example Request
+
+```http
+https://world-clockify-api.onrender.com/api/v1/countdownevent?eventDate=2024-10-21T15:00:00&eventTimezone=America/New_York
+
+```
+
+## Example Response
+
+```json
+{
+  "countdownToEvent": "3 days, 2 hours, 30 minutes, 0 seconds"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid parameters"
+}
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "world-clockify",
-  "version": "1.3.3",
+  "version": "1.4.3",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,13 +16,15 @@
     "docs",
     "src",
     "LICENSE",
-    "REDME.md"
+    "REDME.md",
+    "package.json"
   ],
   "keywords": [
     "world",
     "clockify",
     "time",
     "zone",
+    "currency",
     "converter"
   ],
   "homepage": "https://shivam-sharma7.github.io/world-clockify/#/",