@payping/api

Attention

Please do not use any code linting tool (eslint, prettier, ...) in api/* files, because they are auto generated, and they might be replaced again, so manual changes in the code should be minimal.

---

How to use

1. first config sdk behavior in apiConfigs.ts file:

// root/apiConfigs.ts
import { StatusHandlersTypes, apiConfigs } from "@payping/api";
import { Modal } from "@payping/desktop-components";
import { logout } from "./actions";
import { environment } from "./env";
import { store } from "./index";

const generalHandler = (error): void => {
  // eslint-disable-next-line no-console
  console.error(error);
  Modal.error({
    content: error.message,
    title: "خطا",
  });
};

const unAuthorizedHandler = (): void => {
  store.dispatch(logout());
};

const statusHandlers: StatusHandlersTypes = {
  "401": unAuthorizedHandler,
  default: generalHandler,
};

const networkChecker = new Promise<void>((resolve) => resolve());

apiConfigs.updateConfig({
  environment,
  networkChecker,
  statusHandlers,
});

2. then import apiConfigs.ts file in your root component to intiate configs like this:

import "./apiConfigs";

3. after that, set accessToken in your root component ASAP:

import { apiConfigs } from "@payping/api";

const token = this.props.organizationToken || this.props.token;
if (token) {
  apiConfigs.updateConfig({ accessToken: token });
}

4. call updateConfig wherever accessToken changes:

• on login personal token
• on logout personal token
• on login organization token
• on logout organization token

5. import APIs and use them:

import { invoiceV2Apis } from "@payping/api";
const { invoiceV2List } = invoiceV2Apis;
async function getInvoices() {
  const res = await invoiceV2List();
  return res;
}

6. you can change baseurl by updateConfig method:

import { EnvironmentType, apiConfigs } from "@payping/api";

const environment: EnvironmentType = "Development"; // manatadbir.ir
apiConfigs.updateConfig({ environment });

Other usefull methods:

• getCurrentPath: const { oauthPath, basePath } = getCurrentPath();
• sdkFetch: use it just like fetch but you can ignore base path and it doesn't need accessToken and error handlers

How to Add a method:

Short way

Run following script with the url of openapi schema:

NOTE: you need java & node on your system to be able to run this script

yarn run generate-api:ts --input cash-out --version v1,v2,PublicApi --replace true

• input: serviceName or url or file address, e.g.:
  • oauth
  • https://oauth.payping.dev/swagger/openApi/v1/swagger.json
  • ./schema.json
• version: Comma-separated list of needed versions. e.g.:
  • v1,v2,PublicApi
  • v1
• replace: Whether to replace current api files inside src/<admin|app>/api folder. Default value is true, false should be passed if not wanted.

Input & Versions

If required Input field in not in this list please add it to the switch case in generate-api.ts and update the list

Input	Example Versions
admin	v1
category	v1
permalink	v1
product	v1
coupon	v1
customer	v1
invoice	v1
timeline	v1
oauth	v1
pay	v1
payment	v1
report	v1
request	v1
withdraw	v1
service	v1
user	v1
digitalAccount	BankAgreements,Banks,Khavarmiyaneh,Saman
cashout - cashOut - cash-out - settlement	v1,v2,PublicApi
bnplConsumer	v1
bnplMerchant	v1

Long way

1. Get the (json|yaml) schema file:

• Go to the swagger ui (for example https://swagger.payping.ir/)
• At the top of the page, there is a path for the schema (json or yaml), in this case: https://cdn.payping.ir/statics/openapi.json
• Copy the content of this file to the https://editor.swagger.io/

2. Generate api code:

• The result of the previous step generates the same swagger ui that you saw in the https://swagger.payping.ir

  NOTE: You might be asked to convert your file to yaml, it's okay if you accept

  NOTE: If you see errors at the top of the generated swagger ui, you need to fix them to be able to generate your code. Otherwise no error will be shown and only your request will receive 400 response.

• Now you can generate your desired Server or Client side code (we use typescript-fetch).

3. Merge codes:

• Inside the generated code you need the api.ts file, inside which you will find the type and the methods.
• There are 4 main functions (each function contains functions for each of the methods) for calling methods with name similar to following:
  1. ProductApiFetchParamCreator: this function generates the options for the request, so its output is a json object.
  2. ProductApiFp: this function calls the ProductApiFetchParamCreator to get the request options, then performs the request, and then return the response to us.
  3. ProductApiFactory: this function is how we can use these apis in different places in our code (they are exported in /src/apis.ts).
  4. ProductApi: this function is the same as ProductApiFactory, the only difference is that this one is based on class but last one was based on function.

     WARNING: Do not replace the whole code with the generated one (there are some methods that we have added ourselves).

• Find the 4 functions of the methods that you want to add and add them to the existing ones.
• The missing types, request body type (input of all 4 functions) or output viewModel (output of 2nd function), should be added to the types.ts file next to the functions file.

  NOTE: Check the apisTypes to ensure your new types are all exported

  NOTE: Replace all Date types with string, since we will have problems with Date types.

Checking changes before Publish:

1. Run script for building package on local (customPrepublishOnly:app or customPrepublishOnly:admin).
2. Output will be in a dist|distAdmin folder at the root of the project.
3. Go to the project that you want to install this package in and install it locally:

   yarn add ../apisdk/dist/
   or
   yarn add ../apisdk/distAdmin/

   NOTE: If your project has submodules you need to use the -W option in yarn add command and replace the version of the package in all package.json files with this route ../apisdk/dist/.

How to Publish:

Admin:

1. Create a release branch for this new version (its name should be the new version that you want to publish plus admin for example 1.0.4-admin):

2. Edit build_config/admin/package.json version (pay attention to Semver)

3. Run script for publishing package on registry:

   NOTE: In your terminal you should be logged in at our registry at https://npmregistry.payping.dev If you aren't, run:

    npm logout
    npm login --registry=https://npmregistry.payping.dev

yarn customPublish:admin

4. Finish your release branch

Dashboard:

1. Create a release branch for this new version (its name should be the new version that you want to publish plus app for example 1.0.4-app):

2. Edit build_config/app/package.json version (pay attention to Semver)

3. Run script for publishing package on registry:

   NOTE: In your terminal you should be logged in at npm registry at https://registry.npmjs.org. If you aren't, run:

    npm logout
    npm login

yarn customPublish:app

4. Finish your release branch