Shippo General Types

// Type definitions for shippo 1.1.3
// Project: https://github.com/goshippo/shippo-node-client
// Definitions by: JBool24 <https://github.com/jbool24>

/**
 * USPS Service Levels
 * @enum
 */
export enum USPSServiceLevelEnum {
  /** @remark Priority Mail */
  USPS_PRIORITY = 'usps_priority',
  /** @remark 'Priority Mail Express', */
  USPS_PRIORITY_EXPRESS = 'usps_priority_express',
  /** @remark 'First Class Mail/Package', */
  USPS_FIRST = 'usps_first',
  /** @remark 'Parcel Select', */
  USPS_PARCEL_SELECT = 'usps_parcel_select',
  /** @remark 'Media Mail, only for existing Shippo customers with grandfathered Media Mail option.', */
  USPS_MEDIA_MAIL = 'usps_media_mail',
  /** @remark 'Priority Mail International', */
  USPS_PRIORITY_MAIL_INTERNATIONAL = 'usps_priority_mail_international',
  /** @remark 'Priority Mail Express International', */
  USPS_PRIORITY_MAIL_EXPRESS_INTERNATIONAL = 'usps_priority_mail_express_international',
  /** @remark 'First Class Package International', */
  USPS_FIRST_CLASS_PACKAGE_INTERNATIONAL_SERVICE = 'usps_first_class_package_international_service',
}

/**
 * FedEx Service Levels
 * @enum
 */
export enum FEDEXServiceLevelEnum {
  /**@remark	FedEx Ground® */
  FEDEX_GROUND = 'fedex_ground',
  /**@remark	FedEx Home Delivery® */
  FEDEX_HOME_DELIVERY = 'fedex_home_delivery',
  /**@remark	FedEx SmartPost® */
  FEDEX_SMART_POST = 'fedex_smart_post',
  /**@remark	FedEx 2Day® */
  FEDEX_2_DAY = 'fedex_2_day',
  /**@remark	FedEx 2Day® A.M. */
  FEDEX_2_DAY_AM = 'fedex_2_day_am',
  /**@remark	FedEx Express Saver® */
  FEDEX_EXPRESS_SAVER = 'fedex_express_saver',
  /**@remark	FedEx Standard Overnight® */
  FEDEX_STANDARD_OVERNIGHT = 'fedex_standard_overnight',
  /**@remark	FedEx Priority Overnight® */
  FEDEX_PRIORITY_OVERNIGHT = 'fedex_priority_overnight',
  /**@remark	FedEx First Overnight® */
  FEDEX_FIRST_OVERNIGHT = 'fedex_first_overnight',
  /**@remark	FedEx Freight® Priority */
  FEDEX_FREIGHT_PRIORITY = 'fedex_freight_priority',
  /**@remark	FedEx Next Day Freight */
  FEDEX_NEXT_DAY_FREIGHT = 'fedex_next_day_freight',
  /**@remark	FedEx Freight® Economy */
  FEDEX_FREIGHT_ECONOMY = 'fedex_freight_economy',
  /**@remark	FedEx First Freight */
  FEDEX_FIRST_FREIGHT = 'fedex_first_freight',
  /**@remark	FedEx International Economy® */
  FEDEX_INTERNATIONAL_ECONOMY = 'fedex_international_economy',
  /**@remark	FedEx International Priority® */
  FEDEX_INTERNATIONAL_PRIORITY = 'fedex_international_priority',
  /**@remark	FedEx International First® */
  FEDEX_INTERNATIONAL_FIRST = 'fedex_international_first',
  /**@remark	FedEx International First® */
  FEDEX_EUROPE_FIRST_INTERNATIONAL_PRIORITY = 'fedex_europe_first_international_priority',
  /**@remark	FedEx International Economy® Freight */
  INTERNATIONAL_ECONOMY_FREIGHT = 'international_economy_freight',
  /**@remark	FedEx International Priority® Freight */
  INTERNATIONAL_PRIORITY_FREIGHT = 'international_priority_freight',
}

/**
 * UPS Service Levels
 * @enum
 */
export enum UPSServiceLevelEnum {
  /**@remark	Standard℠ */
  UPS_STANDARD = 'ups_standard',
  /**@remark	Ground */
  UPS_GROUND = 'ups_ground',
  /**@remark	Saver® */
  UPS_SAVER = 'ups_saver',
  /**@remark	3 Day Select® */
  UPS_3_DAY_SELECT = 'ups_3_day_select',
  /**@remark	2nd Day Air® */
  UPS_SECOND_DAY_AIR = 'ups_second_day_air',
  /**@remark	2nd Day Air® A.M. */
  UPS_SECOND_DAY_AIR_AM = 'ups_second_day_air_am',
  /**@remark	Next Day Air® */
  UPS_NEXT_DAY_AIR = 'ups_next_day_air',
  /**@remark	Next Day Air Saver® */
  UPS_NEXT_DAY_AIR_SAVER = 'ups_next_day_air_saver',
  /**@remark	Next Day Air® Early */
  UPS_NEXT_DAY_AIR_EARLY_AM = 'ups_next_day_air_early_am',
  /**@remark	Mail Innovations (domestic) */
  UPS_MAIL_INNOVATIONS_DOMESTIC = 'ups_mail_innovations_domestic',
  /**@remark	Surepost */
  UPS_SUREPOST = 'ups_surepost',
  /**@remark	SurePost® Bound Printed Matter */
  UPS_SUREPOST_BOUND_PRINTED_MATTER = 'ups_surepost_bound_printed_matter',
  /**@remark	Surepost Lightweight */
  UPS_SUREPOST_LIGHTWEIGHT = 'ups_surepost_lightweight',
  /**@remark	SurePost® Media */
  UPS_SUREPOST_MEDIA = 'ups_surepost_media',
  /**@remark	Express® */
  UPS_EXPRESS = 'ups_express',
  /**@remark	Express 12:00 */
  UPS_EXPRESS_1200 = 'ups_express_1200',
  /**@remark	Express Plus® */
  UPS_EXPRESS_PLUS = 'ups_express_plus',
  /**@remark	Expedited® */
  UPS_EXPEDITED = 'ups_expedited',
  /**@remark	Express® Early */
  UPS_EXPRESS_EARLY = 'ups_express_early',
  /**@remark	ACCESS Point™ Economy */
  UPS_ACCESS_POINT_ECONOMY = 'ups_access_point_economy',
}

export type ServiceLevelEnum =
  | USPSServiceLevelEnum
  | UPSServiceLevelEnum
  | FEDEXServiceLevelEnum;


export type ShippoError = {
  type: string;
  code: number;
  message: string;
  detail: string;
  path: string;
  statusCode: string;
};

// https://goshippo.com/docs/reference#addresses
export type IShippoAddress = {
  is_complete: boolean;
  object_created: string;
  object_updated: string;
  object_id: string;
  object_owner: string;
  name: string;
  company?: string;
  phone?: string;
  email?: string;
  street1: string;
  street2?: string;
  street3?: string;
  city: string;
  state: string;
  country: string;
  zip: string;
  test?: boolean;
  is_residential?: boolean;
  validation_results?: {
    is_valid?: boolean;
    messages?: Array<IShippoAddressValidationError>;
  };
};

export type IShippoAddressCreateRequest = {
  name: string;
  company?: string;
  email?: string;
  phone?: string;
  street1: string;
  street2?: string;
  street3?: string;
  city: string;
  zip: string;
  state: string;
  country: string;
  async?: boolean;
  is_residential?: boolean;
  validate?: boolean;
};

export interface IShippoAddressValidationError {
  source: string;
  code: string;
  type: string;
  text: string;
}
export interface IShippoAddressCreateResponse extends IShippoAddress {
  is_complete: boolean;
  object_created: string;
  object_updated: string;
  object_id: string;
  object_owner: string;
  validation_results?: {
    is_valid?: boolean;
    messages?: Array<IShippoAddressValidationError>;
  };
}
export type IShippoAddressGetRequest = IShippoAddressCreateRequest;
export type IShippoAddressValidateResponse = IShippoAddressCreateResponse;

// https://goshippo.com/docs/reference#parcels
export interface IShippoParcel {
  object_state: 'VALID';
  object_created: string; //'2021-10-06T15:06:03.119Z';
  object_updated: string; // '2021-10-06T15:06:03.167Z';
  object_id: string; // '693a26a15e0b4bf8ac530c6eff05791a';
  object_owner: string; //'bryce@idcband.com';
  template: string | null;
  metadata: string; // up to 100 chars
  extra: any; // extra values
  test: boolean;
  distance_unit: 'cm' | 'in' | 'ft' | 'mm' | 'm' | 'yd';
  height: string;
  length: string;
  mass_unit: 'g' | 'oz' | 'lb' | 'kg';
  weight: string;
  width: string;
}

export interface IShippoParcelExtras {
  // Specify collection on delivery details (UPS, and FedEx only).
  COD: {
    // Amount to be collected.
    amount: string;
    // ISO 4217 currency code (string)	Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
    currency: string;
    // Secured funds include money orders, certified cheques and others (see UPS and FedEx for details). If no payment_method inputted the value defaults to "ANY".)
    payment_method: 'SECURED_FUNDS' | 'CASH' | 'ANY';
  };
  // Specify collection on delivery details (UPS, and FedEx only).
  insurance: {
    //	Amount to be collected.
    amount: string;
    // ISO 4217 currency code Currency for the amount to be collected. Currently only USD is supported for FedEx and UPS.
    currency: string;
    // Specify the carrier insurance to have Insurance provided by the carrier directly.
    provider: 'FEDEX' | 'UPS';
    // Specify package content for insurance.
    content: string;
  };
}

export interface IShippoParcelCreateRequest {
  length: string;
  width: string;
  height: string;
  distance_unit: string;
  mass_unit: string;
  extra?: IShippoParcelExtras;
  metadata?: string;
}

export type IShippoParcelCreateResponse = IShippoParcel;
export type IShippoParcelGetResponse = IShippoParcel;

// https://goshippo.com/docs/reference#shipments
export interface IShippoShipment {
  status: 'WAITING' | 'QUEUED' | 'SUCCESS' | 'ERROR';
  object_created: string; // "2013-12-01T06:24:20.121Z"
  object_updated: string; // "2013-12-01T06:24:20.121Z"
  object_id: string; // example "5e40ead7cffe4cc1ad45108696162e42"
  object_owner: string; // "shippotle@goshippo.com",
  address_from: IShippoAddress | string;
  address_to: IShippoAddress | string;
  address_return: IShippoAddress;
  parcels: Array<IShippoParcel>; // array	Array of IDs of the Parcel objects to be shipped.
  shipment_date: string; // datetime (ISO 8601 date)	Date the shipment will be tendered to the carrier. Must be in the format "2014-01-18T00:35:03.463Z". Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
  customs_declaration: string; //ID of the Customs Declarations object for an international shipment.
  carrier_accounts: Array<IShippoCarrier>; //	An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the 'active' field set.
  rates: Array<IShippoRate>; //	An array with all available rates. If async has been set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
  messages: Array<{
    code?: string; //: an identifier for the corresponding message (not always available")
    message: string; // a publishable message containing further information.
  }>;
  extra?: any; //	An object holding optional extra services to be requested. See the Shipment Extra table below for all available services.
  metadata?: string; // A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  test?: boolean;
}

export interface IShippoShipmentCreateRequest {
  address_from: IShippoAddress;
  address_to: IShippoAddress;
  async?: boolean;
  customs_declaration?: IShippoCreateCustomsDeclarationRequest;
  parcels: string | IShippoParcel | IShippoParcel[];
}

export type IShippoShipmentCreateResponse = IShippoShipment;
export type IShippoShipmentGetResponse = IShippoShipment;

// https://goshippo.com/docs/reference#rates
export interface IShippoRate {
  object_id: string;
  object_created: string;
  object_updated: string;
  object_owner: string;
  shipment: string;
  amount: number;
  amount_local: number;
  attributes: Array<'CHEAPEST' | 'FASTEST' | 'BESTVALUE'>;
  currency: string;
  currency_local: string;
  provider: string;
  servicelevel: {
    [x: string]: string;
  };
}

export type IShippoRateGetResponse = IShippoRate;

// https://goshippo.com/docs/reference#carriers
export interface IShippoCarrier {
  object_id: string;
  object_owner: string;
  carrier: string;
  account_id: string;
  parameters?: Array<any>;
  test?: boolean;
  active: boolean;
  is_shippo_account: boolean;
  metadata: string;
  provider_id?: number;
}

export interface IShippoCarrierGetResponse extends IShippoCarrier {
  parameters: Array<any>; //	An array of additional parameters for the account, such as e.g. password or token. Please check the carrier accounts tutorial page for the parameters per carrier.
  test: boolean;
  active: boolean;
}

export interface IShippoCarrierListRequest {
  carrier: string;
}

export interface IShippoCarrierListResponse {
  next: string | null;
  previous: string | null;
  results: IShippoCarrier[];
}

// https://goshippo.com/docs/reference#transaction
export interface IShippoTransaction {
  // Indicates the validity of the Transaction object based on the given data, regardless of what the corresponding carrier returns.
  object_state: 'VALID' | 'INVALID';
  // Indicates the status of the Transaction.
  status: 'WAITING' | 'QUEUED' | 'SUCCESS' | 'ERROR' | 'REFUNDED' | 'REFUNDPENDING' | 'REFUNDREJECTED';
  object_created: string; // datetime	Date and time of Transaction creation.
  object_updated: string; // datetime	Date and time of last Transaction update.
  object_id: string; // string	Unique identifier of the given Transaction object.
  object_owner: string; // Username of the user who created the Transaction object.
  rate: IShippoRate; // ID of the Rate object for which a Label has to be obtained. Please note that only rates that are not older than 7 days can be purchased in order to ensure up-to-date pricing.
  metadata: string; // A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
  label_file_type:
    | 'PNG'
    | 'PNG_2.3x7.5'
    | 'PDF'
    | 'PDF_2.3x7.5'
    | 'PDF_4x6'
    | 'PDF_4x8'
    | 'PDF_A4'
    | 'PDF_A6'
    | 'ZPLII'; // Specify the label file format for this label. If you don't specify this value, the API will default to your default file format that you can set on the settings page. See supported label formats per carrier here.
  test: boolean; //	Indicates whether the object has been created in test mode.
  tracking_number: string; //	The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully.
  tracking_status: 'UNKNOWN' | 'DELIVERED' | 'TRANSIT' | 'FAILURE' | 'RETURNED'; //Indicates the high level status of the shipment:
  tracking_url_provider: string; //A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service.
  eta: string; // The estimated time of arrival according to the carrier.
  label_url: string; // A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully.
  commercial_invoice_url: string; // A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international.
  messages: Array<{
    code?: string; // an identifier for the corresponding message (not always available")
    message: string; // a publishable message containing further information.
  }>; //	An array containing elements of the following schema:
  qr_code_url: string; // A URL pointing directly to the QR code in PNG format. A value will only be returned if requested using qr_code_requested flag and the carrier provides such an option.
}

export interface IShippoTransactionCreateRequest {
  shipment: IShippoShipment;
  carrier_account: string;
  servicelevel_token: string;
  metadata?: string;
  label_file_type?: 'PNG' | 'PDF' | 'PDF_4x6' | 'ZPLII';
}

export interface IShippoTransactionCreateResponse extends Omit<IShippoTransaction, 'rate'> {
  rate: {
    object_id: string;
    amount: string;
    currency: string; // 'USD';
    amount_local: string; // '5.35';
    currency_local: string; // 'USD';
    provider: string; //  'USPS';
    servicelevel_name: string;
    servicelevel_token: ServiceLevelEnum;
    carrier_account: string;
  };
}

// https://goshippo.com/docs/reference#customs-items
export interface IShippoCreateCustomsItemRequest {
  description: string;
  mass_unit: 'g' | 'oz' | 'lb' | 'kg';
  net_weight: number;
  origin_country: string;
  quantity: number;
  value_amount: number;
  value_currency: string;
}

// https://goshippo.com/docs/reference#customs-declarations
export interface IShippoCreateCustomsDeclarationRequest {
  certify: boolean;
  certify_signer: string;
  contents_explanation?: string;
  contents_type:
    | 'DOCUMENTS'
    | 'GIFT'
    | 'SAMPLE'
    | 'MERCHANDISE'
    | 'HUMANITARIAN_DONATION'
    | 'RETURN_MERCHANDISE'
    | 'OTHER';
  eel_pfc?: 'NOEEI_30_37_a' | 'NOEEI_30_37_h' | 'NOEEI_30_36' | 'AES_ITN';
  incoterm?: 'DDP' | 'DDU';
  items: IShippoCreateCustomsItemRequest[];
  non_delivery_option: 'ABANDON' | 'RETURN';
}

export interface IShippoListShipmentsFilter {
  // object(s) created greater than a provided date time
  object_created_gt: string;
  // object(s) created greater than or equal to a provided date time
  object_created_gte: string;
  //object(s) created less than a provided date time
  object_created_lt: string;
  // object(s) created less than or equal to a provided date time
  object_created_lte: string;
}

export interface IShippoClient {
  shipment: {
    create: (request: IShippoShipmentCreateRequest) => Promise<IShippoShipmentCreateResponse>;
    list: (request: IShippoListShipmentsFilter) => Promise<IShippoShipment[]>;
    retrieve: (shipmentId: string) => Promise<IShippoShipmentGetResponse>;
  };
  address: {
    create: (request: IShippoAddressCreateRequest) => Promise<IShippoAddressCreateResponse>;
    validate(id: string): Promise<IShippoAddressValidateResponse>;
    list: () => Promise<IShippoAddress[]>;
    retrieve: (addressId: string) => Promise<IShippoAddress>;
  };
  transaction: {
    create: (request: IShippoTransactionCreateRequest) => Promise<IShippoTransactionCreateResponse>;
    list(): Promise<IShippoShipment[]>;
    retrieve: (id: string) => Promise<IShippoShipment>;
  };
  carrieraccount: {
    create: void;
    list(): Promise<IShippoCarrierListResponse>;
    retrieve(carrierId: string): Promise<IShippoCarrierGetResponse>;
    update: void;
  };
  rate: {
    retrieve(id: string): Promise<IShippoRateGetResponse>;
  };
  parcel: {
    create(): Promise<IShippoParcelCreateResponse>;
    list(): Promise<IShippoParcelGetResponse[]>;
    retrieve(id: string): Promise<IShippoParcelGetResponse>;
  };
}

export interface IShippoStaticConstructor {
  (token: string): IShippoClient;
  new (token: string): IShippoClient;
}