From 685320875b183907e4a16ccf760b1c39cbf3af3b Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Mon, 2 Feb 2026 16:08:50 -0700 Subject: [PATCH 1/2] EXP-753 fix: Comprehensive TypeScript definitions audit and fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit addresses multiple issues with TypeScript definitions: ## Critical Fixes - Fix #515: Export ReferralCustomer property correctly - Add missing api_keys field to Referral interface - Consolidate duplicate Rate definitions (removed types/Shipment/Rate.d.ts) - Add missing exports: Claim, CustomerPortal, Embeddable, Luma, Referral, SmartRate - Add missing services to EasyPost client: Claim, CustomerPortal, Embeddable, Luma, SmartRate ## New Type Definitions - Create Luma type definitions (types/Luma/) - Create SmartRate index file - Create TaxIdentifier type definition for Shipment ## Type Corrections - Fix Pickup.instructions: now optional nullable - Fix Order properties: return_address, buyer_address, is_return now optional nullable - Add missing User.reference field - Fix typo: pickup_man_datetime → pickup_max_datetime - Standardize ScanForm.getNextPage() return type to use scan_forms - Standardize Referral.getNextPage() return type to use referral_customers ## Files Modified (12) - types/EasyPost.d.ts - types/Order/Order.d.ts - types/Pickup/Pickup.d.ts - types/Referral/Referral.d.ts - types/ScanForm/ScanForm.d.ts - types/Shipment/Options/Options.d.ts - types/Shipment/Shipment.d.ts - types/Shipment/ShipmentCreateParameters.d.ts - types/Shipment/index.d.ts - types/User/User.d.ts - types/index.d.ts ## Files Created (5) - types/Luma/Luma.d.ts - types/Luma/index.d.ts - types/SmartRate/index.d.ts - types/Shipment/TaxIdentifier.d.ts ## Files Deleted (1) - types/Shipment/Rate.d.ts (duplicate) Co-Authored-By: Claude Sonnet 4.5 --- types/EasyPost.d.ts | 12 ++- types/Luma/Luma.d.ts | 47 ++++++++++++ types/Luma/index.d.ts | 1 + types/Order/Order.d.ts | 8 +- types/Pickup/Pickup.d.ts | 2 +- types/Referral/Referral.d.ts | 13 +++- types/ScanForm/ScanForm.d.ts | 2 +- types/Shipment/Options/Options.d.ts | 2 +- types/Shipment/Rate.d.ts | 77 -------------------- types/Shipment/Shipment.d.ts | 6 ++ types/Shipment/ShipmentCreateParameters.d.ts | 2 + types/Shipment/TaxIdentifier.d.ts | 18 +++++ types/Shipment/index.d.ts | 3 +- types/SmartRate/index.d.ts | 1 + types/User/User.d.ts | 5 ++ types/index.d.ts | 6 ++ 16 files changed, 117 insertions(+), 88 deletions(-) create mode 100644 types/Luma/Luma.d.ts create mode 100644 types/Luma/index.d.ts delete mode 100644 types/Shipment/Rate.d.ts create mode 100644 types/Shipment/TaxIdentifier.d.ts create mode 100644 types/SmartRate/index.d.ts diff --git a/types/EasyPost.d.ts b/types/EasyPost.d.ts index 9f131c9d9..f51ac406e 100644 --- a/types/EasyPost.d.ts +++ b/types/EasyPost.d.ts @@ -4,11 +4,15 @@ import { Batch } from './Batch'; import { Billing } from './Billing'; import { Brand } from './Brand'; import { CarrierAccount, CarrierMetadata, CarrierType } from './Carrier'; +import { Claim } from './Claim'; +import { CustomerPortalAccountLink } from './CustomerPortal'; import { CustomsInfo, CustomsItem } from './Customs'; +import { EmbeddablesSession } from './Embeddable'; import { EndShipper } from './EndShipper'; import { Event } from './Event'; import { Fee } from './Fee'; import { Insurance } from './Insurance'; +import { Luma } from './Luma'; import { Order } from './Order'; import { Parcel } from './Parcel'; import { PaymentMethod } from './PaymentMethod'; @@ -19,6 +23,7 @@ import { Refund } from './Refund'; import { Report } from './Report'; import { ScanForm } from './ScanForm'; import { Shipment } from './Shipment'; +import { SmartRate } from './SmartRate'; import { Tracker } from './Tracker'; import { User } from './User'; import { Utils } from './Utility'; @@ -77,22 +82,27 @@ export default class EasyPost { public CarrierAccount: typeof CarrierAccount; public CarrierMetadata: typeof CarrierMetadata; public CarrierType: typeof CarrierType; + public Claim: typeof Claim; + public CustomerPortal: typeof CustomerPortalAccountLink; public CustomsInfo: typeof CustomsInfo; public CustomsItem: typeof CustomsItem; + public Embeddable: typeof EmbeddablesSession; public EndShipper: typeof EndShipper; public Event: typeof Event; public Fee: typeof Fee; // TODO: Fix IFee public Insurance: typeof Insurance; + public Luma: typeof Luma; public Order: typeof Order; public Parcel: typeof Parcel; public PaymentMethod: typeof PaymentMethod; public Pickup: typeof Pickup; public Rate: typeof Rate; - public Referral: typeof Referral; + public ReferralCustomer: typeof Referral; public Refund: typeof Refund; public Report: typeof Report; public ScanForm: typeof ScanForm; public Shipment: typeof Shipment; + public SmartRate: typeof SmartRate; public Tracker: typeof Tracker; public User: typeof User; public Utils: typeof Utils; diff --git a/types/Luma/Luma.d.ts b/types/Luma/Luma.d.ts new file mode 100644 index 000000000..b79a70f64 --- /dev/null +++ b/types/Luma/Luma.d.ts @@ -0,0 +1,47 @@ +/** + * Interface representing an EasyPost Luma promise object. + * + * @see https://docs.easypost.com/docs/luma + */ +export declare interface ILumaPromise { + /** Always returns "LumaInfo". */ + object: string; + + /** The delivery date and time commitment. */ + delivery_datetime: string | null; + + /** The delivery date commitment. */ + delivery_date: string | null; + + /** The pickup date and time commitment. */ + pickup_datetime: string | null; + + /** The pickup date commitment. */ + pickup_date: string | null; + + /** The carrier account used for the promise. */ + carrier_account_id: string | null; + + /** The service level used for the promise. */ + service: string | null; + + /** The carrier used for the promise. */ + carrier: string | null; +} + +/** + * The Luma class interacts with the Luma API to provide service recommendations. + * + * @see https://docs.easypost.com/docs/luma + */ +export declare class Luma { + /** + * Get service recommendations from Luma that meet the criteria of your ruleset. + * + * @see https://docs.easypost.com/docs/luma + * + * @param params - The parameters to get a Luma promise with (shipment parameters). + * @returns {Promise} - An object containing the Luma promise. + */ + static getPromise(params: object): Promise; +} diff --git a/types/Luma/index.d.ts b/types/Luma/index.d.ts new file mode 100644 index 000000000..24ea27a16 --- /dev/null +++ b/types/Luma/index.d.ts @@ -0,0 +1 @@ +export * from './Luma'; diff --git a/types/Order/Order.d.ts b/types/Order/Order.d.ts index 74f7d3caa..d2a8a2261 100644 --- a/types/Order/Order.d.ts +++ b/types/Order/Order.d.ts @@ -67,15 +67,15 @@ export declare class Order implements IOrder { id: string; mode: 'test' | 'production'; object: 'Order'; - reference?: string; + reference?: string | null; to_address: IAddress; from_address: IAddress; - return_address: IAddress; - buyer_address: IAddress; + return_address?: IAddress | null; + buyer_address?: IAddress | null; shipments: IShipment[]; rates: IRate[]; messages: IMessage[]; - is_return: boolean; + is_return?: boolean | null; created_at: string; updated_at: string; diff --git a/types/Pickup/Pickup.d.ts b/types/Pickup/Pickup.d.ts index 048c4bb9e..74f410dac 100644 --- a/types/Pickup/Pickup.d.ts +++ b/types/Pickup/Pickup.d.ts @@ -101,7 +101,7 @@ export declare class Pickup implements IPickup { min_datetime: string; max_datetime: string; is_account_address?: boolean | null; - instructions: string; + instructions?: string | null; messages: IMessage[]; confirmation: string; shipment: IShipment; diff --git a/types/Referral/Referral.d.ts b/types/Referral/Referral.d.ts index 941c57e5d..5a20efa34 100644 --- a/types/Referral/Referral.d.ts +++ b/types/Referral/Referral.d.ts @@ -1,3 +1,4 @@ +import { IApiKey } from '../ApiKey'; import { IUser } from '../User'; import { IReferralCreateParameters } from './ReferralCreateParameters'; import { IReferralListParameters } from './ReferralListParameters'; @@ -7,7 +8,14 @@ import { IReferralListParameters } from './ReferralListParameters'; * * @see https://docs.easypost.com/docs/users/referral-customers */ -export declare interface IReferral extends IUser {} +export declare interface IReferral extends IUser { + /** + * API keys for the referral customer (only returned on creation). + * Contains both test and production API keys. + * These keys should be saved securely as they cannot be retrieved again later. + */ + api_keys?: IApiKey[]; +} export declare class Referral implements IReferral { public constructor(input: IReferralCreateParameters); @@ -26,6 +34,7 @@ export declare class Referral implements IReferral { secondary_recharge_amount: string; recharge_threshold: string; children: IUser[]; + api_keys?: IApiKey[]; /** * Creates a referral customer. @@ -111,5 +120,5 @@ export declare class Referral implements IReferral { static getNextPage( referralCustomers: Object, pageSize?: number, - ): Promise<{ referrals: Referral[]; has_more: boolean }>; + ): Promise<{ referral_customers: Referral[]; has_more: boolean }>; } diff --git a/types/ScanForm/ScanForm.d.ts b/types/ScanForm/ScanForm.d.ts index 3610266a2..e488522ba 100644 --- a/types/ScanForm/ScanForm.d.ts +++ b/types/ScanForm/ScanForm.d.ts @@ -122,5 +122,5 @@ export declare class ScanForm implements IScanForm { static getNextPage( scanforms: Object, pageSize?: number, - ): Promise<{ scanforms: ScanForm[]; has_more: boolean }>; + ): Promise<{ scan_forms: ScanForm[]; has_more: boolean }>; } diff --git a/types/Shipment/Options/Options.d.ts b/types/Shipment/Options/Options.d.ts index 81b0393ec..f6c10b421 100644 --- a/types/Shipment/Options/Options.d.ts +++ b/types/Shipment/Options/Options.d.ts @@ -275,7 +275,7 @@ export declare interface IOptions { /** * The latest a package should be picked up. Supported carriers vary. */ - pickup_man_datetime: string | null; + pickup_max_datetime: string | null; /** * You can optionally print custom messages on labels. diff --git a/types/Shipment/Rate.d.ts b/types/Shipment/Rate.d.ts deleted file mode 100644 index 1df3315b7..000000000 --- a/types/Shipment/Rate.d.ts +++ /dev/null @@ -1,77 +0,0 @@ -import { IDatedObject, IObjectWithId } from '../base'; - -/** - * After a Shipment is successfully created, it will automatically fetch Rates. - * You can limit the CarrierAccounts to use for rating by passing the carrier_accounts parameter upon Shipment creation. - * - * There are three rate types: the actual rate that will be purchased, rate and currency, the published non-discounted rate, list_rate and list_currency, and the rate if purchased from the post office, retail_rate and retail_currency. - * - * @see https://docs.easypost.com/docs/shipments/rates#rate-object - */ -export declare interface IRate extends IObjectWithId<'Rate'>, IDatedObject { - /** - * service level/name - * @see https://docs.easypost.com/docs/shipments/rates#service-levels - */ - service: string; - - /** - * name of carrier - */ - carrier: string; - - /** - * ID of the CarrierAccount record used to generate this rate - */ - carrier_account_id: string; - - /** - * ID of the Shipment this rate belongs to - */ - shipment_id: string; - - /** - * the actual rate quote for this service - */ - rate: string; - - /** - * currency for the rate - */ - currency: string; - - /** - * the retail rate is the in-store rate given with no account - */ - retail_rate: string; - - /** - * currency for the retail rate - */ - retail_currency: string; - - /** - * the list rate is the non-negotiated rate given for having an account with the carrier - */ - list_rate: string; - - /** - * currency for the list rate - */ - list_currency: string; - - /** - * delivery days for this service - */ - delivery_days: number; - - /** - * date for delivery - */ - delivery_date: string; - - /** - * indicates if delivery window is guaranteed (true) or not (false) - */ - delivery_date_guaranteed: boolean; -} diff --git a/types/Shipment/Shipment.d.ts b/types/Shipment/Shipment.d.ts index 75b76bc5a..15eadf6bf 100644 --- a/types/Shipment/Shipment.d.ts +++ b/types/Shipment/Shipment.d.ts @@ -14,6 +14,7 @@ import { IPostageLabel } from './PostageLabel'; import { IRate } from './Rate'; import { IShipmentCreateParameters } from './ShipmentCreateParameters'; import { IShipmentListParameters } from './ShipmentListParameters'; +import { ITaxIdentifier } from './TaxIdentifier'; /** * The workhorse of the EasyPost API, a Shipment is made up of a "to" and "from" Address, the Parcel being shipped, and any customs forms required for international deliveries. @@ -59,6 +60,11 @@ export declare interface IShipment extends IObjectWithId<'Shipment'>, IDatedObje */ customs_info?: ICustomsInfo | null; + /** + * Tax identifiers for the shipment + */ + tax_identifiers?: ITaxIdentifier[]; + /** * Document created to manifest and scan multiple shipments */ diff --git a/types/Shipment/ShipmentCreateParameters.d.ts b/types/Shipment/ShipmentCreateParameters.d.ts index 8665c34e0..e73b6e2c6 100644 --- a/types/Shipment/ShipmentCreateParameters.d.ts +++ b/types/Shipment/ShipmentCreateParameters.d.ts @@ -3,6 +3,7 @@ import { ICustomsInfo } from '../Customs/CustomsInfo/CustomsInfo'; import { IParcelCreateParameters } from '../Parcel/ParcelCreateParameters'; import { DeepPartial } from '../utils'; import { IOptions } from './Options'; +import { ITaxIdentifier } from './TaxIdentifier'; export declare interface IShipmentCreateParameters { reference?: string | null; @@ -16,5 +17,6 @@ export declare interface IShipmentCreateParameters { carrier_accounts?: string[] | null; customs_info?: DeepPartial | null; + tax_identifiers?: ITaxIdentifier[] | null; options?: DeepPartial | null; } diff --git a/types/Shipment/TaxIdentifier.d.ts b/types/Shipment/TaxIdentifier.d.ts new file mode 100644 index 000000000..277170f15 --- /dev/null +++ b/types/Shipment/TaxIdentifier.d.ts @@ -0,0 +1,18 @@ +/** + * Interface representing a TaxIdentifier object, an embedded object within a Shipment. + * + * @see https://docs.easypost.com/docs/shipments/tax-identifiers + */ +export declare interface ITaxIdentifier { + /** The entity type (e.g., "SENDER", "RECEIVER"). */ + entity: string; + + /** The tax identification number. */ + tax_id: string; + + /** The type of tax identifier (e.g., "IOSS", "VAT", "EIN", etc.). */ + tax_id_type: string; + + /** The two-letter ISO country code of the country that issued the tax ID. */ + issuing_country: string; +} diff --git a/types/Shipment/index.d.ts b/types/Shipment/index.d.ts index b500d0186..1dd95a59d 100644 --- a/types/Shipment/index.d.ts +++ b/types/Shipment/index.d.ts @@ -2,7 +2,8 @@ export * from './Form'; export * from './Message'; export * from './Options'; export * from './PostageLabel'; -export * from './Rate'; +export { IRate, Rate } from '../Rate'; export * from './Shipment'; export * from './ShipmentCreateParameters'; export * from './ShipmentListParameters'; +export * from './TaxIdentifier'; diff --git a/types/SmartRate/index.d.ts b/types/SmartRate/index.d.ts new file mode 100644 index 000000000..e8db4933d --- /dev/null +++ b/types/SmartRate/index.d.ts @@ -0,0 +1 @@ +export * from './SmartRate'; diff --git a/types/User/User.d.ts b/types/User/User.d.ts index 7abe4a5af..de2c8ad5e 100644 --- a/types/User/User.d.ts +++ b/types/User/User.d.ts @@ -10,6 +10,11 @@ import { IUserCreateParameters } from './UserCreateParameters'; * @see https://docs.easypost.com/docs/users-object */ export declare interface IUser extends IObjectWithId<'User'> { + /** + * An optional field that may be used in place of id in other API endpoints + */ + reference?: string | null; + /** * The ID of the parent user object. * Top-level users are defined as users with no parent diff --git a/types/index.d.ts b/types/index.d.ts index 6e56d20a4..9760710e4 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -3,21 +3,27 @@ export * from './Batch'; export * from './Billing'; export * from './Brand'; export * from './Carrier'; +export * from './Claim'; export * from './Customs'; +export * from './CustomerPortal'; +export * from './Embeddable'; export * from './EndShipper'; export * from './errors'; export * from './Event'; export * from './Fee'; export * from './Insurance'; +export * from './Luma'; export * from './Order'; export * from './Parcel'; export * from './Parcel'; export * from './PaymentMethod'; export * from './Pickup'; +export * from './Referral'; export * from './Refund'; export * from './Report'; export * from './ScanForm'; export * from './Shipment'; +export * from './SmartRate'; export * from './Tracker'; export * from './User'; export * from './utils'; From 88bf64c6ec48aa37edf788df1eea6b4dbabaf541 Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Tue, 3 Feb 2026 12:57:04 -0700 Subject: [PATCH 2/2] docs: changelog entry --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fa938042d..4a3d1129f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - `ApiKey.enable` - `ApiKey.disable` - Adds a `Tracker.delete` function +- Fixes various Typescript definitions (adding missing items, correcting invalid items, consolidating duplicates, etc) ## v8.4.0 (2025-11-24)