EXP-753 fix: Comprehensive TypeScript definitions audit and fixes

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 <noreply@anthropic.com>

Author: Justintime50

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