Stackspot

Stackspot API bindings for NodeJS.

Content

• Installation
• Usage
  • ⚙ Configuration
  • 🌐 Using behind proxy
• Methods
  • ✨ AI
    • AI - KS - Create a new Knowledge Source
    • AI - KS - Upload new file to a Knowledge Source
    • AI - KS - Remove files from a Knowledge Source
    • AI - Quick Command - Create a new execution
    • AI - Quick Command - Get execution
    • AI - Quick Command - Poll execution until it's done
  • 🗝️ Auth
    • Auth - Get the access token
• License

Installation

To install, simply add the package using npm, yarn, pnpm, etc...

npm install stackspot

Usage

You can start using the global instance:

import { Stackspot } from 'stackspot';

// By default, the global instance will configure itself using the environment variables:
// - STACKSPOT_CLIENT_ID
// - STACKSPOT_CLIENT_SECRET
// - STACKSPOT_REALM

// Creating a new 'Knowledge Source' for example:
await Stackspot.instance.ai.ks.createKs('new-ks-test', 'New KS test', 'This is a test KS', 'CUSTOM');

⚙ Configuration

You can configure the global instance:

// Using the 'config(opts)' method, to update all the settings at once:
Stackspot.instance.config({
	clientId: '...',
	clientSecret: '...',
	realm: '...',
	agent: myHttpAgent
});



// Or update them individually:
Stackspot.instance
	.setClientId('...')
	.setClientSecret('...');

If you want to create your own Stackspot instance, you can either pass the settings on the constructor, use the 'config' method, or configure individual properties as well:

// Creating a new stackspot instance (instead of using the 'global' one):
const myInstance = new Stackspot({ clientId: '...', clientSecret: '...', realm: '...' });


// If you want, it's possible to call the 'config(opts)' method of this instance as well to update the settings:
myInstance.config({ ... });


// Or configure properties individually:
myInstance.setClientId('...');

🌐 Using behind proxy

Internally it uses node-fetch to make requests, so you can provide a custom HTTP agent to configure proxy and SSL certificates.

Example using proxy-agent:

import { Stackspot } from 'stackspot';
import { ProxyAgent } from 'proxy-agent';

// ProxyAgent will use environment variables to configure proxy like HTTP_PROXY, HTTPS_PROXY and NO_PROXY.
Stackspot.instance.setAgent(new ProxyAgent());

Methods

Here are all the available methods of this package:

✨ AI

All the AI related functions are bellow Stackspot.instance.ai namespace.

AI - KS - Create a new Knowledge Source

To create a new Knowledge Source, just run:

await Stackspot.instance.ai.ks.createKs('my-new-ks', 'My new KS', 'A test KS', 'CUSTOM');

For more info about the KS creation, check out the official documentation: https://ai.stackspot.com/docs/knowledge-source/create-knowledge-source

AI - KS - Upload new file to a Knowledge Source

You can add or update existing objects inside a Knowledge Source:

// This creates/updates a KS object named 'test.txt' containing 'Hello World' text:
await Stackspot.instance.ai.ks.uploadKsObject('my-ks-slug', 'test.txt', 'Hello World');

// Assuming you have a file in ./my-file.txt:
const fileContent = await fs.promises.readFile('./my-file.txt', 'utf8');

await Stackspot.instance.ai.ks.uploadKsObject('my-ks-slug', 'test.txt', fileContent);

AI - KS - Remove files from a Knowledge Source

To batch remove files from a Knowledge Source:

// This removes ALL objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'ALL');

// This removes only the STANDALONE objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'STANDALONE');

// This removes only the UPLOADED objects from the KS:
await Stackspot.instance.ai.ks.batchRemoveKsObjects('my-ks-slug', 'UPLOADED');

AI - Quick Command - Create a new execution

To manually create a new Quick Command execution:

const executionId = await Stackspot.instance.ai.quickCommand.createExecution('my-quick-command-slug', 'Input for this execution');
// Return example: "06J85YZZ5HVO1XXCKKR4TJ16N2"

AI - Quick Command - Get execution

After creating a new Quick Command execution, you may want to check it to see if it has completed successfully, and get its result:

const execution = await Stackspot.instance.ai.quickCommand.getExecution('06J85YZZ5HVO1XXCKKR4TJ16N2');

console.log('status: ' + execution.progress?.status);

Obs.: Note that, at the time this call have been made, the execution may not yet be done, so you have to write some polling logic, or use the 'pollExecution' method.

AI - Quick Command - Poll execution until it's done

It can be cumbersome to write the logic to poll a Quick Command execution after its creation to check if it's done. This library gets you covered on that:

// Just create a new execution:
const executionId = await Stackspot.instance.ai.quickCommand.createExecution('my-quick-command-slug', 'Input for this execution');

// And call the poll method:
// This will check the execution status until it's done and then return the execution object:
const execution = await Stackspot.instance.ai.quickCommand.pollExecution(executionId);

console.log('status: ' + execution.progress?.status); // 'COMPLETED'
console.log('result: ' + execution.result); // The Quick Command result.

🗝️ Auth

The library methods already handles the authentication process, but you can access the auth methods by yourself using the Stackspot.instance.auth namespace:

Auth - Get the access token

This will get the cached token, or fetch a new one if they aren't valid anymore:

await Stackspot.instance.auth.getAccessToken();

Obs.: To configure the authentication properties like clientId, clientSecret, and realm, head back to the Usage section.

License

MIT