voxelshop-js

A framework-agnostic fully typed JavaScript client for the voxel.shop API (formerly Polymart).

📚 Docs • 🚀 Getting Started • 📖 API Reference • 📝 Changelog

📦 Installation

npm install voxelshop-js
pnpm add voxelshop-js
yarn add voxelshop-js
bun add voxelshop-js

🚀 Usage

import VoxelShopClient from 'voxelshop-js';

const client = new VoxelShopClient({
  apiKey: 'your-api-key',
  userAgent: 'my-app/1.0',
});

const status = await client.general.status();
const resource = await client.resources.getInfo({ resourceId: 4 });

console.log(status);
console.log(resource);

📖 API

new VoxelShopClient(options)

const client = new VoxelShopClient({
  baseUrl: 'https://api.voxel.shop',
  apiKey: 'your-api-key',
  timeoutMs: 10_000,
  userAgent: 'my-app/1.0',
});

Options

interface VoxelShopClientOptions {
  baseUrl?: string;   // default: "https://api.voxel.shop"
  apiKey?: string;    // default api_key used for methods that accept one
  timeoutMs?: number; // default: 10000
  userAgent?: string;
  fetch?: typeof globalThis.fetch;
}

Selected Methods

General:

• client.general.status()
• client.general.search(options?)

Plugins:

• client.plugins.verifyPurchase(params)
• client.plugins.requestUpdateURL(params)
• client.plugins.downloadLatestUpdate(params) — deprecated, use requestUpdateURL

Resources:

• client.resources.getInfo(params)
• client.resources.getInfoSimple(params)
• client.resources.getUpdates(params)
• client.resources.postUpdate(params)
• client.resources.getUserData(params)
• client.resources.addBuyer(params)
• client.resources.importExternalBuyer(params)
• client.resources.addCouponCode(params)

Managers:

• client.managers.generateUserVerifyURL(params)
• client.managers.verifyUser(params)
• client.managers.getAccountInfo(params)
• client.managers.getUserId(params)

Authors:

• client.authors.getUserData(params)
• client.authors.listBuyers(params)

Platforms:

• client.platforms.authorizeUser(params)
• client.platforms.verifyAuthToken(params)
• client.platforms.invalidateAuthToken(params)
• client.platforms.getDownloadURL(params)

🔐 Authentication

Generate an API key from your voxel.shop account settings. Different actions require different key permissions - grant only what you need.

const client = new VoxelShopClient({
  apiKey: 'your-api-key',
});

const { resource } = await client.resources.getInfo({ resourceId: 4 });

🌐 Custom Fetch

You can inject your own fetch implementation.

import VoxelShopClient from 'voxelshop-js';
import fetch from 'node-fetch';

const client = new VoxelShopClient({
  apiKey: 'your-api-key',
  fetch,
});

⚠️ Error Handling

Network errors, timeouts, and non-2xx HTTP responses throw a VoxelShopError. Most actions instead respond with HTTP 200 and success: false for expected negative outcomes (an invalid purchase, a validation error) - always check .success on the returned value.

import VoxelShopClient, { VoxelShopError } from 'voxelshop-js';

const client = new VoxelShopClient({ apiKey: 'your-api-key' });

try {
  const result = await client.plugins.verifyPurchase({ resourceId: 4, license: 'invalid' });
  if (!result.success) {
    // not a genuine purchase - handled as a normal result, not an exception
  }
} catch (error) {
  if (error instanceof VoxelShopError) {
    console.error(error.status);
    console.error(error.message);
    console.error(error.body);
  }
}

👨‍💻 Development

pnpm build

pnpm test

🤝 Contributing

Contributions are always welcome!

Please ensure you run pnpm lint:fix before opening a pull request.

📜 License

MIT