testdog AI SDK (Node.js)

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

npm install @testdog/ai
# or
yarn add @testdog/ai

Usage

import { testdogAI, SdkAuthenticationError, SdkRequestError, SdkInputError } from '@testdog/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:

   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:

   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 ... */ });