{"id":15968,"library":"boclips-api-client","title":"Boclips API Client","description":"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.","status":"active","version":"113.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/boclips/boclips-api-client","tags":["javascript","typescript"],"install":[{"cmd":"npm install boclips-api-client","lang":"bash","label":"npm"},{"cmd":"yarn add boclips-api-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add boclips-api-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for making HTTP requests to the Boclips API. The consumer application is responsible for providing and configuring an `AxiosInstance`.","package":"axios","optional":false}],"imports":[{"note":"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.","wrong":"const { ApiBoclipsClient } = require('boclips-api-client');","symbol":"ApiBoclipsClient","correct":"import { ApiBoclipsClient } from 'boclips-api-client';"},{"note":"Used for local integration testing in consumer applications. Provides an in-memory client for simplified test data setup. Use named import.","wrong":"const { FakeBoclipsClient } = require('boclips-api-client');","symbol":"FakeBoclipsClient","correct":"import { FakeBoclipsClient } from 'boclips-api-client';"},{"note":"Sub-clients like `collectionsClient` are properties of an initialized `ApiBoclipsClient` instance, not top-level exports. Do not attempt to import them directly.","wrong":"import { collectionsClient } from 'boclips-api-client';","symbol":"collectionsClient","correct":"const existingCollection = await client.collectionsClient.get('sample-collection-id');"}],"quickstart":{"code":"import { ApiBoclipsClient } from 'boclips-api-client';\nimport axios from 'axios';\n\nconst initializeClient = async () => {\n  // In a real application, replace this with your actual environment variable or configuration.\n  const apiUrlPrefix = process.env.BOCLIPS_API_URL_PREFIX ?? 'https://api.staging-boclips.com';\n\n  // Configure Axios. This is where you'd typically set up authentication (e.g., Bearer tokens).\n  const axiosInstance = axios.create({\n    baseURL: apiUrlPrefix,\n    headers: {\n      // Example: 'Authorization': `Bearer ${yourAuthToken}`\n    }\n  });\n\n  try {\n    const client = await ApiBoclipsClient.initialize(axiosInstance, apiUrlPrefix);\n\n    // Example: Query an existing collection\n    const sampleCollectionId = 'sample-collection-id'; // Replace with a real ID for testing\n    const existingCollection = await client.collectionsClient.get(sampleCollectionId);\n\n    console.log(`Successfully fetched collection: ${existingCollection?.title}`);\n    return existingCollection;\n  } catch (error) {\n    console.error('Failed to initialize BoclipsClient or fetch collection:', error);\n    throw error;\n  }\n};\n\n// To run this example, ensure you have an environment variable for the API prefix\n// and handle authentication in your axios instance.\n// initializeClient();","lang":"typescript","description":"Demonstrates the initialization of the `ApiBoclipsClient` with an Axios instance and how to access a sub-client to fetch data."},"warnings":[{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { ApiBoclipsClient } from 'boclips-api-client';` for modern JavaScript/TypeScript applications. Avoid `const ApiBoclipsClient = require('boclips-api-client');`.","cause":"Attempting to use `require()` for CommonJS import in an ESM context, or vice-versa, or incorrect named import.","error":"TypeError: ApiBoclipsClient.initialize is not a function"},{"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.","cause":"The `AxiosInstance` provided to `ApiBoclipsClient.initialize` did not include valid authentication credentials, or the credentials have expired.","error":"Error: Request failed with status code 401"},{"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.","cause":"`client` was not successfully initialized, or `collectionsClient` is not available on the client instance.","error":"TypeError: Cannot read properties of undefined (reading 'get') on client.collectionsClient"}],"ecosystem":"npm"}