@bigbinary/neeto-payments-frontend 1.0.1 → 1.0.3

package/README.md

@@ -11,9 +11,9 @@ neetoPayments is the library that manages payments across neeto products.
     proper functioning of the package. Install all the peer dependencies using
     the below command:
 
-      ```zsh
-      yarn add @bigbinary/neeto-commons-frontend@2.0.54 @bigbinary/neeto-filters-frontend@2.8.1 @bigbinary/neeto-icons@1.9.22 @bigbinary/neeto-molecules@1.0.9 @bigbinary/neetoui@4.4.10 @honeybadger-io/js@5.1.1 @honeybadger-io/react@5.1.3 axios@1.3.4 classnames@2.3.2 formik@2.2.9 js-logger@1.6.1 mixpanel-browser@2.45.0 ramda@0.28.0 react-helmet@6.1.0 react-query@3.39.3 react-router-dom@5.3.4 react-toastify@8.2.0 yup@1.0.2
-      ```
+    ```zsh
+    yarn add @bigbinary/neeto-commons-frontend@2.0.54 @bigbinary/neeto-filters-frontend@2.8.1 @bigbinary/neeto-icons@1.9.22 @bigbinary/neeto-molecules@1.0.9 @bigbinary/neetoui@4.4.10 @honeybadger-io/js@5.1.1 @honeybadger-io/react@5.1.3 axios@1.3.4 classnames@2.3.2 formik@2.2.9 js-logger@1.6.1 mixpanel-browser@2.45.0 ramda@0.28.0 react-helmet@6.1.0 react-query@3.39.3 react-router-dom@5.3.4 react-toastify@8.2.0 yup@1.0.2
+    ```
 
 2.  Now install the latest **neetoPayments** package using the below command:
 
@@ -21,6 +21,152 @@ neetoPayments is the library that manages payments across neeto products.
     yarn add @bigbinary/neeto-payments-frontend
     ```
 
+## Usage
+
+neeto-payments-frontend exports:
+
+- `Dashboard` component
+- `buildStripeTransactionLink()` function
+
+### 1. `Dashboard` component
+
+#### Props
+
+1. **holdableId**: To specify the ID of the entity that holds the stripe
+   account. This is an optional prop. If the value is not specified, the current
+   organization ID is taken as the default value while querying for
+   transactions.
+
+2. **payableEntityColumns**: To specify the columns from the payable entity
+   which need to be additionally displayed. It is an optional prop that defaults
+   to `[]` if not specified.
+
+3. **searchProps**: To specify the properties of the search bar in `Dashboard`.
+
+4. **shouldFetchFilterOptions**: To specify whether or not to fetch the options
+   for columns with filter type as `single_option` or `multi_option`. Its value
+   is `false` by default.
+
+5. **tabs**: To specify the tabs to be displayed in the payments dashboard. It is an optional parameter.
+
+**More about `payableEntityColumns`**
+
+Here is an example of `payableEntityColumns` prop:
+
+```js
+const payableEntityColumns = [
+  {
+    title: t("entity.meeting"),
+    dataIndex: "payable",
+    key: "meeting",
+    ellipsis: true,
+    width: 150,
+    render: renderMeeting,
+    isFilterable: true,
+    filterProps: {
+      key: "meeting",
+      label: "Meeting",
+      node: "bookings:payable.meeting.name",
+      type: "multi_option",
+      model: "Meeting",
+    },
+  },
+  {
+    title: t("common.host"),
+    dataIndex: ["payable", "host"],
+    key: "host",
+    ellipsis: true,
+    width: 150,
+    isFilterable: true,
+    filterProps: {
+      key: "host",
+      label: "Host",
+      node: "bookings:payable.user.first_name,last_name",
+      model: "User",
+      type: "multi_option",
+    },
+  },
+];
+```
+
+The `payableEntityColumns` is similar to `columnData` prop used in `Table`
+component in **NeetoUI**. The prop can be modified accordingly to customize the
+columns in the table. For more customizations, refer
+[NeetoUI docs](https://neeto-ui.neeto.com/?path=/docs/components-table--default).
+
+The additional keys are `isFilterable` and `filterProps`. `filterProps` is used
+to build the list of columns to be represented in the filters pane. The
+`isFilterable` key must be `true` for `filterProps` to be considered.
+
+> :memo: **Note:** The data about the payable entity is in the format
+> `{ payable: {...} }`. So the `dataIndex` key must be used accordingly. Refer
+> the example above.
+
+> In the case of columns with filter type as `single_option` or `multi_option`,
+> `values` key can be passed along with `filterProps`. Alternatively it be
+> automated using `Dashboard` component. To know more on this, refer "More about
+> shouldFetchFilterOptions prop" section below.
+
+**More about `searchProps` prop**
+
+Here is an example of `searchProps` prop:
+
+```js
+const searchProps = {
+  key: "keyword",
+  node: "bookings:payable.meeting.name,bookings:payable.user.first_name,last_name,bookings:payable.name",
+  model: "Meeting,User,Booking",
+  placeholder: "Search by meeting name, user name or booking name",
+};
+```
+
+This is passed to the `FiltersBar` and `FiltersPane` components from
+`neeto-filters-frontend`. This is similar to the `keyword` prop used in
+`neeto-filters-frontend` with an additional `placeholder` key which is used as
+the placeholder in the search bar.
+
+To know more about the working of `node` and `model` keys, refer the
+[`neeto-filters-frontend` documentation](https://github.com/bigbinary/neeto-filters-frontend/blob/main/README.md).
+
+**More about `shouldFetchFilterOptions` prop**
+
+`shouldFetchFilterOptions` decides whether or not to fetch the data to be set as
+the `values` key in `filterProp`. For this to work,
+`api/v1/payments/filter_options` endpoint must be defined and it must return the
+filter options.
+
+An example of desired response from the endpoint is:
+
+`{ filterOptions: { host: [...], meeting: [...]}}`
+
+> :memo: **Note:** For the above method to work, the keys inside the
+> `filterOptions` object must match the `key` property in `payableEntityColumns`
+
+**More about `tabs` prop**
+
+`tabs` is an array of strings. It has default value as this: `["all", "successful", "pending", "declined", "refunded"]`.It should only be a subset of the array above. Preferably it shouldn't be an empty array.
+
+
+### 2. `buildStripeTransactionLink` function
+
+This function is used to generate the stripe transaction link from a payment
+identifier.
+
+The arguments are:
+
+1. `identifier`: The payment identifier
+2. `isLive`: Specifying whether or not the environment is live. It defaults to
+   `true`.
+
+Example usage
+
+```js
+const transactionLink = buildStripeTransactionLink(
+  "pi_3MqWX92fKivMPpZ11EPmOBBR",
+  false
+);
+```
+
 ## Other References
 
 - [Development instructions](./docs/general/development-instructions.md)