MyPOS Connect TypeScript SDK

An unofficial, server-side TypeScript client for the MyPOS Connect API v2.

When used in a Node.js runtime, the SDK requires Node.js 24 or newer. The published bundle uses standard Fetch and Web APIs without Node.js built-in imports, so it is also suitable for Cloudflare Workers as well as Vercel Functions. It ships both ESM and CommonJS entry points and preserves the API's path, query, and JSON property casing exactly as documented.

Install

npm install @moltenbot/mypos-connect-sdk

Use a bearer token

Most operations require a JWT bearer token. The API documentation says tokens are valid for 120 minutes. A static token is suitable for short-lived work:

import MyPOSConnect from '@moltenbot/mypos-connect-sdk';

const client = new MyPOSConnect({
  accessToken: process.env.MYPOS_CONNECT_ACCESS_TOKEN,
});

const products = await client.products.list({
  liPageSize: 100,
  liPage: 1,
  filt_active_bool: true,
});
console.log(products);

Long-running processes can provide the current token dynamically. The provider is invoked before every bearer-authenticated request, so it can return a cached token or refresh one when it is close to expiry:

const client = new MyPOSConnect({
  accessToken: async () => tokenCache.getValidAccessToken(),
});

The SDK does not interpret the undocumented token response or implement a token cache itself. The provider owns refresh synchronization and must return a non-empty token.

The default API URL is https://api.myposconnect.com/api/v2. Override it when using another endpoint:

import { MyPOSConnect } from '@moltenbot/mypos-connect-sdk';

const client = new MyPOSConnect({
  baseURL: 'https://example.test/api/v2',
  accessToken: process.env.MYPOS_CONNECT_ACCESS_TOKEN,
  fetch: globalThis.fetch,
});

fetch is optional and is useful for supported runtime adapters and tests.

CommonJS consumers can use the named export:

const { MyPOSConnect } = require('@moltenbot/mypos-connect-sdk');

Obtain a token with Basic authentication

Token creation uses the API user email and password as HTTP Basic credentials. The available API documentation does not define the token response shape, so the result is intentionally typed as unknown. Validate it against the response contract supplied for your account before extracting and storing the JWT.

import { MyPOSConnect } from '@moltenbot/mypos-connect-sdk';

const auth = new MyPOSConnect({
  username: process.env.MYPOS_CONNECT_USERNAME,
  password: process.env.MYPOS_CONNECT_PASSWORD,
});

const tokenResponse: unknown = await auth.auth.tokens.create();
// Validate tokenResponse before extracting its bearer token.

Basic credentials are used only by auth.tokens.create(). An accessToken is required for every other operation. Missing required credentials fail before a network request is made.

Keep API-user credentials and bearer tokens on the server. Do not expose them in browser bundles, public environment variables, logs, or client-side code.

Run a live read-only smoke test

Copy .env.example to .env, then set your API username and password. The .env file is ignored by Git. Run:

pnpm run test:live

The command obtains a token and makes page-size-one stores.list(), products.list(), and—when a store exists—products.storeData.listChanged() requests. Empty stores and product collections are valid; dependent checks are skipped when there is no record to use. HTTP failures still fail the smoke test. It reports only broad response shapes and never prints credentials, bearer tokens, store codes, or returned records.

Resources

Methods return the successful response body directly. Path, query, and body fields are flattened into one generated typed parameter object—for example, products.retrieve({ ProductCode: 'SKU-001' }). Optional per-request settings support custom headers and an AbortSignal. The SDK does not transform property names, retry requests, refresh tokens, validate response bodies at runtime, or automatically paginate results.

| Method | API operation | | --- | --- | | auth.tokens.create() | Obtain a short-lived JWT with Basic authentication. | | products.list() | List general product data from /naproducts. | | products.retrieve() | Retrieve general details for one product. | | products.listChanged() | List general products changed since a date. | | products.listAlternate() | Deprecated provisional /products endpoint; prefer products.list(). | | products.storeData.listChanged() | List changed store price, cost, quantity, and tax data. | | products.storeData.retrieve() | Retrieve store price and quantity for one product. | | products.storeData.listChangedWithOnOrder() | List changed store data including quantity on order. | | products.storeData.retrieveWithOnOrder() | Retrieve store data including quantity on order for one product. | | products.serialNumbers.retrieveStatus() | Retrieve a product serial-number status. | | customers.create() | Create a local customer. | | customers.retrieve() | Retrieve a local customer by the configured lookup value. | | customers.update() | Update a local customer. | | customers.global.retrieve() | Retrieve a global customer by email address. | | customers.global.update() | Update supported global-customer fields. | | stores.list() | List stores, with optional pagination. | | inventory.commitments.create() | Reserve inventory or reverse individual committed quantities. | | inventory.commitments.retrieve() | Retrieve committed quantities for an order. | | rewards.commitments.create() | Commit or reverse customer reward points. | | sales.create() | Insert a sale or cancel all committed quantities for an order. |

Generated types for operation inputs, verified response bodies, and API models are exported from the package. Refer to your editor's TypeScript hints for each method's exact path, query, and body fields.

Request contract details

The SDK validates the request formats that are easy to get subtly wrong:

• Product sort keys contain no whitespace, for example productCodeASC.
• General changed-product requests use YYYY-MM-DD.
• Store changed-product requests use UTC YYYY-MM-DD HH:MM:SS.fff; the SDK percent-encodes the space in the path.
• Completed sales use YYYY-MM-DDTHH:MM:SS, require a billing email, at least one item, and a Taxes array. Use an empty Taxes array for non-taxable sales.
• Cancelling all inventory committed to an order is a separate four-field sale payload whose SaleTotal is exactly 0.00.

await client.sales.create({
  Sales: [{
    SaleDate: '2026-07-16',
    OrderNumber: 'ORDER-100',
    StoreCode: '001',
    SaleTotal: '0.00',
  }],
});

The service guide says Global Customers and serial numbers are optional database features. Confirm the customer lookup mode—customer code or email—for each single database before integrating it. Reward point value is database-specific; verify it with the database owner. Guide v1.4 says negative Points commit rewards and positive values reverse them, but its older companion workbook says the opposite, so confirm that direction before enabling reward writes.

Errors and incomplete response schemas

Non-2xx responses throw MyPOSConnectError. The error contains the HTTP status, statusText, response headers, and parsed response body when available.

import {
  MyPOSConnect,
  MyPOSConnectError,
} from '@moltenbot/mypos-connect-sdk';

const client = new MyPOSConnect({
  accessToken: process.env.MYPOS_CONNECT_ACCESS_TOKEN,
});

try {
  await client.stores.list();
} catch (error: unknown) {
  if (error instanceof MyPOSConnectError) {
    console.error('MyPOS Connect request failed', error.status);
  }
  throw error;
}

openapi.yaml is intentionally conservative where the available MyPOS Connect material omits a response schema. Those success bodies—and all documented error bodies—remain unknown instead of claiming an unverified structure. This currently includes token creation, customer mutations, global-customer updates, inventory commitment writes and reads, reward commitments, and sales. Validate such values in application code before using them.

API contract

openapi.yaml is the executable source of truth for wire behavior and generated types. sdk.md is the supporting MyPOS Connect API guide. If they conflict, openapi.yaml controls the SDK.

Development

The generator is pinned to @hey-api/[email protected], and its output in src/generated is committed. After changing openapi.yaml, regenerate and run the complete release check:

corepack enable
pnpm install --frozen-lockfile
pnpm generate
pnpm validate

pnpm validate lints the OpenAPI document, checks generated-code drift, performs strict type checking, runs the operation tests, builds both module formats, runs publint, inspects the npm tarball, and installs that tarball into clean ESM and CommonJS consumers.

Publishing

The version in package.json is the release source of truth. Publishing does not depend on a Git tag or GitHub Release. To release a new version, update the version field, merge that change to main, and run the Publish to npm workflow from main. The workflow validates the checked-out package before publishing it.

The first publication needs a short-lived granular npm token because npm trusted publishing can only be configured after the package exists. Create the npm-release GitHub environment, add the token as its NPM_TOKEN secret, and run the workflow. The token must grant write access to the @moltenbot scope and be allowed to bypass 2FA for the non-interactive publish.

After the first version exists, configure the npm trusted publisher for repository Molten-Bot/mypos-connect-sdk, workflow publish.yml, and environment npm-release, with npm publish as an allowed action. Then delete the NPM_TOKEN environment secret and revoke the bootstrap token. Later workflow runs will authenticate through npm trusted publishing and OIDC.

Verify each published version using the value from package.json:

npm view "@moltenbot/mypos-connect-sdk@$(node -p "require('./package.json').version")" name version dist-tags

License and status

The SDK implementation is available under the MIT License. MyPOS Connect is a third-party service: this project is unofficial, does not operate or own that API, and the MIT license does not grant rights to the service or its documentation.