Boclips API Client

Common errors

• TypeError: ApiBoclipsClient.initialize is not a function

  cause 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

  cause 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

  cause `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.

Warnings

• gotcha The `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()`.
• breaking Given 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.
• gotcha When 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.

Install

• npm install boclips-api-client npm
• yarn add boclips-api-client yarn
• pnpm add boclips-api-client pnpm

Imports

• ApiBoclipsClient
  wrong:

  const { ApiBoclipsClient } = require('boclips-api-client');

  correct:

  import { ApiBoclipsClient } from '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
  wrong:

  const { FakeBoclipsClient } = require('boclips-api-client');

  correct:

  import { FakeBoclipsClient } from '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
  wrong:

  import { collectionsClient } from 'boclips-api-client';

  correct:

  const existingCollection = await client.collectionsClient.get('sample-collection-id');

  Sub-clients like `collectionsClient` are properties of an initialized `ApiBoclipsClient` instance, not top-level exports. Do not attempt to import them directly.

Quickstart

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();