Contensis Core API Library

Common errors

• TypeError: (0 , contensis_core_api_1.HttpClient) is not a constructor

  cause Attempting to `require` an ESM-only module or using incorrect CommonJS syntax for named exports. The `contensis-core-api` package is written in TypeScript and likely built for ESM, though it might provide CJS bundles.
  fix Use ES module `import` syntax: `import { HttpClient } from 'contensis-core-api';`. If in a CommonJS environment, configure your project for ESM or ensure your transpiler handles `import`/`export` correctly.

• TS2307: Cannot find module 'contensis-core-api' or its corresponding type declarations.

  cause TypeScript compiler cannot locate the package's type definitions. This can happen if the package is not installed, or if `tsconfig.json` is not correctly configured to include `node_modules/@types` or the package's own types.
  fix Ensure `contensis-core-api` is installed (`npm install contensis-core-api` or `yarn add contensis-core-api`). Verify `tsconfig.json` includes `"compilerOptions": { "moduleResolution": "Node" }` and implicitly or explicitly includes `node_modules` in its `include` path.

Warnings

• gotcha This package is a core dependency for other Contensis client libraries (`contensis-delivery-api`, `contensis-management-api`). Direct consumption by application developers is generally not recommended, as the higher-level SDKs provide a more abstracted and feature-rich interface for interacting with the Contensis CMS.
  Fix: For interacting with Contensis APIs, prefer `contensis-delivery-api` for read-only content or `contensis-management-api` for content management operations.
• breaking Major version updates of `contensis-core-api` typically coincide with breaking changes in the consuming client libraries. Changes in internal types, interfaces, or HTTP client behavior in this core package can propagate as breaking changes in the higher-level SDKs. Developers should consult the changelog of `contensis-delivery-api` or `contensis-management-api` when upgrading.
  Fix: Always check the release notes and migration guides for `contensis-delivery-api` and `contensis-management-api` when updating to a new major version of any Contensis SDK. Pay attention to type definition changes and API instantiation methods.
• gotcha The package requires Node.js >=12, as specified in its `engines` field. Using it with older Node.js versions may lead to runtime errors due to unsupported syntax or built-in features (like `fetch` polyfills in consuming libraries).
  Fix: Ensure your Node.js environment meets the minimum requirement. For client-side usage, ensure your build process correctly handles browser compatibility.

Install

• npm install contensis-core-api npm
• yarn add contensis-core-api yarn
• pnpm add contensis-core-api pnpm

Imports

• HttpClient
  wrong:

  const HttpClient = require('contensis-core-api').HttpClient;

  correct:

  import { HttpClient } from 'contensis-core-api';

  Primarily used internally by Contensis client libraries, but available for custom low-level HTTP handling.
• HttpMethod
  wrong:

  import { HTTP_METHOD } from 'contensis-core-api';

  correct:

  import { HttpMethod } from 'contensis-core-api';

  Enum defining standard HTTP verbs (e.g., 'GET', 'POST').
• CallError
  wrong:

  import { ApiError } from 'contensis-core-api';

  correct:

  import { CallError } from 'contensis-core-api';

  Base class for API-related errors, useful for custom error handling logic when interacting with Contensis APIs at a lower level.

Quickstart

Illustrates the usage of core types like `HttpClient`, `HttpMethod`, and `CallError`, demonstrating a low-level HTTP request pattern. This package is typically a dependency and not used directly for API calls by end-user applications.

import { HttpClient, HttpMethod, CallError, IHttpClient } from 'contensis-core-api';

interface MyApiOptions {
  rootUrl: string;
  accessToken: string;
}

// Demonstrating how to set up a basic HttpClient (typically abstracted by higher-level Contensis clients)
class CustomContensisHttpClient implements IHttpClient {
  private client: HttpClient;

  constructor(options: MyApiOptions) {
    this.client = new HttpClient(options.rootUrl);
    // In a real scenario, authentication headers would be added here or via middleware
    this.client.setDefaultHeader('Authorization', `Bearer ${options.accessToken}`);
  }

  async request<T>(method: HttpMethod, path: string, options?: RequestInit): Promise<T> {
    try {
      const response = await this.client.request<T>(method, path, options);
      console.log(`Successfully made ${method} request to ${path}`);
      return response;
    } catch (error) {
      if (error instanceof CallError) {
        console.error(`API Call Error: ${error.message} (Status: ${error.status})`);
      } else {
        console.error('An unexpected error occurred:', error);
      }
      throw error;
    }
  }
}

// Example usage (conceptual, as direct use is rare)
const myClient = new CustomContensisHttpClient({
  rootUrl: process.env.CONTENSIS_ROOT_URL ?? 'https://api.contensis.com',
  accessToken: process.env.CONTENSIS_ACCESS_TOKEN ?? 'YOUR_ACCESS_TOKEN_HERE'
});

async function fetchData() {
  try {
    // This is a simplified example; actual paths and types would vary.
    // Higher-level Contensis SDKs (`contensis-delivery-api`) provide structured methods.
    const data = await myClient.request<any>(HttpMethod.GET, '/some/api/path');
    console.log('Received data:', data);
  } catch (e) {
    console.log('Failed to fetch data via core client.');
  }
}

fetchData();