Class ShipGeniusOmsClient

A client for connecting to the ShipGenius OMS API and running API requests.

Index

Constructors

constructor

new ShipGeniusOmsClient(
    api_key: string,
    server: ServerConnectionSpecification,
    options?: ShipGeniusOmsClientConstructorOptions,
): ShipGeniusOmsClient
Parameters
- api_key: string
  The API Key used to authenticate with the ShipGenius OMS server.
  
  You can create one through the Connected Apps portal.
- server: ServerConnectionSpecification
  The server to connect to.
  
  Connecting via environment (recommended)
  Specify the environment key with a ServerEnvironment value to connect to a standard ShipGenius server
  
  Options are:
  - PRODUCTION = Actual server to purchase real labels
  - SANDBOX = Simple testing server with mock responses
  - DEVELOPMENT = More complex testing environment with semi-persistent data, but still no real money or labels
  Example
```
{ environment: ServerEnvironment.SANDBOX }
```
  Connecting via url (not recommended)
  Specify the url key with a URL to connect to a server at a custom URL.
  
  Useful if you need to connect indirectly, or to a staging server.
  
  Note
  URL should not contain a trailing slash or version number.
  
  URL should contain a protocol (i.e. http:// or https://).
  
  Example
```
{ url: "http://localhost:8000" }
```
- Optionaloptions: ShipGeniusOmsClientConstructorOptions
  Optional extra options
  
  Additional options for the connection, such as the api version.
  
  None of these arguments are required.
  - Optionalversion?: `v${number}_${number}` | "latest"
    The version of the API to use.
    Default
    "latest"
Returns ShipGeniusOmsClient
Example
```
import ShipGeniusOmsClient, { ServerEnvironment } from "@shipgenius/oms/client";

const client = new ShipGeniusOmsClient(
    "f7f4d30c26ac2537e1db50da3dbd990a0261617f857c093d3a261b6b2d27685e",
    { environment: ServerEnvironment.SANDBOX },
    { version: "latest" }, // not necessary since "latest" is the default
);
```
- Defined in src/client/client.ts:116

Properties

`Protected` `Internal`_url

_url: string

The base URL requests are being sent to

`Protected`_version

_version: string

The version of the API to use

`Protected`api_key

api_key: string

The user's App API Token

Accessors

url

get url(): string
The base URL requests are being sent to

Returns string
- Defined in src/client/client.ts:46

version

get version(): string
The version of the API being used

Returns string
- Defined in src/client/client.ts:57

Methods

createLabel

createLabel<Format extends LabelFormat = NONE>(
    request: GraphqlList<LabelCreationInput>,
    service: null | LabelBatchServiceInput,
    options?: {
        as_data_url?: boolean;
        format?: Format;
        payment_id?: null | string;
        weight_unit?: WeightUnit;
    },
): Promise<BulkDomesticLabelResponse<Format>>
Purchase a shipping label
Type Parameters
- Format extends LabelFormat = NONE
Parameters
- request: GraphqlList<LabelCreationInput>
  The shipment or shipments to make
- service: null | LabelBatchServiceInput
  The carrier service to purchase. If set to null, each request must specify an override in LabelCreationInput.override_service.
- Optionaloptions: {
      as_data_url?: boolean;
      format?: Format;
      payment_id?: null | string;
      weight_unit?: WeightUnit;
  }
  Extra, optional, parameters for the label creation and returned information.
  - Optionalas_data_url?: boolean
    Whether to return the image as a base64 data: uri (true), or a base64 encoded bytes string (false)
    Default
    false
  - Optionalformat?: Format
    The format to return label images in.
    
    Only one format can be specified, as converting image formats is a larger-than-typical workload.
    
    If you need the image in multiple formats, you can run a custom query via runGraphql.
    
    Default
    LabelFormat.NONE
  - Optionalpayment_id?: null | string
    The id of the payment method to use for this batch.
    
    Set to null to use your default payment method.
    Default
    null
  - Optionalweight_unit?: WeightUnit
    The unit of measure to return weights in
    
    Default
    LBS
Returns Promise<BulkDomesticLabelResponse<Format>>
Information about the batch of purchased labels.
- Defined in src/client/client.ts:418

getDomesticRate

getDomesticRate(
    request: GraphqlList<DomesticRateInput>,
    services: GraphqlList<CarrierServiceRateInput>,
    options?: { save_rates?: boolean; weight_unit: WeightUnit },
): Promise<BulkDomesticRateResponse[]>
Get cost and transit estimates for a domestic (USA to USA) shipment
Parameters
- request: GraphqlList<DomesticRateInput>
  The package(s) to rate
- services: GraphqlList<CarrierServiceRateInput>
  The carrier service(s) to get rates for
- Optionaloptions: { save_rates?: boolean; weight_unit: WeightUnit }
  Additional options for the request
  - Optionalsave_rates?: boolean
    If set to true, the returned rates will have have the rate_id set.
    
    You can use this returned id to purchase a label at the rated price for the rated service
    Default
    true
  - weight_unit: WeightUnit
    The unit to return weights in
    Default
    
    WeightUnit.LBS
Returns Promise<BulkDomesticRateResponse[]>
A list of rate information for each package, in the order they were input

Note

The return is a list of rated packages, each of which has a rates list containing the actual rates

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:352

getSupportedCarriers

getSupportedCarriers(): Promise<CarrierList>
Fetch a list of carriers supported by the API

Returns Promise<CarrierList>
Throws
client.HttpError if response is not ok
- Defined in src/client/client.ts:264

getSupportedServices

getSupportedServices(): Promise<CarrierServiceList>
Fetch a list of carrier services supported by the API

Returns Promise<CarrierServiceList>
Throws
client.HttpError if response is not ok
- Defined in src/client/client.ts:278

getTrackingInformation

getTrackingInformation(
label_info: FullShipmentIdentifier,
): Promise<TrackingInformation>
Get tracking information for a shipped package
Parameters
- label_info: FullShipmentIdentifier
  The label to get tracking information for
Returns Promise<TrackingInformation>
Information about the shipment of the package

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:395

rateAndShip

rateAndShip<Format extends LabelFormat = NONE>(
    request: GraphqlList<DomesticRateAndShipInput>,
    service_spec: DomesticRateAndShipServiceSpecs,
    options?: {
        as_data_url?: boolean;
        format?: Format;
        payment_id?: null | string;
        weight_unit?: WeightUnit;
    },
): Promise<BulkDomesticLabelResponse<Format>>
Rate and ship packages in a single API call.

Specify the services to consider for shipping and rules for how to select a service. The best service according to those rules will be selected for each shipment.
Type Parameters
- Format extends LabelFormat = NONE
Parameters
- request: GraphqlList<DomesticRateAndShipInput>
  The shipment or shipments to purchase shipping labels for
- service_spec: DomesticRateAndShipServiceSpecs
  The services to rate and rules for selecting the best
- Optionaloptions: {
      as_data_url?: boolean;
      format?: Format;
      payment_id?: null | string;
      weight_unit?: WeightUnit;
  }
  Additional options for controlling the purchase and response
  - Optionalas_data_url?: boolean
    Whether to return the image as a base64 data: uri (true), or a base64 encoded bytes string (false)
    Default
    false
  - Optionalformat?: Format
    The format to return label images in.
    
    Only one format can be specified, as converting image formats is a larger-than-typical workload.
    
    If you need the image in multiple formats, you can run a custom query via runGraphql.
    
    Default
    LabelFormat.NONE
  - Optionalpayment_id?: null | string
    The id of the payment method to use for this batch.
    
    Set to null to use your default payment method.
    Default
    null
  - Optionalweight_unit?: WeightUnit
    The unit of measure to return weights in
    
    Default
    LBS
Returns Promise<BulkDomesticLabelResponse<Format>>
Information about the batch of purchased labels
- Defined in src/client/client.ts:492

recoverLabel

recoverLabel<Format extends LabelFormat = NONE>(
    transaction_id: string,
    options?: {
        as_data_url?: boolean;
        format?: Format;
        payment_id?: null | string;
        weight_unit?: WeightUnit;
    },
): Promise<DomesticLabel<Format>>
Recover a lost label using the transaction if provided when the label was initially created.
Note

This mutation is designed for rare scenarios, such as a lost connection or unexpected crash during the label creation process.

For further assistance, contact us at info@shipgeni.us
- Recovery should only be used if there was a failure to receive a label calling from createLabel or rateAndShip
- This recovery process is only valid within 24 hours of generating the label.
Type Parameters
- Format extends LabelFormat = NONE
Parameters
- transaction_id: string
  The LabelCreationInput.transaction_id or DomesticRateAndShipInput.transaction_id used when creating the label you want to recover
- Optionaloptions: {
      as_data_url?: boolean;
      format?: Format;
      payment_id?: null | string;
      weight_unit?: WeightUnit;
  }
  Additional options for configuring the recovery and the returned label
  - Optionalas_data_url?: boolean
    Whether to return the image as a base64 data: uri (true), or a base64 encoded bytes string (false)
    Default
    false
  - Optionalformat?: Format
    The format to return label images in.
    
    Only one format can be specified, as converting image formats is a larger-than-typical workload.
    
    If you need the image in multiple formats, you can run a custom query via runGraphql.
    
    Default
    LabelFormat.NONE
  - Optionalpayment_id?: null | string
    The payment ID to use to pay for the label if payment was not successful initially.
    
    The payment method will not be charged if the label was already paid for.
    
    If something goes wrong and you get double-charged for a label, contact info@shipgeni.us as soon as possible to resolve the issue.
  - Optionalweight_unit?: WeightUnit
    The unit of measure to return weights in
    
    Default
    LBS
Returns Promise<DomesticLabel<Format>>
the recovered label
- Defined in src/client/client.ts:573

runGraphql

runGraphql(query: string, variables?: JsonObject): Promise<null | JsonObject>
Run an arbitrary GraphQL query on the connected API server.
Parameters
- query: string
  The GraphQL query (or mutation) to run
- Optionalvariables: JsonObject
  The variables to pass into the query
Returns Promise<null | JsonObject>
The data field of the query response

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:297

subscribeToTrackingUpdates

subscribeToTrackingUpdates(
label_info: FullShipmentIdentifier,
subscribers: GraphqlList<Trackingsubscription>,
): Promise<boolean[]>
Request that the list of subscribers recieve notifications about tracking updates for the specified shipment
Parameters
- label_info: FullShipmentIdentifier
  The shipment to subscribe to updates for
- subscribers: GraphqlList<Trackingsubscription>
  A list of people to notify about updates
Returns Promise<boolean[]>
a list of boolean values indicating whether the subscriptions were successful, in the same order as the input.

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:663

validateAddress

validateAddress(
address: GraphqlList<DomesticAddressInput>,
options?: { zip_plus_four?: boolean },
): Promise<(AddressValidationInfo | AddressValidationError)[]>
Validate and correct address(es) against the USPS database
Parameters
- address: GraphqlList<DomesticAddressInput>
  The address(es) to validate
- Optionaloptions: { zip_plus_four?: boolean }
  Additional options to control the response
  - Optionalzip_plus_four?: boolean
    Whether to include ZIP+4 extensions on returned ZIP Codes as opposed to the plain 5-digit ZIP Code
    Default
    false
Returns Promise<(AddressValidationInfo | AddressValidationError)[]>
A list of validated address and/or errors in the same order as the input

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:311

voidLabel

voidLabel(label_info: FullShipmentIdentifier): Promise<VoidLabelResponse>
Void the specified label and request a refund if applicable
Parameters
- label_info: FullShipmentIdentifier
  The label to void
Returns Promise<VoidLabelResponse>
The success status of the void

Throws
client.HttpError if the response is not ok

Throws
client.GraphqlError if the response contains an errors key
- Defined in src/client/client.ts:644

Class ShipGeniusOmsClient

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Connecting via environment (recommended)

Connecting via url (not recommended)

Optionalversion?: `v${number}_${number}` | "latest"

Default

Returns ShipGeniusOmsClient

Example

Properties

Protected Internal_url

Protected_version

Protectedapi_key

Accessors

url

Returns string

version

Returns string

Methods

createLabel

Type Parameters

Parameters

Optionalas_data_url?: boolean

Default

Optionalformat?: Format

Default

Optionalpayment_id?: null | string

Default

Optionalweight_unit?: WeightUnit

Default

Returns Promise<BulkDomesticLabelResponse<Format>>

getDomesticRate

Parameters

Optionalsave_rates?: boolean

Default

weight_unit: WeightUnit

Default

Returns Promise<BulkDomesticRateResponse[]>

Throws

Throws

getSupportedCarriers

Returns Promise<CarrierList>

Throws

getSupportedServices

Returns Promise<CarrierServiceList>

Throws

getTrackingInformation

Parameters

Returns Promise<TrackingInformation>

Throws

Throws

rateAndShip

Type Parameters

Parameters

Optionalas_data_url?: boolean

Default

Optionalformat?: Format

Default

Optionalpayment_id?: null | string

Default

Optionalweight_unit?: WeightUnit

Default

Returns Promise<BulkDomesticLabelResponse<Format>>

recoverLabel

Type Parameters

Parameters

Optionalas_data_url?: boolean

Default

Optionalformat?: Format

Default

Optionalpayment_id?: null | string

Optionalweight_unit?: WeightUnit

Default

Returns Promise<DomesticLabel<Format>>

Connecting via `environment` (recommended)

Connecting via `url` (not recommended)

`Optional`version?: `v${number}_${number}` | "latest"

`Protected` `Internal`_url

`Protected`_version

`Protected`api_key

`Optional`as_data_url?: boolean

`Optional`format?: Format

`Optional`payment_id?: null | string

`Optional`weight_unit?: WeightUnit

`Optional`save_rates?: boolean

`Optional`as_data_url?: boolean

`Optional`format?: Format

`Optional`payment_id?: null | string

`Optional`weight_unit?: WeightUnit

`Optional`as_data_url?: boolean

`Optional`format?: Format

`Optional`payment_id?: null | string

`Optional`weight_unit?: WeightUnit

`Optional`zip_plus_four?: boolean