npm package: @partiu-vantagens/partiu-sdk
Description: Library for communicating with Partiu API
Author: Partiu Vantagens
Latest version: 1.3.1

# Partiu SDK

Library made to integrate Partiu React/React-Native/JS front-end applications with the Partiu servers.

The SDK is divided in modules that are responsible for communicating with certain parts of the API.
All the developed modules can be found below.

## Glossary

- [Initializing the SDK](#initializing-the-sdk)
- [Modules](#modules)
- [Pagination](#pagination)

## Installing

```bash
yarn add @partiu-vantagens/partiu-sdk
# or
npm install @partiu-vantagens/partiu-sdk
```

```ts
import Partiu from "@partiu-vantagens/partiu-sdk";

const partiu = new Partiu();
const partiu = new Partiu(true); // Initialize in beta mode (access beta api servers for testing)

const data = await partiu.promotions.list(); // Example for listing promotions
```

## Modules:

- [Auth](#auth)
- [Profile](#profile)
- [Categories](#categories)
- [Promotions](#promotions)
- [Utilizations](#utilizations)
- [Contact](#contact)
- [Banners](#banners)
- [APIs](#apis)

### Auth

The Auth module is responsible for <b>setting and removing the token from all the other requests</b>. Each user has a unique token that's used by the API for verifying the client. <b>For now, the token is fixed and is never refreshed</b>, altough this functionality will probably be implemented soon.

#### Commands

##### Login

Adds a token to all request to server.

```ts
const token = "asdjhasdijuhg12312312asdasdsad";

partiu.auth.setToken(token);
```

##### Logout

Removes a token to all request to server.

```ts
partiu.auth.clearToken();
```

### Profile

The Profile module is responsible for retrieving and updating user profile. <b>Requires token.</b>

#### Model

```ts
export interface Profile {
  id: number;
  full_name: string;
  email: string;
  telephone: string;
  image: string;
  city: string;
  cpf: string;
  active_agreement: object;
  allowed_push_notifications: boolean;
  allowed_promotional_emails: boolean;
}
```

#### Commands

##### Retrieve

```ts
const profile: Profile = await partiu.profile.retrieve();
```

##### Update

This endpoint uses the PATCH HTTP verb, so it's not necessary to pass the whole profile.

```ts
const updatedData = {
  full_name: "New Name",
  allowed_push_notifications: false,
};

await partiu.profile.update(updatedData);
```

### Categories

The Categories module is responsible for listing Category models from the server.

#### Model

```ts
export interface Category {
  id: number;
  name: string;
  icon: string;
  image: string;
}
```

#### Commands

##### List

```ts
const data: Category[] = await partiu.categories.list();
```

##### List (Paginated)

For more details on pagination, see [Pagination](#pagination).

### Promotions

The Promotions module is responsible for listing and retrieving Promotion models from the server.

<b>OBS: When listing with `promotions.list()`, promotions from same company or stores are aggregated in the same object. After retrieving the promotion using the `promotions.retrieve()` all the promotions will be listed in the `promotions` attribute.</b>

<b>OBS 2: Link and Coupon fields are only given if the user is logged and have a valid subscription.</b>

#### Model

```ts
declare enum PromotionModes {
  online = "online",
  local = "local",
}

declare enum PromotionTypes {
  discount = "discount",
  buy_and_gain = "buy_and_gain",
  treat = "treat",
}

export interface Promotion {
  id: number;
  mode: PromotionModes;
  type: PromotionTypes;
  original_price: number;
  discount: number;
  image: string;
  rules: string;
  link?: string;
  coupon?: string;
  featured: boolean;
  limited_codes: boolean;
}

export interface PromotionAggregator {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  percentage: number;
  mode: PromotionModes;
  type: PromotionTypes;
  distance: string;
  favorite: boolean;
  featured: boolean;
  new: boolean;
}

export interface StorePromotions {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  mode: PromotionModes;
  type: PromotionTypes;
  description: string;
  promotions: Promotion[];
  site: string;
  latitude: number;
  longitude: number;
}

export interface CompanyPromotions {
  id: number;
  image: string;
  show_name: string;
  subtitle: string;
  category: string;
  mode: PromotionModes;
  type: PromotionTypes;
  description: string;
  promotions: Promotion[];
  site: string;
}
```

#### Commands

##### List

```ts
const data: PromotionAggregator[] = await partiu.promotions.list();
```

###### AvailableFilters

```ts
export interface PromotionsFilters {
  category: string;
  mode: PromotionModes;
  name: string; // Company name
  type: PromotionTypes;
  featured: boolean;
  new: boolean;
  latitude: number; // Required for local discounts
  longitude: number; // Required for local discounts
}
```

Example:

```ts
const data = PromotionAggregator[] = await partiu.promotions.list({type: "buy_and_gain", new: true})
```

##### List (Paginated)

For more details on pagination, see [Pagination](#pagination).

##### Retrieve

```ts
const company_promotions: CompanyPromotions = await partiu.promotions.retrieve(
  "online_10"
);
const store_promotions: StorePromotions = await partiu.promotions.retrieve(
  "local_10"
);
```

### Utilizations

The Utilizations module is responsible for:

1. Storing the history of the user's promotion usage.
2. Generating a code that will be use in the PDV for validating the user usage.
3. Storing the value of the discount that was given, together with the feedback of the whole experience.

Once the user has chosen a promotion to use, the system must call the `utilizations.create(promotionId)` action to keep history of the usage. <b>In case of local promotions, this is essencial since it will return a code that will be input in the PDV system for validation that the user is subscribed to Partiu.</b>

Once the user used (accessed the site if online or had the code validated if local), it can give two aditional information: How much it payed and the feedback (good or bad experience). It must be passed using the `utilizations.update(code, {user_given_value: 23.00, feedback: true /* True if good false if bad */ })` action.

#### Model

```ts
export interface Utilization {
  code: string;
  created_at: Date;
  expires_at: Date;
  company: string;
  used: boolean;
  feedback: boolean;
  user_given_total: number;
  pdv_given_total: number;
  display_name: string;
}

export interface CategoryReport {
  name: string;
  usage: number;
  economized: number;
}
```

#### Commands

##### Create

Creates a utilization from a promotion.

```ts
const utilization: Utilization = await partiu.utilizations.create("3881");
```

##### Update

Adds more information about the utilization, such as: total paid and feedback.

```ts
const utilization = await partiu.utilizations.update("UFP12A", {
  user_given_total: 30.4,
  feedback: true,
});
```

##### List

Lists all user utilizations.

```ts
const utilizations: Utilization[] = await partiu.utilizations.paginated.list();
```

##### List (Paginated)

For more details on pagination, see [Pagination](#pagination).

##### Report

Lists user usage grouped by category. Receives two parameters for filtering: month and year.

```ts
const report: CategoryReport[] = await partiu.utilizations.report(4, 2022);
```

### Contact

The Contact module is responsible for creating support tickets.

#### Model

```ts
export interface ContactForm {
  name: string;
  email: string;
  subject: string;
  telephone: string;
  message: string;
  landing: string; // This is about where the contact came from (landing, app, iframe, etc...)
}
```

#### Commands

##### Create

```ts
const response: ContactForm = await partiu.contact.create(
  "Test",
  "test@test.com",
  "test subject",
  "21995150897",
  "Help, everything is on fire!!!",
  "smartfit landing"
);
```

### Banners

The Banners module is responsible for listing Banner models from the server.

#### Model

```ts
export interface Banner {
  name: string;
  image: string;
}
```

#### Commands

##### List

Lists all banners.

```ts
const banners: Banner[] = await partiu.banner.list();
```

### APIs

Partiu uses some third party APIs to fetch extra information when needed.

#### CEP API (ViaCEP)

Returns an address from CEP.

```ts
const address = await partiu.api.getAddressFromCEP("99999-999");
```

```ts
export interface Address {
  cep: string;
  logradouro: string;
  complemento: string;
  bairro: string;
  localidade: string;
  uf: string;
  ibge: string;
  gia: string;
  ddd: string;
  siafi: string;
}
```

#### CNPJ API (ReceitaWS)

Returns company data from CNPJ.

```ts
const companyData: CompanyData = await partiu.api.getCompanyDataFromCNPJ(
  "99.999.999/9999-99"
);
```

```ts
declare enum CompanyTypes {
  MATRIZ = "MATRIZ",
  FILIAL = "FILIAL",
}

export interface CompanyActivity {
  code: string;
  text: string;
}

export interface CompanyOwner {
  nome: string;
  qual: string;
  pais_origem: string;
  nome_rep_legal: string;
  qual_rep_legal: string;
}

export interface CompanyData {
  ultima_atualizacao: string;
  cnpj: string;
  cep: string;
  nome: string;
  tipo: CompanyTypes;
  porte: string;
  fantasia: string;
  abertura: string;
  atividade_principal: CompanyActivity;
  atividades_secundarias: CompanyActivity[];
  natureza_juridica: string;
  logradouro: string;
  numero: string;
  complemento: string;
  bairro: string;
  municipio: string;
  uf: string;
  email: string;
  telefone: string;
  efr: string;
  situacao: string;
  data_situacao: string;
  motivo_situacao: string;
  situacao_especial: string;
  data_situacao_especial: string;
  capital_social: string;
  qsa: CompanyOwner[];
}
```

## Pagination

Some modules provides a pagination object to easily deal with paginated endponts. They can be used as described below (using the promotions module as an example):

```ts
const data: PromotionAggregator[] = await partiu.promotions.paginated.list({
  mode: "online",
  type: "discount",
});
const moreData: PromotionAggregator[] =
  await partiu.promotions.paginated.next();

partiu.promotions.reset(); // Resets pagination to default
```

As seen by the code above, the `paginated.next()` command will call the next page of models, <b> with the the filters already applied</b>.

To reset the pagination, you can call `paginated.list()` command again or the `paginated.reset()` command.

This implementation of pagination is focused on infinite scrolling, so the page data is not provided. However, a `paginated.previous()` command is provided if needed.