Basta JS

A lightweight package for client-side apps to easily access and manage data from Basta's online auctions, providing a seamless integration for creating engaging auction experiences. A React library for integrating with the Basta API, providing type-safe GraphQL clients for both the Client API and Management API.

Installation

npm install basta-js
# or
pnpm add basta-js
# or
yarn add basta-js

Features

• Type-safe GraphQL client generated with genql
• React Context and Hooks for easy API access
• Support for both Client API and Management API
• Built with TypeScript
• React 16.8+ support
• All currency amounts follow the ISO 4217 standard. See here.

Usage

Basic Setup

Wrap your application with the BastaProvider and configure the relevant API/s:

import { BastaProvider } from "basta-js";

function App() {
  return (
    <BastaProvider
      clientApi={{
        headers: {
          // Add any custom headers here, e.g.: 'Authorization': 'Bearer client-token'
        },
      }}
      // managementApi={{}}
    >
      <YourApp />
    </BastaProvider>
  );
}

Using the Client API

There are two ways to access the Client API:

1. Using useBasta() hook

Returns both clientApi and managementApi (nullable):

import { useBasta } from "basta-js";

function SomeComponent() {
  const { clientApi } = useBasta();

  const fetchSale = async () => {
    const response = await clientApi?.query({
      sale: {
        __args: { id: "your-sale-id" },
        id: true,
        title: true,
        description: true,
      },
    });

    console.log(response?.sale);
  };

  return <div>Your component</div>;
}

2. Using useClientApi() hook

Returns a non-null Client instance (throws if not configured):

import { useClientApi } from "basta-js";

function SomeComponent() {
  const clientApi = useClientApi();

  const fetchSale = async () => {
    const response = await clientApi.query({
      sale: {
        __args: { id: "your-sale-id" },
        id: true,
        title: true,
        description: true,
      },
    });

    console.log(response.sale);
  };

  return <div>Your component</div>;
}

Configuration Options

BastaProvider Props

interface BastaProviderProps {
  clientApi?: {
    url?: string;
    headers?: Record<string, string>;
    wsUrl?: string;
  };
  managementApi?: {
    url?: string;
    headers?: Record<string, string>;
    wsUrl?: string;
  };
}

API Reference

Hooks

• useBasta(): Returns { clientApi: Client | null, managementApi: Client | null }
• useClientApi(): Returns Client (non-null, throws if not configured)
• useManagementApi(): Returns Client (non-null, throws if not configured)

Components

• BastaProvider: Context provider for configuring and accessing the Basta APIs

Development

Scripts

# Build the library
pnpm build

# Format code
pnpm format
pnpm format:fix

# Update the Client API schema
pnpm client:update

# Update the Management API schema
pnpm manage:update

This will prompt you to select an API version (e.g., 2022-10, unstable) and regenerate the client from the latest GraphQL schema.

For the Management API you'll have to supply an Account ID and API Key, you can put them in an .env file and the script will pick it up for you. Otherwise you'll be prompted for it by the script.

Local dev

There are a couple of example projects setup within this repo for demonstration purposes. They can be run by doing pnpm example:next or pnpm example:vite. For the nextjs project you are required to have a .env file in the examples/nextjs folder for the extra authentication needed to perform queries with the management api.

Requirements / Peer dependencies

• react 16.8.0 or higher
• urql 5.0.0 or higher
• graphql-ws 6.0.0 or higher (optional)

Publishing a new version

Right now this is a manual process.

1. Update the package.json version
2. run pnpm build for a new dist folder (probably smart to clear dist folder beforehand)
3. run the pnpm publish script, make sure you're logged in on your terminal with correct access to publish new versions