Installation


To install Carbon Connect as a pre-built React component, use npm as follows:

npm install carbon-connect

Prerequisites


The package expects the following npm packages to be installed in your project:

  1. @radix-ui/react-dialog
  2. "lodash": "^4.17.21
  3. react
  4. react-dom
  5. react-drag-drop-files
  6. react-icons
  7. react-toastify
  8. tailwindcss

Please check for the versions from package.json if you encounter a version mismatch error.

Component Properties


The CarbonConnect component accepts the following properties:

PropertyTypeRequired?Description
brandIconStringYesA URL or a local path to your organization’s brand icon.
orgNameStringYesThe name of your organization. This is displayed in the initial announcement modal view.
tokenFetcherFunctionYesA function that returns a promise which resolves with the access and refresh tokens.
onSuccessFunctionNoA callback function that will be called after the file upload is successful.
onErrorFunctionNoA callback function that will be called if there is any error in the file upload.
childrenReact Node(JSX)NoYou can pass any valid React node that will be used as a trigger to open the component.
entryPointStringNoThe initial active step when the component loads. Default entry point is LOCAL_FILES. More integrations are upcoming.
maxFileSizeNumberNoMaximum file size in bytes that is allowed to be uploaded. Defaults to 10 MB
tagsObjectNoAny additional data you want to associate with the component’s state, such as an app ID.
enabledIntegrationsdictNoLet’s you choose which 3rd party integrations to show. See below for more details about this prop
primaryBackgroundColorStringNoThe primary background color of the component. Defaults to #000000.
primaryTextColorStringNoThe primary text color of the component. Defaults to #FFFFFF.
secondaryBackgroundColorStringNoThe secondary background color of the component. Defaults to #FFFFFF.
secondaryTextColorStringNoThe secondary text color of the component. Defaults to #000000.
allowMultipleFilesBooleanNoWhether or not to allow multiple files to be uploaded at once. Defaults to false.
chunkSizeNumberNoThe no.of tokens per chunk. Defaults to 1500.
overlapSizeNumberNoThe no.of tokens to overlap between chunks. Defaults to 20.
openBooleanNoWhether or not to open the component. Defaults to false.
setOpenFunctionNoA function that will be called to set the open state of the component. Defaults to None.
alwaysOpenBooleanNoWhether or not to always keep the component open. Defaults to false.
tosURLStringNoA URL to your organization’s terms of service. Defaults to https://carbon.ai/terms.
privacyPolicyURLStringNoA URL to your organization’s privacy policy. Defaults to https://carbon.ai/privacy.
navigateBackURLStringNoA URL to your intended destination. Defaults to None.
backButtonTextStringNoThe label that you want to show on the back button. Defaults to Go back.
zIndexNumberNoUpdate the z-index of the Carbon Connect modal.
enableToastsBooleanNoSetting to false disables Toast notifications by default in Carbon Connect.
embeddingModelStringNoSpecifies the embedding model used for the integration. The options are OPENAI, AZURE_OPENAI, or COHERE_MULTILINGUAL_V3 for text and audio files, and VERTEX_MULTIMODAL for image files.
filePickerModeStringNoSpecifies whether users can locally upload files, folders, or both. The options are FILES, FOLDERS, or BOTH.
prependFilenameToChunksStringNoAdds the file title to each chunk. Defaults to false.
showFilesTabBooleanNoShows the files tab in Carbon Connect 2.0. Defaults to true.
useRequestIdsStringNoA request_id will be assigned to the uploaded files in that session.

When you do not pass open or setOpen, Carbon Connect will manage the open state internally. If you pass open and setOpen, you will have to manage the open state yourself.

Usage


This section demonstrates how to integrate the Carbon Connect component within a Next.js project.

Client Side Configuration

1. Import Libraries and Components:

import { CarbonConnect } from 'carbon-connect';
import axios from 'axios';

2. Token Retrieval:

The tokenFetcher function is set up to request access tokens from Carbon directly via your backend:

const tokenFetcher = async () => {
  const response = await axios.get('/api/auth/fetchCarbonTokens', {
    params: { customer_id: 'your_customer_id' },
  });
  return response.data; // Must return data containing access_token
};

In the example above, tokenFetcher is a helper function that retrieves the necessary tokens for authentication. This function should be implemented in your client-side code and is designed to make a request to an API on your backend server. The API then requests tokens from the Carbon token creation endpoint. The Carbon token creation endpoint is a secure endpoint that requires a valid API key and customer ID. The customer ID is a unique identifier for your end-user, and you can pass any string as the customer ID. The API key is a secret key provided to you by Carbon. Please contact us to obtain your API key.

3. Implement Carbon Connect Component:

Here’s a concise usage example. Customize according to your requirements:

<CarbonConnect
  orgName="Your Organization"
  brandIcon="path/to/your/brand/icon"
  embeddingModel= 'OPENAI'
  tokenFetcher={tokenFetcher}
  tags={{
    tag1: 'tag1_value',
    tag2: 'tag2_value',
    tag3: 'tag3_value',
  }}
  maxFileSize={10000000}
  enabledIntegrations={[
    {
      id: 'LOCAL_FILES',
      chunkSize: 100,
      overlapSize: 10,
      maxFileSize: 20000000,
      allowMultipleFiles: true,
      maxFilesCount: 5,
      allowedFileTypes: [
        {
          extension: 'csv',
          chunkSize: 1200,
          overlapSize: 120,
          embeddingModel: 'OPENAI',
        },
        {
          extension: 'txt',
          chunkSize: 1599,
          overlapSize: 210,
          embeddingModel: 'AZURE_OPENAI',
        },
        {
          extension: 'pdf',
        },
      ],
    },
    {
      id: 'NOTION',
      chunkSize: 1500,
      overlapSize: 20,
      embeddingModel: 'OPENAI',
    },
    {
      id: 'WEB_SCRAPER',
      chunkSize: 1500,
      overlapSize: 20,
    },
    {
      id: 'GOOGLE_DRIVE',
      chunkSize: 1000,
      overlapSize: 20,
    },
  ]}
  onSuccess={(data) => console.log('Data on Success: ', data)}
  onError={(error) => console.log('Data on Error: ', error)}
  primaryBackgroundColor="#F2F2F2"
  primaryTextColor="#555555"
  secondaryBackgroundColor="#f2f2f2"
  secondaryTextColor="#000000"
  allowMultipleFiles={true}
  open={true}
  chunkSize={1500}
  overlapSize={20}
  // entryPoint="LOCAL_FILES"
></CarbonConnect>

4. Specify an Embedding Model (Optional)

If you are using Carbon to generate embeddings, in the Carbon Connect component, the specification of an embedding model (view available models) can be set at different levels:

Global Level: Here, the Embedding Model (embeddingModel) prop applies universally across the entire system or application. It serves as the default unless overridden at other levels.

Per Connector Level: This setting applies to a specific connector (ie: Google Drive), allowing customization for a particular connector’s behavior, which takes precedence over the global setting for that connector.

Per File Type Level: The most specific setting, it applies at the individual file level, allowing granular control over embedding models for particular file types. This setting supersedes both connector and global settings, providing the highest priority. This is applicable for local file uploads only.

The order of precedence is: File Level > Connector Level > Global Level. Meaning, if a specific embedding model is defined at the file level, it takes priority over the connector-level setting, and the connector-level setting takes priority over the global setting. We default to OPENAI if no value is provided.

Server Side Configuration

Your backend should handle token requests like this:

const response = await axios.get('https://api.carbon.ai/auth/v1/access_token', {
  headers: {
    'Content-Type': 'application/json',
    'customer-id': '<YOUR_USER_UNIQUE_IDENTIFIER>',
    authorization: 'Bearer <YOUR_API_KEY>',
  },
});
if (response.status === 200 && response.data) {
  res.status(200).json(response.data);
}

Return Value

Ensure that your tokenFetcher returns an object structured as:

{
  access_token: string;
}

Enabling Connectors


You can enable connectors users can access via the enabledIntegrations property. The property also allows additional configuration per connector.

Here’s the list of connectors available for activation:

Callback Function Props


onSuccess

Responds to successful events: file upload, 3rd party account connection, file selection, and web scraping initiation.

Event Types

  1. INITIATE: This event type is triggered when a user enters the integration flow (either for auth or file selection)
  2. ADD: This event type is triggered when a user authenticates an account under an integration.
  3. UPDATE: This event type is triggered when a user adds or removes files for an integration. We’ll list the files added or removed.
  4. CANCEL: This event type is triggered when when a user exits the integration flow without taking any action.

Callback Response

The data passed to the onSuccess callback prop will be:

LOCAL_FILES:

{
  status: 200,
  data: {
    "data_source_external_id": null, // This field is not applicable for local files
    "sync_status": null, // This is not applicable for local files
    "files": <Array of objects corresponding to the files uploaded>, (Refer to the file object format below)
  },
  action: 'UPDATE'
  event: 'UPDATE'
  integration: 'LOCAL_FILES',
}

WEB_SCRAPER:

{
  status: 200,
  data: {
    "data_source_external_id": null, // This field is not applicable for webscrapers
    "sync_status": null, // This is not applicable for webscrapers
    "files": <Array of objects corresponding to the parent URLs submitted>, (Refer to the file object format below)
  },
  action: 'UPDATE'
  event: 'UPDATE'
  integration: 'WEB_SCRAPER',
}

3rd Party Connectors

{
  status: 200,
  data: {
    "data_source_external_id": <Unique ID for the data source>,
    "sync_status": <SYNC_STATUS>,
    "files": <Array of objects corresponding to the files / pages selected>,
  } or null,
  action: <ACTION_TYPE>, // `ACTION_TYPE` can be one of the following: `INITIATE`, `ADD`, `UPDATE`, `CANCEL`
  event: <EVENT_TYPE>, // `EVENT_TYPE` can be one of the following: `INITIATE`, `ADD`, `UPDATE`, `CANCEL`
  integration: <INTEGRATION_NAME>, // `INTEGRATION_NAME` can be one of the following: `LOCAL_FILES`, `NOTION`, `WEB_SCRAPER`, `GOOGLE_DRIVE`, `INTERCOM`, `DROPBOX`, `ONEDRIVE`,`BOX`
}

Each files object follows this format:

{
    "id": `Unique ID for the file, can be used for resyncing, deleting, updating tags etc.`,
    "source": `<integration_name>`, // One among `LOCAL_FILES`, `NOTION`, `WEB_SCRAPER`, `GOOGLE_DRIVE`, `INTERCOM`, `DROPBOX`, `ONEDRIVE`
    "organization_id": `<organization_id>`, // This is your unique organization id in carbon
    "organization_supplied_user_id": `<organization_supplied_user_id>`, // This is the unique user id that you pass to CC
    "organization_user_data_source_id": `<organization_user_data_source_id>`, // This is the unique user data source id that Carbon Connect creates for each user for each integration
    "external_file_id": `<external_file_id>`, // This is the unique file id in the 3rd party integration
    "external_url": `<external_url>`, // This is the unique url of the file in the 3rd party integration
    "sync_status": `<sync_status>`, // This is the sync status of the file. It can be one of the following: `READY`, `QUEUED_FOR_SYNCING`, `SYNCING`, `SYNC_ERROR`
    "last_sync": `<last_sync>`, // This is the timestamp of the last sync
    "tags": `<tags>`, // These are the tags passed in to CC
    "file_statistics": `<file_statistics>`, // This is the file statistics object
    "file_metadata": `<file_metadata>`, // This is the file metadata object
    "chunk_size":   `<chunk_size>`, // This is the chunk size used for the file
    "chunk_overlap": `<chunk_overlap>`, // This is the chunk overlap used for the file
    "name": `<name>`, // This is the name of the file
    "enable_auto_sync": `<enable_auto_sync>`, // This is the auto sync status of the file. This is a boolean flag
    "presigned_url": `<presigned_url>`, // This is the presigned url of the file
    "parsed_text_url": `<parsed_text_url>`, // This is the parsed text url of the file
    "skip_embedding_generation": `<skip_embedding_generation>`, // This is the skip embedding generation status of the file. This is a boolean flag
    "created_at": `<created_at>`, // This is the timestamp of the file creation
    "updated_at": `<updated_at>`, // This is the timestamp of the file updation
    "action": `<action>`, // This is the action type. It can be one of the following: `ADD`, `UPDATE`, `REMOVE`
}

onError

Triggered during file upload errors.

Structure:

{
  status: 400,
  action: 'UPDATE',
  event: 'UPDATE',
  integration: `<INTEGRATION_NAME>`, // 'LOCAL_FILES' or 'WEB_SCRAPER',
  data: `<data_object>`, // This field will be present only if the error is related to a file or web scraper
}