feat: refactor codebase for better TypeScript annotations and TSDoc documentation (#101)

* feat: refactor codebase for better TypeScript annotations and TSDoc comments

* chore: update node-version for github workflow

* feat: add TypeScript interfaces, types, examples, update README, and improve documentation and unit tests

* feat: add deploy workflow and changelog

Author: ranjanrak

.eslintrc.js

@@ -1,15 +1,19 @@
-module.exports = {
-    env: {
-        browser: true,
-        es2021: true
-    },
-    overrides: [
+module.exports =  {
+    plugins: [
+      "@typescript-eslint/eslint-plugin",
+      "eslint-plugin-tsdoc"
+    ],
+    extends:  [
+      'plugin:@typescript-eslint/recommended'
     ],
+    parser:  '@typescript-eslint/parser',
     parserOptions: {
-        ecmaVersion: "latest",
-        sourceType: "module"
+      project: "./tsconfig.json",
+      tsconfigRootDir: __dirname,
+      ecmaVersion: 2018,
+      sourceType: "module"
     },
     rules: {
-        'quote-props': ['error', 'as-needed'],
+      "tsdoc/syntax": "warn"
     }
-}
+  };

.github/workflows/deploy.yml

@@ -0,0 +1,50 @@
+name: Release, npm publish and deploy gh-pages
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-doc:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - name: Install Dependencies
+        run: |
+          npm install
+          npm install typedoc
+      - name: Building documentation for GitHub Pages
+        run: npx typedoc --out ./docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifacts
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/node-test.yml

@@ -5,7 +5,7 @@ jobs:
   test:
     strategy:
       matrix:
-        node-version: [12.x, 13.x, 14.x]
+        node-version: [18.x, 20.x, 21.x]
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     runs-on: ${{ matrix.os }}
@@ -22,5 +22,5 @@ jobs:
       - name: Install Dependencies
         run: npm install
 
-      - name: Run All Node.js Tests
+      - name: Run All typescript Tests
         run: npm run test

.jsdoc.json

@@ -1,99 +1,38 @@
-# Kite v4
+# Kite v5 - TypeScript
 
-### Breaking changes
-- Upgrade deps and set minimum nodejs version to 8.0.0+
-- Return promise instead of throwing error on generateSession and renewAccessToken
-- Handle gtt payload validation and throw proper error
-- Change ticker response attributes naming as per [kite connect doc](https://kite.trade/docs/connect/v3/websocket/#quote-packet-structure)
+## [5.0.0] - 2024-06-13
 
-### New features
-- Order margin call : [orderMargins](https://github.com/zerodha/kiteconnectjs/blob/master/lib/connect.js#L704)
-- Basket order margin call : [orderBasketMargins](https://github.com/zerodha/kiteconnectjs/blob/master/lib/connect.js#L727)
-- Add OI param to `getHistoricalData`
-- Add global constant for postion types `POSITION_TYPE_DAY`, `POSITION_TYPE_OVERNIGHT` and `EXCHANGE_BCD`
+### Breaking Changes
 
-### Fixes
-- Remove `order_id` param from complete tradebook fetch `getTrades`
-- Fix `cancelMF` order_id param struct
-- Handle price conversion for BCD segment in ticker
-- Remove un-used `headers` param for `parseHistorical`
-- Update comment block for `getQuote, getOHLC, getLTP, placeOrder and placeMFOrder`
+- **TypeScript Conversion**: The entire codebase has been converted to TypeScript. This means type definitions are now included, and any custom integrations may need to be updated to match the new type definitions.
+- **Node.js Version Requirement**: The minimum required Node.js version is now 18.0.0. Please upgrade your Node.js installation if you are using an older version.
+- **API Changes**: Updated various function signatures and added explicit types for better TypeScript support.
 
+### New Features
 
-# Kite v3
+- **TypeScript Support**: The library is now fully written in TypeScript, providing better type safety.
+- **Documentation**: Added and updated documentation to reflect the new TypeScript codebase as per the [TSDOC standard](https://tsdoc.org/).
+- **Examples**: Added new examples for both REST API and WebSocket client in TypeScript.
 
-### New features
-- method: `getProfile`
-- method: `getOHLC`
-- method: `getLTP`
-- method: `getInstrumentsMargins`
-- Added MF API calls
-- method: `getMFOrders`
-- method: `getMFHoldings`
-- method: `placeMFOrder`
-- method: `cancelMFOrder`
-- method: `getMFSIPS`
-- method: `placeMFSIP`
-- method: `modifyMFSIP`
-- method: `cancelMFSIP`
-- method: `getMFInstruments`
-- method: `exitOrder`
-- method: `renewAccessToken`
-- method: `invalidateRefreshToken`
-- constants for products, order type, transaction type, variety, validity, exchanges and margin segments
+### Improvements
 
-### API method name changes
+- **Code Quality**: Refactored codebase to improve readability, maintainability, and performance.
+- **Error Handling**: Improved error handling and added more descriptive error messages.
 
-| v2  						| v3 						|
-| -------------------------	| -------------------------	|
-| requestAccessToken		| generateSession			|
-| invalidateToken			| invalidateAccessToken		|
-| setSessionHook 			| setSessionExpiryHook		|
-| loginUrl					| getLoginURL				|
-| margins					| getMargins				|
-| orderPlace				| placeOrder				|
-| orderModify				| modifyOrder				|
-| orderCancel 				| cancelOrder				|
-| orders 					| getOrders 				|
-| orders(order_id) 			| getOrderHistory			|
-| trades 					| getTrades 				|
-| trades(order_id) 			| getOrderTrades 			|
-| holdings					| getHoldings 				|
-| positions					| getPositions 				|
-| productModify 			| convertPosition 			|
-| instruments				| getInstruments 			|
-| historical				| getHistoricalData 		|
-| triggerRange 				| getTriggerRange 			|
+### Migration Guide
 
-### Params and other changes
-- `KiteConnect` takes all the params as object including `api_key`
-- `convertPosition` method takes all the params as object
-- All success response returns only `data` field in response instead with envelope
-- All error thrown are in the format of `{"message": "Unknown error", "error_type": "GeneralException", "data": null}`
-- [Changes in `generateSession` response structure](https://kite.trade/docs/connect/v3/user/#response-attributes)
-- [Changes in `getPositions` response structure](https://kite.trade/docs/connect/v3/portfolio/#response-attributes_1)
-- [Changes in `getQuote` response structure](https://kite.trade/docs/connect/v3/market-quotes/#retrieving-full-market-quotes)
-- [Changes in `placeOrder` params](https://kite.trade/docs/connect/v3/orders/#bracket-order-bo-parameters)
-- Changes in `getHistoricalData` params
-- All datetime string fields has been converted to `Date` object.
-	- `getOrders`, `getOrderHistory`, `getTrades`, `getOrderTrades`, `getMFOrders` responses fields `order_timestamp`, `exchange_timestamp`, `fill_timestamp`
-	- `getMFSIPS` fields `created`, `last_instalment`
-	- `generateSession` field `login_time`
-	- `getQuote` fields `timestamp`, `last_trade_time`
-	- `getInstruments` field `expiry`
-	- `getMFInstruments` field `last_price_date`
+If you are upgrading from a previous version, please review the following changes and adjust your code accordingly:
 
-### KiteTicker changes
-- `KiteTicker` receives param `access_token` instead of `public_token`
-- New params addedd to `KiteTicker` initializer
-	- `reconnect` - Toggle auto reconnect on/off
-	- `max_retry` - Max retry count for auto reconnect
-	- `max_delay` - Max delay between subsequent retries
-	- Auto reconnect is enabled by default
-- Renamed callback `reconnecting` to `reconnect`
-- Added new callbacks
-	- `error` - when socket connection is closed with error. Error is received as a first param
-	- `close` - when socket connection is closed cleanly
-	- `order_update` - When order update (postback) is received for the connected user (Data object is received as first argument)
+- **Node.js Version**: Ensure your Node.js version is 18.0.0 or higher.
+- **TypeScript Integration**: Update your project to handle the new TypeScript types. This may involve adding or adjusting type definitions in your project.
+- **Function Signatures**: Review the updated function signatures in the documentation and adjust your usage of the library accordingly.
 
+### Bug Fixes
 
+- Fixed various minor bugs and performance issues reported in the previous version.
+
+### Notes
+
+- This release marks a significant update with the transition to TypeScript. Please report any issues or bugs to the repository's issue tracker.
+
+[5.0.0]: https://github.com/your-repo/kiteconnect-ts/releases/tag/v5.0.0

CHANGELOG.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Zerodha Technology Pvt. Ltd. (India)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.