Developers: SDK Usage

Package Name

@eshopos/sdk

You do not need access to the eshopOS source repository to use the SDK.

Install

npm install @eshopos/sdk
# or
bun add @eshopos/sdk
# or
pnpm add @eshopos/sdk

If install returns package-not-found in your registry, use direct REST API integration (/api/public/v1/*) and request SDK access/publication status from the eshopOS team.

Minimal Working Example (API Key)

import { EshopOSPublicClient } from '@eshopos/sdk';

const client = new EshopOSPublicClient({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.ESHOPOS_PUBLISHABLE_KEY,
  mode: 'test',
});

const countries = await client.listSupportedPaymentCountries();
console.log(countries.data);

Minimal Working Example (OAuth Token)

import { EshopOSPublicClient } from '@eshopos/sdk';

const client = new EshopOSPublicClient({
  baseUrl: 'http://localhost:8080',
  accessToken: process.env.ESHOPOS_OAUTH_ACCESS_TOKEN,
  mode: 'live',
});

const merchant = await client.resolveMerchantByHandle('merchant-handle');
console.log(merchant.data);

Use one auth input at a time:

• apiKey for key-based integrations
• accessToken for OAuth app integrations

Error Handling Example

import { EshopOSPublicClient, PublicApiError } from '@eshopos/sdk';

const client = new EshopOSPublicClient({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.ESHOPOS_PUBLISHABLE_KEY,
  mode: 'test',
});

try {
  await client.listSupportedPaymentCountries();
} catch (error) {
  if (error instanceof PublicApiError) {
    console.error({
      status: error.status,
      code: error.code,
      requestId: error.requestId,
      details: error.details,
    });
  }
}