@testdog/ai
Version:
SDK for integrating the Testdog AI Video Intelligence API
129 lines (98 loc) • 5.37 kB
Markdown
# testdog AI SDK (Node.js)
[](https://badge.fury.io/js/testdog-ai-sdk) <!-- Replace with your actual package name -->
Official Node.js SDK for integrating the testdog AI Video Intelligence API into your backend applications.
This SDK simplifies the process of authenticating with the API and generating secure URLs for the AI chat iframe.
## Installation
```bash
npm install /ai
# or
yarn add /ai
```
## Usage
```typescript
import { testdogAI, SdkAuthenticationError, SdkRequestError, SdkInputError } from '/ai';
// Initialize the SDK with your API keys
const testdogAI = new testdogAI({
accessKey: 'YOUR_ACCESS_KEY', // Replace with your actual Access Key
secretKey: 'YOUR_SECRET_KEY', // Replace with your actual Secret Key
// apiBaseUrl: 'https://your-api.testdog.com/api/v1' // Optional: Override API base URL
});
// --- Generate Iframe URL ---
async function getChatUrlForStudent(studentInfo: { studentId: string; studentName: string; sourceId: string }) {
try {
const iframeUrl = await testdogAI.generateIframeUrl({
studentId: studentInfo.studentId,
studentName: studentInfo.studentName,
sourceId: studentInfo.sourceId,
// iframeBaseUrl: 'https://your-custom-chat-domain.com/chat' // Optional: Override iframe base URL
});
console.log('Generated Iframe URL:', iframeUrl);
// Use this URL as the src for an iframe in your frontend
return iframeUrl;
} catch (error) {
if (error instanceof SdkAuthenticationError) {
console.error('SDK Authentication Failed:', error.message);
// Handle invalid API keys
} else if (error instanceof SdkInputError) {
console.error('Invalid Input:', error.message);
// Handle missing or invalid parameters passed to the SDK method
} else if (error instanceof SdkRequestError) {
console.error(`API Request Error (${error.statusCode || 'Network Error'}):`, error.message, error.details || '');
// Handle errors from the testdog AI backend API
} else {
console.error('An unexpected SDK error occurred:', error);
// Handle other errors
}
throw error; // Re-throw or handle as needed
}
}
// Example usage in an Express route handler (or similar backend logic)
app.get('/chat-url/:sourceId/:studentId', async (req, res) => {
// In a real app, get studentName securely based on studentId
const studentName = `Student ${req.params.studentId}`;
const url = await getChatUrlForStudent({
studentId: req.params.studentId,
studentName: studentName,
sourceId: req.params.sourceId
});
res.json({ iframeUrl: url });
});
```
## API
### `new testdogAI(config)`
Initializes the SDK.
* `config`: `SdkConfig` object
* `accessKey` (string, required): Your API Access Key.
* `secretKey` (string, required): Your API Secret Key.
* `apiBaseUrl` (string, optional): Override the default base URL for the testdog AI API.
### `testdogAI.generateIframeUrl(options)`
Generates a secure URL for the AI chat iframe.
* `options`: `GenerateIframeUrlOptions` object
* `studentId` (string, required): A unique identifier for the end-user (student).
* `studentName` (string, required): The display name for the end-user.
* `sourceId` (string, required): The unique identifier for the video or knowledge source the chat pertains to.
* `iframeBaseUrl` (string, optional): Override the default base URL for the chat iframe content.
* **Returns:** `Promise<string>` - Resolves with the generated iframe URL.
* **Throws:** `SdkInputError`, `SdkAuthenticationError`, `SdkRequestError`, `SdkError`.
## Error Handling
The SDK throws custom errors to help distinguish different failure modes:
* `SdkError`: Base class for all SDK errors.
* `SdkInputError`: Invalid input provided to SDK methods.
* `SdkAuthenticationError`: Failed to authenticate with the API (invalid keys or token issues).
* `SdkRequestError`: The request to the testdog AI API failed (includes optional `statusCode` and `details`).
Catch these specific error types for granular error handling.
**How to Use This Structure:**
1. **Create Files:** Create the directory structure and files as outlined above within your `testdog-ai/Sdk/` folder.
2. **Install Dependencies:** Navigate to the `Sdk/` directory in your terminal and run `npm install`.
3. **Build the SDK:** Run `npm run build` in the `Sdk/` directory. This will compile the TypeScript code into JavaScript (`.js`, `.mjs`) and generate type definitions (`.d.ts`) in the `Sdk/dist/` folder.
4. **Consume the SDK (Locally for Testing):** In your main `Backend` project, you can install the SDK locally for testing:
```bash
cd ../Backend # Navigate to your main backend folder
npm install ../Sdk # Installs the SDK locally using file path
```
Then, in your backend code (e.g., a specific route handler that needs to generate the URL for its own frontend), you can import and use it:
```typescript
import { testdogAI } from 'testdog-ai-sdk'; // Import from the installed package
// In your route handler or service:
const sdk = new testdogAI({ accessKey: '...', secretKey: '...' });
const url = await sdk.generateIframeUrl({ /* ... student/source details ... */ });