bidjs-api-client

A lightweight, well‑structured JavaScript client library for the BidJS API (Bidlogix). This repository provides a BidJS for authentication and request signing, plus a collection of endpoint helpers for common API calls (auctions, users, items, reports, vendors, health, etc.).

Status: scaffolded and tested locally for GET/POST/PATCH/DELETE flows. Add more endpoints as needed.

Table of contents

• Why this library
• Requirements
• Installation
• Environment variables
• Quick start
• API surface (helpers)
• Examples
• Development
• Testing
• Publishing to npm
• Contributing
• License

Why this library

Many projects need to call BidJS endpoints repeatedly and implement the same signature/auth logic. This library centralises that logic into:

• A single BidJS that handles SHA‑1 signature generation and header management.
• Small, composable helper functions for individual endpoints (easy to import and test).
• Clear separation between networking (client), crypto (signature util), and endpoint logic.

That makes onboarding new projects fast and reduces duplicated code across clients.

Requirements

• Node.js 18+ (includes native fetch) — recommended
• npm (or yarn)

Installation

For now you can add the repo as a git dependency or copy the src/ folder into your project. Once published to npm you can install via:

npm install bidjs-api-client
# or
yarn add bidjs-api-client

Environment variables

Store secrets in a .env file during local development and never commit it.

Example .env:

BIDJS_API_KEY=012345678910
BIDJS_API_SECRET=AbCdEfGhIjKlMnOpQrStUvWxYz
BIDJS_CLIENT_ID=123

We recommend adding .env to .gitignore.

Quick start

1. Create a BidJS instance.
2. Use helpers exported from src/endpoints/*.

import { BidJS, getAuctionByUUID, getUserByUUID } from 'bidjs-api-client'

const client = new BidJS({
  apiKey: process.env.BIDJS_API_KEY,
  apiSecret: process.env.BIDJS_API_SECRET,
  clientId: process.env.BIDJS_CLIENT_ID,
})

const auction = await getAuctionByUUID(client, 'xxxxxx')
const user = await getUserByUUID(client, 'xxxxxx')

console.log(auction, user)

The client automatically generates the SHA‑1 signature and sends the required bdxapi_name header.

API surface (helpers)

This library exposes small helper functions grouped by resource:

Auctions (src/endpoints/auctions.js)

• getAuctionByUUID(client, uuid) — GET /v2/auctions/{uuid}
• getAuctionById(client, id) — GET /v2/auctions/{id}
• listAuctions(client, params) — GET /v2/auctions (supports simple query param serialization)
• getAuctionRegistrants(client, auctionId) — GET /v2/auctions/{id}/registrants
• createAuction(client, auctionData) — POST /v2/auctions
• updateRegistrantStatus(client, auctionUuid, registrantUuid, statusData) — PATCH /v2/auctions/{auctionUuid}/registrants/{registrantUuid}

Users (src/endpoints/users.js)

• getUserByUUID(client, uuid) — GET /v2/users/{uuid}

Reports (src/endpoints/reports.js)

• getItemReports(client, itemUuids, options) — GET /v2/reports/items/{clientId}/{itemUuids}
• getItemSalesValue(client, itemIds) — POST /v2/reports/itemsalesvalue

Vendors (src/endpoints/vendors.js)

• getVendorByAuctioneerId(client, auctioneerId) — GET /v2/vendors/{clientId}/{auctioneerId}

Items (src/endpoints/items.js)

• updateItem(client, itemId, itemData) — PATCH /v2/items/{itemId}
• updateLiveItem(client, itemId, itemData) — POST /v2/liveItems/{itemId}
• deleteItemImages(client, itemId, publicIds) — DELETE /v2/items/{itemId}/images
• updateFullItem(client, itemUuid, itemData) — PATCH /v2/items/{itemUuid}

Health (src/endpoints/health.js)

• getHealth() — GET /v2/health (public; does not require a BidJS)

Each helper returns the parsed JSON response, and throws an Error when a non‑2xx status is returned.

Examples

Pretty print responses

Use JSON.stringify(obj, null, 2) or util.inspect(obj, { depth: null }) for deep objects.

import util from 'node:util'
console.log(util.inspect(response, { depth: null, colors: true }))

Example: Update a registrant status

import { BidJS, updateRegistrantStatus } from 'bidjs-api-client'

const client = new BidJS({ apiKey, apiSecret, clientId })
await updateRegistrantStatus(client, auctionUuid, registrantUuid, {
  statusChange: 'APPROVED',
})

Example: Post item sales value report

import { BidJS, getItemSalesValue } from 'bidjs-api-client'

const report = await getItemSalesValue(client, [123, 456])
console.log(JSON.stringify(report, null, 2))

Development

Recommendations and standards applied in this repo:

• ES Modules: "type": "module" in package.json so import/export works across Node and bundlers.
• Node 18+: relies on built‑in fetch and crypto.
• dotenv for local env vars.
• Keep client.request() responsible for insertion of auth headers (single source of truth).
• Keep endpoint helpers tiny and pure: validate args and call client.request().

Contributing

• Use feature branches: feature/<what-you-are-building>
• Open PRs; keep changes small and focused.
• Add a CHANGELOG and follow semver for releases.

Security

• Never commit secrets. Use .env and GitHub Secrets for CI.
• Rotate API secrets if you suspect compromise.

Further reading

• Official BidJS API docs: https://docs.bidjs.com/apiDefinitions
• Node crypto docs: https://nodejs.org/api/crypto.html

License

MIT