@deliverart/sdk-js-delivery

Delivery management package for the DeliverArt JavaScript SDK.

Installation

npm install @deliverart/sdk-js-delivery @deliverart/sdk-js-core
# or
pnpm add @deliverart/sdk-js-delivery @deliverart/sdk-js-core

Exported Types

Models

• Delivery
• DeliveryDetails
• DeliveryStop
• WritableDelivery
• UpdateDeliveryAssignmentInput
• UpdateDeliveryAssignmentResponse
• DeliveryPosition
• DeliveryPositionDetails
• WritableDeliveryPosition
• DeliveryFee
• DeliveryFeeDetails
• DeliveryFeeListItem
• WritableCreateDeliveryFee
• WritableUpdateDeliveryFee

IRI Types

• DeliveryIri - /deliveries/:id
• DeliveryNullableIri - nullable delivery IRI
• DeliveryPositionIri - /deliveries/positions/:id
• DeliveryPositionNullableIri - nullable delivery position IRI

Deliveries

CreateDelivery

Create a delivery for an existing bundle.

import { CreateDelivery } from '@deliverart/sdk-js-delivery'

const delivery = await sdk.call(
  new CreateDelivery({
    bundle: '/bundles/123e4567-e89b-12d3-a456-426614174000',
    deliveryUser: '/users/123e4567-e89b-12d3-a456-426614174001',
  }),
)

CreateDeliveryInput

• bundle: BundleIri required
• deliveryUser?: UserNullableIri optional

Response: DeliveryDetails

DeliveryDetails now includes courier-facing run fields:

• runState
• totalStops
• pendingStopsCount
• completedStopsCount
• canFinish
• stops
• pendingStops
• suggestedNextStop
• currentStop

runState can be:

• not_started
• awaiting_stop_selection
• delivering_stop
• ready_to_finish
• finished

DeliveryStop contains:

• orderId
• displayId
• sequence
• planned
• plannedSequence
• eta
• windowStart
• windowEnd
• deliveredAt
• current

GetDeliveries

Get paginated deliveries.

import { GetDeliveries } from '@deliverart/sdk-js-delivery'

const deliveries = await sdk.call(
  new GetDeliveries({
    query: {
      'bundle.id': '123e4567-e89b-12d3-a456-426614174000',
      deliveryUser: '/users/123e4567-e89b-12d3-a456-426614174001',
      'exists[startedAt]': true,
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Main query params

• 'bundle.id'?: string | string[]
• deliveryUser?: string | UserIri | Array<string | UserIri>
• currentOrder?: string | OrderIri | Array<string | OrderIri>
• 'exists[startedAt]'?: boolean
• 'exists[endedAt]'?: boolean
• 'order[createdAt]'?: 'asc' | 'desc'
• 'order[updatedAt]'?: 'asc' | 'desc'
• 'order[startedAt]'?: 'asc' | 'desc'
• 'order[endedAt]'?: 'asc' | 'desc'
• page?: number

Response: Paginated<Delivery>

GetDeliveriesFromUser

Get deliveries assigned to a user.

import { GetDeliveriesFromUser } from '@deliverart/sdk-js-delivery'

const deliveries = await sdk.call(
  new GetDeliveriesFromUser('123e4567-e89b-12d3-a456-426614174001', {
    query: {
      'exists[endedAt]': false,
      page: 1,
    },
  }),
)

Response: Paginated<Delivery>

GetDeliveryDetails

import { GetDeliveryDetails } from '@deliverart/sdk-js-delivery'

const delivery = await sdk.call(new GetDeliveryDetails('123e4567-e89b-12d3-a456-426614174002'))

Response: DeliveryDetails

GetDeliveryDetailsFromBundle

import { GetDeliveryDetailsFromBundle } from '@deliverart/sdk-js-delivery'

const delivery = await sdk.call(
  new GetDeliveryDetailsFromBundle('123e4567-e89b-12d3-a456-426614174000'),
)

Response: DeliveryDetails

UpdateDelivery

Update the assigned courier.

import { UpdateDelivery } from '@deliverart/sdk-js-delivery'

const updated = await sdk.call(
  new UpdateDelivery('123e4567-e89b-12d3-a456-426614174002', {
    deliveryUser: '/users/123e4567-e89b-12d3-a456-426614174003',
  }),
)

UpdateDeliveryInput

• deliveryUser?: UserNullableIri

Response: DeliveryDetails

UpdateDeliveryAssignment

Assign, reassign, or remove the courier through the delivery assignment contract.

import { UpdateDeliveryAssignment } from '@deliverart/sdk-js-delivery'

const reassigned = await sdk.call(
  new UpdateDeliveryAssignment('123e4567-e89b-12d3-a456-426614174002', {
    deliveryUser: '/users/123e4567-e89b-12d3-a456-426614174005',
  }),
)

const unassigned = await sdk.call(
  new UpdateDeliveryAssignment('123e4567-e89b-12d3-a456-426614174002', {
    deliveryUser: null,
  }),
)

UpdateDeliveryAssignmentInput

• deliveryUser: UserNullableIri required; pass a user IRI to assign or reassign and null to remove the courier

Response: DeliveryDetails

The API permits removal only before the delivery starts, permits reassignment while it is in progress without resetting the delivery run, and rejects assignment changes after completion.

Delivery Lifecycle Requests

import {
  DeliverCurrentOrder,
  EndDelivery,
  StartDelivery,
  StartDeliveryOrder,
} from '@deliverart/sdk-js-delivery'

await sdk.call(new StartDelivery('123e4567-e89b-12d3-a456-426614174002'))
await sdk.call(
  new StartDeliveryOrder(
    '123e4567-e89b-12d3-a456-426614174002',
    '123e4567-e89b-12d3-a456-426614174004',
  ),
)
await sdk.call(new DeliverCurrentOrder('123e4567-e89b-12d3-a456-426614174002'))
await sdk.call(new EndDelivery('123e4567-e89b-12d3-a456-426614174002'))

Available requests

• StartDelivery
• StartDeliveryOrder
• DeliverCurrentOrder
• EndDelivery
• DeleteDelivery

Delivery Positions

CreateDeliveryPosition

import { CreateDeliveryPosition } from '@deliverart/sdk-js-delivery'

const position = await sdk.call(
  new CreateDeliveryPosition({
    delivery: '/deliveries/123e4567-e89b-12d3-a456-426614174002',
    positionData: {
      lat: 45.470664,
      lng: 9.19554,
    },
  }),
)

CreateDeliveryPositionInput

• delivery: DeliveryIri required
• positionData: { lat: number; lng: number } required

Response: DeliveryPositionDetails

GetDeliveryPositions

Get paginated delivery positions.

import { GetDeliveryPositions } from '@deliverart/sdk-js-delivery'

const positions = await sdk.call(
  new GetDeliveryPositions({
    query: {
      'order[createdAt]': 'asc',
      page: 1,
    },
  }),
)

Response: Paginated<DeliveryPosition>

GetDeliveryPositionsFromDelivery

import { GetDeliveryPositionsFromDelivery } from '@deliverart/sdk-js-delivery'

const positions = await sdk.call(
  new GetDeliveryPositionsFromDelivery('123e4567-e89b-12d3-a456-426614174002', {
    query: {
      'order[createdAt]': 'asc',
    },
  }),
)

Response: DeliveryPosition[]

GetDeliveryPositionDetails

import { GetDeliveryPositionDetails } from '@deliverart/sdk-js-delivery'

const position = await sdk.call(
  new GetDeliveryPositionDetails('123e4567-e89b-12d3-a456-426614174005'),
)

Response: DeliveryPositionDetails

Delivery Fees

Delivery fees are discriminated by type.

CreateDeliveryFee

import { CreateDeliveryFee } from '@deliverart/sdk-js-delivery'

const fee = await sdk.call(
  new CreateDeliveryFee({
    pointOfSale: '/point_of_sales/123e4567-e89b-12d3-a456-426614174006',
    type: 'distance',
    amount: '3.0000',
    taxRate: 10,
    settings: {
      min: 0,
      max: 5000,
    },
  }),
)

Supported variants

• type: 'amount' with settings: { min: number; max: number }
• type: 'distance' with settings: { min: number; max: number }
• type: 'postal_code' with settings: { values: string[] }

GetDeliveryFees

import { GetDeliveryFees } from '@deliverart/sdk-js-delivery'

const fees = await sdk.call(
  new GetDeliveryFees({
    query: {
      type: ['distance', 'postal_code'],
      'order[createdAt]': 'desc',
      page: 1,
    },
  }),
)

Response: Paginated<DeliveryFeeListItem>

GetDeliveryFeesFromPointOfSale

import { GetDeliveryFeesFromPointOfSale } from '@deliverart/sdk-js-delivery'

const fees = await sdk.call(
  new GetDeliveryFeesFromPointOfSale('123e4567-e89b-12d3-a456-426614174006', {
    query: {
      type: 'distance',
    },
  }),
)

Response: DeliveryFeeListItem[]

UpdateDeliveryFee

import { UpdateDeliveryFee } from '@deliverart/sdk-js-delivery'

const updated = await sdk.call(
  new UpdateDeliveryFee('123e4567-e89b-12d3-a456-426614174007', {
    type: 'distance',
    amount: '4.0000',
    settings: {
      min: 0,
      max: 7000,
    },
  }),
)

UpdateDeliveryFeeInput

• requires type
• all other fields are partial within the selected variant

License

MIT

Concurrent order amendments and assignment changes

Start, stop-selection, finish and delete commands retain their existing request and response schemas. The API refreshes current run state and authorization under shared amendment locks before saving. Assignment changes cannot overwrite a concurrent rider change; creation revalidates bundle availability. Handle 409/422 by reloading and showing current delivery state, without automatically repeating a stale transition. After a transport error, read the delivery to determine what was persisted. A successful operational action does not acknowledge amendment debt or confirm a payment; use the order fulfillment/settlement contracts.