@revolugo/common 7.4.3 → 7.5.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revolugo/common",
-  "version": "7.4.3",
+  "version": "7.5.0-rc.0",
   "private": false,
   "description": "Revolugo common",
   "author": "Revolugo",
@@ -23,12 +23,12 @@
     "./utils": "./src/utils/index.ts"
   },
   "dependencies": {
-    "@asteasolutions/zod-to-openapi": "8.4.3",
+    "@asteasolutions/zod-to-openapi": "8.5.0",
     "change-case": "5.4.4",
     "dayjs": "1.11.20",
     "ky": "1.14.3",
     "slugify": "1.6.8",
-    "type-fest": "5.4.4",
+    "type-fest": "5.5.0",
     "uuid": "13.0.0",
     "zod": "4.3.6"
   },

package/src/schemas/booking-policy.ts

@@ -9,6 +9,7 @@ import {
   CHECK_IN_DATE_SCHEMA,
   CHECK_OUT_DATE_SCHEMA,
   CHILDREN_SCHEMA,
+  IS_CANCELLATION_POLICIES_UPDATED,
   IS_PRICE_INCREASED,
 } from './global.ts'
 import { HOTEL_ROOM_OFFER_SCHEMA } from './hotel-room-offer.ts'
@@ -39,6 +40,7 @@ export const BOOKING_POLICY_SCHEMA = z
     id: z.string().openapi({
       description: '**Booking Policy** id',
     }),
+    is_cancellation_policies_updated: IS_CANCELLATION_POLICIES_UPDATED,
     is_price_increased: IS_PRICE_INCREASED,
   })
   .openapi('bookingPoliciesApi', {

package/src/schemas/booking.ts

@@ -0,0 +1,172 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { PayLaterStatusEnum } from '../types/booking.ts'
+import { BookingStatusEnum } from '../types/index.ts'
+
+import { CANCELLATION_POLICY_SCHEMA } from './cancellation-policies.ts'
+import { CONTACT_PERSON_SCHEMA } from './contact-person.ts'
+import { CURRENCY_SCHEMA } from './currency.ts'
+import { EVENT_SCHEMA } from './event.ts'
+import {
+  ADULT_COUNT_SCHEMA,
+  CHECK_IN_DATE_SCHEMA,
+  CHECK_OUT_DATE_SCHEMA,
+  CHILDREN_SCHEMA,
+  SOURCE_MARKET_SCHEMA,
+} from './global.ts'
+import { HOTEL_ROOM_OFFER_SCHEMA } from './hotel-room-offer.ts'
+import { HOTEL_ROOMING_LISTS_SCHEMA } from './hotel-rooming-list.ts'
+import { INVOICES_SCHEMA } from './invoice.ts'
+import { PAYMENT_METHODS_RESPONSE_SCHEMA } from './payment-methods.ts'
+import { TAXES_SCHEMA } from './taxes.ts'
+
+export const FILTER_BOOKING_STATUS_SCHEMA = z
+  .string()
+  .regex(
+    /^(?:bkg-af|bkg-cx|bkg-ip|bkg-cf)(,?(?:bkg-af|bkg-cx|bkg-ip|bkg-cf))*/u,
+  )
+  .transform(values => values.split(','))
+  .optional()
+  .nullish()
+  .openapi({
+    description:
+      'Comma separated list of booking status values to filter by. Possible values are: `bkg-af` (Failure), `bkg-cx` (Canceled), `bkg-ip` (In Progress), `bkg-cf` (Confirmed). Example: `bkg-af,bkg-cx`',
+  })
+
+export const BOOKING_METADATA_SCHEMA = z
+  .record(z.string(), z.string())
+  .openapi('bookingMetadataApi', {
+    description:
+      "You can use this parameter to attach key-value data to bookings. Metadata is useful for storing additional, structured information on a booking. As an example, you could store your user's full name and corresponding unique identifier from your system on a booking. Metadata is not used internally by the Booking Engine and won't be seen by your users unless you choose to show it to them.",
+  })
+  .optional()
+  .nullish()
+
+export const BOOKING_SCHEMA = z
+  .object({
+    additionalCheckInInstruction: z
+      .string()
+      .openapi({
+        description: 'Additional instructions on how to check-in.',
+      })
+      .nullish(),
+    additionalPolicies: z
+      .string()
+      .openapi({
+        description:
+          'Additional house policy, house manual, or condominium rules.',
+      })
+      .nullish(),
+    adultCount: ADULT_COUNT_SCHEMA,
+    canceledAt: z
+      .string()
+      .openapi({
+        description: 'Date of booking cancellation request, when applicable.',
+      })
+      .optional()
+      .nullish(),
+    cancellationPolicies: z.array(CANCELLATION_POLICY_SCHEMA).openapi({
+      description:
+        'The list of cancellation policy date range with their corresponding penalty percentage.',
+    }),
+    cancellationPolicyRemarks: z
+      .string()
+      .openapi({ description: 'Remarks about the cancellation policy.' })
+      .optional()
+      .nullish(),
+    checkInDate: CHECK_IN_DATE_SCHEMA,
+    checkOutDate: CHECK_OUT_DATE_SCHEMA,
+    children: CHILDREN_SCHEMA.optional().nullish(),
+    confirmedAt: z
+      .string()
+      .openapi({
+        description: 'Date of booking confirmation request, when applicable.',
+      })
+      .optional()
+      .nullish(),
+    contactPerson: CONTACT_PERSON_SCHEMA,
+    createdAt: z
+      .string()
+      .openapi({ description: 'Creation date of the **Booking**.' }),
+    currency: CURRENCY_SCHEMA,
+    customerReference: z
+      .string()
+      .openapi({
+        description:
+          'Customer Reference of the requested Booking (sometimes to present by the customer at hotel check-in).',
+      })
+      .optional()
+      .nullish(),
+    event: EVENT_SCHEMA,
+    failedAt: z
+      .string()
+      .openapi({ description: 'Date of booking failure, when applicable.' })
+      .optional()
+      .nullish(),
+    hotelConfirmationId: z
+      .string()
+      .openapi({
+        description:
+          'Code your guest might need to show to the hotel during check-in. This number will only but available a few days prior to check-in and it’s subject to availability.',
+      })
+      .nullish(),
+    hotelId: z
+      .string()
+      .openapi({ description: 'Hotel Id of the requested Booking.' }),
+    hotelRoomingLists: HOTEL_ROOMING_LISTS_SCHEMA.optional(),
+    hotelRoomOffer: HOTEL_ROOM_OFFER_SCHEMA,
+    id: z.string().openapi({ description: 'Booking Id' }).nullish(),
+    invoices: INVOICES_SCHEMA.optional().nullish(),
+    lastStatusUpdatedAt: z
+      .string()
+      .openapi({ description: 'Date of the last booking status update.' }),
+    metadata: BOOKING_METADATA_SCHEMA,
+    payLater: z
+      .enum(PayLaterStatusEnum)
+      .optional()
+      .nullish()
+      .openapi({
+        description: 'Booking Pay Later Status',
+        enum: Object.values(PayLaterStatusEnum),
+      }),
+    paymentMethods: PAYMENT_METHODS_RESPONSE_SCHEMA,
+    penaltyPercentage: z
+      .number()
+      .optional()
+      .nullish()
+      .openapi({
+        description: `Penalty percentage of the requested Booking.\n\n When **booking.status = ${BookingStatusEnum.Cx}** this is the percentage of the **booking.tax_included_price** that have been charged on the canceled booking. Otherwise, this field won't be returned.`,
+      }),
+    reference: z.string().openapi({
+      description: 'Booking Reference of the requested Booking.',
+    }),
+    sourceMarket: SOURCE_MARKET_SCHEMA,
+    status: z.enum(BookingStatusEnum).openapi({
+      description:
+        'Booking status. Please, refer to [Booking Status](/v1/documentation#tag/Booking-Status) for details.',
+    }),
+    taxAmount: z.number().openapi({
+      description: 'Total tax amount expressed in the booking currency.',
+    }),
+    taxes: TAXES_SCHEMA.optional().nullish(),
+    taxIncludedPrice: z.number().openapi({
+      description:
+        'Price of the booking including taxes expressed in the booking currency.',
+    }),
+    terms: z.string().openapi({
+      description:
+        'Link to Revolugo terms and conditions under which the booking is made.',
+    }),
+    token: z.string().optional().nullish().openapi({
+      description:
+        'This is the token to pass as URL params to [Cancel Booking endpoint](/v1/documentation#operation/deleteV1BookingsId) in order to perform a cancel request on the booking. If you want to cancel a booking, you should use this token instead of the booking id.\n\n⚠️ For security reasons, this token is unique and once generated, it is valid during a period of 10 minutes.\n\nIn order to get a fresh valid token you need to call **[Retrieve Booking endpoint](/v1/documentation#operation/getV1BookingsId)**.',
+    }),
+  })
+  .strict()
+  .openapi('bookingApi', { description: 'Booking record' })
+
+export const BOOKINGS_SCHEMA = z
+  .array(BOOKING_SCHEMA)
+  .openapi('bookingsApi', { description: 'List of detailed Bookings' })
+/* eslint-enable camelcase */

package/src/schemas/contact-person.ts

@@ -0,0 +1,97 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { CountryIso2Code } from '../countries/constants.ts'
+import { ContactPersonSalutationEnum } from '../types/index.ts'
+
+import { COUNTRY_ISO2_CODE_SCHEMA, LANG_SCHEMA } from './global.ts'
+
+export const CONTACT_PERSON_ORGANIZATION_SCHEMA = z
+  .object({
+    address: z.string().openapi({ description: 'Address of the organization' }),
+    city: z.string().openapi({ description: 'City of the organization' }),
+    country: COUNTRY_ISO2_CODE_SCHEMA.openapi({
+      description: 'Country of the organization',
+    }),
+    name: z.string().openapi({ description: 'Name of the organization' }),
+    state: z
+      .string()
+      .openapi({ description: 'State of the organization' })
+      .optional()
+      .nullish(),
+    vatNumber: z
+      .string()
+      .openapi({ description: 'VAT Number of the organization' })
+      .optional()
+      .nullish(),
+    zipCode: z
+      .string()
+      .openapi({ description: 'ZIP Code of the organization' }),
+  })
+  .openapi('contactPersonOrganizationApi')
+
+export const CONTACT_PERSON_SCHEMA = z
+  .object({
+    address: z
+      .string()
+      .openapi({ description: "Contact person's postal code of residence" })
+      .optional()
+      .nullish(),
+    city: z
+      .string()
+      .openapi({ description: "Contact person's city of residence" })
+      .optional()
+      .nullish(),
+    country: COUNTRY_ISO2_CODE_SCHEMA.openapi({
+      description: "Contact person's country of residence",
+      enum: Object.values(CountryIso2Code),
+    })
+      .optional()
+      .nullish(),
+    email: z.email().openapi({ description: "Contact person's email address" }),
+    firstName: z
+      .string()
+      .openapi({ description: "Contact person's first name" }),
+    lang: LANG_SCHEMA.openapi({
+      description:
+        'Set the prefered language to use when contacting the contact person for booking related communication(s).',
+    }).optional(),
+    lastName: z.string().openapi({ description: "Contact person's last name" }),
+    nationality: COUNTRY_ISO2_CODE_SCHEMA.openapi({
+      description: "Contact person's nationality",
+    }),
+    organization: CONTACT_PERSON_ORGANIZATION_SCHEMA.openapi({
+      description:
+        'Organization details of the contact person for invoicing purposes',
+    })
+      .optional()
+      .nullish(),
+    phone: z.string().openapi({ description: "Contact person's phone number" }),
+    remarks: z
+      .string()
+      .openapi({ description: "Contact person's remarks" })
+      .optional(),
+    salutation: z
+      .enum(ContactPersonSalutationEnum)
+      .optional()
+      .nullish()
+      .openapi({
+        description: 'Title of the contact person',
+        enum: Object.values(ContactPersonSalutationEnum),
+      }),
+    state: z
+      .string()
+      .openapi({ description: "Contact person's state of residence" })
+      .optional()
+      .nullish(),
+    zipCode: z
+      .string()
+      .openapi({ description: "Contact person's postal code of residence" })
+      .optional()
+      .nullish(),
+  })
+  .openapi('contactPersonApi', {
+    description:
+      'Contact details that will be used to communicate with the contact person for booking related communication (confirmation, modification, etc)',
+  })
+/* eslint-enable camelcase */

package/src/schemas/event.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod'
+
+export const EVENT_SCHEMA = z
+  .object({
+    name: z
+      .string()
+      .nullish()
+      .openapi({ description: 'Unique name of the event' }),
+    slug: z
+      .string()
+      .nullish()
+      .openapi({ description: 'Unique slug of the event' }),
+  })
+  .nullish()
+  .openapi('eventApi')

package/src/schemas/global.ts

@@ -70,6 +70,11 @@ export const IMAGES_SCHEMA = z
       '🛑 DEPRECATED - Hotel images details.\n\nIn order to retrieve a specific image you need to construct the complete URL from the images parameters: **[images.prefix][highres|lowres|thumb]/[index]/[images.suffix]**. If **images.count = n**, then index is in [0...n-1] range.\n\ne.g.: https://s3.eu-west-3.amazonaws.com/revolugo/hotels/yhKY/images/highres/0.jpg',
   })
 
+export const IS_CANCELLATION_POLICIES_UPDATED = z.boolean().openapi({
+  description:
+    'Indicates whether the cancellation policies of the **Hotel Room Offer** have changed (become stricter) compared to those returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers).\n\nIf **is_cancellation_policies_updated** is **true**, the cancellation policies are now less favourable than when the offer was first retrieved. ⚠️ It is strongly advised to clearly inform your customer of any cancellation policy change that may occur.',
+})
+
 export const IS_PRICE_INCREASED = z.boolean().openapi({
   description:
     'Indicates whether the price of the **Hotel Room Offer** (without breakfast included) has increased compared to the price returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers).\n\nIn some case, the returned price may increase for various reasons including: Currency rate change between the POST **Booking Policies** call and the GET **Hotel Room Offers** call, **Hotel Room Offer** price has increased since the GET **Hotel Room Offers** call.\n\nIf **is_price_increased** is **true**, it means that the actual/updated price of the **Hotel Room Offer** is greater than the price previously returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers). If **is_price_increased** is **false**, the price of the **Hotel Room Offer** is equal to the price returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers).\n\n⚠️ It is strongly advised to clearly inform your customer of any price increase that may occur.',

package/src/schemas/hotel-rooming-list.ts

@@ -0,0 +1,34 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { HOTEL_ROOM_SCHEMA } from './hotel-room.ts'
+
+export const HOTEL_ROOMING_LIST_GUEST_SCHEMA = z
+  .object({
+    fullname: z.string(),
+    id: z.string(),
+  })
+  .openapi({ description: 'Guest of a hotel rooming list' })
+  .openapi('hotelRoomingListGuestApi')
+
+export const HOTEL_ROOMING_LIST_GUESTS_SCHEMA = z
+  .array(HOTEL_ROOMING_LIST_GUEST_SCHEMA)
+  .openapi({ description: 'Guests of a hotel rooming list' })
+  .openapi('hotelRoomingListGuestsApi')
+
+export const HOTEL_ROOMING_LIST_SCHEMA = z
+  .object({
+    hotelRoom: HOTEL_ROOM_SCHEMA.optional().nullish(),
+    hotelRoomId: z.string(),
+    hotelRoomingListGuests: HOTEL_ROOMING_LIST_GUESTS_SCHEMA,
+    id: z.string(),
+    limitDate: z.coerce.date().optional(),
+  })
+  .openapi({ description: 'Hotel rooming list of a hotel booking' })
+  .openapi('hotelRoomingListApi')
+
+export const HOTEL_ROOMING_LISTS_SCHEMA = z
+  .array(HOTEL_ROOMING_LIST_SCHEMA)
+  .openapi({ description: 'Hotel rooming lists of a hotel booking' })
+  .openapi('hotelRoomingListsApi')
+/* eslint-enable camelcase */

package/src/schemas/index.ts

@@ -1,6 +1,8 @@
 export * from './booking-policy.ts'
+export * from './booking.ts'
 export * from './breakfast.ts'
 export * from './cancellation-policies.ts'
+export * from './contact-person.ts'
 export * from './currency.ts'
 export * from './global.ts'
 export * from './hotel-offer.ts'
@@ -8,5 +10,6 @@ export * from './hotel-room-offer.ts'
 export * from './hotel-room.ts'
 export * from './hotel.ts'
 export * from './list-polling-meta.ts'
+export * from './payment-methods.ts'
 export * from './tag.ts'
 export * from './taxes.ts'

package/src/schemas/invoice.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+
+import { InvoiceApiTypeEnum } from '../types/index.ts'
+
+export const INVOICE_SCHEMA = z
+  .object({
+    type: z.enum(InvoiceApiTypeEnum),
+    url: z.string(),
+  })
+  .openapi('invoiceApi')
+
+export const INVOICES_SCHEMA = z
+  .array(INVOICE_SCHEMA)
+  .openapi({
+    description:
+      'The list of invoices and credit notes (when applicable) direct urls associated to the Booking.',
+  })
+  .openapi('invoicesApi')

package/src/schemas/payment-methods.ts

@@ -0,0 +1,135 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import {
+  BookingStatusEnum,
+  PayLaterStatusEnum,
+  PaymentMethodNameEnum,
+} from '../types/index.ts'
+import { isEqual } from '../utils/is-equal.ts'
+
+const allowedPaymentMethodCombinations = [
+  [PaymentMethodNameEnum.CreditCard],
+  [PaymentMethodNameEnum.DepositAccount],
+  [PaymentMethodNameEnum.CreditCard, PaymentMethodNameEnum.Coupon],
+  [PaymentMethodNameEnum.Coupon, PaymentMethodNameEnum.CreditCard],
+]
+
+export const PAYMENT_METHOD_REQUEST_SCHEMA = z
+  .object({
+    name: z.enum([
+      PaymentMethodNameEnum.Coupon,
+      PaymentMethodNameEnum.CreditCard,
+      PaymentMethodNameEnum.DepositAccount,
+    ]),
+    payload: z
+      .object({
+        // TODO: Add coupon validation with name
+        coupon_id: z.string().nullish(),
+      })
+      .optional()
+      .openapi('paymentMethodRequestPayloadApi'),
+  })
+  .openapi('paymentMethodRequestApi')
+
+export const PAYMENT_METHODS_REQUEST_SCHEMA = z
+  .array(PAYMENT_METHOD_REQUEST_SCHEMA)
+  .transform((value, ctx) => {
+    if (
+      !allowedPaymentMethodCombinations.some(allowedPaymentMethodCombination =>
+        isEqual(
+          allowedPaymentMethodCombination,
+          value.map(
+            (paymentMethod: { name: PaymentMethodNameEnum }) =>
+              paymentMethod.name,
+          ),
+        ),
+      )
+    ) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Invalid payment method combination',
+        path: [],
+      })
+      return z.never()
+    }
+
+    return value
+  })
+  .openapi('paymentMethodsRequestApi', {
+    description:
+      'List of preferred payment methods to be used along with their respective payload (when applicable) in order to fulfill the booking.',
+  })
+
+export const PAYMENT_METHOD_RESPONSE_SCHEMA = z
+  .discriminatedUnion('name', [
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.CreditCard),
+      payload: z.object({
+        amount: z.number(),
+        couponId: z.string().nullish(),
+        token: z.string(),
+      }),
+    }),
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.Coupon),
+      payload: z.object({
+        amount: z.number(),
+        couponId: z.string(),
+        token: z.string().nullish(),
+      }),
+    }),
+    z.object({
+      name: z.enum([PaymentMethodNameEnum.DepositAccount]),
+      payload: z.object({
+        amount: z.number(),
+        couponId: z.string().nullish(),
+        token: z.string().nullish(),
+      }),
+    }),
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.PayLater),
+      payload: z.object({
+        amount: z.number(),
+        couponId: z.string().nullish(),
+        status: z.enum(PayLaterStatusEnum),
+        token: z.string().nullish(),
+      }),
+    }),
+  ])
+  .openapi('paymentMethodApi')
+
+export const PAYMENT_METHODS_RESPONSE_SCHEMA = z
+  .array(PAYMENT_METHOD_RESPONSE_SCHEMA)
+  .openapi('paymentMethodsApi', {
+    description: `List of preferred payment methods to be used along with their respective payload (when applicable) in order to fulfill the booking.\n\n⚠️ This field is only returned when **booking.status = ${BookingStatusEnum.Created}**`,
+  })
+  .optional()
+
+export const ALLOWED_PAYMENT_METHOD_RESPONSE_SCHEMA = z
+  .discriminatedUnion('name', [
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.CreditCard),
+    }),
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.Coupon),
+    }),
+    z.object({
+      name: z.enum([PaymentMethodNameEnum.DepositAccount]),
+    }),
+    z.object({
+      name: z.literal(PaymentMethodNameEnum.PayLater),
+      payload: z.object({
+        status: z.enum(PayLaterStatusEnum),
+      }),
+    }),
+  ])
+  .openapi('allowedPaymentMethodApi')
+
+export const ALLOWED_PAYMENT_METHODS_RESPONSE_SCHEMA = z
+  .array(ALLOWED_PAYMENT_METHOD_RESPONSE_SCHEMA)
+  .openapi('allowedPaymentMethodsApi', {
+    description:
+      'List of allowed payment methods to be used in order to fulfill the booking.',
+  })
+/* eslint-enable camelcase */

package/src/types/elements/booking-policy.ts

@@ -78,6 +78,7 @@ export interface BookingPolicies {
    * @type {boolean}
    * @memberof BookingPolicies
    */
+  isCancellationPoliciesUpdated: boolean
   isPriceIncreased: boolean
 }
 

package/src/types/elements/hotel-offer-request.ts

@@ -166,5 +166,4 @@ export interface HotelOfferRequestCreate {
   latitude?: HotelOfferRequest['latitude']
   longitude?: HotelOfferRequest['longitude']
   roomCount: HotelOfferRequest['roomCount']
-  sourceMarket: HotelOfferRequest['sourceMarket']
 }

package/src/types/elements/hotel-room-offer-request.ts

@@ -135,7 +135,6 @@ export interface HotelRoomOfferRequestCreate {
   eventMetadata?: HotelRoomOfferRequest['eventMetadata']
   hotelId: HotelRoomOfferRequest['hotelId']
   roomCount: HotelRoomOfferRequest['roomCount']
-  sourceMarket: HotelRoomOfferRequest['sourceMarket']
 }
 export interface HotelRoomOfferRequestsCreatePayload {
   hotelRoomOfferRequestCreateApi?: HotelRoomOfferRequestCreate

package/src/utils/dayjs.ts

@@ -13,12 +13,12 @@ import timezone from 'dayjs/plugin/timezone.js'
 import utc from 'dayjs/plugin/utc.js'
 /* eslint-enable no-restricted-imports, no-restricted-syntax */
 
-/* eslint-disable no-restricted-syntax, import/no-unassigned-import */
+/* eslint-disable no-restricted-syntax, import-x/no-unassigned-import */
 import 'dayjs/locale/fr.js'
 import 'dayjs/locale/en.js'
-/* eslint-enable no-restricted-syntax, import/no-unassigned-import */
+/* eslint-enable no-restricted-syntax, import-x/no-unassigned-import */
 
-/* eslint-disable import/no-named-as-default-member */
+/* eslint-disable import-x/no-named-as-default-member */
 dayjs.extend(advancedFormat)
 dayjs.extend(customParseFormat)
 dayjs.extend(isBetween)
@@ -30,7 +30,7 @@ dayjs.extend(minMax)
 dayjs.extend(relativeTime)
 dayjs.extend(timezone)
 dayjs.extend(utc)
-/* eslint-enable import/no-named-as-default-member */
+/* eslint-enable import-x/no-named-as-default-member */
 
 export { dayjs }
 

package/src/utils/get-user-ip-address.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'vitest'
+
+import { getUserIpAddress } from './get-user-ip-address.ts'
+
+describe('getUserIpAddress', () => {
+  test('UT-1a: extracts first IP from x-forwarded-for (comma-separated)', () => {
+    const headers = new Headers({
+      'x-forwarded-for': '203.0.113.1, 70.41.3.18, 150.172.238.178',
+    })
+    expect(getUserIpAddress(headers)).toBe('203.0.113.1')
+  })
+
+  test('UT-1a: extracts single IP from x-forwarded-for', () => {
+    const headers = new Headers({ 'x-forwarded-for': '203.0.113.1' })
+    expect(getUserIpAddress(headers)).toBe('203.0.113.1')
+  })
+
+  test('UT-1b: extracts IP from cf-connecting-ip', () => {
+    const headers = new Headers({ 'cf-connecting-ip': '198.51.100.1' })
+    expect(getUserIpAddress(headers)).toBe('198.51.100.1')
+  })
+
+  test('UT-1c: extracts IP from x-real-ip', () => {
+    const headers = new Headers({ 'x-real-ip': '198.51.100.2' })
+    expect(getUserIpAddress(headers)).toBe('198.51.100.2')
+  })
+
+  test('UT-1c: extracts IP from true-client-ip', () => {
+    const headers = new Headers({ 'true-client-ip': '198.51.100.3' })
+    expect(getUserIpAddress(headers)).toBe('198.51.100.3')
+  })
+
+  test('UT-1c: extracts IP from x-client-ip', () => {
+    const headers = new Headers({ 'x-client-ip': '198.51.100.4' })
+    expect(getUserIpAddress(headers)).toBe('198.51.100.4')
+  })
+
+  test('UT-1a: x-forwarded-for takes priority over other headers', () => {
+    const headers = new Headers({
+      'cf-connecting-ip': '198.51.100.1',
+      'x-forwarded-for': '203.0.113.1',
+    })
+    expect(getUserIpAddress(headers)).toBe('203.0.113.1')
+  })
+
+  test('UT-1d: returns null when no IP headers present', () => {
+    const headers = new Headers({ 'content-type': 'application/json' })
+    expect(getUserIpAddress(headers)).toBeNull()
+  })
+
+  test('UT-1e: extracts IP from Forwarded header (RFC 7239)', () => {
+    const headers = new Headers({
+      forwarded: 'for=192.0.2.60;proto=http;by=203.0.113.43',
+    })
+    expect(getUserIpAddress(headers)).toBe('192.0.2.60')
+  })
+
+  test('UT-1e: extracts quoted IP from Forwarded header', () => {
+    const headers = new Headers({ forwarded: 'for="192.0.2.60"' })
+    expect(getUserIpAddress(headers)).toBe('192.0.2.60')
+  })
+})

package/src/utils/get-user-ip-address.ts

@@ -0,0 +1,28 @@
+const IP_HEADERS = [
+  'x-forwarded-for',
+  'cf-connecting-ip',
+  'x-real-ip',
+  'true-client-ip',
+  'x-client-ip',
+] as const
+
+export function getUserIpAddress(headers: Headers): string | null {
+  for (const header of IP_HEADERS) {
+    const value = headers.get(header)
+    if (value) {
+      return header === 'x-forwarded-for'
+        ? (value.split(',')[0]?.trim() ?? null)
+        : value
+    }
+  }
+
+  const forwarded = headers.get('forwarded')
+  if (forwarded) {
+    const match = /for=["']?([^;"',\s]+)/u.exec(forwarded)
+    if (match?.[1]) {
+      return match[1]
+    }
+  }
+
+  return null
+}

package/src/utils/index.ts

@@ -26,6 +26,7 @@ export * from './get-random-element-from-array.ts'
 export * from './get-random-hex-color.ts'
 export * from './get-random-int.ts'
 export * from './get-sanitized-room-count.ts'
+export * from './get-user-ip-address.ts'
 export * from './group-by.ts'
 export * from './images.ts'
 export * from './is-empty.ts'
@@ -55,6 +56,7 @@ export * from './sum.ts'
 export * from './to-boolean.ts'
 export * from './to-lang.ts'
 export * from './to-locale.ts'
+export * from './to-number.ts'
 export * from './transform-schema-keys.ts'
 export * from './uniq-by.ts'
 export * from './uniq-with.ts'

package/src/utils/to-number.ts

@@ -0,0 +1,9 @@
+export const toNumber = (
+  value: number | string | undefined,
+): number | undefined => {
+  if (value === undefined || value === '') {
+    return undefined
+  }
+  const n = Number(value)
+  return Number.isNaN(n) ? undefined : n
+}