Merge pull request #334 from razorpay/type-declaration

feat: type declaration

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.8.5 - 2023-02-22
+
+feat(Typescript): add typescript definitions
+
+- TypeScript definitions for all modules and functions in the SDK.
+- Add comments throughout the codebase to improve readability and maintainability.
+- Add a type declarations file (*.d.ts) to provide better type checking and editor support for consumers of the SDK.
+
+Overall, this update should provide a better developer experience for anyone using the SDK, by leveraging the power of TypeScript's static type checking and providing clearer documentation and comments throughout the codebase.
+
 ## 2.8.4 - 2022-11-21
 
 - [#310](https://github.com/razorpay/razorpay-node/pull/310) [`3e6daf3`](https://github.com/razorpay/razorpay-node/commit/3e6daf3c555f62eb23660a54eaae756e395ea3b6) : Thanks [@ankitdas13](https://github.com/ankitdas13)! - Fixed `virtualAccount.close` function implementation

lib/razorpay.d.ts

@@ -1 +1,113 @@
-declare module "razorpay";
+import API, { RazorpayHeaders } from './types/api'
+import addons from "./types/addons"
+import plans from "./types/plans"
+import items from "./types/items"
+import fundAccount from "./types/fundAccount"
+import invoices from "./types/invoices"
+import transfers from "./types/transfers"
+import settlements from './types/settlements'
+import orders from './types/orders'
+import refunds from './types/refunds'
+import qrCode from './types/qrCode'
+import virtualAccounts from './types/virtualAccounts'
+import payments from './types/payments'
+import subscriptions from './types/subscriptions'
+import paymentLink from './types/paymentLink'
+import cards from './types/cards'
+import { validateWebhookSignature } from "./utils/razorpay-utils"
+import customers from './types/customers'
+
+interface IRazorpayConfig {
+    key_id: string;
+    key_secret?: string;
+    headers?: RazorpayHeaders;
+}
+
+declare class Razorpay {
+    static VERSION: string
+    static validateWebhookSignature: typeof validateWebhookSignature
+
+    constructor(config: IRazorpayConfig)
+    api: API
+    /**
+     * Customers Entity
+     * @see https://razorpay.com/docs/api/customers/
+     */
+    customers: ReturnType<typeof customers>
+    /**
+     * Addons Entity
+     * @see https://razorpay.com/docs/api/payments/subscriptions/#add-on
+     */
+    addons: ReturnType<typeof addons>
+    /**
+     * Plans Entity
+     * @see https://razorpay.com/docs/api/payments/subscriptions/#plans
+     */
+    plans: ReturnType<typeof plans>
+    /**
+     * Orders Entity
+     * @see https://razorpay.com/docs/api/orders
+     */
+    orders: ReturnType<typeof orders>
+    /**
+     * Orders Entity
+     * @see https://razorpay.com/docs/api/payments
+     */
+    payments: ReturnType<typeof payments>
+    /**
+     * Payments Entity
+     * @see https://razorpay.com/docs/api/payments/route/transfers
+     */
+    transfers: ReturnType<typeof transfers>
+    /**
+     * Transfers Entity
+     * @see https://razorpay.com/docs/api/refunds
+     */
+    refunds: ReturnType<typeof refunds>
+    /**
+     * Cards Entity
+     */
+    cards: ReturnType<typeof cards>
+    /**
+     * FundaAccount Entity
+     * @see https://razorpay.com/docs/api/x/fund-accounts/
+     */
+    fundAccount: ReturnType<typeof fundAccount>
+    /**
+     * Items Entity
+     * @see https://razorpay.com/docs/payments/invoices/items/api/
+     */
+    items: ReturnType<typeof items>
+    /**
+     * PaymentLinks Entity
+     * @see https://razorpay.com/docs/payments/payment-links/apis
+     */
+    paymentLink: ReturnType<typeof paymentLink>
+    /**
+     * Invoices Entity
+     * @see https://razorpay.com/docs/payments/invoices/apis/
+     */
+    invoices: ReturnType<typeof invoices>
+    /**
+     * QrCode Entity
+     * @see https://razorpay.com/docs/payments/qr-codes/apis/
+     */
+    qrCode: ReturnType<typeof qrCode>
+    /**
+     * Subscrptions Entity
+     * @see https://razorpay.com/docs/api/payments/subscriptions/#subscriptions
+     */
+    subscriptions: ReturnType<typeof subscriptions>
+    /**
+     * Settlements Entity
+     * @see https://razorpay.com/docs/api/settlements
+     */
+    settlements: ReturnType<typeof settlements>
+    /**
+     * VirtualAccounts Entity
+     * @see https://razorpay.com/docs/api/payments/smart-collect/
+     */
+    virtualAccounts: ReturnType<typeof virtualAccounts>
+}
+
+export = Razorpay

lib/types/addons.d.ts

@@ -0,0 +1,72 @@
+import API, { INormalizeError, RazorpayPaginationOptions } from './api'
+import { Items } from './items';
+
+export declare namespace Addons {
+    interface RazorpayAddon {
+        /**
+         * The unique identifier of the created add-on.
+         */
+        id: string;
+        /**
+         * Indicates the type of entity.
+         */
+        entity: string;
+        /**
+         * Details of the created add-on.
+         */
+        item: Items.RazorpayItem;
+        /**
+         * This specifies the number of units of the add-on to be charged to the customer. For example, `2`. The total amount is calculated as `amount` * `quantity`.
+         */
+        quantity: number;
+        /**
+         * The Unix timestamp, indicates when the add-on was created. For example, `1581597318`.
+         */
+        created_at: number;
+        /**
+         * The unique identifier of the Subscription to which the add-on is being added.
+         */
+        subscription_id: string;
+        /**
+         * The add-on is added to the next invoice that is generated after it is created. This field is populated only after the invoice is generated. Until then, it is `null`. Once the add-on is linked to an invoice, it cannot be deleted.
+         */
+        invoice_id: string;
+    }
+}
+
+
+declare function addons(api: API): {
+    /**
+    * Fetches an addon given Addon ID
+    *
+    * @param addonId - addon id to be fetched 
+    * 
+    */
+    fetch(addonId: string): Promise<Addons.RazorpayAddon>
+    fetch(addonId: string, callback: (err: INormalizeError | null, data: Addons.RazorpayAddon) => void): void;
+    /**
+    * Delete a addon given Addon ID
+    *
+    * @param addonId - addon id to be fetched 
+    * 
+    */
+    delete(addonId: string): Promise<[]>
+    delete(addonId: string, callback: (err: INormalizeError | null, data: []) => void): void;
+    /**
+    * Get all addons
+    *
+    * @param params - Check [doc](https://razorpay.com/docs/api/payments/subscriptions/#fetch-all-add-ons) for required params
+    * 
+    */
+    all(params?: RazorpayPaginationOptions): Promise<{
+        entity: string,
+        count: number,
+        items: Array<Addons.RazorpayAddon>
+    }>;
+    all(params: RazorpayPaginationOptions, callback: (err: INormalizeError | null, data: {
+        entity: string,
+        count: number,
+        items: Array<Addons.RazorpayAddon>
+    }) => void): void
+};
+export default addons;

lib/types/api.d.ts

@@ -0,0 +1,84 @@
+import nodeify from '../utils/nodeify'
+
+interface IOption {
+    hostUrl: string;
+    key_id: string;
+    key_secret?: string;
+    ua: string;
+    headers?: string;
+}
+
+interface IPayload<T> {
+    url: string;
+    data: T;
+}
+
+export type INotify = 'email' | 'sms'
+
+export interface RazorpayHeaders {
+    'X-Razorpay-Account'?: string;
+    'Content-Type'?: string;
+}
+
+/**
+ * Key-value pairs 
+ */
+export interface IMap<T> {
+    [key: string]: T | null;
+}
+
+export type PartialOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+export interface RazorpayPaginationOptions {
+    /**
+     * The Unix timestamp from when data are to be fetched
+     */
+    from?: number;
+    /**
+     * The Unix timestamp till when data are to be fetched.
+     */
+    to?: number;
+    /**
+     * The number of data to be fetched. Default value is `10`. Maximum value is `100`.
+     * This can be used for pagination, in combination with skip.
+     */
+    count?: number;
+    /**
+     * The number of data to be skipped. Default value is `0`. 
+     * This can be used for pagination, in combination with count.
+     */
+    skip?: number;
+}
+
+export interface INormalizeError {
+    statusCode: string | number;
+    error: {
+        code: string;
+        description: string;
+        field?: any;
+        source?: string;
+        step?: string;
+        reason?: string;
+        metadata?: { [key: string]: string };
+    }
+}
+
+declare class API {
+    constructor(options: IOption)
+    get<T, V>(params: IPayload<T>): Promise<V>
+    get<T, V>(params: IPayload<T>, callback: (err: INormalizeError, data: V) => void): void
+
+    post<T, V>(params: IPayload<T>): Promise<V>
+    post<T, V>(params: IPayload<T>, callback: (err: INormalizeError, data: V) => void): void
+
+    put<T, V>(params: IPayload<T>): Promise<V>
+    put<T, V>(params: IPayload<T>, callback: (err: INormalizeError, data: V) => void): void
+
+    patch<T, V>(params: IPayload<T>): Promise<V>
+    patch<T, V>(params: IPayload<T>, callback: (err: INormalizeError, data: V) => void): void
+
+    delete<T, V>(params: IPayload<T>): Promise<V>
+    delete<T, V>(params: IPayload<T>, callback: (err: INormalizeError, data: V) => void): void
+}
+
+export default API

lib/types/cards.d.ts

@@ -0,0 +1,16 @@
+import { Payments } from "./payments";
+import { INormalizeError } from "./api";
+
+declare function cards(api: any): {
+    /**
+    * Fetch a card given a Card ID
+    *
+    * @param cardId - The unique identifier of the card
+    *
+    */
+    fetch(cardId: string): Promise<Payments.RazorpayCard>
+    fetch(cardId: string, callback: (err: INormalizeError | null, data: Payments.RazorpayCard) => void): void
+
+}
+
+export default cards