npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@uplab/vendure-plugin-nova-poshta

v0.1.3

Published

Vendure plugin for Nova Poshta: city and warehouse lookups for checkout, in Ukraine and abroad

Readme

@uplab/vendure-plugin-nova-poshta

npm Vendure License: MIT

Feed your checkout's delivery pickers from Nova Poshta: cities and warehouses in Ukraine, and cities and warehouses abroad. The plugin adds four Shop API queries, picks the warehouse types customers may choose per country, and keeps Nova Poshta's country refs on your Country entities.

Every query is a live request to Nova Poshta: nothing is cached or stored besides the country refs. The client is built on the global fetch, so the plugin has no runtime dependencies besides graphql-tag.

Compatible with Vendure ^3.7.0.

Contents

Install · Usage · Options · Database · Shop API · Delivering abroad · Admin API · API key per request · Calling other methods · Errors · Limitations

Install

npm install @uplab/vendure-plugin-nova-poshta
# or
pnpm add @uplab/vendure-plugin-nova-poshta

Usage

import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
import { NovaPoshtaPlugin } from '@uplab/vendure-plugin-nova-poshta';

export const config: VendureConfig = {
  // ...
  plugins: [
    DefaultSchedulerPlugin.init(), // runs the daily country sync
    NovaPoshtaPlugin.init({ apiKey: process.env.NOVA_POSHTA_API_KEY! }),
  ],
};

Get the key in your Nova Poshta business account: Settings → Security → API key.

Options

| Option | Type | Default | Description | | ------------- | --------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | apiKey | string \| NovaPoshtaApiKeyStrategy | — | The key, or a strategy that resolves it per request: see API key per request. | | apiUrl | string | 'https://api.novaposhta.ua/v2.0/json/' | Nova Poshta's JSON endpoint. | | timeout | number | 10000 | Milliseconds before a request is aborted. | | countrySync | { schedule?: ScheduledTaskConfig['schedule'] } \| false | { schedule: '0 7 * * *' } | The daily task that syncs country refs. Needs a scheduler plugin. false leaves the task out; the mutation stays. |

Database

The plugin adds two Region custom fields and no tables. Generate a migration after installing it:

| Custom field | Type | Public | Written by | | ------------------------------- | ---------------------------------- | ------ | ---------------- | | novaPoshtaCountryRef | string, nullable, read-only | yes | the country sync | | novaPoshtaWarehouseCategories | string list, one of four options | no | an admin |

Custom fields on Region apply to provinces too; the plugin reads them on countries only.

Shop API

novaPoshtaCities(input: { term: String!, limit: Int! }): [NovaPoshtaCity!]!            # { Ref, Description }
novaPoshtaWarehouses(input: { cityId: String!, term: String, limit: Int }): [NovaPoshtaWarehouse!]!  # { Ref, Description }
novaPoshtaInternationalCities(input: { term: String!, country: String!, limit: Int! }): [NovaPoshtaInternationalCity!]!  # { City }
novaPoshtaInternationalWarehouses(input: { city: String!, country: String!, limit: Int }): [NovaPoshtaInternationalWarehouse!]!  # { WarehouseRef, FullDescription }

The queries are public, like the rest of checkout. cityId is the Ref of a city from novaPoshtaCities. Typographic apostrophes in term (Кам’янське) are replaced with the plain one Nova Poshta matches.

A typical domestic picker:

query {
  novaPoshtaCities(input: { term: "Київ", limit: 10 }) {
    Ref
    Description
  }
}

then novaPoshtaWarehouses(input: { cityId: "<Ref>", term: "5" }) as the customer types the branch.

Delivering abroad

Nova Poshta identifies a country by its own Ref, not by ISO code. The country sync reads International.getCountries and writes that ref into customFields.novaPoshtaCountryRef of every Vendure country whose ISO code matches. Clients read it from availableCountries and pass it as country:

query {
  availableCountries {
    code
    customFields {
      novaPoshtaCountryRef
    }
  }
}

Countries without a ref are the ones Nova Poshta does not deliver to.

Warehouse types per country

On the country page in the dashboard, Nova Poshta: warehouse types chooses which types novaPoshtaInternationalWarehouses returns there. Empty means all of them.

| Value | Meaning | | ------------- | ----------------------------------------- | | PostBranch | Nova Post's own post branches | | CargoBranch | Nova Post's cargo branches and fulfilment | | PUDO | Partner pick-up points | | Poshtomat | Parcel lockers |

These are the values of the WarehouseCategory filter of International.getWarehouses. The filter takes one value per request and the response does not say a warehouse's type, so each selected type is a request of its own, run in parallel; the results are merged in the order the types are stored and capped at limit.

Admin API

mutation {
  novaPoshtaSyncCountries {
    matched # Vendure countries Nova Poshta knows
    updated # of those, the ones whose ref changed
  }
}

Runs the country sync now. Requires UpdateCountry. Run it once after installing the plugin, or wait for the daily task.

API key per request

To keep the key in the database or use a key per channel, pass a strategy instead of a string. The plugin calls its init(injector) on bootstrap and destroy() on shutdown.

import { Injector, RequestContext, TransactionalConnection } from '@vendure/core';
import { NovaPoshtaApiKeyStrategy } from '@uplab/vendure-plugin-nova-poshta';

class DbApiKeyStrategy implements NovaPoshtaApiKeyStrategy {
  private connection: TransactionalConnection;

  init(injector: Injector) {
    this.connection = injector.get(TransactionalConnection);
  }

  async getApiKey(ctx: RequestContext) {
    const settings = await this.connection.getRepository(ctx, MySettings).findOneBy({});
    return settings?.novaPoshtaApiKey;
  }
}

NovaPoshtaPlugin.init({ apiKey: new DbApiKeyStrategy() });

Calling other methods

NovaPoshtaClient is exported and calls any method of the Nova Poshta API with the resolved key: creating a waybill, tracking a parcel.

const statuses = await novaPoshtaClient.request(ctx, 'TrackingDocument', 'getStatusDocuments', {
  Documents: [{ DocumentNumber: '20450000000000' }],
});

NovaPoshtaService is exported as well, for the lookups above.

Errors

Every failure throws a NovaPoshtaError:

  • no API key;
  • a network error or timeout;
  • a non-2xx status, in status;
  • an answer with success: false, with Nova Poshta's errors and errorCodes.

In the Shop API it surfaces as a GraphQL error.

Limitations

  • Your API quota. The Shop queries are public and uncached, so every keystroke of a picker is a request on your key. Debounce on the client.
  • The country page of the Vendure dashboard up to 3.7.3 shows no custom fields, so it does not show the warehouse types. vendure#5449 fixes it for the next release; until then set them through updateCountry in the Admin API.

Changelog

See CHANGELOG.md.

License

MIT

Nova Poshta and Vendure are trademarks of their respective owners. This is an independent plugin, not affiliated with or endorsed by either.