@deliverart/sdk-js-point-of-sale

Point of Sale (POS) management package for the DeliverArt JavaScript SDK. Provides methods for managing points of sale, their users, menu versions, time overrides, and slot availability queries.

Installation

npm install @deliverart/sdk-js-point-of-sale @deliverart/sdk-js-core
# or
pnpm add @deliverart/sdk-js-point-of-sale @deliverart/sdk-js-core
# or
yarn add @deliverart/sdk-js-point-of-sale @deliverart/sdk-js-core

Features

• Points of Sale: Full CRUD operations for points of sale with advanced filtering
• POS Users: Manage users associated with points of sale
• POS Menu Versions: Retrieve menu versions for specific points of sale
• POS Time Overrides: Manage special opening hours and closures
• Availability Times: Get unified slot options, with legacy delivery and take-away compatibility requests

Usage

Points of Sale

Get Points of Sale

import { GetPointOfSales } from '@deliverart/sdk-js-point-of-sale'

const pointsOfSale = await client.call(
  new GetPointOfSales({
    query: {
      page: 1,
      itemsPerPage: 20,
      company: 'company-iri',
      salesMode: ['delivery', 'pickup'],
    },
  }),
)

Location-Based Search

You can filter points of sale by address or by geographic coordinates:

// Filter by address
const nearby = await client.call(
  new GetPointOfSales({
    query: {
      address: '123 Main St, New York, NY',
      maxDistance: 5000, // meters
    },
  }),
)

// Filter by coordinates (latitude|longitude)
const nearbyByCoords = await client.call(
  new GetPointOfSales({
    query: {
      location: '40.7128|-74.0060', // New York coordinates
      maxDistance: 5000, // meters
    },
  }),
)

Note: Both address and location are optional. If neither is provided, distance-based filtering will be skipped and all points of sale will be returned (subject to other filters).

Get Company Points of Sale

import { GetCompanyPointOfSales } from '@deliverart/sdk-js-point-of-sale'

const companyPOS = await client.call(
  new GetCompanyPointOfSales('company-id', {
    query: {
      page: 1,
      itemsPerPage: 20,
    },
  }),
)

Get Point of Sale Details

import { GetPointOfSaleDetails } from '@deliverart/sdk-js-point-of-sale'

const pos = await client.call(new GetPointOfSaleDetails('pos-id'))

Create Point of Sale

import { CreatePointOfSale } from '@deliverart/sdk-js-point-of-sale'

const newPOS = await client.call(
  new CreatePointOfSale({
    name: [
      { locale: 'en', value: 'Downtown Store' },
      { locale: 'it', value: 'Negozio Centro' },
    ],
    company: '/api/companies/123',
    address: {
      street: '123 Main St',
      city: 'New York',
      postalCode: '10001',
      country: 'US',
    },
    // ... other fields
  }),
)

Update Point of Sale

import { UpdatePointOfSale } from '@deliverart/sdk-js-point-of-sale'

const updated = await client.call(
  new UpdatePointOfSale('pos-id', {
    name: [{ locale: 'en', value: 'Updated Store Name' }],
  }),
)

Delete Point of Sale

import { DeletePointOfSale } from '@deliverart/sdk-js-point-of-sale'

await client.call(new DeletePointOfSale('pos-id'))

POS Menu Versions

Get Point of Sale Menu Versions

import { GetPointOfSaleMenuVersions } from '@deliverart/sdk-js-point-of-sale'

const menuVersions = await client.call(
  new GetPointOfSaleMenuVersions('pos-id', {
    query: {
      page: 1,
      itemsPerPage: 20,
    },
  }),
)

Get Point of Sale Menu Version Details

import { GetPointOfSaleMenuVersionDetails } from '@deliverart/sdk-js-point-of-sale'

const menuVersion = await client.call(
  new GetPointOfSaleMenuVersionDetails('pos-id', 'menu-version-id'),
)

POS Users

Get Point of Sale Users

import { GetPointOfSaleUsers } from '@deliverart/sdk-js-point-of-sale'

const users = await client.call(
  new GetPointOfSaleUsers({
    query: {
      page: 1,
      itemsPerPage: 20,
    },
  }),
)

Get Point of Sale Users from Point of Sale

import { GetPointOfSaleUsersFromPointOfSale } from '@deliverart/sdk-js-point-of-sale'

const users = await client.call(
  new GetPointOfSaleUsersFromPointOfSale('pos-id', {
    query: {
      page: 1,
      itemsPerPage: 20,
    },
  }),
)

Get Point of Sale Users from User

import { GetPointOfSaleUsersFromUser } from '@deliverart/sdk-js-point-of-sale'

const associations = await client.call(
  new GetPointOfSaleUsersFromUser('user-id', {
    query: {
      page: 1,
      itemsPerPage: 20,
    },
  }),
)

Get Point of Sale User Details

import { GetPointOfSaleUserDetails } from '@deliverart/sdk-js-point-of-sale'

const userDetails = await client.call(new GetPointOfSaleUserDetails('pos-user-id'))

Update Point of Sale User

import { UpdatePointOfSaleUser } from '@deliverart/sdk-js-point-of-sale'

const updated = await client.call(
  new UpdatePointOfSaleUser('pos-user-id', {
    role: 'manager',
    // ... other fields
  }),
)

Delete Point of Sale User

import { DeletePointOfSaleUser } from '@deliverart/sdk-js-point-of-sale'

await client.call(new DeletePointOfSaleUser('pos-user-id'))

Availability Times

Get Point of Sale Slot Options

Unified request for GET /point_of_sales/{id}/slot_options.

Supported query params: mode, date, searchFrom, address, location, countableItems, includeInvalid, onlyFree, output.

import { GetPointOfSaleSlotOptions } from '@deliverart/sdk-js-point-of-sale'

const pointSlots = await client.call(
  new GetPointOfSaleSlotOptions('pos-id', {
    query: {
      mode: 'delivery',
      date: '2026-03-17',
      address: '123 Main St, New York, NY',
      countableItems: 2,
      includeInvalid: false,
      onlyFree: true,
      output: 'point',
    },
  }),
)

import { GetPointOfSaleSlotOptions } from '@deliverart/sdk-js-point-of-sale'

const rangeSlots = await client.call(
  new GetPointOfSaleSlotOptions('pos-id', {
    query: {
      mode: 'collection',
      date: '2026-03-17',
      searchFrom: '2026-03-17T12:00:00+01:00',
      output: 'range',
    },
  }),
)

The response includes:

• mode
• output
• intervalMinutes
• searchFrom
• windows[]
  • start
  • end
  • label
  • options[]
    • time
    • label
    • scheduledAt
    • available
    • free
    • invalidReason
    • rangeStart and rangeEnd when output = 'range'
    • compatibleBundle

Legacy Availability Times

These requests are kept for backward compatibility. Prefer GetPointOfSaleSlotOptions for new integrations.

Get Available Delivery Times

import { GetAvailablePointOfSaleDeliveryTimes } from '@deliverart/sdk-js-point-of-sale'

const deliveryTimes = await client.call(
  new GetAvailablePointOfSaleDeliveryTimes('pos-id', {
    query: {
      date: '2025-10-18',
    },
  }),
)

Get Available Take-Away Times

import { GetAvailablePointOfSaleTakeAwayTimes } from '@deliverart/sdk-js-point-of-sale'

const takeAwayTimes = await client.call(
  new GetAvailablePointOfSaleTakeAwayTimes('pos-id', {
    query: {
      date: '2025-10-18',
    },
  }),
)

POS Time Overrides

Manage special opening hours, closures, and time exceptions for points of sale.

import {
  GetPointOfTimeOverrides,
  GetPointOfTimeOverrideDetails,
  CreatePointOfTimeOverride,
  UpdatePointOfTimeOverride,
  DeletePointOfTimeOverride,
} from '@deliverart/sdk-js-point-of-sale'

// Get time overrides
const overrides = await client.call(
  new GetPointOfTimeOverrides({
    query: {
      page: 1,
      itemsPerPage: 20,
      pointOfSale: '/api/point-of-sales/123',
    },
  }),
)

// Create a time override (e.g., holiday closure)
const override = await client.call(
  new CreatePointOfTimeOverride({
    pointOfSale: '/api/point-of-sales/123',
    date: '2025-12-25',
    closed: true,
    reason: [
      { locale: 'en', value: 'Christmas Day' },
      { locale: 'it', value: 'Natale' },
    ],
  }),
)

License

MIT

Operational overview

client.call(new GetPosOperationalOverview(posId)) returns the human workspace's POS-local daily order snapshot. scheduledConfirmed uses preparation time and includes completed confirmed orders; receivedTotal uses creation time and all statuses. These cohorts overlap and must not be summed. Pending/rejected scheduled orders, remaining scheduled work, earlier unfinished orders and missing schedules are separate fields. Decimal-string order values are not collected cash. Use the returned timezone, period boundaries and generatedAt to explain scope/freshness. Partner integration API tokens do not grant access to this workspace summary.

Operational dashboard drill-down

GetPosOperationalOrders reads the selected POS cohort with required cohort and day query fields. Preserve the overview's POS calendar date rather than recomputing today in the browser. The closed cohort schema includes scheduled, received, remaining and cross-date attention groups; page and page size are bounded. Responses carry minimal typed order identities, status and timestamps, with decimal amounts kept as strings. Empty pages retain totalItems; failed reads must not be presented as an empty cohort. Lists are live, not immutable exports, and contain no customer details.

Daily operational dashboard

GetPosOperationalOverview includes optional additive counters for platform orders received today, distinct orders successfully sent to all relevant cash-register destinations, register deliveries in progress or requiring attention, actual deliveries/collections completed today, and overdue preparation. Missing fields during a rolling API deployment mean unavailable data, never zero.

Use GetPosOperationalOrders with the matching platform_received, register_sent, register_pending, register_attention, delivered, collected, preparation_late, preparation_late_not_started, or preparation_late_in_progress cohort and the overview's POS calendar day. Safe operational rows include partner/subpartner provenance and preparation/fulfillment state. Overdue cohorts return the oldest preparation deadline first. The event-date and scheduled-date cohorts overlap and must not be summed.