macbid-ts-api

Unofficial TypeScript client for the Mac.Bid API.

Requirements

Node.js >= 16

Install

npm install macbid-ts-api

Usage

import MacBid, { type SerializableAuthState } from "macbid-ts-api";

const api = new MacBid();
let state: SerializableAuthState = {};

state = await api.authenticate({
  email: "[email protected]",
  password: "your-password",
  ...state,
});

const watchlist = await api.get_watchlist();

authenticate() returns persistable state (tokens and device_id, never credentials). Pass it back in on the next call with ...state.

Two-factor authentication

If SMS verification is required, the first call throws after sending a code. Set state from api.getAuthState() and call again with the code:

let state: SerializableAuthState = {};

try {
  state = await api.authenticate({ email, password, ...state });
} catch {
  state = api.getAuthState();
}

// User receives SMS, then retry:
state = await api.authenticate({
  email,
  password,
  validation_code: "123456",
  ...state,
});

If device_id is set but there are no tokens and no validation_code, a code was already sent and a new SMS will not be requested.

For JSON storage, use MacBid.serializeAuthState / MacBid.parseAuthState.

AuthInfo is the type for authenticate() params (credentials, validation_code, etc.). SerializableAuthState is what comes back — safe to persist.

API

| Method | Description | |---|---| | authenticate(params?) | Log in or refresh session; returns persistable state | | get_watchlist() | Active watchlist items | | get_active() | Active won items (e.g. awaiting pickup) | | get_buildings() | Warehouse buildings | | get_locations() | Pickup locations | | get(path) / post(path, options?) | Authenticated API requests | | refreshToken() | Refresh the access token | | getAuthState() | Current persistable state | | get_refresh_token_expiration() | Refresh token expiry |

Development

npm install
npm run build
npm run lint

License

MIT