Nuclia JavaScript SDK

The Nuclia SDK is an open-source library wrapping the Nuclia API in order to integrate the Nuclia services in your frontend or NodeJS application.

It supports both JavaScript and TypeScript.

We document here all the objects and methods offered by the SDK.

If you are looking for a step-by-step guide to integrate Nuclia in your application, please refer to the SDK guide.

`Nuclia`

Constructor

new Nuclia(options)

Depending on your use case, you might want to:

use the Nuclia SDK to access and manage a Nuclia account, in that case, you will need to provide the backend and account options, and you will use account authentication.
use the Nuclia SDK to use a Nuclia KnowledgeBox, in that case, you will need to provide the backend, knowledgeBox and zone options, and you will use knowledge box authentication or no authentication if the knowledge box is public.

Input:

options: Object

backend: String The Nuclia backend to use. Example: https://nuclia.cloud/api
account: String (optional) The Nuclia account slug. Example: my-account
knowledgeBox: String (optional) The Nuclia knowledge box unique id. Example: 17815eb2-06a5-40ee-a5aa-b2f9dbc5da70
kbSlug: String (optional) The knowledge box slug. Example: my-kb
zone: String (optional) The geographical zone for the regional API calls. Example: europe-1
apiKey: String (optional) Allows to make calls to a private Knowledge Box. It can be used in a server-side app, but never in a web app.

Output:

A Nuclia instance.

Example:

const nuclia = new Nuclia({
  backend: 'https://nuclia.cloud/api',
  knowledgeBox: '17815eb2-06a5-40ee-a5aa-b2f9dbc5da70',
  zone: 'europe-1',
});

Properties

knowledgeBox: Direct access to the current knowledge box instance (it returns a knowledge box in read mode, and it does not work with account authentication)
asyncKnowledgeBox: Similar to the previous property, but the returned object exposes Promises instead of RxJS Observables.
auth: Allows to authenticate using username/password or using an API key.
db: Allows to access and query the Nuclia database.
rest: Allows to make authenticated REST requests to the Nuclia backend.
backend: the Nuclia backend URL.
regionalBackend: the Nuclia regional backend URL.
options: the Nuclia options.

`Nuclia.auth`

Nuclia.auth manages the authentication to the Nuclia backend. It can be based on login/password for account authentication, or on an API key for private knowledge box authentication. Authentication is not needed when using a public knowledge box.

Methods

`authenticate(tokens: AuthTokens)`

Returns a boolean if successful. Stores authentication tokens in localStorage and triggers isAuthenticated. This method is automatically called when using login. It can be useful when using a custom authentication flow.

Example:

nuclia.auth.authenticate(tokens);

`deleteAuthenticatedUser()`

Deletes current user account and remove stored tokens.

Output: Observable<void>

Example:

nuclia.auth.deleteAuthenticatedUser().subscribe(() => {
  console.log('User deleted');
});

`getAuthHeaders()`

Returns the authentication header (which will be Authorization for account authentication, or X-STF-Serviceaccount for private knowledge box authentication).

Output: { [key: string]: string }

Example:

const headers = nuclia.auth.getAuthHeaders();

`getJWTUser()`

Parses JWT token and returns corresponding user information.

Output: JwtUser | null

Example:

const user = nuclia.auth.getJWTUser();
console.log(`Hello ${user?.ext.first_name}!`);

`getRefreshToken()`

Returns refresh token stored in localStorage.

Output: string

Example:

const refreshToken = nuclia.auth.getRefreshToken();

`getToken()`

Returns authentication token stored in localStorage.

Output: string

Example:

const token = nuclia.auth.getToken();

`hasLoggedOut()`

Returns an Observable emitting when the user has logged out.

Output: Observable<boolean>

Example:

nuclia.auth.hasLoggedOut().subscribe((loggedOut) => {
  if (loggedOut) {
    // do something
  }
});

`isAuthenticated()`

Emits when the authentication status changes.

Output: Observable<boolean>

Example:

nuclia.auth.isAuthenticated().subscribe((isAuthenticated) => {
  if (isAuthenticated) {
    console.log('You are authenticated');
  } else {
    console.log('You are not authenticated');
  }
});

`login(username: string, password: string, validation?: string)`

Calls the login endpoint for account authentication and emits when done.

It can optionally take a reCaptcha validation code if the Nuclia backend requires it. Once authenticated, the Nuclia SDK will periodically refresh the token before it expires.

Output: Observable<boolean>

Example:

nuclia.auth.login(username, password).subscribe({
  next: (success) => {
    this.loginError = success ? '' : 'Error';
    console.log('logged in', success);
  },
  error: (error) => {
    this.loginError = 'Error';
    console.error(error);
  },
  complete: () => {
    this.pending = false;
  },
});

`logout()`

Calls the logout endopint and remove the token stored in localstorage.

Example:

nuclia.auth.logout();

`setPassword(password: string)`

Sets current user's password.

Output: Observable<boolean>

Example:

nuclia.auth.setPassword(password).subscribe({
  next: (success) => {
    this.passwordError = success ? '' : 'Error';
    console.log('password set', success);
  },
  error: (error) => {
    this.passwordError = 'Error';
    console.error(error);
  },
  complete: () => {
    this.pending = false;
  },
});

`Nuclia.db`

Nuclia.db allows to access the Nuclia accounts and/or the Nuclia knowledge boxes.

Methods

`createKnowledgeBox(account: string, knowledgeBox: KnowledgeBoxCreation)`

Creates a new knowledge box.

Output: Observable<WritableKnowledgeBox>

It requires account authentication.

Parameters:

account: the account slug.
knowledgeBox: the knowledge box creation object
- slug: the knowledge box slug, only lowercase letters, numbers, - and _ are allowed.
- title: the knowledge box title.
- description: Optional, the knowledge box description.
- zone: Optional (default to europe-1), the geographical zone for the regional API calls.

Example:

const knowledgeBox = {
  slug: 'my-kb',
  title: 'My knowledge box',
};
nuclia.db.createKnowledgeBox('my-account', knowledgeBox).subscribe((knowledgeBox) => {
  console.log('knowledge box', knowledgeBox);
});

`createAccount(account: AccountCreation)`

Creates a new account.

Output: Observable<Account>

It requires account authentication.

Parameters:

slug: the account slug. A slug can contain only lowercase letters, numbers, - and _.
title: the account title.
description: the account description (optional).
email: owner's email (optional).
zone: the geographical zone (optional).

Example:

nuclia.db.createAccount({ slug: 'my-account', title: 'my-account' }).subscribe((account) => {
  console.log('account', account);
});

`deleteAccount(account: string)`

Deletes an account.

Output: Observable<void>

It requires account authentication.

Example:

nuclia.db.deleteAccount('my-account').subscribe(() => {
  console.log('account deleted');
});

`deleteNUAClient(account: string, client_id: string)`

Deletes a NUA client.

It requires account authentication.

Output: Observable<void>

`getAccount()`

Returns the account defined in the Nuclia options.

Output: Observable<Account>

It requires account authentication.

Example:

nuclia.db.getAccount().subscribe((account) => {
  console.log('account', account);
});

`getAccount(account?: string)`

Returns the account with the given slug.

Output: Observable<Account>

It requires account authentication.

Example:

nuclia.db.getAccount('my-account').subscribe((account) => {
  console.log('account', account);
});

`getAccounts()`

Returns a list of all the accounts.

Output: Observable<Account[]>

It requires account authentication.

Example:

nuclia.db.getAccounts().subscribe((accounts) => {
  console.log('accounts', accounts);
});

`getAccountStatus(account: string)`

Returns account status.

Output: Observable<AccountStatus> ({ available: boolean })

Example:

nuclia.db
  .getAccountStatus('my-account')
  .pipe(filter((status) => status.available))
  .subscribe((status) => {
    console.log('account ready');
  });

`getKnowledgeBox()`

Returns the knowledge box defined in the Nuclia options.

Output: Observable<WritableKnowledgeBox>

Example:

nuclia.db.getKnowledgeBox().subscribe((knowledgeBox) => {
  console.log('knowledge box', knowledgeBox);
});

`getKnowledgeBox(account: string, knowledgeBox: string)`

Returns the knowledge box with the given slug.

Output: Observable<WritableKnowledgeBox>

It requires account authentication.

Example:

nuclia.db.getKnowledgeBox('my-account', 'my-kb').subscribe((knowledgeBox) => {
  console.log('knowledge box', knowledgeBox);
});

`getKnowledgeBoxes(account: string)`

Returns a list of all the knowledge boxes for the given account.

Output: Observable<WritableKnowledgeBox[]>

It requires account authentication.

Example:

nuclia.db.getKnowledgeBoxes('my-account').subscribe((knowledgeBoxes) => {
  console.log('knowledge boxes', knowledgeBoxes);
});

`getWelcome()`

Returns user information.

Output: Observable<Welcome>

  preferences: {
    last_login?: string;
    email: string;
    name?: string;
    type: UserType;
    language?: Language;
  };
  accounts: string[];
  dependant_accounts: { id: string, slug: string }[];

Example:

nuclia.db.getWelcome().subscribe((welcome) => {
  console.log(`Welcome ${welcome.preferences.name}`);
});

`modifyAccount(account: string, data: Partial<Account>)`

Modifies account properties.

Output: Observable<void>

It requires account authentication.

Example:

nuclia.db.modifyAccount('my-account', { title: 'My account' }).subscribe({
  next: () => {
    console.log('account modified');
  },
  error: (error) => {
    console.error(error);
  },
});

`upload(file: FileWithMetadata)`

Uploads and push a file to Nuclia Understanding API.

It requires a NUA token.

Parameters:

FileWithMetadata: the file to upload. FileWithMetadata is an extension of File with the following properties:
- md5: the file md5 (optional).
- payload: not applicable with Nuclia Understanding API (optional).

Output: Observable<ProcessingPushResponse>

ProcessingPushResponse {
  seqid: number;
  uuid: string;
}

Example:

const file = input.files[0];
nuclia.db.upload(file).subscribe({
  next: (response) => {
    console.log('file uploaded', response);
  },
  error: (error) => {
    console.error(error);
  },
});

`pull()`

Pulls the latest data from Nuclia Understanding API.

It requires a NUA token.

Output: Observable<ProcessingPullResponse>

ProcessingPullResponse {
  status: string;
  payload?: string; // protobuf base64 encoded
  msgid?: string;
}

See @nuclia/protobuf

`createNUAClient(account: string, data: NUAClientPayload)`

Creates a NUA client and a NUA token.

It requires account authentication.

Parameters:

account: the account slug.
data: the NUA client payload:

{
  client_id?: string;
  contact: string;
  description?: string;
  title: string;
  webhook?: string;
}

Output: Observable<{client_id: string; token: string}>

Example:

nuclia.db
  .createNUAClient('my-account', {
    contact: 'me@here.net',
    client_id: 'my-laptop',
  })
  .subscribe((response) => {
    console.log('NUA client created', response.token);
  });

`renewNUAClient(account: string, client_id: string)`

Renews a NUA token.

It requires account authentication.

Output: Observable<{client_id: string; token: string}>

`Nuclia.rest`

Nuclia.rest handles the elementary REST requests to the Nuclia backend, setting the appropriate HTTP headers.

On POST, PUT, PATCH and DELETE, synchronous parameter will make the call synchronous, meaning the response will be returned only when the operation is fully completed. It is false by default.

Methods

In the following methods, extraHeaders is an optional parameter that can be used to add headers to the request. The default headers set by Nuclia.rest are:

'content-type': 'application/json',
Authorization or X-STF-Serviceaccount depending on the type of authentication. The default headers will be overridden by the extraHeaders ones if they have the same entries.

doNotParse is a boolean that can be used to disable the automatic JSON parsing of the response.

`get<T>(path: string, extraHeaders?: { [key: string]: string }, doNotParse?: boolean)`

Performs a GET request to the Nuclia backend.

Output: Observable<T>

`post<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

Performs a POST request to the Nuclia backend.

Output: Observable<T>

`put<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

Performs a PUT request to the Nuclia backend.

Output: Observable<T>

`patch<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

Performs a PATCH request to the Nuclia backend.

Output: Observable<T>

`delete(path: string, extraHeaders?: { [key: string]: string }, synchronous?: boolean)`

Performs a DELETE request to the Nuclia backend.

Output: Observable<void>

`head(path: string, extraHeaders?: { [key: string]: string })`

Performs a HEAD request to the Nuclia backend.

Output: Observable<Response>

`getFullUrl(path: string)`

Returns the full URL of the given path, using the regional or the global Nuclia backend according the path.

Output: string

Example:

nuclia.rest.getFullUrl('/account/my-account');
// https://nuclia.cloud/api/v1/account/my-account

`getObjectURL(filePath: string)`

Downloads the file, converts it to a Blob and returns its blob: URL.

Output: Observable<string>

`getZones()`

Returns a dictionary giving the geographical zones available slugs by unique ids.

Output: Observable<{ [key: string]: string }>

`KnowledgeBox`

Properties

id: the knowledge box unique id.
zone: the geographical zone for the regional API calls.
path: the knowledge box path on the regional API
Example: /v1/kb/3cce4a71-9cb9-4fda-beee-8a1512616bf0
fullpath: the knowledge box fullpath on the regional API
Example: https://europe-1.nuclia.cloud/api/v1/kb/3cce4a71-9cb9-4fda-beee-8a1512616bf0

Methods

`counters()`

Returns total elements stored in the knowledge box.

Output:

Observable<{
  resources: number;
  paragraphs: number;
  fields: number;
  sentences: number;
}>;

`getEntities()`

Returns all the entities groups in the knowledge box.

Output: Observable<Entities>

Entities : {[key: string]: EntitiesGroup}
EntitiesGroup : {title: string; color?: string; entities: { [entityName: string]: Entity }}

An Entity is a dictionary with the following properties:

value: string
merged: optional, boolean
represents: optional, string[]

Example:

nuclia.knowledgeBox.getEntities().subscribe((entities) => {
  console.log('entities', entities);
});

`getEntitiesGroup(groupId: string)`

Returns the entities group with the given id.

Output: Observable<EntitiesGroup> EntitiesGroup : {title: string; color?: string; entities: { [entityName: string]: Entity }}

Example:

nuclia.knowledgeBox.getEntitiesGroup('countries').subscribe((entitiesGroup) => {
  console.log('entities group', entitiesGroup);
});

`getLabels()`

Returns all the labels in the knowledge box.

Output: Observable<Labels>

Labels : {[key: string]: LabelSet}
LabelSet : {title: string; color?: string; labels: Label[]}
Label : {title: string; related?: string; text?: string; uri?: string;}

Example:

nuclia.knowledgeBox.getLabels().subscribe((labels) => {
  console.log('labels', labels);
});

`getResource(uuid: string, show: ResourceProperties[], extracted: ExtractedDataTypes[])`

Retrieve a resource from the knowledge box.

Parameters:

uuid: the resource uuid.
show: optional, ResourceProperties[]. It defines which properties are returned. Default takes all the properties:
- ResourceProperties.BASIC
- ResourceProperties.ORIGIN
- ResourceProperties.RELATIONS
- ResourceProperties.VALUES
- ResourceProperties.EXTRACTED
- ResourceProperties.ERRORS
extracted: optional, ExtractedDataTypes[]. It defines which extracted data are returned (it is ignored if ResourceProperties.EXTRACTED is not in the returned properties). Default takes the following:
- ExtractedDataTypes.TEXT
- ExtractedDataTypes.METADATA
- ExtractedDataTypes.LINK
- ExtractedDataTypes.FILE
Other possible values are ExtractedDataTypes.LARGE_METADATA and ExtractedDataTypes.VECTOR (Note: they might significantly increase the response size).

Output: Observable<IResource>

Example:

nuclia.db
  .getKnowledgeBox()
  .pipe(switchMap((knowledgeBox) => knowledgeBox.getResource('09a94719a6444c5a9689394f6ed9baf6')))
  .subscribe((resource) => {
    console.log('resource', resource);
  });

`getTempToken()`

Returns an ephemeral token. It is useful when displaying a clickable link to a file.

Output: string

Example:

const downloadLink = `${nuclia.rest.getFullpath(filePath)}?eph-token=${nuclia.knowledgeBox.getTempToken()}`;

`listResources(page?: number, size?: number)`

List all the resources stored in the knowledge box.

Output: Observable<ResourceList>

ResourceList {
  resources: Resource[];
  pagination: ResourcePagination;
}

`search(query: string, features: Search.Features[], options?: SearchOptions)`

Performs a search in the knowledge box.

Parameters:

query: the search query.
features: optional, Search.Features[]. It defines which features are returned in each result. Default is []. Possible values are:
- PARAGRAPH
- DOCUMENT
- RELATIONS
- VECTOR
options: optional
- highlight: boolean. If true, the matching words are marked in paragraphs text. Default is false (optional).
- inTitleOnly: boolean. If true, the search is performed only in the title. Default is false (optional).

Output: Observable<SearchResult>

Example:

nuclia.knowledgeBox
  .search('where does the Little Prince live', [Search.Features.PARAGRAPH])
  .subscribe((searchResult) => {
    console.log('search result', searchResult);
  });

`suggest(query: string)`

Suggests paragraphs based on the given query.

Output: Observable<{error?: boolean; paragraphs?: Paragraphs;}[]>

`getWidgets()`

Returns all the widgets in the knowledge box.

Output: Observable<Widgets>

Widgets: {[key: string]: Widget}
Widget:
- id: string
- mode: 'button' | 'input' | 'form'`
- description: optional, string`
- features: { useFilters: boolean; suggestEntities: boolean; suggestSentences: boolean; suggestParagraphs: boolean; }
- filters: optional, string[]
- topEntities: optional, string[]
- style: optional, { [key: string]: string }

Example:

nuclia.knowledgeBox.getWidgets().subscribe((widgets) => {
  console.log('widgets', widgets);
});

`getWidget(widgetId: string)`

Returns the widget with the given id.

Output: Observable<Widget>

Example:

nuclia.knowledgeBox.getWidget('my-widget').subscribe((widget) => {
  console.log('widget', widget);
});

`WritableKnowledgeBox`

It extends KnowledgeBox with the following properties and methods:

Properties

slug: knowledge box slug.
title: knowledge box title.
state: 'PUBLISHED' or 'PRIVATE'
description: knowledge box description.
admin: boolean, true if the current user is an administrator of the knowledge box.
contrib: boolean, true if the current user is a contributor.

Methods

`modify(data: Partial<IKnowledgeBox>)`

Modify the knowledge box properties.

It requires account authentication.

Output: Observable<void>

Example:

nuclia.db.getKnowledgeBox("my-account", "my-kb").pipe(
  switchMap((knowledgeBox) => knowledgeBox.modify({title: "My new title"}),
).subscribe(() => {
  console.log("knowledge box modified");
});

`publish(published: boolean)`

Publish or unpublish the knowledge box.

It requires account authentication.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.publish(true)))
  .subscribe(() => {
    console.log('knowledge box published');
  });

`delete()`

Delete the knowledge box.

It requires account authentication.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.delete()))
  .subscribe(() => {
    console.log('knowledge box deleted');
  });

`setEntitiesGroup(groupId: string, group: EntitiesGroup)`

Add or modify the entities group with the given id.

It requires account authentication or an API key with contributor access.

Parameters:

groupId: the entities group id.
group:
- title: string
- color: optional, string
- entities: { [entityName: string]: Entity }

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.setEntitiesGroup('countries', {
        title: 'Countries',
        color: '#ff0000',
        entities: {
          fr: { value: 'France' },
          de: { value: 'Germany' },
          it: { value: 'Italy' },
        },
      }),
    ),
  )
  .subscribe(() => {
    console.log('entities group set');
  });

`deleteEntitiesGroup(groupId: string)`

Delete an entities group.

It requires account authentication or an API key with contributor access.

Parameters:

groupId: the entities group id.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.deleteEntitiesGroup('countries')))
  .subscribe(() => {
    console.log('entities group deleted');
  });

`setLabelSet(setId: string, labelSet: LabelSet)`

Add or modify the label set with the given id.

It requires account authentication or an API key with contributor access.

Parameters:

setId: the label set id.
labelSet:
- title: string
- color: optional, string
- labels: {title: string; related?: string; text?: string; uri?: string;}[]

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.setLabelSet('status', {
        title: 'Status',
        color: '#ff0000',
        labels: [{ title: 'Major' }, { title: 'Minor' }, { title: 'Critical' }],
      }),
    ),
  )
  .subscribe(() => {
    console.log('label set set');
  });

`deleteLabelSet(setId: string)`

Delete a label set.

It requires account authentication or an API key with contributor access.

Parameters:

setId: the label set id.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.deleteLabelSet('status')))
  .subscribe(() => {
    console.log('label set deleted');
  });

`createResource(resource: ICreateResource)`

Create and index a new resource in the knowledge box.

It requires account authentication or an API key with contributor access.

Parameters:

TO BE COMPLETED

title: optional, string
summary: optional, string
icon: optional, string
metadata: optional, Metadata
usermetadata: optional, UserMetadata
origin: optional, Origin
files: optional, { [key: string]: FileField }
links: optional, { [key: string]: LinkField }
texts: optional, { [key: string]: TextField }

Output: Observable<{ uuid: string }>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.createResource({
        title: 'My new resource',
        summary: 'This is my new resource',
      }),
    ),
  )
  .subscribe(() => {
    console.log('resource created');
  });

`createLinkResource(link: LinkField, metadata?: UserMetadata)`

Create a new link resource in the knowledge box in a simpler way than using createResource.

It requires account authentication or an API key with contributor access.

Parameters:

link:
- added: optional, string
- headers: optional, { [id: string]: string }
- cookies: optional, { [id: string]: string }
- uri: optional, string
- localstorage: optional, { [id: string]: string }
metadata: optional, UserMetadata

Output: Observable<{ uuid: string }>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.createLinkResource(
        {
          uri: 'https://en.wikipedia.org/wiki/Hedy_Lamarr',
        },
        { classifications: [{ labelset: 'Genius', label: 'Inventor' }] },
      ),
    ),
  )
  .subscribe(() => {
    console.log('resource created');
  });

`saveWidget(id: string, widget: Partial<Widget>)`

Add or modify the widget with the given id.

It requires account authentication or an API key with contributor access.

Parameters:

id: string
widget:
- id: string
- mode: 'button' | 'input' | 'form'`
- description: optional, string`
- features: { useFilters: boolean; suggestEntities: boolean; suggestSentences: boolean; suggestParagraphs: boolean; }
- filters: optional, string[]
- topEntities: optional, string[]
- style: optional, { [key: string]: string }

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.saveWidget('my-widget', {
        mode: 'button',
        features: {
          useFilters: true,
          suggestEntities: true,
          suggestSentences: true,
          suggestParagraphs: true,
        },
      }),
    ),
  )
  .subscribe(() => {
    console.log('widget saved');
  });

`deleteWidget(widgetId: string)`

Delete the widget with the given id.

It requires account authentication or an API key with contributor access.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.deleteWidget('my-widget')))
  .subscribe(() => {
    console.log('widget deleted');
  });

`upload(data: File | ArrayBuffer, TUS?: boolean, metadata?: FileMetadata)`

Upload a file to the knowledge box. It automatically creates a new resource to store the file. The resource path is returned in the resource property of the UploadResult (and field provides the path to the FileField).

It requires account authentication or an API key with contributor access.

Parameters:

data: the file to upload. It can be either a File object (as provided by an HTML input file element) or an ArrayBuffer object.
TUS: optional, boolean. If true, the file will be uploaded using the TUS protocol. Default is false.
metadata: optional, FileMetadata. It defines the file metadata. It can contain the following properties:
- contentType: string
- filename: string

Output: Observable<UploadResponse>

An UploadResponse object might contain the following properties:

resource: string
field: string
progress: number (percentage)
failed: boolean
completed: boolean

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.upload(fileInputElement.files[0])))
  .subscribe(() => {
    console.log('file uploaded');
  });

`batchUpload(files: FileList | File[], creationPayload?: ICreateResource)`

Upload a list of files to the knowledge box. It automatically creates a new resource for each file. It uses the TUS protocol to upload the files.

It requires account authentication or an API key with contributor access.

Parameters:

files: a list of files to upload. It can be either a FileList object (as provided by an HTML input multiple file element), or a list of File.
creationPayload: optional, ICreateResource. It defines the default payload to create the resources that will contains the files.

Output: Observable<{ progress: number; completed: boolean; uploaded: number; failed: number }>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(switchMap((knowledgeBox) => knowledgeBox.upload(fileInputElement.files[0])))
  .subscribe((res) => {
    if (res.completed) {
      console.log(`Uploaded completed, ${res.uploaded} files uploaded, ${res.failed} failed`);
    } else {
      console.log('upload progress', res.progress);
    }
  });

`Resource`

A resource allows to store content in the knowledge box. A single resource might contain several fields.

Fields have different types: files, links, texts, conversations, etc. (TO BE COMPLETED)

Properties

uuid: string
kb: parent knowledge box

Methods

Constructor

new Resource(nuclia: INuclia, kb: string, uuid: string, data: IResource)

Usually, you don't need to create a Resource object yourself. It is returned by the getResource method of the KnowledgeBox object.

`addField(type: FIELD_TYPE, field: string, data: TextField | LinkField | FileField | KeywordSetField)`

Adds a field to the resource.

It requires account authentication or an API key with contributor access.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) =>
      knowledgeBox.getResource('my-resource').pipe(
        switchMap((resource) =>
          resource.addField(FIELD_TYPE.text, 'my-field', {
            body: '*my text*',
            format: 'MARKDOWN',
          }),
        ),
      ),
    ),
  )
  .subscribe(() => {
    console.log('field added');
  });

`delete()`

Delete the resource.

It requires account authentication or an API key with contributor access.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) => knowledgeBox.getResource('my-resource')),
    switchMap((resource) => resource.delete()),
  )
  .subscribe(() => {
    console.log('resource deleted');
  });

`deleteField(type: FIELD_TYPE, field: string)`

Deletes the field with the given type and name.

It requires account authentication or an API key with contributor access.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) => knowledgeBox.getResource('my-resource')),
    switchMap((resource) => resource.deleteField(FIELD_TYPE.text, 'my-field')),
  )
  .subscribe(() => {
    console.log('field deleted');
  });

`getField(type: FIELD_TYPE, field: string)`

Gets a field of the resource.

Output: Observable<ResourceField>

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getField(FIELD_TYPE.text, 'my-field')))
  .subscribe((field) => {
    console.log('field', field);
  });

`getFields()`

Return all the fields contained in the resource.

Output: Observable<IFieldData[]>

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getFields()))
  .subscribe((fields) => {
    console.log('fields', fields);
  });

`getExtractedSummaries()`

Return the summaries generated by Nuclia for each resource field.

Output: string[]

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getExtractedSummaries()))
  .subscribe((summaries) => {
    console.log('summaries', summaries);
  });

`getExtractedTexts()`

Return the texts generated by Nuclia for each resource field.

Output: ExtractedText[].

An ExtractedText object might contain the following properties:

text: string
split_text: { [id: string]: string }
deleted_splits: string[]

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getExtractedTexts()))
  .subscribe((extractedTexts) => {
    console.log('extractedTexts', extractedTexts);
  });

`getFiles()`

Return the files contained in the resource.

Output: CloudLink[]

A CloudLink object might contain the following properties:

uri: string
size: number
content_type: string

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getFiles()))
  .subscribe((files) => {
    console.log('files', files);
  });

`getNamedEntities()`

Return the entities extracted from the resource.

Output: { [key: string]: string[] }

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getNamedEntities()))
  .subscribe((entities) => {
    console.log('entities', entities);
  });

`getThumbnails()`

Returns the thumbnails generated by Nuclia for each resource field.

Output: CloudLink[]

CloudLink {
  uri?: string;
  size?: number;
  content_type?: string;
}

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(map((resource) => resource.getThumbnails()))
  .subscribe((thumbnails) => {
    console.log('thumbnails', thumbnails);
  });

`getThumbnailsUrl()`

Returns the thumbnails generated by Nuclia for each resource field as blob: URLs.

Output: Observable<string[]>

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(switchMap((resource) => resource.getThumbnailsUrl()))
  .subscribe((thumbnails) => {
    container.innerHtml = thumbnails.map((thumbnail) => `<img src="${thumbnail}" />`).join('');
  });

`modify(data: Partial<IResource>)`

Modifies the resource attributes.

It requires account authentication or an API key with contributor access.

Output: Observable<void>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) => knowledgeBox.getResource('my-resource')),
    switchMap((resource) => resource.modify({ description: 'new description' })),
  )
  .subscribe(() => {
    console.log('resource modified');
  });

`reprocess()`

Reprocesses the resource.

Output: Observable<void>

`search(query: string, features: Search.ResourceFeatures[] = [], highlight = false)`

Searches in the resource.

Parameters:

query: the search query.
features: Search.ResourceFeatures[] (optional). It defines which features are returned in each result. Default is []. Possible values are:
- PARAGRAPH
- RELATIONS
- VECTOR
- highlight: boolean (optional). If true, the matching words are marked in paragraphs text. Default is false.

Output: Observable<SearchResult>

Example:

nuclia.knowledgeBox
  .getResource('my-resource')
  .pipe(switchMap((resource) => resource.search('my query', [Search.ResourceFeatures.PARAGRAPH])))
  .subscribe((result) => {
    console.log('result', result);
  });

`upload(field: string, data: File | ArrayBuffer, TUS?: boolean, metadata?: FileMetadata)`

Uploads a file in the resource. The field will be stored in the indicated field.

It requires account authentication or an API key with contributor access.

Parameters:

field: string
data: the file to upload. It can be either a File object (as provided by an HTML input file element) or an ArrayBuffer object.
TUS: optional, boolean. If true, the file will be uploaded using the TUS protocol. Default is false.
metadata: optional, FileMetadata. It defines the file metadata. It can contain the following properties:
- contentType: string
- filename: string

Output: Observable<UploadResponse>

An UploadResponse object might contain the following properties:

resource: string
field: string
progress: number (percentage)
failed: boolean
completed: boolean

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) => knowledgeBox.getResource('my-resource')),
    switchMap((resource) => resource.upload(fileInputElement.files[0])),
  )
  .subscribe(() => {
    console.log('file uploaded');
  });

`batchUpload(files: FileList | File[])`

Upload a list of files in teh resource. It automatically creates a new field for each file (named according the filename). It uses the TUS protocol to upload the files.

It requires account authentication or an API key with contributor access.

Parameters:

files: a list of files to upload. It can be either a FileList object (as provided by an HTML input multiple file element), or a list of File.

Output: Observable<{ progress: number; completed: boolean; uploaded: number; failed: number }>

Example:

nuclia.db
  .getKnowledgeBox('my-account', 'my-kb')
  .pipe(
    switchMap((knowledgeBox) => knowledgeBox.getResource('my-resource')),
    switchMap((resource) => resource.upload(fileInputElement.files[0])),
  )
  .subscribe((res) => {
    if (res.completed) {
      console.log(`Uploaded completed, ${res.uploaded} files uploaded, ${res.failed} failed`);
    } else {
      console.log('upload progress', res.progress);
    }
  });

Nuclia JavaScript SDK

Nuclia​

Constructor​

Properties​

Nuclia.auth​

Methods​

authenticate(tokens: AuthTokens)​

deleteAuthenticatedUser()​

getAuthHeaders()​

getJWTUser()​

getRefreshToken()​

getToken()​

hasLoggedOut()​

isAuthenticated()​

login(username: string, password: string, validation?: string)​

logout()​

setPassword(password: string)​

Nuclia.db​

Methods​

createKnowledgeBox(account: string, knowledgeBox: KnowledgeBoxCreation)​

createAccount(account: AccountCreation)​

deleteAccount(account: string)​

deleteNUAClient(account: string, client_id: string)​

getAccount()​

getAccount(account?: string)​

getAccounts()​

getAccountStatus(account: string)​

getKnowledgeBox()​

getKnowledgeBox(account: string, knowledgeBox: string)​

getKnowledgeBoxes(account: string)​

getWelcome()​

modifyAccount(account: string, data: Partial<Account>)​

upload(file: FileWithMetadata)​

pull()​

createNUAClient(account: string, data: NUAClientPayload)​

renewNUAClient(account: string, client_id: string)​

Nuclia.rest​

Methods​

get<T>(path: string, extraHeaders?: { [key: string]: string }, doNotParse?: boolean)​

post<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)​

put<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)​

patch<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)​

delete(path: string, extraHeaders?: { [key: string]: string }, synchronous?: boolean)​

head(path: string, extraHeaders?: { [key: string]: string })​

getFullUrl(path: string)​

getObjectURL(filePath: string)​

getZones()​

KnowledgeBox​

Properties​

Methods​

counters()​

getEntities()​

getEntitiesGroup(groupId: string)​

getLabels()​

getResource(uuid: string, show: ResourceProperties[], extracted: ExtractedDataTypes[])​

getTempToken()​

listResources(page?: number, size?: number)​

search(query: string, features: Search.Features[], options?: SearchOptions)​

suggest(query: string)​

getWidgets()​

getWidget(widgetId: string)​

WritableKnowledgeBox​

Properties​

Methods​

modify(data: Partial<IKnowledgeBox>)​

publish(published: boolean)​

delete()​

setEntitiesGroup(groupId: string, group: EntitiesGroup)​

deleteEntitiesGroup(groupId: string)​

setLabelSet(setId: string, labelSet: LabelSet)​

deleteLabelSet(setId: string)​

createResource(resource: ICreateResource)​

createLinkResource(link: LinkField, metadata?: UserMetadata)​

saveWidget(id: string, widget: Partial<Widget>)​

deleteWidget(widgetId: string)​

upload(data: File | ArrayBuffer, TUS?: boolean, metadata?: FileMetadata)​

batchUpload(files: FileList | File[], creationPayload?: ICreateResource)​

Resource​

Properties​

Methods​

`Nuclia`

Constructor

Properties

`Nuclia.auth`

Methods

`authenticate(tokens: AuthTokens)`

`deleteAuthenticatedUser()`

`getAuthHeaders()`

`getJWTUser()`

`getRefreshToken()`

`getToken()`

`hasLoggedOut()`

`isAuthenticated()`

`login(username: string, password: string, validation?: string)`

`logout()`

`setPassword(password: string)`

`Nuclia.db`

Methods

`createKnowledgeBox(account: string, knowledgeBox: KnowledgeBoxCreation)`

`createAccount(account: AccountCreation)`

`deleteAccount(account: string)`

`deleteNUAClient(account: string, client_id: string)`

`getAccount()`

`getAccount(account?: string)`

`getAccounts()`

`getAccountStatus(account: string)`

`getKnowledgeBox()`

`getKnowledgeBox(account: string, knowledgeBox: string)`

`getKnowledgeBoxes(account: string)`

`getWelcome()`

`modifyAccount(account: string, data: Partial<Account>)`

`upload(file: FileWithMetadata)`

`pull()`

`createNUAClient(account: string, data: NUAClientPayload)`

`renewNUAClient(account: string, client_id: string)`

`Nuclia.rest`

Methods

`get<T>(path: string, extraHeaders?: { [key: string]: string }, doNotParse?: boolean)`

`post<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

`put<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

`patch<T>(path: string, body: any, extraHeaders?: { [key: string]: string }, doNotParse?: boolean, synchronous?: boolean)`

`delete(path: string, extraHeaders?: { [key: string]: string }, synchronous?: boolean)`

`head(path: string, extraHeaders?: { [key: string]: string })`

`getFullUrl(path: string)`

`getObjectURL(filePath: string)`

`getZones()`

`KnowledgeBox`

Properties

Methods

`counters()`

`getEntities()`

`getEntitiesGroup(groupId: string)`

`getLabels()`

`getResource(uuid: string, show: ResourceProperties[], extracted: ExtractedDataTypes[])`

`getTempToken()`

`listResources(page?: number, size?: number)`

`search(query: string, features: Search.Features[], options?: SearchOptions)`

`suggest(query: string)`

`getWidgets()`

`getWidget(widgetId: string)`

`WritableKnowledgeBox`

Properties

Methods

`modify(data: Partial<IKnowledgeBox>)`

`publish(published: boolean)`

`delete()`

`setEntitiesGroup(groupId: string, group: EntitiesGroup)`

`deleteEntitiesGroup(groupId: string)`

`setLabelSet(setId: string, labelSet: LabelSet)`

`deleteLabelSet(setId: string)`

`createResource(resource: ICreateResource)`

`createLinkResource(link: LinkField, metadata?: UserMetadata)`

`saveWidget(id: string, widget: Partial<Widget>)`

`deleteWidget(widgetId: string)`

`upload(data: File | ArrayBuffer, TUS?: boolean, metadata?: FileMetadata)`

`batchUpload(files: FileList | File[], creationPayload?: ICreateResource)`

`Resource`

Properties

Methods

Constructor