@deliverart/sdk-js-order

Order management package for the DeliverArt JavaScript SDK.

Installation

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

Exported Types

Core Types

OrderType

type OrderType = 'delivery' | 'take_away' | 'kitchen'

OrderStatus

type OrderStatus = 'pending' | 'confirmed' | 'rejected'

OrderPreparationStatus

type OrderPreparationStatus = 'to_prepare' | 'in_preparation' | 'done'

OrderSource

type OrderSource = 'application' | 'ecommerce' | 'partner'

Models

See the source code for complete model definitions including:

• Order - Basic order information
• OrderDetails - Extended order with items and customer info
• OrderMenuItem - Menu item in an order
• OrderMenuItemModifier - Modifier for a menu item
• OrderCustomerInfo - Customer contact information
• OrderBillingInfo - Billing information
• FeeSimulation - Fee calculation results

Available Requests

Order Management

CreateOrder

Create a new order.

import { CreateOrder } from '@deliverart/sdk-js-order';

const order = await sdk.call(new CreateOrder({
  type: 'delivery',
  source: 'application',
  pointOfSale: '/point_of_sales/123',
  salesMode: '/sales_modes/456',
  customer: '/customers/789',
  customerInfo: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phoneNumber: '+39123456789'
  },
  billingInfo: {
    businessName: 'Acme Corp',
    vat: 'IT12345678901',
    taxCode: 'RSSMRA80A01H501U',
    billingAddress: {
      street: 'Via Fatturazione 10',
      city: 'Milano',
      postalCode: '20100',
      country: 'IT'
    },
    billingData: {
      recipientCode: 'ABCDEFG',
      pec: '[email protected]'
    }
  },
  address: {
    street: 'Via Roma 1',
    city: 'Milano',
    postalCode: '20100',
    country: 'IT',
    location: {
      latitude: 45.464664,
      longitude: 9.188540
    }
  },
  items: [
    {
      menuItem: '/menu_items/1',
      quantity: 2,
      price: 1500, // In cents
      modifiers: [
        {
          menuItemModifier: '/menu_item_modifiers/1',
          quantity: 1,
          price: 200
        }
      ]
    }
  ],
  deliveryTime: '2024-12-25T19:30:00+00:00',
  notes: 'Please ring the bell'
}));

Input Parameters:

• type: OrderType (required) - Order type
• source: OrderSource (required) - Order source
• pointOfSale: string (required) - Point of sale IRI
• salesMode: string (optional) - Sales mode IRI
• customer: string (optional) - Customer IRI
• customerBusinessProfile: string (optional) - Business profile IRI
• customerInfo: OrderCustomerInfo (optional) - Customer contact info
• billingInfo: OrderBillingInfo (optional) - Billing information (includes businessName, vat, taxCode, billingAddress, billingData)
• address: Address (optional) - Delivery/collection address
• items: OrderMenuItem[] (required) - Order items
• deliveryTime: string (optional) - Requested delivery time (ISO 8601)
• collectionTime: string (optional) - Requested collection time (ISO 8601)
• preparationTime: string (optional) - Preparation time (ISO 8601)
• discount: string (optional) - Discount amount in cents
• notes: string (optional) - General notes
• deliveryNotes: string (optional) - Delivery notes
• kitchenNotes: string (optional) - Kitchen notes
• autoAccept: boolean (optional) - Auto-accept order
• partner: string (optional) - Partner identifier
• partnerIdentifier: string (optional) - External partner order ID
• displayId: string (optional) - Custom display ID

Response: OrderDetails

GetOrders

Get paginated list of orders with filters.

import { GetOrders } from '@deliverart/sdk-js-order';

const orders = await sdk.call(new GetOrders({
  query: {
    'status[]': ['pending', 'confirmed'],
    'type[]': ['delivery'],
    pointOfSale: '/point_of_sales/123',
    'order[createdAt]': 'desc',
    page: 1
  }
}));

Query Parameters:

• status[]?: OrderStatus[] - Filter by statuses
• type[]?: OrderType[] - Filter by types
• pointOfSale?: string - Filter by point of sale IRI
• customer?: string - Filter by customer IRI
• createdAt[before]?: string - Created before date
• createdAt[after]?: string - Created after date
• order[createdAt]?: 'asc' | 'desc' - Sort by creation date
• order[deliveryTime]?: 'asc' | 'desc' - Sort by delivery time
• page?: number - Page number

Response: Paginated<Order>

GetOrderDetails

Get detailed information about a specific order.

import { GetOrderDetails } from '@deliverart/sdk-js-order';

const order = await sdk.call(new GetOrderDetails('order-123'));

Parameters:

• orderId: string (required)

Response: OrderDetails

GetPointOfSaleOrders

Get orders for a specific point of sale.

import { GetPointOfSaleOrders } from '@deliverart/sdk-js-order';

const orders = await sdk.call(new GetPointOfSaleOrders('pos-123', {
  query: {
    'status[]': ['pending'],
    page: 1
  }
}));

Parameters:

• pointOfSaleId: string (required)
• query?: object (optional) - Same as GetOrders query params

Response: Paginated<Order>

UpdateOrder

Update an existing order (partial update).

import { UpdateOrder } from '@deliverart/sdk-js-order';

const updated = await sdk.call(new UpdateOrder('order-123', {
  notes: 'Updated notes',
  deliveryTime: '2024-12-25T20:00:00+00:00'
}));

Parameters:

• orderId: string (required)
• input: Partial<OrderInput> (required) - Fields to update

Response: OrderDetails

ConfirmOrder

Confirm a pending order.

import { ConfirmOrder } from '@deliverart/sdk-js-order';

const confirmed = await sdk.call(new ConfirmOrder('order-123'));

Parameters:

• orderId: string (required)

Response: OrderDetails

RejectOrder

Reject a pending order.

import { RejectOrder } from '@deliverart/sdk-js-order';

const rejected = await sdk.call(new RejectOrder('order-123', {
  reason: 'Restaurant is closed'
}));

Parameters:

• orderId: string (required)
• input: { reason: string } (required)

Response: OrderDetails

AdvanceOrderPreparationStatus

Advance the preparation status of an order.

import { AdvanceOrderPreparationStatus } from '@deliverart/sdk-js-order';

const advanced = await sdk.call(new AdvanceOrderPreparationStatus('order-123'));

Parameters:

• orderId: string (required)

Response: OrderDetails

MarkOrderAsRead

Mark an order as read.

import { MarkOrderAsRead } from '@deliverart/sdk-js-order';

await sdk.call(new MarkOrderAsRead('order-123'));

Parameters:

• orderId: string (required)

Response: void

DeleteOrder

Delete an order.

import { DeleteOrder } from '@deliverart/sdk-js-order';

await sdk.call(new DeleteOrder('order-123'));

Parameters:

• orderId: string (required)

Response: void

CalculateOrderFees

Calculate fees for an order before creation.

import { CalculateOrderFees } from '@deliverart/sdk-js-order';

const fees = await sdk.call(new CalculateOrderFees({
  pointOfSale: '/point_of_sales/123',
  salesMode: '/sales_modes/456',
  billingInfo: {
    businessName: 'Acme Corp',
    vat: 'IT12345678901',
    taxCode: 'RSSMRA80A01H501U',
    billingAddress: {
      street: 'Via Fatturazione 10',
      city: 'Milano',
      postalCode: '20100',
      country: 'IT'
    },
    billingData: {
      recipientCode: 'ABCDEFG',
      pec: '[email protected]'
    }
  },
  address: {
    street: 'Via Roma 1',
    city: 'Milano',
    postalCode: '20100',
    country: 'IT'
  },
  items: [
    {
      menuItem: '/menu_items/1',
      quantity: 2,
      price: 1500
    }
  ]
}));

console.log('Total fees:', fees.feeAmount);
fees.fees.forEach(fee => {
  console.log(`${fee.key}: ${fee.amount}`);
});

Parameters:

• Same as CreateOrder but only requires minimal fields
• billingInfo: OrderBillingInfo (optional) - Billing information (includes billingAddress)

Order Items Management

AddOrderMenuItem

Add a menu item to an existing order.

import { AddOrderMenuItem } from '@deliverart/sdk-js-order';

const item = await sdk.call(new AddOrderMenuItem('order-123', {
  menuItem: '/menu_items/1',
  quantity: 1,
  price: 1500
}));

UpdateOrderMenuItem

Update a menu item in an order.

import { UpdateOrderMenuItem } from '@deliverart/sdk-js-order';

const updated = await sdk.call(new UpdateOrderMenuItem('item-123', {
  quantity: 3
}));

DeleteOrderMenuItem

Remove a menu item from an order.

import { DeleteOrderMenuItem } from '@deliverart/sdk-js-order';

await sdk.call(new DeleteOrderMenuItem('item-123'));

Bundles Management

Bundles group multiple orders for delivery optimization.

GetBundles

Get list of bundles.

import { GetBundles } from '@deliverart/sdk-js-order';

const bundles = await sdk.call(new GetBundles({
  query: {
    'status[]': ['pending', 'busy'],
    page: 1
  }
}));

Complete Usage Example

import { sdk } from './lib/sdk';
import {
  CreateOrder,
  GetOrders,
  ConfirmOrder,
  AdvanceOrderPreparationStatus,
  CalculateOrderFees
} from '@deliverart/sdk-js-order';

async function orderWorkflow() {
  // Calculate fees first
  const fees = await sdk.call(new CalculateOrderFees({
    pointOfSale: '/point_of_sales/123',
    billingInfo: {
      businessName: 'Acme Corp',
      vat: 'IT12345678901',
      taxCode: 'RSSMRA80A01H501U',
      billingAddress: {
        street: 'Via Fatturazione 10',
        city: 'Milano',
        postalCode: '20100',
        country: 'IT'
      },
      billingData: {
        recipientCode: 'ABCDEFG',
        pec: '[email protected]'
      }
    },
    items: [
      { menuItem: '/menu_items/1', quantity: 2, price: 1500 }
    ]
  }));
  
  console.log('Estimated fees:', fees.feeAmount);

  // Create order
  const order = await sdk.call(new CreateOrder({
    type: 'delivery',
    source: 'application',
    pointOfSale: '/point_of_sales/123',
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: '[email protected]',
      phoneNumber: '+39123456789'
    },
    billingInfo: {
      businessName: 'Acme Corp',
      vat: 'IT12345678901',
      taxCode: 'RSSMRA80A01H501U',
      billingAddress: {
        street: 'Via Fatturazione 10',
        city: 'Milano',
        postalCode: '20100',
        country: 'IT'
      },
      billingData: {
        recipientCode: 'ABCDEFG',
        pec: '[email protected]'
      }
    },
    address: {
      street: 'Via Roma 1',
      city: 'Milano',
      postalCode: '20100',
      country: 'IT'
    },
    items: [
      {
        menuItem: '/menu_items/1',
        quantity: 2,
        price: 1500
      }
    ]
  }));

  console.log('Order created:', order.id);

  // Confirm order
  const confirmed = await sdk.call(new ConfirmOrder(order.id));
  console.log('Order confirmed');

  // Advance preparation status
  await sdk.call(new AdvanceOrderPreparationStatus(order.id));
  console.log('Preparation started');

  // Get all pending orders
  const pendingOrders = await sdk.call(new GetOrders({
    query: {
      'status[]': ['pending'],
      'order[createdAt]': 'desc'
    }
  }));

  console.log(`Found ${pendingOrders.pagination.totalItems} pending orders`);
}

License

MIT