feat: add parsePrepTime item helper

src/helpers/item.ts

@@ -1,7 +1,7 @@
 import {
 	OptionSelection,
 	Item as ItemResource,
-	ItemOption, 
+	ItemOption,
 	ModifierList,
 	Variation,
 	ValidateItemError,
@@ -10,9 +10,10 @@ import {
 	QuantityErrorTypeEnum,
 	GetItemPriceRequest,
 	ValidateItemRequest,
-	GetInStockVariationsForSelectedOptionsOrVariationRequest
+	GetInStockVariationsForSelectedOptionsOrVariationRequest,
+	ItemPrepTime
 } from '../types/helpers/item';
-import { 
+import {
 	AddLineItem,
 	AddItemModifier,
 	ChoiceModifier,
@@ -37,7 +38,7 @@ const getVariationSelections = (variation: Variation) => {
 };
 
 const getEventEndDate = (item: ItemResource): Date => {
-    
+
 	const endDate = item.item_type_details.end_date;
 	const endTime = item.item_type_details.end_time!;
 
@@ -87,7 +88,7 @@ export class Item {
 	isVariationSoldOut(variation: Variation): boolean {
 		return variation.sold_out || (variation.inventory_tracking_enabled && variation.inventory === 0);
 	}
-    
+
 	/**
      * Returns the QuantityErrorType if there's an item quantity error with the item varation, otherwise null.
      */
@@ -376,7 +377,7 @@ export class Item {
 			}
 			return itemPrice;
 		}
-		
+
 		return null;
 	}
 
@@ -401,4 +402,31 @@ export class Item {
 		const cutoffTime = item.fulfillment_availability.PICKUP[0].availability_cutoff_at;
 		return new Date(cutoffTime) <= new Date();
 	}
-}
+
+	/**
+	 * Returns the item's prep time duration parsed into value, unit, is_time.
+	 * is_time means prep duration includes a time component (hour/minute/second). It's used to differentiate '4M' between '4 months' and '4 minutes'
+	 * Note that this function relies on the fact that prepTimeDuration currently only supports
+	 * a single time unit! I.e. P2DT6H20M is not currently supported and will not work.
+	 */
+	parsePrepTime(prepTimeDuration: string): ItemPrepTime | null {
+		const parsedPrepTime = /(PT(?<timeValue>\d+)(?<timeUnit>\w))|(P(?<value>\d+)(?<unit>\w))/g.exec(prepTimeDuration)?.groups;
+		if (!(parsedPrepTime?.timeValue && parsedPrepTime?.timeUnit) && !(parsedPrepTime?.value && parsedPrepTime?.unit)) {
+			return null;
+		}
+
+		const isTime = Boolean(parsedPrepTime?.timeValue);
+		const value = isTime
+			? Number(parsedPrepTime?.timeValue)
+			: Number(parsedPrepTime?.value);
+		const unit = isTime
+			? parsedPrepTime?.timeUnit
+			: parsedPrepTime?.unit;
+
+		return {
+			value: value,
+			unit: unit,
+			is_time: isTime,
+		};
+	}
+}

src/types/helpers/item/index.ts

@@ -112,6 +112,12 @@ export interface ModifierList {
     type: ModifierTypeEnum;
 }
 
+export interface ItemPrepTime {
+    value: number;
+    unit: string;
+    is_time: boolean;
+}
+
 export interface Item {
     id: string;
     variations: Variation[];
@@ -134,4 +140,4 @@ export interface Item {
             availability_cutoff_at: string;
         }[];
     };
-}
+}

test/helpers.item.test.ts

@@ -1492,7 +1492,7 @@ describe('Get item price', () => {
 			regular: {
 				amount: multipleVariationItem.variations[3].price.regular.amount,
 				formatted: '',
-				currency: multipleVariationItem.variations[3].price.regular.currency	
+				currency: multipleVariationItem.variations[3].price.regular.currency
 			},
 			sale: {
 				amount: multipleVariationItem.variations[3].price.sale.amount,
@@ -1758,7 +1758,7 @@ describe('Is event item in the past', () => {
 	it('should test event in the future for pacific time', () => {
 		const date = '2023-07-18T22:00:00-07:00';
 		vi.setSystemTime(new Date(date));
-        
+
 		const item = createTestItem({
 			squareOnlineType: 'EVENT',
 			itemTypeDetailsEndDate: '2023-07-19',
@@ -1788,7 +1788,7 @@ describe('Is event item in the past', () => {
 	it('should test event in the future for eastern time', () => {
 		const date = '2023-07-18T16:00:00-04:00';
 		vi.setSystemTime(new Date(date));
-        
+
 		const item = createTestItem({
 			squareOnlineType: 'EVENT',
 			itemTypeDetailsEndDate: '2023-07-18',
@@ -1814,11 +1814,11 @@ describe('Is event item in the past', () => {
 		const result3 = sdk.helpers.item.isEventItemInThePast(item3);
 		expect(result3).toStrictEqual(false);
 	});
-    
+
 	it('should test event in the future for eastern time at noon', () => {
 		const date = '2023-07-18T12:00:00-04:00';
 		vi.setSystemTime(new Date(date));
-        
+
 		const item = createTestItem({
 			squareOnlineType: 'EVENT',
 			itemTypeDetailsEndDate: '2023-07-18',
@@ -1893,4 +1893,31 @@ describe('Is preorder item cutoff in the past', () => {
 		const result3 = sdk.helpers.item.isPreorderItemCutoffInThePast(item3);
 		expect(result3).toStrictEqual(false);
 	});
-});
+});
+
+describe('Is item prep time correctly parsed', () => {
+	it.each([
+		{ value: 'PT20M', expected: { value: 20, unit: 'M', is_time: true } },
+		{ value: 'PT60M', expected: { value: 60, unit: 'M', is_time: true } },
+		{ value: 'PT90M', expected: { value: 90, unit: 'M', is_time: true } },
+		{ value: 'PT120M', expected: { value: 120, unit: 'M', is_time: true } },
+		{ value: 'PT1H', expected: { value: 1, unit: 'H', is_time: true } },
+		{ value: 'PT2H', expected: { value: 2, unit: 'H', is_time: true } },
+		{ value: 'P1D', expected: { value: 1, unit: 'D', is_time: false } },
+		{ value: 'P2D', expected: { value: 2, unit: 'D', is_time: false } },
+		{ value: 'P7D', expected: { value: 7, unit: 'D', is_time: false } },
+		{ value: 'P1W', expected: { value: 1, unit: 'W', is_time: false } },
+		{ value: 'P3W', expected: { value: 3, unit: 'W', is_time: false } },
+		{ value: 'P8W', expected: { value: 8, unit: 'W', is_time: false } },
+		{ value: 'P1M', expected: { value: 1, unit: 'M', is_time: false } },
+		{ value: 'P3M', expected: { value: 3, unit: 'M', is_time: false } },
+		{ value: 'P1Y', expected: { value: 1, unit: 'Y', is_time: false } },
+		{ value: 'P3Y', expected: { value: 3, unit: 'Y', is_time: false } },
+		{ value: 'P3', expected: null },
+		{ value: 'PD', expected: null },
+		{ value: 'PT3', expected: null },
+		{ value: 'PTD', expected: null },
+	])('should return $expected for value $value', ({ value, expected }) => {
+		expect(sdk.helpers.item.parsePrepTime(value)).toStrictEqual(expected);
+	});
+});

typedocs/classes/helpers_item.Item.md

@@ -26,6 +26,7 @@
 - [getItemPrice](helpers_item.Item.md#getitemprice)
 - [isEventItemInThePast](helpers_item.Item.md#iseventiteminthepast)
 - [isPreorderItemCutoffInThePast](helpers_item.Item.md#ispreorderitemcutoffinthepast)
+- [parsePrepTime](helpers_item.Item.md#parsepreptime)
 
 ## Constructors
 
@@ -297,3 +298,24 @@ Returns whether an item is a preorder and the cutoff time has passed.
 #### Returns
 
 `boolean`
+
+___
+
+### parsePrepTime
+
+▸ **parsePrepTime**(`prepTimeDuration`): ``null`` \| [`ItemPrepTime`](../interfaces/types_helpers_item.ItemPrepTime.md)
+
+Returns the item's prep time duration parsed into value, unit, is_time.
+is_time means prep duration includes a time component (hour/minute/second). It's used to differentiate '4M' between '4 months' and '4 minutes'
+Note that this function relies on the fact that prepTimeDuration currently only supports
+a single time unit! I.e. P2DT6H20M is not currently supported and will not work.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `prepTimeDuration` | `string` |
+
+#### Returns
+
+``null`` \| [`ItemPrepTime`](../interfaces/types_helpers_item.ItemPrepTime.md)

typedocs/interfaces/types_helpers_item.ItemPrepTime.md

@@ -0,0 +1,31 @@
+[@square/site-theme-sdk](../GettingStarted.md) / [Modules](../modules.md) / [types/helpers/item](../modules/types_helpers_item.md) / ItemPrepTime
+
+# Interface: ItemPrepTime
+
+[types/helpers/item](../modules/types_helpers_item.md).ItemPrepTime
+
+## Table of contents
+
+### Properties
+
+- [value](types_helpers_item.ItemPrepTime.md#value)
+- [unit](types_helpers_item.ItemPrepTime.md#unit)
+- [is\_time](types_helpers_item.ItemPrepTime.md#is_time)
+
+## Properties
+
+### value
+
+• **value**: `number`
+
+___
+
+### unit
+
+• **unit**: `string`
+
+___
+
+### is\_time
+
+• **is\_time**: `boolean`

typedocs/modules/types_helpers_item.md

@@ -16,6 +16,7 @@
 - [ItemOption](../interfaces/types_helpers_item.ItemOption.md)
 - [Modifier](../interfaces/types_helpers_item.Modifier.md)
 - [ModifierList](../interfaces/types_helpers_item.ModifierList.md)
+- [ItemPrepTime](../interfaces/types_helpers_item.ItemPrepTime.md)
 - [Item](../interfaces/types_helpers_item.Item.md)
 
 ### Type Aliases