bkper-js

bkper-js library is a simple and secure way to access the Bkper REST API on Node.js and modern browsers.

It provides a set of classes and functions to interact with the Bkper API, including authentication, authorization, and data manipulation.

Installation

Add the package:

npm

npm i -S bkper-js

bun

bun add bkper-js

pnpm

pnpm add bkper-js

yarn

yarn add bkper-js

Usage

CDN / Browser

The simplest way to use bkper-js in a browser — no build tools, no npm, just a <script> tag and a valid access token. Works on any domain.

<script src="https://cdn.jsdelivr.net/npm/bkper-js@2/dist/bkper.min.js"></script>
<script>
    const { Bkper } = bkperjs;

    async function listBooks(token) {
        Bkper.setConfig({
            oauthTokenProvider: async () => token,
        });
        const bkper = new Bkper();
        return await bkper.getBooks();
    }

    // Example: prompt for a token and list books
    document.addEventListener('DOMContentLoaded', () => {
        document.getElementById('go').addEventListener('click', async () => {
            const token = document.getElementById('token').value;
            const books = await listBooks(token);
            document.getElementById('output').textContent = books.map(b => b.getName()).join('\n');
        });
    });
</script>

<input id="token" placeholder="Paste your access token" />
<button id="go">List Books</button>
<pre id="output"></pre>

Get an access token with the Bkper CLI:

bkper auth login   # one-time setup
bkper auth token   # prints a token (valid for 1 hour)

Pin to a specific version by replacing @2 with e.g. @2.31.0.

Node.js / CLI Scripts

For local scripts and CLI tools, use the bkper CLI package for authentication:

import { Bkper } from 'bkper-js';
import { getOAuthToken } from 'bkper';

// Configure with CLI authentication
Bkper.setConfig({
    oauthTokenProvider: async () => getOAuthToken(),
});

// Create Bkper instance
const bkper = new Bkper();

// Get a book and work with it
const book = await bkper.getBook('your-book-id');
console.log(`Book: ${book.getName()}`);

// List all books
const books = await bkper.getBooks();
console.log(`You have ${books.length} books`);

First, login via CLI: bkper auth login

npm + Bundler

If you are using a bundler (Vite, webpack, esbuild, etc.), install from npm and provide an access token the same way as the CDN example:

import { Bkper } from 'bkper-js';

Bkper.setConfig({
    oauthTokenProvider: async () => 'your-access-token',
});

const bkper = new Bkper();
const books = await bkper.getBooks();

Web Applications on *.bkper.app

Note: @bkper/web-auth only works on *.bkper.app subdomains. Its session cookies are scoped to the .bkper.app domain and will not work on any other domain. For apps on other domains, use the CDN / Browser approach with an access token instead.

For apps hosted on *.bkper.app subdomains, use the @bkper/web-auth SDK for built-in OAuth login flow:

import { Bkper } from 'bkper-js';
import { BkperAuth } from '@bkper/web-auth';

// Initialize authentication
const auth = new BkperAuth({
    onLoginSuccess: () => initializeApp(),
    onLoginRequired: () => showLoginButton(),
});

// Restore session on app load
await auth.init();

// Configure Bkper with web auth
Bkper.setConfig({
    oauthTokenProvider: async () => auth.getAccessToken(),
});

// Create Bkper instance and use it
const bkper = new Bkper();
const books = await bkper.getBooks();

See the @bkper/web-auth documentation for more details.

For Bkper Platform app server routes under /api/*, send Authorization: Bearer ${auth.getAccessToken()} from the client. The server route can use new Bkper() without a token provider because platform outbound auth injects the validated user’s token on Bkper API calls.

API Key (Optional)

API keys are optional and only needed for dedicated quota limits. If not provided, requests use a shared managed quota via the Bkper API proxy.

Bkper.setConfig({
    oauthTokenProvider: async () => getOAuthToken(),
    apiKeyProvider: async () => process.env.BKPER_API_KEY, // Optional - for dedicated quota
});