@automattic/data-stores 3.0.1 → 3.1.0-rc.1

package/src/plans/queries/lib/unpack-intro-offer.ts

@@ -0,0 +1,40 @@
+import type { PlanIntroductoryOffer, PricedAPIPlan, PricedAPISitePlan } from '../../types';
+
+/**
+ * Unpacks an intro offer from an API plan to the respective `PlanIntroductoryOffer` structure for the store.
+ */
+const unpackIntroOffer = (
+	plan: PricedAPISitePlan | PricedAPIPlan
+): PlanIntroductoryOffer | null => {
+	// these aren't grouped or separated. so no introductory offer if no cost or interval
+	if ( ! plan.introductory_offer_interval_unit && ! plan.introductory_offer_interval_count ) {
+		return null;
+	}
+
+	/**
+	 * An offer is complete if:
+	 *   1. an expiry date is set on the plan that exceeds the offer end date, OR
+	 *   2. the current Date exceeds the offer end date
+	 */
+	const isOfferComplete =
+		'expiry' in plan
+			? Boolean(
+					plan.expiry &&
+						plan.introductory_offer_end_date &&
+						new Date( plan.expiry ) > new Date( plan.introductory_offer_end_date )
+			  )
+			: Boolean(
+					plan.introductory_offer_end_date &&
+						new Date() > new Date( plan.introductory_offer_end_date )
+			  );
+
+	return {
+		formattedPrice: plan.introductory_offer_formatted_price as string,
+		rawPrice: plan.introductory_offer_raw_price as number,
+		intervalUnit: plan.introductory_offer_interval_unit as string,
+		intervalCount: plan.introductory_offer_interval_count as number,
+		isOfferComplete,
+	};
+};
+
+export default unpackIntroOffer;

package/src/plans/queries/lib/use-query-keys-factory.ts

@@ -0,0 +1,6 @@
+const useQueryKeysFactory = () => ( {
+	sitePlans: ( siteId?: string | number | null ) => [ 'site-plans', siteId ],
+	plans: ( coupon?: string ) => [ 'plans', coupon ],
+} );
+
+export default useQueryKeysFactory;

package/src/plans/queries/use-plans.ts

@@ -0,0 +1,79 @@
+import { calculateMonthlyPriceForPlan } from '@automattic/calypso-products';
+import { useLocale } from '@automattic/i18n-utils';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import wpcomRequest from 'wpcom-proxy-request';
+import unpackIntroOffer from './lib/unpack-intro-offer';
+import useQueryKeysFactory from './lib/use-query-keys-factory';
+import type { PricedAPIPlan, PlanNext } from '../types';
+
+interface PlansIndex {
+	[ planSlug: string ]: PlanNext;
+}
+
+/**
+ * Plans from `/plans` endpoint, transformed into a map of planSlug => PlanNext
+ */
+function usePlans( {
+	coupon,
+}: {
+	/**
+	 * `coupon` required on purpose to mitigate risk with not passing something through when we should
+	 */
+	coupon: string | undefined;
+} ): UseQueryResult< PlansIndex > {
+	const queryKeys = useQueryKeysFactory();
+	const locale = useLocale();
+	const params = new URLSearchParams();
+	coupon && params.append( 'coupon_code', coupon );
+	params.append( 'locale', locale );
+
+	return useQuery( {
+		queryKey: queryKeys.plans( coupon ),
+		queryFn: async (): Promise< PlansIndex > => {
+			const data: PricedAPIPlan[] = await wpcomRequest( {
+				path: `/plans`,
+				apiVersion: '1.5',
+				query: params.toString(),
+			} );
+
+			return Object.fromEntries(
+				data.map( ( plan ) => {
+					const discountedPriceFull =
+						plan.orig_cost_integer !== plan.raw_price_integer ? plan.raw_price_integer : null;
+
+					return [
+						plan.product_slug,
+						{
+							planSlug: plan.product_slug,
+							productSlug: plan.product_slug,
+							productId: plan.product_id,
+							pathSlug: plan.path_slug,
+							productNameShort: plan.product_name_short,
+							pricing: {
+								billPeriod: plan.bill_period,
+								currencyCode: plan.currency_code,
+								introOffer: unpackIntroOffer( plan ),
+								originalPrice: {
+									monthly:
+										typeof plan.orig_cost_integer === 'number'
+											? calculateMonthlyPriceForPlan( plan.product_slug, plan.orig_cost_integer )
+											: null,
+									full: plan.orig_cost_integer,
+								},
+								discountedPrice: {
+									monthly:
+										typeof discountedPriceFull === 'number'
+											? calculateMonthlyPriceForPlan( plan.product_slug, discountedPriceFull )
+											: null,
+									full: discountedPriceFull,
+								},
+							},
+						},
+					];
+				} )
+			);
+		},
+	} );
+}
+
+export default usePlans;

package/src/plans/queries/use-site-plans.ts

@@ -0,0 +1,82 @@
+import { calculateMonthlyPriceForPlan } from '@automattic/calypso-products';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import wpcomRequest from 'wpcom-proxy-request';
+import unpackCostOverrides from './lib/unpack-cost-overrides';
+import unpackIntroOffer from './lib/unpack-intro-offer';
+import useQueryKeysFactory from './lib/use-query-keys-factory';
+import type { PricedAPISitePlan, SitePlan } from '../types';
+
+interface SitePlansIndex {
+	[ planSlug: string ]: SitePlan;
+}
+interface PricedAPISitePlansIndex {
+	[ productId: number ]: PricedAPISitePlan;
+}
+
+interface Props {
+	siteId: string | number | null | undefined;
+}
+
+/**
+ * Plans from `/sites/[siteId]/plans` endpoint, transformed into a map of planSlug => SitePlan
+ * - Plans from `/sites/[siteId]/plans`, unlike `/plans`, are returned indexed by product_id, and do not include that in the plan's payload.
+ * - UI works with product/plan slugs everywhere, so returned index is transformed to be keyed by product_slug
+ */
+function useSitePlans( { siteId }: Props ): UseQueryResult< SitePlansIndex > {
+	const queryKeys = useQueryKeysFactory();
+
+	return useQuery( {
+		queryKey: queryKeys.sitePlans( siteId ),
+		queryFn: async (): Promise< SitePlansIndex > => {
+			const data: PricedAPISitePlansIndex = await wpcomRequest( {
+				path: `/sites/${ encodeURIComponent( siteId as string ) }/plans`,
+				apiVersion: '1.3',
+			} );
+
+			return Object.fromEntries(
+				Object.keys( data ).map( ( productId ) => {
+					const plan = data[ Number( productId ) ];
+					const originalPriceFull = plan.raw_discount_integer
+						? plan.raw_price_integer + plan.raw_discount_integer
+						: plan.raw_price_integer;
+					const discountedPriceFull = plan.raw_discount_integer ? plan.raw_price_integer : null;
+
+					return [
+						plan.product_slug,
+						{
+							planSlug: plan.product_slug,
+							productSlug: plan.product_slug,
+							productId: Number( productId ),
+							expiry: plan.expiry,
+							currentPlan: plan.current_plan,
+							hasRedeemedDomainCredit: plan?.has_redeemed_domain_credit,
+							purchaseId: plan.id ? Number( plan.id ) : undefined,
+							pricing: {
+								currencyCode: plan.currency_code,
+								introOffer: unpackIntroOffer( plan ),
+								costOverrides: unpackCostOverrides( plan ),
+								originalPrice: {
+									monthly:
+										typeof originalPriceFull === 'number'
+											? calculateMonthlyPriceForPlan( plan.product_slug, originalPriceFull )
+											: null,
+									full: originalPriceFull,
+								},
+								discountedPrice: {
+									monthly:
+										typeof discountedPriceFull === 'number'
+											? calculateMonthlyPriceForPlan( plan.product_slug, discountedPriceFull )
+											: null,
+									full: discountedPriceFull,
+								},
+							},
+						},
+					];
+				} )
+			);
+		},
+		enabled: !! siteId,
+	} );
+}
+
+export default useSitePlans;

package/src/plans/resolvers.ts

@@ -27,7 +27,6 @@ const MONTHLY_PLAN_BILLING_PERIOD = 31;
 /**
  * Calculates the monthly price of a plan
  * Annual plans are only priced yearly
- *
  * @param plan the plan object
  */
 function getMonthlyPrice( plan: PricedAPIPlan ) {
@@ -36,7 +35,6 @@ function getMonthlyPrice( plan: PricedAPIPlan ) {
 
 /**
  * Calculates the yearly price of a monthly plan
- *
  * @param plan the plan object
  */
 function getAnnualPrice( plan: PricedAPIPlan ) {
@@ -46,7 +44,6 @@ function getAnnualPrice( plan: PricedAPIPlan ) {
 /**
  * Formats the plan price according to 'format-currency' package rules
  * We use this for consistency in prices formats across monthly and annual plans
- *
  * @param plan the plan object
  */
 function getFormattedPrice( plan: PricedAPIPlan ) {
@@ -62,7 +59,7 @@ function calculateDiscounts( planProducts: PlanProduct[] ) {
 		if ( annualPlan && monthlyPlan ) {
 			const annualCostIfPaidMonthly = monthlyPlan.rawPrice * 12;
 			const annualCostIfPaidAnnually = annualPlan.rawPrice;
-			const discount = Math.round(
+			const discount = Math.floor(
 				100 * ( 1 - annualCostIfPaidAnnually / annualCostIfPaidMonthly )
 			);
 			annualPlan.annualDiscount = discount;
@@ -72,17 +69,20 @@ function calculateDiscounts( planProducts: PlanProduct[] ) {
 }
 
 function processFeatures( features: DetailsAPIFeature[] ) {
-	return features.reduce( ( features, feature ) => {
-		features[ feature.id ] = {
-			id: feature.id,
-			name: feature.name,
-			description: feature.description,
-			type: 'checkbox',
-			requiresAnnuallyBilledPlan:
-				FEATURE_IDS_THAT_REQUIRE_ANNUALLY_BILLED_PLAN.indexOf( feature.id ) > -1,
-		};
-		return features;
-	}, {} as Record< string, PlanFeature > );
+	return features.reduce(
+		( features, feature ) => {
+			features[ feature.id ] = {
+				id: feature.id,
+				name: feature.name,
+				description: feature.description,
+				type: 'checkbox',
+				requiresAnnuallyBilledPlan:
+					FEATURE_IDS_THAT_REQUIRE_ANNUALLY_BILLED_PLAN.indexOf( feature.id ) > -1,
+			};
+			return features;
+		},
+		{} as Record< string, PlanFeature >
+	);
 }
 
 function featureRequiresAnnual(
@@ -186,10 +186,13 @@ export function* getSupportedPlans( locale = 'en' ) {
 			features: processPlanFeatures( plan, features ),
 			storage: plan.storage,
 			title: plan.short_name,
-			featuresSlugs: plan.features.reduce( ( slugs, slug ) => {
-				slugs[ slug ] = true;
-				return slugs;
-			}, {} as Record< string, boolean > ),
+			featuresSlugs: plan.features.reduce(
+				( slugs, slug ) => {
+					slugs[ slug ] = true;
+					return slugs;
+				},
+				{} as Record< string, boolean >
+			),
 			isFree: planSlug === TIMELESS_PLAN_FREE,
 			isPopular: planSlug === TIMELESS_PLAN_PREMIUM,
 			periodAgnosticSlug: planSlug,

package/src/plans/selectors.ts

@@ -15,6 +15,7 @@ import type {
 	PlanProduct,
 	PlanPath,
 	PlanSlug,
+	PlansSelect,
 	StorePlanSlug,
 } from './types';
 
@@ -37,9 +38,9 @@ export const getPlanByProductId = (
 		return undefined;
 	}
 
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getSupportedPlans( locale )
-		.find( ( plan ) => plan.productIds.indexOf( productId ) > -1 );
+		.find( ( plan: Plan ) => plan.productIds.indexOf( productId ) > -1 );
 };
 
 export const getPlanProductById = (
@@ -50,9 +51,9 @@ export const getPlanProductById = (
 		return undefined;
 	}
 
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getPlansProducts()
-		.find( ( product ) => product.productId === productId );
+		.find( ( product: PlanProduct ) => product.productId === productId );
 };
 
 export const getPlanByPeriodAgnosticSlug = (
@@ -63,21 +64,21 @@ export const getPlanByPeriodAgnosticSlug = (
 	if ( ! slug ) {
 		return undefined;
 	}
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getSupportedPlans( locale )
-		.find( ( plan ) => plan.periodAgnosticSlug === slug );
+		.find( ( plan: Plan ) => plan.periodAgnosticSlug === slug );
 };
 
 export const getDefaultPaidPlan = ( _: State, locale: string ): Plan | undefined => {
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getSupportedPlans( locale )
-		.find( ( plan ) => plan.periodAgnosticSlug === DEFAULT_PAID_PLAN );
+		.find( ( plan: Plan ) => plan.periodAgnosticSlug === DEFAULT_PAID_PLAN );
 };
 
 export const getDefaultFreePlan = ( _: State, locale: string ): Plan | undefined => {
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getSupportedPlans( locale )
-		.find( ( plan ) => plan.periodAgnosticSlug === TIMELESS_PLAN_FREE );
+		.find( ( plan: Plan ) => plan.periodAgnosticSlug === TIMELESS_PLAN_FREE );
 };
 
 export const getSupportedPlans = ( state: State, _locale: string ): Plan[] => {
@@ -90,7 +91,6 @@ export const getPlansProducts = ( state: State ): PlanProduct[] => {
 
 /**
  * @deprecated  getPrices is deprecated, please use plan.price directly
- *
  * @param _state the state
  * @param _locale the locale
  */
@@ -98,12 +98,13 @@ export const getPrices = ( _state: State, _locale: string ): Record< StorePlanSl
 	deprecate( 'getPrices', {
 		alternative: 'getPlanProduct().price',
 	} );
-	return select( STORE_KEY )
-		.getPlansProducts()
-		.reduce( ( prices, plan ) => {
+	return ( select( STORE_KEY ) as PlansSelect ).getPlansProducts().reduce(
+		( prices: Record< StorePlanSlug, string >, plan: PlanProduct ) => {
 			prices[ plan.storeSlug ] = plan.price;
 			return prices;
-		}, {} as Record< StorePlanSlug, string > );
+		},
+		{} as Record< StorePlanSlug, string >
+	);
 };
 
 export const getPlanByPath = (
@@ -115,17 +116,17 @@ export const getPlanByPath = (
 		return undefined;
 	}
 
-	const planProduct = select( STORE_KEY )
+	const planProduct = ( select( STORE_KEY ) as PlansSelect )
 		.getPlansProducts()
-		.find( ( product ) => product.pathSlug === path );
+		.find( ( product: PlanProduct ) => product.pathSlug === path );
 
 	if ( ! planProduct ) {
 		return undefined;
 	}
 
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getSupportedPlans( locale )
-		.find( ( plan ) => plan.periodAgnosticSlug === planProduct.periodAgnosticSlug );
+		.find( ( plan: Plan ) => plan.periodAgnosticSlug === planProduct.periodAgnosticSlug );
 };
 
 export const getPlanProduct = (
@@ -137,9 +138,9 @@ export const getPlanProduct = (
 		return undefined;
 	}
 
-	return select( STORE_KEY )
+	return ( select( STORE_KEY ) as PlansSelect )
 		.getPlansProducts()
-		.find( ( product ) => {
+		.find( ( product: PlanProduct ) => {
 			const matchesSlug = product.periodAgnosticSlug === periodAgnosticSlug;
 			// The billing period doesn't matter when dealing with free plan
 			const matchesBillingPeriod =

package/src/plans/types.ts

@@ -1,13 +1,32 @@
+import { PERIOD_LIST } from './constants';
+import * as selectors from './selectors';
 import type { plansProductSlugs, plansSlugs } from './constants';
+import type { SelectFromMap } from '../mapped-types';
+import type { PlanSlug as PlanSlugFromProducts } from '@automattic/calypso-products';
 
-export type StorePlanSlug = typeof plansProductSlugs[ number ];
-export type PlanSlug = typeof plansSlugs[ number ];
+export type StorePlanSlug = ( typeof plansProductSlugs )[ number ];
+export type PlanSlug = ( typeof plansSlugs )[ number ];
 
-// at the moment possible plan paths are identical with plan slugs
+/**
+ * at the moment possible plan paths are identical with plan slugs
+ *
+ * Update 2024/07/10:
+ *   - it looks like the above is no longer the reality
+ *   - the type should either be removed (widened to string) or compiled to a list of all possible paths
+ */
 export type PlanPath = PlanSlug;
 
 export type PlanBillingPeriod = 'MONTHLY' | 'ANNUALLY';
-export type PlanNonlocalizedShortName = 'Free' | 'Personal' | 'Premium' | 'Business' | 'eCommerce';
+export type PlanNonlocalizedShortName =
+	| 'Free'
+	| 'Personal'
+	| 'Premium'
+	| 'Business'
+	| 'eCommerce'
+	| 'Starter'
+	| 'Explorer'
+	| 'Creator'
+	| 'Entrepreneur';
 
 export type PlanAction = {
 	type: string;
@@ -38,27 +57,216 @@ export interface PlanProduct {
 	storeSlug: StorePlanSlug;
 	annualDiscount?: number;
 	periodAgnosticSlug: PlanSlug;
-	pathSlug?: PlanPath;
-	/** Useful for two cases:
+	pathSlug?: string;
+	/**
+	 * Useful for two cases:
 	 * 1) to show how much we bill the users for annual plans ($8/mo billed $96)
 	 * 2) to show how much a monthly plan would cost in a year (billed 12$/mo costs $144/yr)
-	 *  */
+	 */
 	annualPrice: string;
 }
 
+export interface PlanIntroductoryOffer {
+	formattedPrice: string;
+	rawPrice: number;
+	intervalUnit: string;
+	intervalCount: number;
+	isOfferComplete: boolean;
+}
+
+export interface CostOverride {
+	doesOverrideOriginalCost: boolean;
+	firstUnitOnly: boolean;
+	newPrice: number;
+	oldPrice: number;
+	overrideCode: string;
+	percentage: number;
+}
+
+export interface PlanPricing {
+	billPeriod: -1 | ( typeof PERIOD_LIST )[ number ];
+	currencyCode: string;
+	introOffer?: PlanIntroductoryOffer | null;
+	/**
+	 * This is the original cost as defined for the associated billing plan.
+	 */
+	originalPrice: {
+		monthly: number | null;
+		full: number | null;
+	};
+	/**
+	 * This is the original cost as defined for the associated billing plan, minus any discounts
+	 * stemming from either currency conversion and/or prorated credits (in the case of Site Plans).
+	 *   1. If a concrete value exists for `Plan` (derived from `usePlans`),
+	 * then it refers to a technical discount due to currency conversion.
+	 *   2. If a concrete value exists for `SitePlan` (derived from `useSitePlans`),
+	 * then it refers to a credit-based discount on the plan price (e.g. from proration).
+	 */
+	discountedPrice: {
+		monthly: number | null;
+		full: number | null;
+	};
+}
+
+export interface SitePlanPricing extends Omit< PlanPricing, 'billPeriod' > {
+	costOverrides?: CostOverride[];
+}
+
+/**
+ * `PricingMetaForGridPlan` should be adjusted to extend `PlanPricing`, or modify `PlanPricing` to have a single pricing interface.
+ * - optional/required properties should be the same
+ * - types should be the same
+ * - naming inconsistencies (billingPeriod -> billPeriod)
+ * - `expiry` missing in `PlanPricing`
+ */
+export interface PricingMetaForGridPlan {
+	billingPeriod?: PlanPricing[ 'billPeriod' ];
+	currencyCode?: PlanPricing[ 'currencyCode' ];
+	originalPrice: PlanPricing[ 'originalPrice' ];
+	/**
+	 * If discounted prices are provided (not null), they will take precedence over originalPrice.
+	 * UI will show original with a strikethrough or grayed out
+	 */
+	discountedPrice: PlanPricing[ 'discountedPrice' ];
+	/**
+	 * Intro offers override billing and pricing shown in the UI
+	 * they are currently defined off the site plans (so not defined when siteId is not available)
+	 */
+	introOffer?: PlanPricing[ 'introOffer' ];
+	expiry?: SitePlan[ 'expiry' ];
+}
+
+export interface SitePlan {
+	/* START: Same SitePlan/PlanNext props */
+	planSlug: PlanSlugFromProducts;
+	productSlug: PlanSlugFromProducts;
+	productId: number;
+	pricing: SitePlanPricing;
+	/* END: Same SitePlan/PlanNext props */
+	currentPlan?: boolean;
+	hasRedeemedDomainCredit?: boolean;
+	/**
+	 * This value is only returned for the current plan on the site.
+	 * It is only available from site plans and is the expiry date of an existing plan.
+	 */
+	expiry?: string;
+	/**
+	 * This is only set when `currentPlan` is true (so for the current plan on the site).
+	 * It is sent through as `id` from the endpoint and remapped here to avoid confusion e.g. with `productId`.
+	 */
+	purchaseId?: number;
+}
+
+/**
+ * This is the new interface for API Plans that will replace the existing Plan interface above.
+ * The existing Plan interface will be removed once this interface is fully implemented.
+ */
+export interface PlanNext {
+	/* START: Same SitePlan/PlanNext props */
+	planSlug: PlanSlugFromProducts;
+	productSlug: PlanSlugFromProducts;
+	productId: number;
+	pricing: PlanPricing;
+	/* END: Same SitePlan/PlanNext props */
+	productNameShort: string;
+	pathSlug?: string;
+}
+
+export interface PricedAPIPlanIntroductoryOffer {
+	introductory_offer_formatted_price?: string;
+	introductory_offer_raw_price?: number;
+	introductory_offer_interval_unit?: string;
+	introductory_offer_interval_count?: number;
+	introductory_offer_end_date?: string;
+}
+
+export interface PricedAPISitePlanCostOverride {
+	does_override_original_cost: boolean;
+	first_unit_only: boolean;
+	new_price: number;
+	old_price: number;
+	override_code: string;
+	percentage: number;
+}
+
+export interface PricedAPIPlanPricing {
+	bill_period: -1 | ( typeof PERIOD_LIST )[ number ];
+	product_display_price: string;
+	formatted_price: string;
+
+	/**
+	 * The product price in the currency's smallest unit.
+	 */
+	raw_price_integer: number;
+
+	/**
+	 * The orig cost in the currency's smallest unit. Note that orig_cost_integer is never null.
+	 * If the cost of a store product is overridden by a promotion or a coupon, orig_cost_integer
+	 * will return a price identical to raw_price_integer instead.
+	 */
+	orig_cost_integer: number;
+
+	currency_code: string;
+}
+
+export interface PricedAPISitePlanPricing
+	extends Omit< PricedAPIPlanPricing, 'orig_cost_integer' | 'bill_period' > {
+	raw_discount_integer: number;
+
+	cost_overrides?: PricedAPISitePlanCostOverride[];
+}
+
 /**
  * Item returned from https://public-api.wordpress.com/rest/v1.5/plans response
  * Only the properties that are actually used in the store are typed
  */
-export interface PricedAPIPlan {
+export interface PricedAPIPlan extends PricedAPIPlanPricing, PricedAPIPlanIntroductoryOffer {
 	product_id: number;
 	product_name: string;
-	path_slug?: PlanPath;
+	path_slug?: string;
 	product_slug: StorePlanSlug;
-	bill_period: -1 | 31 | 365;
+	product_name_short: string;
+	product_type?: string;
+
+	/**
+	 * The product price as a float.
+	 * @deprecated use raw_price_integer as using floats for currency is not safe.
+	 */
 	raw_price: number;
-	currency_code: string;
+
+	/**
+	 * The orig cost as a float.
+	 * @deprecated use orig_cost_integer as using floats for currency is not safe.
+	 */
+	orig_cost?: number | null;
+}
+
+/**
+ * Item returned from https://public-api.wordpress.com/rest/v1.3/sites/[siteId]/plans response
+ * Only the properties that are actually used in the store are typed
+ * Note: These, unlike the PricedAPIPlan, are returned indexed by product_id (and do not inlcude that in the plan's payload)
+ */
+export interface PricedAPISitePlan
+	extends PricedAPISitePlanPricing,
+		PricedAPIPlanIntroductoryOffer {
+	/* product_id: number; // not included in the plan's payload */
+	product_slug: StorePlanSlug;
+	current_plan?: boolean;
+	has_redeemed_domain_credit?: boolean;
+
+	/**
+	 * This is the purchase ID present when `current_plan` is true.
+	 * For this, we map it (on `SitePlan` interface) as `purchaseId` instead
+	 * of `id` to avoid confusion e.g. with `productId`.
+	 */
+	id?: string;
+
+	/**
+	 * This value is only returned for the current plan on the site
+	 */
+	expiry?: string;
 }
+
 export interface PricedAPIPlanFree extends PricedAPIPlan {
 	product_id: 1;
 	cost: 0;
@@ -66,9 +274,10 @@ export interface PricedAPIPlanFree extends PricedAPIPlan {
 	product_slug: 'free_plan';
 	bill_period: -1;
 	raw_price: 0;
+	raw_price_integer: 0;
 }
 export interface PricedAPIPlanPaidAnnually extends PricedAPIPlan {
-	path_slug: PlanPath;
+	path_slug: string;
 	bill_period: 365;
 }
 export interface PricedAPIPlanPaidMonthly extends PricedAPIPlan {
@@ -118,3 +327,5 @@ export interface DetailsAPIResponse {
 	features_by_type: FeaturesByType[];
 	features: DetailsAPIFeature[];
 }
+
+export type PlansSelect = SelectFromMap< typeof selectors >;