JavaScript client

@boxpressd/api-client is the official server-side TypeScript and JavaScript client for the Boxpressd Developer API. It provides typed REST and GraphQL helpers, OAuth forwarding, billing attribution, response metadata, timeouts, and typed errors. Version 0.1.4 and later supports both ECMAScript modules (ESM) and CommonJS (CJS). The package requires Node.js 18 or newer.

Keep the developer key and this client on a trusted server. Do not include them in browser, Expo, React Native, or other distributable application code.

Install the package

Install the client and its graphql peer dependency:

npm install @boxpressd/api-client graphql

pnpm add @boxpressd/api-client graphql

yarn add @boxpressd/api-client graphql

Choose a module system

The package uses conditional exports. Node and compatible bundlers select the correct build from the package-root import.

Your application	File or package setting	Boxpressd syntax
ESM	`.mjs` or `"type": "module"`	`import { BoxpressdClient } from "@boxpressd/api-client"`
CommonJS	`.cjs`, or `.js` without `"type": "module"`	`const { BoxpressdClient } = require("@boxpressd/api-client")`

The package publishes shared TypeScript declarations, the ESM runtime for the import condition, and the CommonJS runtime for the require condition. Import from @boxpressd/api-client; internal dist paths are not public exports.

TypeScript configuration

TypeScript applications can use normal named imports in either output mode. Set the compiler module mode to match the Node.js application.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "strict": true
  }
}

For ESM output, set "type": "module" in your application’s package.json or use .mts. For CommonJS output, set "type": "commonjs", omit type, or use .cts. TypeScript compiles the named import to require() for CommonJS output while preserving the package’s types.

Create a client

Store your key in BOXPRESSD_DEVELOPER_API_KEY, then create one client for your backend process.

import { BoxpressdClient } from "@boxpressd/api-client";

export const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

const { BoxpressdClient } = require("@boxpressd/api-client");

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

module.exports = { boxpressd };

The client uses https://api.boxpressd.com and a 15-second timeout by default. When you set apiBaseUrl, the GraphQL URL defaults to ${apiBaseUrl}/graphql.

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
  apiBaseUrl: "https://dev-api.boxpressd.com",
  timeoutMs: 20_000,
});

Search with REST

REST helpers return the API response body, including its data and pagination fields.

import { BoxpressdClient } from "@boxpressd/api-client";

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

const result = await boxpressd.searchCigars({
  query: "Liga Privada No. 9",
  first: 5,
});

for (const cigar of result.data) {
  console.log(cigar.id, cigar.brandName, cigar.name);
}

const { BoxpressdClient } = require("@boxpressd/api-client");

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

async function main() {
  const result = await boxpressd.searchCigars({
    query: "Liga Privada No. 9",
    first: 5,
  });

  for (const cigar of result.data) {
    console.log(cigar.id, cigar.brandName, cigar.name);
  }
}

main().catch(console.error);

Common REST helpers include searchCigars, getCigar, resolveCigar, getProduct, lookupBarcode, and getMe.

Query GraphQL

GraphQL helpers return the GraphQL data object directly.

import { BoxpressdClient } from "@boxpressd/api-client";

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

const result = await boxpressd.searchCigarsGraphQL({
  query: "Liga Privada No. 9",
  first: 5,
});

for (const { node } of result.searchCigars.edges) {
  console.log(node.id, node.brand?.name, node.name);
}

const { BoxpressdClient } = require("@boxpressd/api-client");

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

async function main() {
  const result = await boxpressd.searchCigarsGraphQL({
    query: "Liga Privada No. 9",
    first: 5,
  });

  for (const { node } of result.searchCigars.edges) {
    console.log(node.id, node.brand?.name, node.name);
  }
}

main().catch(console.error);

Use graphql() when you need a query that does not have a dedicated helper. It accepts a GraphQL string or a DocumentNode from the graphql package.

Call AI endpoints

Use request() for API routes without a dedicated helper. The client adds x-boxpressd-key; you supply the paid operation’s idempotency key.

import { randomUUID } from "node:crypto";
import { BoxpressdClient } from "@boxpressd/api-client";

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

const match = await boxpressd.request("/v1/matches", {
  method: "POST",
  headers: { "Idempotency-Key": randomUUID() },
  body: JSON.stringify({
    imageUrl: process.env.CIGAR_BAND_IMAGE_URL,
    researchMode: "auto",
    suggestionLimit: 5,
  }),
});

console.log(match);

const { randomUUID } = require("node:crypto");
const { BoxpressdClient } = require("@boxpressd/api-client");

const boxpressd = new BoxpressdClient({
  apiKey: process.env.BOXPRESSD_DEVELOPER_API_KEY,
});

async function main() {
  const match = await boxpressd.request("/v1/matches", {
    method: "POST",
    headers: { "Idempotency-Key": randomUUID() },
    body: JSON.stringify({
      imageUrl: process.env.CIGAR_BAND_IMAGE_URL,
      researchMode: "auto",
      suggestionLimit: 5,
    }),
  });

  console.log(match);
}

main().catch(console.error);

See AI and cigar matching for endpoint inputs, credit behavior, and safe retry rules.

Check billing

The client includes helpers for the non-billable billing reads:

const status = await boxpressd.getBillingStatus();
const usage = await boxpressd.getBillingUsage();
const plans = await boxpressd.listBillingPlans();
const creditPacks = await boxpressd.listCreditPacks();

Pass a stable opaque endUserId from your backend when you want billing usage attributed to one of your application users:

const status = await boxpressd.getBillingStatus({
  endUserId: internalCustomer.id,
});

The API hashes this value before storage. It does not authenticate or authorize a Boxpressd user.

Handle errors

The same named error classes are available from both module formats.

import {
  BoxpressdGraphQLError,
  BoxpressdHttpError,
  BoxpressdTimeoutError,
} from "@boxpressd/api-client";

try {
  await boxpressd.getCigar("cigar_k9P4m");
} catch (error) {
  if (error instanceof BoxpressdHttpError) {
    console.error(error.status, error.requestId, error.body);
  } else if (error instanceof BoxpressdGraphQLError) {
    console.error(error.status, error.requestId, error.errors);
  } else if (error instanceof BoxpressdTimeoutError) {
    console.error(error.timeoutMs);
  }
}

const {
  BoxpressdGraphQLError,
  BoxpressdHttpError,
  BoxpressdTimeoutError,
} = require("@boxpressd/api-client");

async function main() {
  try {
    await boxpressd.getCigar("cigar_k9P4m");
  } catch (error) {
    if (error instanceof BoxpressdHttpError) {
      console.error(error.status, error.requestId, error.body);
    } else if (error instanceof BoxpressdGraphQLError) {
      console.error(error.status, error.requestId, error.errors);
    } else if (error instanceof BoxpressdTimeoutError) {
      console.error(error.timeoutMs);
    }
  }
}

main().catch(console.error);

Use requestWithResponse() or graphqlWithResponse() when you also need response headers, the request ID, rate-limit metadata, or GraphQL cost.

Troubleshoot module loading

Symptom	Fix
`require is not defined in ES module scope`	Use `import`, rename the file to `.cjs`, or remove `"type": "module"` from the nearest package when the application is CommonJS.
`Cannot use import statement outside a module`	Rename the file to `.mjs` or set `"type": "module"` in the application package.
A deep `dist/...` import fails	Import from `@boxpressd/api-client` so conditional exports can select the build.
An older lockfile resolves an ESM-only release	Update `@boxpressd/api-client` to `0.1.4` or later and reinstall dependencies.

Getting started

API guides

REST reference

Install the package

Choose a module system

TypeScript configuration

Create a client

Search with REST

Query GraphQL

Call AI endpoints

Check billing

Handle errors

Troubleshoot module loading

​Install the package

​Choose a module system

​TypeScript configuration

​Create a client

​Search with REST

​Query GraphQL

​Call AI endpoints

​Check billing

​Handle errors

​Troubleshoot module loading

Install the package

Choose a module system

TypeScript configuration

Create a client

Search with REST

Query GraphQL

Call AI endpoints

Check billing

Handle errors

Troubleshoot module loading