API response models are misleading for nullish values

[sevrai]

Problem

Aftership tracking API return null when a property is not defined. However, the typescript response model is defined with an optional value, but not nullable.

I tested it with getTrackingById API, looking for latest_estimated_delivery property for example. The model says

export interface GetTrackingByIdResponse {
    // ...
    latest_estimated_delivery?: LatestEstimatedDeliveryGetTrackingByIdResponse;
}

but It seems to be more like:

export interface GetTrackingByIdResponse {
    // ...
    latest_estimated_delivery: LatestEstimatedDeliveryGetTrackingByIdResponse | null;
}

-> value can be null and was never undefined in my tests.

Can I assume the value will always be defined (with null value when undefined in Aftership)? Is there a reason for having this response signature?

Thanks in advance.

[tgensol]

@1415003719 @panxl6 Any news ?

[foamzou]

@sevrai @tgensol

Hi there, apologies for the delayed response.

We agree with your assessment: all fields in the API response should ideally be treated as Required, rather than Optional. Your understanding, as reflected in the code you'll provide, is correct.

export interface GetTrackingByIdResponse {
    // ...
    latest_estimated_delivery: LatestEstimatedDeliveryGetTrackingByIdResponse | null;
}

We are aiming to fix this in our October 2025 release. However, due to various factors, we cannot guarantee its completion by then.

BTW, Could you please elaborate on whether this specific issue with the API response declaration is causing any problems for your current integration?

[tgensol]

@foamzou today, we are using @hey-api to generate zod schema validators, so from your SDK or this method, zod will invalidate the payload

[foamzou]

Got it @tgensol . We will prioritize this and aim to release the new version in July or August.

[foamzou]

Hi there,
@sevrai @tgensol @f19yd

Could you please confirm if the following code meets your expectations?

export interface GetTrackingByIdResponse {
    // ...
    latest_estimated_delivery?: LatestEstimatedDeliveryGetTrackingByIdResponse | null;
}

Due to certain constraints, we may need to keep the ? in the response model field (although in practice, this field will never be undefined). Could you please review the code below and let me know if it works for your team?

[sevrai]

Hi there, @sevrai @tgensol @f19yd

Could you please confirm if the following code meets your expectations?

export interface GetTrackingByIdResponse {
    // ...
    latest_estimated_delivery?: LatestEstimatedDeliveryGetTrackingByIdResponse | null;
}

Due to certain constraints, we may need to keep the ? in the response model field (although in practice, this field will never be undefined). Could you please review the code below and let me know if it works for your team?

Hi @foamzou,

This interface should work for us, we'll narrow the type to remove the optionnal.
Glad to read that fields are never undefined in practice, thanks !