fix: Comprehensive TypeScript definitions audit and fixes

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;

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<ILumaPromise>} - An object containing the Luma promise.
+   */
+  static getPromise(params: object): Promise<ILumaPromise>;
+}

types/Luma/index.d.ts

@@ -0,0 +1 @@
+export * from './Luma';

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;
 

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;

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 }>;
 }

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 }>;
 }

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.

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
    */

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<ICustomsInfo> | null;
+  tax_identifiers?: ITaxIdentifier[] | null;
   options?: DeepPartial<IOptions> | null;
 }

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;
+}

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';

types/SmartRate/index.d.ts

@@ -0,0 +1 @@
+export * from './SmartRate';

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

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';