Registry / http-networking / boclips-api-client

boclips-api-client

JSON →
library113.5.2jsnpmunverified

The Boclips API Client is a JavaScript/TypeScript library designed to provide frontend applications with a structured interface for interacting with the Boclips API. Currently at version 113.5.2, this client likely follows a rapid release cadence, indicated by its high major version number, suggesting frequent updates aligned with backend API evolution. A key differentiator is its robust testing strategy leveraging Pact for contract testing, which generates contracts against a mock HTTP layer and then verifies them against the staging API gateway. This ensures client-backend compatibility without relying solely on brittle end-to-end integration tests. The library also includes a `FakeBoclipsClient` implementation, offering an in-memory test client that simplifies integration testing for consumer applications by removing the need for HTTP mocks. Users are expected to provide their own configured Axios instance, including authentication, to the client.

npm install boclips-api-client
INSTALL
IMPORT
SIG · BOCLIPS-API-CLIENT
B
boclips-api-client
http-networkingjavascriptv113.5.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ApiBoclipsClient
import { ApiBoclipsClient } from 'boclips-api-client';
const { ApiBoclipsClient } = require('boclips-api-client');
The primary entry point for the real API client. Use named import. CommonJS `require` is not officially supported and will likely lead to issues in modern frontend setups.
FakeBoclipsClient
import { FakeBoclipsClient } from 'boclips-api-client';
const { FakeBoclipsClient } = require('boclips-api-client');
Used for local integration testing in consumer applications. Provides an in-memory client for simplified test data setup. Use named import.
collectionsClient
const existingCollection = await client.collectionsClient.get('sample-collection-id');
import { collectionsClient } from 'boclips-api-client';
Sub-clients like `collectionsClient` are properties of an initialized `ApiBoclipsClient` instance, not top-level exports. Do not attempt to import them directly.

Demonstrates the initialization of the `ApiBoclipsClient` with an Axios instance and how to access a sub-client to fetch data.

import { ApiBoclipsClient } from 'boclips-api-client'; import axios from 'axios'; const initializeClient = async () => { // In a real application, replace this with your actual environment variable or configuration. const apiUrlPrefix = process.env.BOCLIPS_API_URL_PREFIX ?? 'https://api.staging-boclips.com'; // Configure Axios. This is where you'd typically set up authentication (e.g., Bearer tokens). const axiosInstance = axios.create({ baseURL: apiUrlPrefix, headers: { // Example: 'Authorization': `Bearer ${yourAuthToken}` } }); try { const client = await ApiBoclipsClient.initialize(axiosInstance, apiUrlPrefix); // Example: Query an existing collection const sampleCollectionId = 'sample-collection-id'; // Replace with a real ID for testing const existingCollection = await client.collectionsClient.get(sampleCollectionId); console.log(`Successfully fetched collection: ${existingCollection?.title}`); return existingCollection; } catch (error) { console.error('Failed to initialize BoclipsClient or fetch collection:', error); throw error; } }; // To run this example, ensure you have an environment variable for the API prefix // and handle authentication in your axios instance. // initializeClient();
Debug
Known issues
gotchaThe `ApiBoclipsClient` requires an `AxiosInstance` to be passed during initialization. It is the consumer's responsibility to configure this Axios instance, including setting up all necessary authentication (e.g., `Authorization` headers, interceptors for token refresh). Incorrect authentication setup will lead to unauthorized API requests.
fix
Ensure your `axios.create()` call includes headers for authentication or uses Axios interceptors to inject authorization tokens before passing the instance to `ApiBoclipsClient.initialize()`.
affects: >=1.0.0
breakingGiven the high major version (113.x.x), this package likely undergoes frequent updates, often including breaking changes to align with the evolving Boclips API. New major versions can introduce changes in client method signatures, return types, or data models.
fix
Always review the package's `CHANGELOG.md` or release notes when upgrading to a new major version. Test your application thoroughly against new client versions, especially after API updates.
affects: >=1.0.0
gotchaWhen developing locally, using `pnpm link` (or `npm link`) to symlink `boclips-api-client` into a consumer application can lead to issues, particularly with duplicate React instances or inconsistent dependency resolutions if the linked client and consumer application have conflicting versions of shared dependencies.
fix
If encountering issues like 'Invalid hook call' or strange dependency errors, try `pnpm unlink boclips-api-client` and install a published version. Ensure all dependencies of the linked package are also hoisted correctly or use tools like `yalc` for more robust local package linking scenarios.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: ApiBoclipsClient.initialize is not a function
Attempting to use `require()` for CommonJS import in an ESM context, or vice-versa, or incorrect named import.
fix
Ensure you are using `import { ApiBoclipsClient } from 'boclips-api-client';` for modern JavaScript/TypeScript applications. Avoid `const ApiBoclipsClient = require('boclips-api-client');`.
Error: Request failed with status code 401
The `AxiosInstance` provided to `ApiBoclipsClient.initialize` did not include valid authentication credentials, or the credentials have expired.
fix
Verify that your `axiosInstance` is correctly configured with `Authorization` headers (e.g., `Bearer` token) before passing it to `ApiBoclipsClient.initialize`. Ensure your authentication token is valid and refreshed if necessary.
TypeError: Cannot read properties of undefined (reading 'get') on client.collectionsClient
`client` was not successfully initialized, or `collectionsClient` is not available on the client instance.
fix
Ensure that `await ApiBoclipsClient.initialize(axios, prefix)` completed successfully and returned a valid client object. Check that the `prefix` is correct and the API is accessible. Verify that the sub-client (e.g., `collectionsClient`) actually exists in the current version of the library.
Upgrade
Version history
113.5.2latest on npm
Audit
Dependencies
axiosrequiredRequired for making HTTP requests to the Boclips API. The consumer application is responsible for providing and configuring an `AxiosInstance`.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
boclips-api-client — npm install boclips-api-client · libregistry