npm package: @quable/quable-partner-js
Description: Quable Partner API Client
Author: Quable
Latest version: 1.2.0

# Quable Partner JS

The Quable Partner JS is designed to simplify partnership experience, making it easier for partners to build their apps successfully within the Quable PIM platform. It's a user-friendly and efficient tool that assists partners in their Quable journey.

The Quable Partner JS is organized into two key modules:

1.  **Partner Module**: This module is specifically designed to assist partners in managing their partnership-related entities within the Quable platform. It simplifies interactions with Quable instances, apps and teams.
2.  **Payment Module**: The payment module is dedicated to handling financial transactions within Quable apps. It provides the necessary tools to manage monetary operations. This includes linking Stripe accounts, generating payment links, and retrieving payment information, giving partners control over their financial transactions.

## Getting started

### Requirements

1.  You must [download and install Node.js](https://nodejs.org/en/download/) if you don't already have it.
2.  You must [create a partner account](https://partners.quable.io/) if you don’t have one.

### Installing

The library can be installed through NPM or Yarn:

```bash
yarn  add  @quable/quable-partner-js
or
npm  install  @quable/quable-partner-js
```

### Usage

You must get your `<partner-id> ` and `<access-token>`.

To obtain your `<partner-id>` and `<access-token>`, you need to go to your partner's dashboard and follow these steps:

1.  Navigate to your dashboard.
2.  Click on "Settings."
3.  Look for the "API Token" section.

You'll find your `<partner-id>` and `<access-token>` there.

**Initialize the client :**
Once your client is initialized, you can access either the Partner or Payment modules.

```ts
import { QuablePartnerAPI } from '@quable/quable-partner-js';

const partnerClient = new QuablePartnerAPI({
  accessToken: '<access-token>',
  partnerId: '<partner-id>',
});
```

#### a) Partner Methods

#### Get Quable applications

The provided code snippet fetches a list of Quable applications. The code specifies a limit of 5, meaning it will retrieve at most 5 Quable applications.

```ts
const quableApps = await partnerClient.Partner.QuableApplication.getAll({
  limit: 5,
});
```

#### Create a Quable application

The provided code snippet demonstrates the creation of a new application within the Quable ecosystem through the partner portal:

```ts
const createdApp = await partnerClient.Partner.QuableApplication.create({
  appType: 'in_app',
  name: 'Quable App',
  url: 'https://your-app-url.com',
  description: '',
  appIcon: 'bezier-curve',
});
```

#### Add a Quable instance

The provided code snippet adds a Quable instance within the partner portal:

```ts
const instance = await partnerClient.Partner.QuableInstance.add({
  authToken: '<instance-api-key>',
  quableInstanceName: '<instance-name>',
});
```

#### Install a Quable application

The provided code snippet installs a Quable application on the specified Quable instance:

```ts
const installedApp = await partnerClient.Partner.QuableApplication.install(
  quable - app - id,
  { instance: '<instance-name>' },
);
```

#### a) Payment Methods

#### Get payments

The provided code snippet is used to retrieve payments from the Quable payment, including both subscription and one-time payments based on the provided criteria:

```ts
//To retrieve subscription payments
const subscriptionPayments =
  await partnerClient.Payment.SubscriptionPayment.getPayments({
    appCheckoutId: '<app-checkout-id>',
    appId: '<app-id>',
    customer: '<customer>',
    limit: 5,
    status: 'paid',
  });

//To retrieve onetime payments
const onetimePayments = await partnerClient.Payment.OneTimePayment.getPayments({
  appCheckoutId: '<app-checkout-id>',
  appId: '<app-id>',
  customer: '<customer>',
  limit: 5,
  status: 'paid',
});
```

#### Generate payment link for an existing product

The provided code snippet is used to generate payment links for both subscription and one-time payments.

**Note**: It's important to note that you need to create a product on Stripe and obtain the corresponding price ID. The product represents the item you want to sell, and the price ID defines the specific pricing details. You can set up your product and price on Stripe's platform and then use the provided code to generate payment links:

```ts
//To generate subscription payment link
const subscriptionPaymentLink =
  await partnerClient.Payment.SubscriptionPayment.generatePaymentLink({
    appCheckoutId: '99811bd2-99e8-412f-a3a9-6ac50bdd654a',
    appId: '<app-id>',
    customer: '<customer>',
    quantity: 1,
    price: { priceId: '<stripe-price-id>' },
    interval: 'DAILY',
  });

//To generate onetime payment link
const onetimePaymentLink =
  await partnerClient.Payment.OneTimePayment.generatePaymentLink({
    appCheckoutId: '13671fdd-f563-43ef-a391-d5ba8c8e0e13',
    appId: '<app-id>',
    customer: '<customer>',
    quantity: 1,
    price: { priceId: '<stripe-price-id>' },
  });
```

#### Generate payment link without an existing product

The provided code snippet is used to generate payment links for both subscription and one-time payments without creating the product on stripe beforehand:

```ts
//To generate subscription payment link
const subscriptionPaymentLink =
  await partnerClient.Payment.SubscriptionPayment.generatePaymentLink({
    appCheckoutId: '99811bd2-99e8-412f-a3a9-6ac50bdd654a',
    appId: '<app-id>',
    customer: '<customer>',
    quantity: 1,
    price: {
      priceData: {
        amount: 10,
        currency: 'EUR',
        product: { name: 'Product name' },
      },
    },
    interval: 'DAILY',
  });

//To generate onetime payment link
const onetimePaymentLink =
  await partnerClient.Payment.OneTimePayment.generatePaymentLink({
    appCheckoutId: '13671fdd-f563-43ef-a391-d5ba8c8e0e13',
    appId: '<app-id>',
    customer: '<customer>',
    quantity: 1,
    price: {
      priceData: {
        amount: 100,
        currency: 'EUR',
        product: { name: 'Product name' },
      },
    },
  });
```

### Testing the library:

To run tests within the Quable Partner JS, run the following command:

```bash
yarn  test
```

## [Author](https://www.quable.com)

[support@quable.com](mailto:support@quable.com)

## License

[MIT License](https://opensource.org/license/mit/)