# ../../api

Composables Vue 3 + TypeScript para integração simplificada com a API pública da Uappi, facilitando o consumo, gerenciamento e reutilização de endpoints em aplicações modernas.

## Instalação

Adicione ao seu projeto:

```bash
npm install ../../api
```

## Escopos Disponíveis

O pacote expõe os seguintes escopos, cada um agrupando recursos relacionados:

- [**cart**](#cart): Operações de carrinho, como adicionar/remover produtos, simular frete, pagamentos e condições.
	- listDetail Lista detalhes do carrinho
	- addProduct Adiciona um produto ao carrinho
	- deleteProduct Remove um produto do carrinho
	- upsertProduct Atualiza ou insere produto
	- shipmentQuote Lista opções de frete com base no carrinho
	- selectShipment Seleciona opção de frete
	- applyAddresses Aplica endereços entrega/faturamento ao carrinho
	- listPayments Lista formas de pagamento
	- buy: Finaliza a compra
	- paymentConditions: Lista condições de pagamento

- [**common**](#common): Utilitários como consulta de CEP, países e bandeiras de cartão.
	- listZipcode: Lista detalhes de endereço de CEP
	- listContries: Lista detalhes de países
	- countryDetail: Detalhes de um país
	- listCardFlags: Retorna dados utilitários sobre cada bandeira de cartão (regex de validação, etc)

- [**customer**](#customer): Recursos para autenticação, cadastro, endereços, pedidos, newsletter, avaliações e histórico do cliente.
	- addNewsletter: Inscreve na newsletter da loja por email e name
	- deleteNewsletter: Remove inscrição na newsletter (apenas cliente logado)
	- createProductReview: Avalia um produto (apenas clientes logado)
	- listProductReview: Listagem paginada de todas avaliações do produto
	- listStoreReview: Listagem paginada de todas avaliações da loja
	- createInterest: Cria uma solicitação de interesse em um produto fora de estoque
	- changePasswordByAuthenticated: Alteração de senha com cliente autenticado
	- changePasswordByCode: Alteração de senha através de código enviado por e-mail
	- check: Verifica existencia de cliente com base no e-mail ou documento
	- listAddress: Listagem de endereços do cliente logado
	- createAddress: Cria novo endereço do cliente logado
	- deleteAddress: Remove um endereço do cliente logado
	- updateAddress: Atualiza endereço do cliente logado
	- updatePrimaryAddress: Define um endereço como principal
	- detail: Detalhes do cliente logado
	- passwordRecovery: Recuperação de senha
	- signinByDocument: Login por documento
	- signinByEmail: Login por e-mail
	- signup: Cadastro de novo cliente
	- update: Atualiza dados do cliente
	- loggout: Logout
	- detailOrderGroup: Detalhes de pedido
	- listOrderGroups: Lista pedidos
	- listOrderItemHistory: Exibe o histórico de atualizações do pedido
	- listCustomerHistory: Exibe o histórico de atualizações do cliente (senha, endereço, etc.)
	- listCustomerReview: Lista avaliações do cliente em produto
	- listWalletTransaction: Lista transações da carteira
	- claimGiftCard: Resgata gift card

- [**customization**](#customization): Listagem de banners, vitrines e menus customizados.
	- listShowcase: Lista detalhes de vitrines
	- listBanners: Lista detalhes de banners
	- listMenu: Lista detalhes de menus
	- listTemplateSettings: Lista as configurações de settings e apps da loja com base na URI

- [**product**](#product): Consulta de marcas, variações, busca, comentários e informações de produtos.
	- listBrands: Listagem de marcas ativas
	- listVariation: Lista variações de um produto
	- getUrl: Consulta URL de produto (categorias, institucionais, detalhe de produto, etc.)
	- getSearch: Pesquisa produtos por termo
	- listShipmentQuoteProduct: Lista opções frete com base em um produto
	- deleteProductComment: Remove um comentário no produto
	- createProductComment: Adiciona um comentário no produto
	- listProductComments: Lista comentários de produto
	- getCategoryTree: Retorna a árvore de uma categoria (atual, filhas, irmãs e pai)
	- listCategoriesTree: Retorna a árvore completa de categorias ativas

- [**promotional**](#promotional): Ofertas, cupons, carteiras e pontos promocionais.
	- listPairOffers: Lista ofertas em pares de um produto (compre junto)
	- addCoupon: Adiciona cupom no carrinho
	- deleteCoupon: Remove cupom no carrinho
	- applyWallet: Aplica carteira saldo da carteira no carrinho
	- deleteWallet: Remove carteira saldo da carteira no carrinho
	- applyPoint: Aplica saldo de pontos no carrinho
	- deletePoint: Remove saldo de pontos no carrinho

---

## Exemplos de Uso por Escopo

### [cart](#cart)
```ts
import api from '../../api';

// Listar detalhes do carrinho
await api.cart.listDetail(): CartResponse;

// Adiciona produto ao carrinho
await api.cart.addProduct(
	payload: UpsertCartRequest
): CartResponse;

// Remover um ou varios produtos do carrinho
await api.cart.deleteProduct(
	payload: DeleteCartRequest
): CartResponse;

// Adiciona ou atualiza a quantidade do produto no carrinho
await api.cart.upsertProduct(
	payload: UpsertCartRequest
): CartResponse;

// Retorna opções de frete no contexto do carrinho
await api.cart.shipmentQuote(
	payload: ShipmentQuoteCartRequest
): CartResponse;

// Seleciona uma opção de frete no contexto do carrinho.
await api.cart.selectShipment(
	payload: SelectShipimentRequest
): CartResponse;

// Aplica endereço no contexto do carrinho.
await api.cart.applyAddresses(
	payload: AddressesToCartRequest
): CartResponse;

// Lista as opções de pagamento no contexto do carrinho.
await api.cart.listPayments(): PaymentResponse;

// Informa as condições do pagamento, para verificar condições do mix de pagamento
await api.cart.paymentConditions(
	payload: PaymentConditionsRequest
): PaymentConditionsResponse;
```

### [common](#common)
```ts
import api from '../../api';

// Consultar CEP
await api.common.listZipcode(zipcode: string): ZipcodeResponse;

// Retorna dados complementares de cada pais
await api.common.listContries(): Array<CountryResponse>;

// Retorna os detalhes de um pais
await api.common.countryDetail(code: CountryAlpha3): CountryResponse;

// Retorna dados utilitários sobre cada bandeira de cartão
await api.common.listCardFlags(): CardFlags;
```

### [customer](#customer)
```ts
import api from '../../api';

// Inscreve na newsletter da loja por email e name
await api.customer.addNewsletter(): CustomerOrderResponse;

// Remove inscrição na newsletter (apenas clientes logado)
await api.customer.deleteNewsletter(): CustomerOrderResponse;

// Avalia um produto (apenas clientes logado)
await api.customer.createProductReview(
	productId: number,
	payload: ProductReviewRequest,
): ProductReviewResponse;

// Listagem paginada de todas avaliações do produto
await api.customer.listProductReview(
	options?: Pick<
	ApiParams<ReviewFields, ReviewSortFields, ReviewConditionFields>,
		'condition' | 'order' | 'fields' | 'limit' | 'offset'
	>
): ProductReviewResponse;

// Listagem paginada de todas avaliações da loja
await api.customer.listStoreReview(): ProductReviewResponse;

// 
await api.customer.createInterest(
	payload: RequestInterest
): ResponseInterest;

// Alteração de senha com cliente autenticado
await api.customer.changePasswordByAuthenticated(
	payload: ChangePasswordCustomerAuthenticated,
): boolean;

// Alteração de senha através de código enviado por e-mail
await api.customer.changePasswordByCode(
	payload: ChangePasswordCustomerByCode
): boolean;

// Verifica existencia de cliente com base no e-mail ou documento
await api.customer.check(
	payload: CheckCustomer
): boolean;

// Listagem de endereços do cliente logado
await api.customer.listAddress(): CustomerAddressesResponse;

// Cria novo endereço do cliente logado
await api.customer.createAddress(
	payload: UpsertCustomerAddressRequest
): CustomerAddressResponse;

// Remove um endereço do cliente logado
await api.customer.deleteAddress(
	addressId: number
): CustomerAddressResponse;

// Atualiza endereço do cliente logado
await api.customer.updateAddress(
	addressId: number,
	payload: UpsertCustomerAddressRequest,
): CustomerAddressResponse;

// 
await api.customer.updatePrimaryAddress(
	addressId: number
): CustomerAddressResponse;

// 
await api.customer.detail(
	options?: Pick<
		ApiParams<CustomerFields, CustomerSortFields, CustomerConditionFields>,
		'condition' | 'fields' | 'order'
	>
): CustomerResponse;

// 
await api.customer.passwordRecovery(
	payload: PasswordRecoveryCustomer
): boolean;

// 
await api.customer.signinByDocument(
	payload: SigninCustomerByDocument
): ResponseSigninCustomer;

// 
await api.customer.signinByEmail(
	payload: SigninCustomerByEmail
): ResponseSigninCustomer;

// 
await api.customer.signup(
	payload: SignupCustomer
): CustomerResponse;

// 
await api.customer.update(
	payload: UpdateCustomer
): CustomerResponse;

// 
await api.customer.loggout(): boolean;

// 
await api.customer.detailOrderGroup(
	orderId: number,
	options?: Pick<ApiParams<CustomerOrderGroupFields>, 'fields'>,
): CustomerOrderResponse;

// 
await api.customer.listOrderGroups(
	options?: Pick<
		ApiParams<
			CustomerOrderGroupFields,
			CustomerOrderGroupSortFields,
			CustomerOrderGroupConditionFields
		>,
		'condition' | 'fields' | 'limit' | 'offset' | 'order'
	>,
): CustomerOrdersResponse;

// 
await api.customer.listOrderItemHistory(
	orderId: number,
	options?: Pick<
		ApiParams<
			'',
			CustomerOrderItemHistorySortFields,
			CustomerOrderItemHistoryConditionFields
		>,
		'condition' | 'fields' | 'limit' | 'offset' | 'order'
	>,
): CustomerOrderItemHistoriesResponse;

// 
await api.customer.listCustomerHistory(
	options?: Pick<
		ApiParams<
			'', 
			CustomerHistorySortFields, 
			CustomerHistoryConditionFields
		>,
		'condition' | 'limit' | 'offset' | 'order'
	>,
): CustomerHistoryResponse;

// 
await api.customer.listCustomerReview(
	options?: Pick<
		ApiParams<
			ReviewFields, 
			ReviewSortFields, 
			ReviewConditionFields
		>,
		'condition' | 'order' | 'fields' | 'limit' | 'offset'
	>,
): ProductReviewResponse;

// 
await api.customer.listWalletTransaction(
	options?: Pick<
		ApiParams<
			'',
			WalletSortFields, 
			WalletConditionFields
		>,
		'condition' | 'order' | 'limit' | 'offset'
	>,
): WalletTransactionResponse;

// 
await api.customer.claimGiftCard(
	payload: ClaimGiftCardRequest
): ClaimGiftCardResponse;
```

### [customization](#customization)
```ts
import api from '../../api';

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Retorna uma ou varias vitrines com base nos code passado como parametro
await api.customization.listShowcase(codes: Array<string>): Array<Showcase>;
await api.customization.listShowcase(code: string): Showcase;

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Esse método possui Generic AdditionalParameters usado para definir a tipagem dos parametros personalizados e dinamicos cadastrados no grupo de banner.
// Retorna uma ou varios grupos de banner com base nos code passado como parametro
await api.customization.listBanners<AdditionalParameters>(codes: Array<string>): Array<Banners<AdditionalParameters>>;
await api.customization.listBanners<AdditionalParameters>(code: string): Banners<AdditionalParameters>;

// Esse método possui sobrecarga de função, permitindo uma mesma função possuir duas assinaturas. 
// Retorna uma ou varias vitrines com base nos code passado como parametro
await api.customization.listMenu(codes: Array<string>) Array<Menu>;
await api.customization.listMenu(code: string) Menu;
```

### [product](#product)
```ts
import api from '../../api';

// Listar marcas
await api.product.listBrands(
	options?: Pick<
		ApiParams<BrandFields, BrandOrders, BrandConditions>,
		'condition' | 'fields' | 'offset' | 'limit' | 'order'
	>
): Brand;

// Buscar variações de um produto
await api.product.listVariation(
	variationData: VariationData,
	options?: Pick<
		ApiParams<ProductFields, ProductSortFields, ProductConditionFields>,
		'condition' | 'fields' | 'meta'
	>
): Product;

// Nesse método é necessário definir o Generic UrlType conforme a request da página que espera ser retornado, exemplo: para buscar uma página de catalogo é informamos UrlListing. Todos os tipos podem ser conferidos na documentação oficial.
// Request com dados da página (categoria, detalhe de produto, institucional, marca, etc)
await api.product.getUrl<UrlType>(
	path: string,
	options?: Pick<
		ApiParams<ProductFields, ProductOrderFields, ProductConditionFields>,
		'condition' | 'fields' | 'limit' | 'offset' | 'meta' | 'order'
	>
): UrlType;

// Retorna uma lista de produtos com base no termo de pesquisa. Pode ser usado para criar uma sugestão no header do site e também para criar uma listagem paginada de busca de produto
await api.product.getSearch(
	term: string,
	options?: Pick<
		ApiParams<ProductFields, ProductSortFields, ProductConditionFields>,
		'condition' | 'fields' | 'limit' | 'meta' | 'offset' | 'order'
	>
): Search;

// Usado para cotar frete no contexto do produto informado na requisição. Não considera produtos persistidos no carrinho.
await api.product.listShipmentQuoteProduct(
	payload: Pick<ApiParams, 'targetCountryCode' | 'targetZipCode' | 'items'>,
): ShipmentQuoteProductResponse;

// Permite o cliente deletar seu comentário/pergunta realizada no produto.
await api.product.deleteProductComment(
	commentId: number
): boolean;

// Permite o cliente criar um comentário/pergunta no produto.
await api.product.createProductComment(
	productId: number,
  	payload: CreateProductComment,
): ProductComment;

// Retorna uma listagem paginada de todos os comentários do produto 
await api.product.listProductComments(
	options?: Pick<
		ApiParams<
			ProductCommentFields,
			ProductCommentSortFields,
			ProductCommentConditionFields
		>,
		'condition' | 'order' | 'limit' | 'offset' | 'fields'
	>
): ProductCommentsResponse;

// Retorna a árvore de uma categoria: categoria atual, filhas, irmãs e pai.
await api.product.getCategoryTree(
	categoryId: number
): CategoryTree;

// Retorna a árvore completa de categorias ativas, com todos os níveis aninhados.
await api.product.listCategoriesTree(): Array<CategoryTreeItem>;
```


### [promotional](#promotional)
```ts
import api from '../../api';

// Retorna a listagem de opções de compre junto no contexto do produto.
await api.promotional.listPairOffers(
	productId: number,
	options?: Pick<ApiParams<ProductFields>, 'fields' | 'variationMap'>
): PairOfferResponse;

// Adiciona cupom no contexto do carrinho.
await api.promotional.addCoupon(
	payload: AddCouponRequest
): CartResponse;

// Remove cupom no contexto do carrinho.
await api.promotional.deleteCoupon(): CartResponse;

// Aplica saldo em carteira como forma de desconto no contexto carrinho.
await api.promotional.applyWallet(): CartResponse;

// Remove saldo em carteira aplicado no contexto do carrinho.
await api.promotional.deleteWallet(): CartResponse;

// Aplica saldo de pontos como forma de desconto no contexto do carrinho.
await api.promotional.applyPoint(): CartResponse;

// Remove saldo de pontos aplicado no contexto do carrinho.
await api.promotional.deletePoint(): CartResponse;
```

## Tipos

Todos os métodos retornam dados tipados para melhor experiência com TypeScript.

## Contribuição

Contribuições são bem-vindas! Abra uma issue ou envie um pull request.

## Licença

ISC