Hybiscus JavaScript / TypeScript SDK

Official JavaScript / TypeScript library for interacting with the Hybiscus API (Cloud and Managed Cloud).

[!NOTE] This library supersedes the previous @hybiscus/web-api library, which is now deprecrated in favour of this library.

⚠️ Breaking changes from @hybiscus/web-api

• reportSchema option from Client.HybiscusClient.buildReport and Client.HybiscusClient.previewReport changed to reportJSON, in alignment with terminology update on API docs
• Client.HybiscusClient.buildReport / Client.HybiscusClient.previewReport throw an error if there is an error received from the API, instead of resolving with the error in the attribute errorMessage
• The return from Client.HybiscusClient.buildReport / Client.HybiscusClient.previewReport no longer contains the attribute errorMessage. Instead, the error thrown is typed with the interface utils.api.HybiscusAPIError
• Minimum version of NodeJS v20.X required

🪛 Requirements

• NodeJS 20.X or newer

🛠 Installation

The library can be installed via npm as follows:

$   npm install @hybiscus/api

🚀 Usage

This library provides a declarative API for building up the report and the components inside it. Below is a simple example to get you started:

[!NOTE] To use the Hybiscus API, you will require an API key which you can get by signing up at https://hybiscus.dev/signup for a Free trial. For more details of the plans on offer, see here. This library can also be used with the Managed Cloud deployment of the API in your own private cloud, available to Enterprise plan subscribers.

Quick start

1. Setup your report with components

import { HybiscusClient, Report, Components } from "@hybiscus/api";
const { Core } = Components;
const { Section, Table, Row } = Core;

const section = new Section({ section_title: "title" }).addComponents([
    new Row({ width: "1/3" }),
    new Row({ width: "2/3" }).addComponents([
        new Table({
            title: "Table title",
            headings: ["URL", "Page views"],
            rows: [
                ["google.com", "500"],
                ["bing.com", "50"],
            ],
        }),
    ]),
]);

const options = {
   report_title: "Report title",
   report_byline: "The byline"
};
const config = {
   color_theme: "forest"
}

const report = new Report(options, config);
report.addComponent(section);

1. Initialise an instance of HybiscusClient, and call the buildReport method.

const client = new HybiscusClient({
    apiKey: "<<API_KEY>>"
});
try {
    const response = await client.buildReport({ report });
    console.log(response);
} catch (error) {
    console.error(error);
}

client.buildReport returns an object if the PDF report generation succeeds, with the following format:

type TaskStatus =
    | "CREATED"
    | "SUCCESS"
    | "FAILED"
    | "RUNNING"
    | "QUEUED"
    | null;

interface IBuildReportResponse {
    taskID: string | null;
    status: TaskStatus;
}

Components

Classes are available for each of the components in the Hybiscus API. All component classes follow the same basic principle, where they must be instantiated using the options defined in the API docs.

[!TIP] The variable naming format for component options is maintained as snake_case in line with the format used in the REST API, which is detailed in the API docs online. Although snake_case is not consistent with JavaScript / TypeScript camelCase convention, it was done to improve the developer experience and reduce the mental overhead when switching between the API docs online and this library.

Components which are specified as extendable in the API docs, have the optional method .addComponents or .addComponent, which you can use to add components within them. Components can be deeply nested through this way, giving a lot flexibility.

import { Components } from "@hybiscus/api";
const { Core } = Components;
const { Section, Text } = Components;

const section = new Section({ section_title: "title" })
    .addComponents([
        new Section({ section_title: "Sub-section" })
            .addComponents([
                new Text({ text: "Example text" }),
                new Text({ text: "More example text" }),
            ]);
        new Section({ section_title: "Sub-section" })
            .addComponents([
                new Text({ text: "Example text" }),
                new Text({ text: "More example text" }),
            ]);
    ])

This forms part of the declarative API, which lets you define the report contents without worrying about layout and design, and focusing on content.

Cover page

To add a cover page to your report, call the Report.addCoverPage method as follows. This method accepts an object with the same options for the cover page as defined in the API docs.

import { HybiscusClient, Report, Components } from "@hybiscus/api";
const { Core } = Components;
const { Section, Table, Row } = Core;

const options = {
   report_title: "Report title",
   report_byline: "The byline"
};
const config = {
    enable_multi_page: true
}
const report = new Report(options, config);
report.addCoverPage({
    bg_color: "accent"
});

To add a component to the cover page, call the report.addCoverPageComponent method with an instance of a component. As per the API docs, only the Row, Image, Text and VerticalSpacer components are supported in the cover page.

import { Components } from "@hybiscus/api";
const { Core } = Components;
const { Text } = Core;

...

report.addCoverPageComponent(
   new Text({
      text: "# Cover page title",
      color: "headline",
      size: "xl",
      markdown_format: true,
      bg_color: "background-default",
      inner_padding: 12,
   }),
);

Client

The class HybiscusClient requires at minimum to be initialised with your API token. The complete list of options that can be configured as follows:

Option | Type | Description --- | --- | --- apiKey | String | API key for the target API service. asyncBaseURL | String | The base URL for the async API endpoints. Defaults to https://api.hybiscus.dev/api/v1. timeout | number | The timeout in seconds for API calls to timeout. fetchInstance | crossFetch | Instance of crossFetch or fetch compatible API

Two functions are available which correspond to the two API endpoints:

• Build report (.buildReport)
• Preview report (.previewReport)

The .previewReport function generates a low resolution JPEG preview of the report, which doesn't count against your monthly quota.

Both functions accept either an instance of the Report class for the report parameter, or an object in the reportJSON parameter, which has the report defined according to the API documentation online.

import { HybiscusClient } from "@hybiscus/api";

const client = new HybiscusClient({
    apiKey: "<<API_KEY>>"
});

const reportJSON = {
    type: "Report",
    options: {
        report_title: "Report title"
    },
    components: [
        {
            type: "Text",
            options: {
                text: "Lorem ipsum dolor sit amet"
            }
        }
    ]
};
try {
    const response = await client.previewReport({ reportJSON });
    console.log(response);
} catch (error) {
    console.error(error);
}

Usage with Managed Cloud

If you are an Enterprise plan subscriber, you will be able to deploy a private instance of the Hybiscus API within your own private cloud, known as the Managed Cloud API. This library can also be used with that deployment, by simply providing the base URL to HybiscusClient.

For example, if your Azure Container Apps application URL is https://hybiscus.azurecontainerapps.io/, then the async base URL must be https://hybiscus.azurecontainerapps.io/api/v1/async. This is because asyncBaseURL must incorporate the full path to the async API endpoint group.

[!NOTE] For the Managed Cloud API, separate async and sync API endpoints are available. This library currently only supports the async API endpoints.

import { HybiscusClient } from "@hybiscus/api";

const client = new HybiscusClient({
    asyncBaseURL: "https://hybiscus.azurecontainerapps.io/api/v1/async",
    apiKey: process.env.HYBISCUS_API_KEY
});

Error handling

If calling any of the methods on HybiscusClient fails, an error will be thrown using the following object

interface HybiscusAPIError {
    status: TaskStatus;
    taskID: string | null;
    error: string | object | null;
}

You can use the following helper function to handle errors

import { HybiscusClient, isHybiscusAPIError } from "@hybiscus/api";

try {
    ...
} catch (error) as  error {
    if (isHybiscusAPIError(error)) {
        console.error("Status:", error.status);
        console.error("Task ID:", error.taskID);
        console.error("Error message:", error.error);
    } else {
        console.error(error);
    }

}

Using a custom HTTP client

By default Hybiscus will use native fetch, falling back to cross-fetch if no native implementation is available. You can use an alternative fetch implementation by passing an instance of it as the second argument of the HybiscusClient constructor. This client must support the Fetch API.

import nodeFetch from "node-fetch";

const client = new HybiscusClient({ 
    apiKey: "<<API_KEY>>",
    fetchInstance: nodeFetch
});

📖 Documentation

Documentation can be autogenerated using jsdoc by running npm run doc. This will generate HTML documentation in the docs/ folder which can be viewed directly in a browser without the need for a web server.

© 2025, Hybiscus