Pz/qualifications api (#254)

* in progress

* done?

* readme

* done

* Create right-po-voucherify.md

* done

* Update DiscountVoucher.ts

* Update DiscountVoucher.ts

* Update DiscountVoucher.ts

* es lint fix

* Update right-po-voucherify.md

* Update DiscountVoucher.ts

* Update DiscountVoucher.ts

* changes requested

* requested changes - type names

* Update Orders.ts

* Update right-po-voucherify.md

* fix

.changeset/right-po-voucherify.md

@@ -0,0 +1,10 @@
+---
+'@voucherify/sdk': minor
+---
+
+Add support for few endpoints of Loyalties API.
+- Added support for new endpoints: `POST /v1/qualifications`, `POST /client/v1/qualifications` [(examples of usage available in readme.md)](..%2F..%2Fpackages%2Fsdk%2FREADME.md)
+- New exported types/interfaces: `InapplicableTo`, `Referrer`, `ReferrerWithSummaryLoyaltyReferrals`, `Customer`, `CustomerWithSummaryLoyaltyReferrals`, `CustomerSummary`, `CustomerSummaryRedemptions`, `CustomerSummaryOrders`, `CustomerLoyalty`, `CustomerReferrals`, `Discount`, `DiscountAmount_`, `DiscountUnit_`, `DiscountUnitBase_`, `DiscountUnitMultiple_`, `DiscountPercent_`, `DiscountFixed_`, `Order`, `OrderItem`, `OrderCalculated`, `OrderRedemptions`, `OrderItemCalculated`, `QualificationsCheckEligibilityRequestBody`, `QualificationsCheckEligibilityResponseBody`, `QualificationsFiltersFields`, `QualificationsFiltersCondition`, `QualificationsFieldConditions`, `QualificationsRedeemablesResponse`, `QualificationsStackingRulesResponse`, `QualificationsRedeemable`, `QualificationsRedeemableBase`, `RedeemableSingleResultResponse`, `ValidationRulesAssignmentsList`,
+- Added optional properties to `ApplicableTo`: `product_id`, `product_source_id`, `quantity_limit`, `aggregated_quantity_limit`, `amount_limit`, `aggregated_amount_limit`, `order_item_indices`
+- Added required property: `data_ref: 'data'` to `ApplicableToResultList` // NOTE: as this type is only used in responses, this is not a breaking change.
+- Added optional properties to `CustomerRequest`: `birthday` and `birthdate`

packages/sdk/README.md

@@ -450,6 +450,20 @@ client.categories.list()
 
 ---
 
+### Qualifications
+
+Methods are provided within `client.qualifications.*` or `client.promotions.*` namespace.
+
+- [Check Eligibility](#Check-Eligibility)
+
+#### [Check Eligibility](https://docs.voucherify.io/reference/check-eligibility)
+
+```javascript
+client.qualifications.checkEligibility(body)
+```
+
+---
+
 ### Validations
 
 Methods are provided within `client.validations.*` or `client.promotions.*` namespace.
@@ -1606,6 +1620,7 @@ Methods are provided within `client.*` namespace.
 - [List consents](#list-consents)
 - [Update consents](#update-consents)
 - [Track custom events](#track-custom-events)
+- [Qualifications](#Qualifications)
 
 #### Set Identity
 
@@ -1678,6 +1693,12 @@ client.updateConsents(idOrSourceId, consents)
 client.track(eventName, metadata, customer)
 ```
 
+#### [Qualifications](https://docs.voucherify.io/reference/check-eligibility-client-side)
+
+```javascript
+client.qualifications(body)
+```
+
 # <a name="snippet"></a>🏎 Marketer-ready Voucherify snippet
 
 Go [here](./examples/sdk/with-html) for more HTML-based examples

packages/sdk/src/ClientSide.ts

@@ -1,4 +1,5 @@
 import * as T from './types/ClientSide'
+import * as TQ from './types/Qualifications'
 
 import { assert, encode, isObject, isOptionalObject, isOptionalString, isString } from './helpers'
 
@@ -169,4 +170,10 @@ export class ClientSide {
 	public redeemStackable(params: T.ClientSideRedemptionsRedeemStackableParams) {
 		return this.client.post<T.ClientSideRedemptionsRedeemStackableResponse>(`/redemptions`, params)
 	}
+	/**
+	 * @see https://docs.voucherify.io/reference/check-eligibility
+	 */
+	public qualifications(body: TQ.QualificationsCheckEligibilityRequestBody) {
+		return this.client.post<TQ.QualificationsCheckEligibilityResponseBody>('/qualifications', body)
+	}
 }

packages/sdk/src/Qualifications.ts

@@ -0,0 +1,14 @@
+import * as T from './types/Qualifications'
+
+import type { RequestController } from './RequestController'
+
+export class Qualifications {
+	constructor(private client: RequestController) {}
+
+	/**
+	 * @see https://docs.voucherify.io/reference/check-eligibility
+	 */
+	public checkEligibility(body: T.QualificationsCheckEligibilityRequestBody) {
+		return this.client.post<T.QualificationsCheckEligibilityResponseBody>('/qualifications', body)
+	}
+}

packages/sdk/src/VoucherifyServerSide.ts

@@ -24,6 +24,7 @@ import { MetadataSchemas } from './MetadataSchemas'
 import { Categories } from './Categories'
 import { PromotionsStacks } from './PromotionsStacks'
 import { ProductCollections } from './ProductCollections'
+import { Qualifications } from './Qualifications'
 
 export interface VoucherifyServerSideOptions {
 	/**
@@ -191,6 +192,7 @@ export function VoucherifyServerSide(options: VoucherifyServerSideOptions) {
 	const promotions = new Promotions(client, promotionTiers, promotionStack)
 	const validations = new Validations(client, promotions)
 	const redemptions = new Redemptions(client)
+	const qualifications = new Qualifications(client)
 	const customers = new Customers(client)
 	const consents = new Consents(client)
 	const orders = new Orders(client)
@@ -216,6 +218,7 @@ export function VoucherifyServerSide(options: VoucherifyServerSideOptions) {
 		orders,
 		products,
 		productCollections,
+		qualifications,
 		rewards,
 		loyalties,
 		segments,

packages/sdk/src/index.ts

@@ -22,3 +22,4 @@ export type { ValidationRules } from './ValidationRules'
 export type { Validations } from './Validations'
 export type { VoucherifyError } from './VoucherifyError'
 export type { Vouchers } from './Vouchers'
+export type { Qualifications } from './Qualifications'

packages/sdk/src/types/ApplicableTo.ts

@@ -4,14 +4,31 @@ export interface ApplicableTo {
 	object: 'product' | 'sku' | 'products_collection'
 	id: string
 	source_id?: string
+	product_id?: string
+	product_source_id?: string
 	strict: boolean
 	price?: number
 	price_formula?: number
 	effect: ApplicableToEffect
+	quantity_limit?: number
+	aggregated_quantity_limit?: number
+	amount_limit?: number
+	aggregated_amount_limit?: number
+	order_item_indices?: number[]
 }
 
 export interface ApplicableToResultList {
 	object: 'list'
 	total: number
 	data: ApplicableTo[]
+	data_ref: 'data'
 }
+
+export type InapplicableToResultList = {
+	data: InapplicableTo[]
+	total: number
+	object: 'list'
+	data_ref: string
+}
+
+export type InapplicableTo = ApplicableTo

packages/sdk/src/types/Customers.ts

@@ -71,9 +71,11 @@ export interface CustomerRequest {
 	id?: string
 	source_id?: string
 	name?: string
-	email?: string
-	metadata?: Record<string, any>
 	description?: string
+	email?: string
+	phone?: string
+	birthday?: string
+	birthdate?: string
 	address?: {
 		city?: string
 		state?: string
@@ -82,7 +84,7 @@ export interface CustomerRequest {
 		country?: string
 		postal_code?: string
 	}
-	phone?: string
+	metadata?: Record<string, any>
 }
 
 export interface CustomersCommonListRequest {
@@ -162,6 +164,95 @@ type CustomerAddress = {
 	} | null
 }
 
+export type Referrer = CustomerRequest
+export type Customer = CustomerRequest
+
+export type ReferrerWithSummaryLoyaltyReferrals = CustomerWithSummaryLoyaltyReferrals
+
+export type CustomerId = {
+	id: string
+	object: 'customer'
+}
+
+export type ReferrerId = CustomerId
+
+export type CustomerWithSummaryLoyaltyReferrals = {
+	id?: string
+	source_id?: string
+	name?: string
+	description?: string
+	email?: string
+	phone?: string
+	birthday?: string
+	birthdate?: string
+	address: {
+		city?: string
+		state?: string
+		line_1?: string
+		line_2?: string
+		country?: string
+		postal_code?: string
+	} | null
+	metadata?: Record<string, any>
+	summary: CustomerSummary
+	loyalty: CustomerLoyalty
+	referrals: CustomerReferrals
+	system_metadata: Record<string, unknown>
+	created_at: string
+	updated_at?: string
+	assets?: {
+		cockpit_url?: string
+	}
+	object: 'customer'
+}
+
+export type CustomerSummary = {
+	redemptions: CustomerSummaryRedemptions
+	orders: CustomerSummaryOrders
+}
+
+export type CustomerSummaryRedemptions = {
+	total_redeemed: number
+	total_failed: number
+	total_succeeded: number
+	total_rolled_back: number
+	total_rollback_failed: number
+	total_rollback_succeeded: number
+	gift: {
+		redeemed_amount: number
+		amount_to_go: number
+	}
+	loyalty_card: {
+		redeemed_points: number
+		points_to_go: number
+	}
+}
+
+export type CustomerSummaryOrders = {
+	total_amount: number
+	total_count: number
+	average_amount: number
+	last_order_amount: number
+	last_order_date: string
+}
+
+export type CustomerLoyalty = {
+	points: number
+	referred_customers: number
+	campaigns: Record<string, { points: number; loyalty_tier: string; referred_customers: number }>
+}
+
+export type CustomerReferrals = {
+	total: number
+	campaigns: {
+		campaign_id: string
+		referrer_id: string
+		related_object_id: string
+		related_object_type: string
+		date: string
+	}[]
+}
+
 // 0-level types
 
 export type CustomersUpdateInBulkRequestBody = (CustomerBase &

packages/sdk/src/types/DiscountVoucher.ts

@@ -15,6 +15,7 @@ export type DiscountVouchersEffectTypes =
 	| 'APPLY_TO_ITEMS'
 	| 'APPLY_TO_ITEMS_PROPORTIONALLY'
 	| 'APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY'
+	| 'APPLY_TO_ITEMS_BY_QUANTITY'
 
 export type DiscountUnitVouchersEffectTypes = 'ADD_MISSING_ITEMS' | 'ADD_NEW_ITEMS' | 'ADD_MANY_ITEMS'
 
@@ -23,6 +24,7 @@ export type DiscountAmountVouchersEffectTypes =
 	| 'APPLY_TO_ITEMS'
 	| 'APPLY_TO_ITEMS_PROPORTIONALLY'
 	| 'APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY'
+	| 'APPLY_TO_ITEMS_BY_QUANTITY'
 
 export type DiscountPercentVouchersEffectTypes = 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS'
 
@@ -70,3 +72,53 @@ export interface DiscountFixed {
 	fixed_amount_formula?: string
 	effect?: DiscountFixedVouchersEffectTypes
 }
+
+// domain types
+
+// didn't want to make major changes
+export type Discount = DiscountAmount_ | DiscountUnit_ | DiscountUnitMultiple_ | DiscountPercent_ | DiscountFixed_
+
+export type DiscountAmount_ = {
+	type: 'AMOUNT'
+	amount_off?: number
+	amount_off_formula?: string
+	aggregated_amount_limit?: number
+	effect?: DiscountAmountVouchersEffectTypes
+	is_dynamic?: boolean
+}
+
+export type DiscountUnit_ = { type: 'UNIT' } & DiscountUnitBase_
+
+export type DiscountUnitBase_ = {
+	unit_off?: number
+	unit_off_formula?: string
+	unit_type: string
+	product?: SimpleProductDiscountUnit
+	sku?: SimpleSkuDiscountUnit
+	effect?: 'ADD_MISSING_ITEMS' | 'ADD_NEW_ITEMS'
+	is_dynamic?: boolean
+}
+
+export type DiscountUnitMultiple_ = {
+	type: 'UNIT'
+	effect: 'ADD_MANY_ITEMS'
+	units: DiscountUnitBase_[]
+}
+
+export type DiscountPercent_ = {
+	type: 'PERCENT'
+	percent_off?: number
+	percent_off_formula?: string
+	amount_limit?: number
+	aggregated_amount_limit?: number
+	effect?: DiscountPercentVouchersEffectTypes
+	is_dynamic?: boolean
+}
+
+export type DiscountFixed_ = {
+	type: 'FIXED'
+	fixed_amount?: number
+	fixed_amount_formula?: string
+	effect?: DiscountFixedVouchersEffectTypes
+	is_dynamic?: boolean
+}