Deepgram JavaScript SDK

https://github.com/deepgram/deepgram-js-sdk
Admin
The Deepgram JavaScript SDK provides a comprehensive set of tools for developers to integrate...
Tokens:96,521
Snippets:626
Trust Score:9.5
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run browser examples with make browser-serve

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/README.md

Starts a local server for browser examples, automatically copying the browser build and starting a proxy server. Requires DEEPGRAM_API_KEY and DEEPGRAM_PROJECT_ID environment variables.

```bash
DEEPGRAM_API_KEY=your_key DEEPGRAM_PROJECT_ID=your_id make browser-serve
```

--------------------------------

### Install, build, test, lint, and typecheck headlessly

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/AGENTS.md

Headless setup and verification commands for the deepgram-js-sdk repository. Run `make test` instead of calling vitest directly because the target rewrites wire-test imports before the run and reverts them afterward. Some tests in `tests/esm-build.test.ts` read files from `dist/`, so run `make build` before `make test` on a fresh clone. The example scripts (`make example-N`, `make examples`) call the live Deepgram API and read the `DEEPGRAM_API_KEY` environment variable; skip them when no key is available. `make browser` needs Playwright browsers installed and is not part of the headless core loop.

```bash
pnpm install          # install dependencies (respects .npmrc release-age gates)
```

```bash
make build            # compile CommonJS, ESM, and browser bundles into dist/
```

```bash
make test             # unit + wire test suites (vitest against local mocks)
```

```bash
make lint             # Biome linter
```

```bash
make typecheck-tests  # type-level regression gate for the compat shims
```

--------------------------------

### Run all examples with make

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/README.md

Runs all examples in the repository, requiring the same environment variables.

```bash
DEEPGRAM_API_KEY="your-api-key-here" DEEPGRAM_PROJECT_ID="your-id-here" make examples
```

--------------------------------

### Install dependencies

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/tests/browser/README.md

Install project dependencies and the required Playwright browser.

```bash
pnpm install
npx playwright install chromium
```

--------------------------------

### Run a single example with make

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/README.md

Runs a specific example by name, passing the required environment variables inline.

```bash
DEEPGRAM_API_KEY="your-api-key-here" DEEPGRAM_PROJECT_ID="your-id-here" make example-1
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/README.md

Installs project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### CI: Install Playwright browsers

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/tests/browser/README.md

Step to install Playwright browsers in a CI environment.

```yaml
- name: Install Playwright browsers
  run: npx playwright install chromium --with-deps
```

--------------------------------

### Build the SDK with make build

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/README.md

Builds the SDK before running browser examples. Required if the SDK is not already built.

```bash
make build
```

--------------------------------

### Install Deepgram SDK

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/docs/Migrating-v3-to-v4.md

Install the @deepgram/sdk package using npm, pnpm, or yarn.

```bash
npm install @deepgram/sdk
# or
pnpm add @deepgram/sdk
# or
yarn add @deepgram/sdk
```

--------------------------------

### Configure Deepgram SDK Endpoints

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/33-configuration-eu-endpoint.html

Examples showing how to initialize the DeepgramClient with different base URLs for US, EU, and self-hosted instances.

```javascript
// US Endpoint (default)
const usClient = new DeepgramClient({
 apiKey: "proxy",
 baseUrl: "http://localhost:8001" // proxy to api.deepgram.com
});

// EU Endpoint (via EU proxy)
const euClient = new DeepgramClient({
 apiKey: "proxy",
 baseUrl: "https://eu-proxy.example.com" // forwards to api.eu.deepgram.com
});

// Self-Hosted Deepgram
const onpremClient = new DeepgramClient({
 apiKey: "proxy",
 baseUrl: "https://proxy.example.com" // forwards to your self-hosted instance
});
```

--------------------------------

### v5.0.0 Manage V1 Keys

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/docs/Migrating-v4-to-v5.md

v5.0.0 API for managing project keys: list, get, create, and delete.

```typescript
// List keys
const data = await deepgram.manage.v1.projects.keys.list(projectId);

// Get key
const data = await deepgram.manage.v1.projects.keys.get(projectId, keyId);

// Create key
const data = await deepgram.manage.v1.projects.keys.create(projectId, options);

// Delete key
await deepgram.manage.v1.projects.keys.delete(projectId, keyId);
```

--------------------------------

### Setup and handling of Deepgram Voice Agent WebSocket connection

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/09-voice-agent.html

This snippet shows the event handling for connection open, messages, errors, and close. It also includes the connection setup and configuration with sendSettings and sendKeepAlive, as well as sending audio chunks.

```JavaScript
startButton.addEventListener('click', async () => { if (isStreaming) return;
        isStreaming = true;
        startButton.disabled = true;
        stopButton.disabled = false;

        const audioFile = audioInput.files[0];
        if (!audioFile) {
          log('✗ Please select an audio file first', 'error');
          isStreaming = false;
          startButton.disabled = false;
          stopButton.disabled = true;
          return;
        }

        try {
          // Create a WebSocket connection to Deepgram
          const deepgramConnection = new Deepgram.WsClient({
            url: 'wss://agent.deepgram.com',
            apiKey: apiKeyInput.value.trim(),
            options: {
              headers: {
                'Authorization': 'Token ' + apiKeyInput.value.trim(),
              },
            },
          });

          // Reset connection state
          holdAudioSessions = false;
          textInput.value = '';
          transcript.replaceChildren();
          log('Connecting to Deepgram Voice Agent...', 'info');

          // Log connection status
          deepgramConnection.on('open', () => {
            log('Connected to Deepgram Voice Agent', 'info');
          });

          // Log the result
          deepgramConnection.on('message', (message) => {
            log(`message: ${JSON.stringify(message, null, 2)}`, 'info');
          });

          // Log any errors
          deepgramConnection.on('error', (error) => {
            log(`✗ Error: ${error.message}`, 'error');
          });

          // Log when the connection closes
          deepgramConnection.on('close', () => {
            log('Connection closed', 'info');
            if (keepAliveInterval) {
              clearInterval(keepAliveInterval);
              keepAliveInterval = null;
            }
            isStreaming = false;
            startButton.disabled = false;
            stopButton.disabled = true;
            deepgramConnection = null;
          });

          // Connect to the websocket
          deepgramConnection.connect();

          // Wait for connection to open before configuring
          await deepgramConnection.waitForOpen();

          // Configure the agent once connection is established
          deepgramConnection.sendSettings({
            type: 'Settings',
            audio: {
              input: {
                encoding: 'linear16',
                sample_rate: 24000,
              },
              output: {
                encoding: 'linear16',
                sample_rate: 16000,
                container: 'wav',
              },
            },
            agent: {
              language: 'en',
              listen: {
                provider: {
                  type: 'deepgram',
                  model: 'nova-3',
                },
              },
              think: {
                provider: {
                  type: 'open_ai',
                  model: 'gpt-4o-mini',
                },
                prompt: 'You are a friendly AI assistant.',
              },
              speak: {
                provider: {
                  type: 'deepgram',
                  model: 'aura-2-thalia-en',
                },
              },
              greeting: 'Hello! How can I help you today?',
            },
          });

          // Wait a moment for settings to be applied
          await new Promise((resolve) => setTimeout(resolve, 1000));

          // Set up keepalive messages to keep the connection alive
          keepAliveInterval = setInterval(() => {
            if (deepgramConnection && deepgramConnection.socket.readyState === 1) {
              deepgramConnection.sendKeepAlive({ type: 'KeepAlive' });
            } else {
              if (keepAliveInterval) {
                clearInterval(keepAliveInterval);
                keepAliveInterval = null;
              }
            }
          }, 5000);

          // Read audio file and send in chunks
          const arrayBuffer = await readFileAsArrayBuffer(audioFile);
          const chunkSize = 4096; // 4KB chunks
          for (let offset = 0; offset < arrayBuffer.byteLength && isStreaming; offset += chunkSize) {
            const chunk = arrayBuffer.slice(offset, offset + chunkSize);
            deepgramConnection.sendMedia(chunk);
            // Small delay to simulate streaming
            await new Promise(resolve => setTimeout(resolve, 10));
          }
          log('Finished sending audio data', 'info');

          // Auto-close after 1 minute
          setTimeout(() => {
            if (deepgramConnection && isStreaming) {
              deepgramConnection.close();
            }
          }, 60000);
        } catch (error) {
          log(`✗ Error: ${error.message}`, 'error');
          if (error.body) {
            log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
          }
          isStreaming = false;
          startButton.disabled = false;
          stopButton.disabled = true;
          if (keepAliveInterval) {
            clearInterval(keepAliveInterval);
            keepAliveInterval = null;
          }
        }
      });
```

```JavaScript
stopButton.addEventListener('click', () => {
        if (deepgramConnection) {
          isStreaming = false;
          deepgramConnection.close();
        }
      });
```

```JavaScript
const readFileAsArrayBuffer = (file) => {
        return new Promise((resolve, reject) => {
          const reader = new FileReader();
          reader.onload = () => resolve(reader.result);
          reader.onerror = reject;
          reader.readAsArrayBuffer(file);
        });
      };
```

--------------------------------

### Self-Hosted Distribution Credentials (v3+)

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/docs/Migrating-v2-to-v3.md

In v3+, use the onprem namespace to list, get, create, and delete distribution credentials. Each method returns a result and error object.

```typescript
// List credentials
const { result, error } = await deepgram.onprem.listCredentials(projectId);

// Get credentials
const { result, error } = await deepgram.onprem.getCredentials(
  projectId,
  credentialId
);

// Create credentials
const { result, error } = await deepgram.onprem.createCredentials(
  projectId,
  options
);

// Delete credentials
const { result, error } = await deepgram.onprem.deleteCredentials(
  projectId,
  credentialId
);
```

--------------------------------

### Handle binary response as Blob

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/25-binary-response.html

Uses the blob() method to get the response as a Blob, logs its size and type, and creates an audio element for playback.

```javascript
blobButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const text = textInput.value.trim();
  if (!text) {
    log('Please enter text', 'error');
    return;
  }
  output.textContent = '';
  blobButton.disabled = true;
  try {
    const response = await client.speak.v1.audio.generate({
      text,
      model: "aura-2-thalia-en",
    });
    log(`Body used: ${response.bodyUsed}`, 'info');
    const blob = await response.blob();
    log(`✓ Blob received, size: ${blob.size} bytes, type: ${blob.type}`, 'success');
    createAudioElement(blob);
    log(`Body used after: ${response.bodyUsed}`, 'info');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
  } finally {
    blobButton.disabled = false;
  }
});
```

--------------------------------

### Model Management: List and Get Models with DeepgramClient

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/19-management-models.html

Client-side JavaScript for the Model Management example. It creates a DeepgramClient with a proxy API key and base URL, and wires up three buttons: list all models, list project models, and get a single model. The code uses the manage.v1 API endpoints and logs results or errors to the output element.

```javascript
const { DeepgramClient } = deepgram;
const projectIdInput = document.getElementById('projectId');
const allModelsButton = document.getElementById('allModelsButton');
const projectModelsButton = document.getElementById('projectModelsButton');
const getModelButton = document.getElementById('getModelButton');
const output = document.getElementById('output');

// Try to load project ID from localStorage (non-sensitive)
const savedProjectId = localStorage.getItem('DEEPGRAM_PROJECT_ID');
if (savedProjectId) projectIdInput.value = savedProjectId;

function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}

function getClient() {
  return new DeepgramClient({
    apiKey: 'proxy',
    baseUrl: 'http://localhost:8001',
  });
}

allModelsButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  output.textContent = '';
  allModelsButton.disabled = true;
  try {
    const data = await client.manage.v1.models.list();
    log(`✓ All models:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    allModelsButton.disabled = false;
  }
});

projectModelsButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  projectModelsButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.models.list(projectId, {});
    log(`✓ Project models:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    projectModelsButton.disabled = false;
  }
});

getModelButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  const modelId = prompt('Enter model ID:');
  if (!modelId) return;
  output.textContent = '';
  getModelButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.models.get(projectId, modelId);
    log(`✓ Model:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    getModelButton.disabled = false;
  }
});
```

--------------------------------

### Usage Management with DeepgramClient.manage.v1.projects

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/17-management-usage.html

Browser example that uses the Deepgram JavaScript SDK to call usage management endpoints: list requests, get a request, get usage summary, and list usage fields. The client is created with a proxy API key and base URL, and the API key is configured via the DEEPGRAM_API_KEY environment variable on the proxy server. Each button handler validates the project ID, disables the button during the request, and logs success or error details.

```javascript
const { DeepgramClient } = deepgram;
const projectIdInput = document.getElementById('projectId');
const requestsButton = document.getElementById('requestsButton');
const requestButton = document.getElementById('requestButton');
const usageButton = document.getElementById('usageButton');
const fieldsButton = document.getElementById('fieldsButton');
const output = document.getElementById('output');

// Try to load project ID from localStorage (non-sensitive)
const savedProjectId = localStorage.getItem('DEEPGRAM_PROJECT_ID');
if (savedProjectId) projectIdInput.value = savedProjectId;

function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}

function getClient() {
  return new DeepgramClient({
    apiKey: 'proxy',
    baseUrl: 'http://localhost:8001',
  });
}

requestsButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  requestsButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.requests.list(projectId, {});
    log(`✓ Requests:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    requestsButton.disabled = false;
  }
});

requestButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  const requestId = prompt('Enter request ID:');
  if (!requestId) return;
  output.textContent = '';
  requestButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.requests.get(projectId, requestId);
    log(`✓ Request:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    requestButton.disabled = false;
  }
});

usageButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  usageButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.usage.get(projectId, {});
    log(`✓ Usage summary:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    usageButton.disabled = false;
  }
});

fieldsButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  fieldsButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.usage.fields.list(projectId, {});
    log(`✓ Usage fields:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
  } finally {
    fieldsButton.disabled = false;
  }
});
```

--------------------------------

### Manage Deepgram projects with client.manage.v1.projects

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/13-management-projects.html

Complete browser example for managing Deepgram projects via the Deepgram JavaScript SDK. It sets up a DeepgramClient with a proxy API key and base URL, then wires up event listeners for listing, getting, updating, and deleting projects. The list operation auto-saves the first project ID to localStorage, and the delete operation requires a confirmation dialog.

```javascript
const { DeepgramClient } = deepgram;
const projectIdInput = document.getElementById('projectId');
const listButton = document.getElementById('listButton');
const getButton = document.getElementById('getButton');
const updateButton = document.getElementById('updateButton');
const deleteButton = document.getElementById('deleteButton');
const output = document.getElementById('output');

// Try to load project ID from localStorage (non-sensitive)
const savedProjectId = localStorage.getItem('DEEPGRAM_PROJECT_ID');
if (savedProjectId) {
  projectIdInput.value = savedProjectId;
}

function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}

function getClient() {
  return new DeepgramClient({
    apiKey: 'proxy',
    baseUrl: 'http://localhost:8001',
  });
}

listButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  output.textContent = '';
  listButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.list();
    log(`✓ Projects:\n${JSON.stringify(data, null, 2)}`, 'success');
    if (data.projects && data.projects.length > 0 && !projectIdInput.value) {
      projectIdInput.value = data.projects[0].project_id;
      localStorage.setItem('DEEPGRAM_PROJECT_ID', data.projects[0].project_id);
    }
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  } finally {
    listButton.disabled = false;
  }
});

getButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  getButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.get(projectId);
    log(`✓ Project:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  } finally {
    getButton.disabled = false;
  }
});

updateButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  updateButton.disabled = true;
  try {
    const data = await client.manage.v1.projects.update(projectId, {
      name: "Naomi's Sandbox",
    });
    log(`✓ Updated project:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  } finally {
    updateButton.disabled = false;
  }
});

deleteButton.addEventListener('click', async () => {
  if (!confirm('Are you sure you want to delete this project? This action cannot be undone.')) {
    return;
  }
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  deleteButton.disabled = true;
  try {
    await client.manage.v1.projects.delete(projectId);
    log('✓ Project deleted successfully', 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  } finally {
    deleteButton.disabled = false;
  }
});
```

--------------------------------

### Build the project with pnpm build

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/CONTRIBUTING.md

Builds the project. Run this after making changes to ensure the build succeeds.

```bash
pnpm build
```

--------------------------------

### Run tests with make

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/README.md

Run this command to execute the test suite.

```bash
make test
```

--------------------------------

### Manage Deepgram project members and permissions

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/31-management-member-permissions.html

Complete browser example for managing Deepgram project members: list members, list invitations, get member scopes, update a member's scope, and send invitations. Uses the Deepgram JavaScript SDK with a proxy API key and local base URL. Includes validation, confirmation for scope updates, and error handling that logs error bodies.

```javascript
const { DeepgramClient } = deepgram;
const projectIdInput = document.getElementById('projectId');
const memberIdInput = document.getElementById('memberId');
const updateMemberIdInput = document.getElementById('updateMemberId');
const newScopeSelect = document.getElementById('newScope');
const inviteEmailInput = document.getElementById('inviteEmail');
const inviteScopeSelect = document.getElementById('inviteScope');
const output = document.getElementById('output');

function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}

function validateProjectId() {
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return null;
  }
  return projectId;
}

document.getElementById('listMembers').addEventListener('click', async () => {
  const projectId = validateProjectId();
  if (!projectId) return;
  output.textContent = '';
  log('Fetching project members...\n');
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: 'proxy',
      baseUrl: 'http://localhost:8001',
    });
    const data = await deepgramClient.manage.v1.projects.members.list(projectId);
    log(`✓ Project members:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  }
});

document.getElementById('listInvites').addEventListener('click', async () => {
  const projectId = validateProjectId();
  if (!projectId) return;
  output.textContent = '';
  log('Fetching pending invitations...\n');
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: 'proxy',
      baseUrl: 'http://localhost:8001',
    });
    const data = await deepgramClient.manage.v1.projects.members.invites.list(projectId);
    log(`✓ Pending invitations:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  }
});

document.getElementById('getScopes').addEventListener('click', async () => {
  const projectId = validateProjectId();
  if (!projectId) return;
  const memberId = memberIdInput.value.trim();
  if (!memberId) {
    log('Please enter a member ID', 'error');
    return;
  }
  output.textContent = '';
  log('Fetching member scopes...\n');
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: 'proxy',
      baseUrl: 'http://localhost:8001',
    });
    const data = await deepgramClient.manage.v1.projects.members.scopes.list(projectId, memberId);
    log(`✓ Member scopes:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  }
});

document.getElementById('updateScope').addEventListener('click', async () => {
  const projectId = validateProjectId();
  if (!projectId) return;
  const memberId = updateMemberIdInput.value.trim();
  if (!memberId) {
    log('Please enter a member ID', 'error');
    return;
  }
  if (!confirm(`Are you sure you want to update this member's scope to ${newScopeSelect.value}?`)) {
    log('Scope update cancelled', 'error');
    return;
  }
  output.textContent = '';
  log('Updating member scope...\n');
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: 'proxy',
      baseUrl: 'http://localhost:8001',
    });
    const data = await deepgramClient.manage.v1.projects.members.scopes.update(projectId, memberId, { scope: newScopeSelect.value });
    log(`✓ Member scope updated:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  }
});

document.getElementById('sendInvite').addEventListener('click', async () => {
  const projectId = validateProjectId();
  if (!projectId) return;
  const email = inviteEmailInput.value.trim();
  if (!email) {
    log('Please enter an email address', 'error');
    return;
  }
  output.textContent = '';
  log('Sending invitation...\n');
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: 'proxy',
      baseUrl: 'http://localhost:8001',
    });
    const data = await deepgramClient.manage.v1.projects.members.invites.create(projectId, { email, scope: inviteScopeSelect.value });
    log(`✓ Invitation sent:\n${JSON.stringify(data, null, 2)}`, 'success');
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
  }
});
```

--------------------------------

### Create distribution credentials with client.selfHosted.v1.distributionCredentials.create

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/20-onprem-credentials.html

Listens for clicks on the create button. Calls `client.selfHosted.v1.distributionCredentials.create(projectId, {})` with an empty options object to create a new credential. Logs the created credential JSON or an error, and re-enables the button in a finally block.

```javascript
createButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  createButton.disabled = true;
  try {
    const data = await client.selfHosted.v1.distributionCredentials.create(projectId, {});
    log(\`✓ Created credentials:\n${JSON.stringify(data, null, 2)}\`, 'success');
  } catch (error) {
    log(\`✗ Error: ${error.message}\`, 'error');
    if (error.body) log(\`Error details: ${JSON.stringify(error.body, null, 2)}\`, 'error');
  } finally {
    createButton.disabled = false;
  }
});
```

--------------------------------

### Live transcription via WebSocket with DeepgramClient

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/07-transcription-live-websocket.html

Sets up a live transcription workflow: creates a DeepgramClient, connects via listen.v1.connect with model nova-3, sends audio in 4KB chunks, and handles open/message/error/close events. Requires an API key and an audio file; logs transcripts and metadata to the output element. Includes a stop button and auto-close after 1 minute.

```javascript
const { DeepgramClient } = deepgram;
const apiKeyInput = document.getElementById('apiKey');
const audioFileInput = document.getElementById('audioFile');
const startButton = document.getElementById('startButton');
const stopButton = document.getElementById('stopButton');
const output = document.getElementById('output');
let deepgramConnection = null;
let audioChunks = [];
let isStreaming = false;
function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : type === 'info' ? 'info' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}
async function readFileAsArrayBuffer(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result);
    reader.onerror = reject;
    reader.readAsArrayBuffer(file);
  });
}
startButton.addEventListener('click', async () => {
  // codeql[js/clear-text-storage-of-sensitive-information] This is an example file demonstrating API key usage
  const apiKey = apiKeyInput.value.trim();
  const audioFile = audioFileInput.files[0];
  if (!apiKey) {
    log('Please enter an API key', 'error');
    return;
  }
  if (!audioFile) {
    log('Please select an audio file', 'error');
    return;
  }
  output.textContent = '';
  startButton.disabled = true;
  stopButton.disabled = false;
  isStreaming = true;
  try {
    const deepgramClient = new DeepgramClient({
      apiKey: apiKey,
    });
    deepgramConnection = await deepgramClient.listen.v1.connect({
      model: "nova-3",
      language: "en",
      punctuate: "true",
      interim_results: "true",
    });
    // Set up event handlers
    deepgramConnection.on("open", () => {
      log('✓ Connection opened', 'success');
    });
    let receivedFinal = false;
    deepgramConnection.on("message", (data) => {
      if (data.type === "Results") {
        log(`Transcript: ${JSON.stringify(data, null, 2)}`);
        if (data.is_final) {
          receivedFinal = true;
          setTimeout(() => {
            if (deepgramConnection) {
              deepgramConnection.close();
            }
          }, 1000);
        }
      } else if (data.type === "Metadata") {
        log(`Metadata: ${JSON.stringify(data, null, 2)}`, 'info');
      } else {
        log(`Unknown message type: ${JSON.stringify(data, null, 2)}`);
      }
    });
    deepgramConnection.on("error", (error) => {
      log(`✗ Error: ${error.message}`, 'error');
    });
    deepgramConnection.on("close", () => {
      log('Connection closed', 'info');
      isStreaming = false;
      startButton.disabled = false;
      stopButton.disabled = true;
      deepgramConnection = null;
    });
    // Connect to the websocket
    deepgramConnection.connect();
    // Wait for connection to open
    await deepgramConnection.waitForOpen();
    // Read audio file and send in chunks
    const arrayBuffer = await readFileAsArrayBuffer(audioFile);
    const chunkSize = 4096; // 4KB chunks
    for (let offset = 0; offset < arrayBuffer.byteLength && isStreaming; offset += chunkSize) {
      const chunk = arrayBuffer.slice(offset, offset + chunkSize);
      deepgramConnection.sendMedia(chunk);
      // Small delay to simulate streaming
      await new Promise(resolve => setTimeout(resolve, 10));
    }
    if (isStreaming) {
      deepgramConnection.sendFinalize({ type: "Finalize" });
    }
    // Auto-close after 1 minute
    setTimeout(() => {
      if (deepgramConnection && isStreaming) {
        deepgramConnection.close();
      }
    }, 60000);
  } catch (error) {
    log(`✗ Error: ${error.message}`, 'error');
    if (error.body) {
      log(`Error details: ${JSON.stringify(error.body, null, 2)}`, 'error');
    }
    isStreaming = false;
    startButton.disabled = false;
    stopButton.disabled = true;
  }
});
stopButton.addEventListener('click', () => {
  if (deepgramConnection) {
    isStreaming = false;
    deepgramConnection.close();
  }
});
```

--------------------------------

### Use v5 versioned method namespaces

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/AGENTS.md

Versioned method namespaces in v5. Use `client.listen.v1.media.transcribeFile(...)` for files, `await client.listen.v1.connect({...})` for live streaming, `client.speak.v1.audio.generate({...})` for text-to-speech, `await client.agent.v1.createConnection()` for the Voice Agent, and `client.manage.v1.*` for the management plane. The v3/v4 paths such as `deepgram.listen.prerecorded.transcribeFile(...)` are gone. `reference.md` covers REST methods; use `README.md`, `src/CustomClient.ts`, and the relevant examples for streaming methods.

```javascript
client.listen.v1.media.transcribeFile(...)
```

```javascript
await client.listen.v1.connect({...})
```

```javascript
client.speak.v1.audio.generate({...})
```

```javascript
await client.agent.v1.createConnection()
```

```javascript
client.manage.v1.*
```

--------------------------------

### v4 Manage V1 Projects

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/docs/Migrating-v4-to-v5.md

v4 API for managing projects: get all, get one, update, and delete.

```typescript
// Get projects
const { result, error } = await deepgram.manage.getProjects();

// Get project
const { result, error } = await deepgram.manage.getProject(projectId);

// Update project
const { result, error } = await deepgram.manage.updateProject(
  projectId,
  options
);

// Delete project
const { error } = await deepgram.manage.deleteProject(projectId);
```

--------------------------------

### Set up DOM references, logging, and proxy DeepgramClient

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/20-onprem-credentials.html

Sets up DOM element references, a log helper that appends messages to an output div, and a getClient() factory that creates a DeepgramClient with apiKey 'proxy' and baseUrl 'http://localhost:8001' pointing to the on-prem proxy. Loads the last used project ID from localStorage if present.

```javascript
const { DeepgramClient } = deepgram;
const projectIdInput = document.getElementById('projectId');
const listButton = document.getElementById('listButton');
const getButton = document.getElementById('getButton');
const createButton = document.getElementById('createButton');
const deleteButton = document.getElementById('deleteButton');
const output = document.getElementById('output');

// Try to load project ID from localStorage (non-sensitive)
const savedProjectId = localStorage.getItem('DEEPGRAM\_PROJECT\_ID');
if (savedProjectId) projectIdInput.value = savedProjectId;

function log(message, type = 'info') {
  const div = document.createElement('div');
  const className = type === 'error' ? 'error' : type === 'success' ? 'success' : '';
  if (className) {
    div.className = className;
  }
  div.textContent = message;
  output.appendChild(div);
  output.scrollTop = output.scrollHeight;
}

function getClient() {
  return new DeepgramClient({
    apiKey: 'proxy',
    baseUrl: 'http://localhost:8001',
  });
}
```

--------------------------------

### Install https-proxy-agent for WebSocket proxy

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/README.md

Installs a Node 18-compatible version of https-proxy-agent to enable custom HTTP agents for streaming connections.

```bash
npm install https-proxy-agent@8
```

--------------------------------

### Get project usage with client.manage.v1.projects.usage.get

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/reference.md

Retrieves usage for a specific project. Use Get Project Usage Breakdown for a more comprehensive summary. The request includes many optional parameters for filtering usage data.

```typescript
await client.manage.v1.projects.usage.get("123456-7890-1234-5678-901234", {
    start: "start",
    end: "end",
    accessor: "12345678-1234-1234-1234-123456789012",
    alternatives: true,
    callback_method: true,
    callback: true,
    channels: true,
    custom_intent_mode: true,
    custom_intent: true,
    custom_topic_mode: true,
    custom_topic: true,
    deployment: "hosted",
    detect_entities: true,
    detect_language: true,
    diarize: true,
    dictation: true,
    encoding: true,
    endpoint: "listen",
    extra: true,
    filler_words: true,
    intents: true,
    keyterm: true,
    keywords: true,
    language: true,
    measurements: true,
    method: "sync",
    model: "6f548761-c9c0-429a-9315-11a1d28499c8",
    multichannel: true,
    numerals: true,
    paragraphs: true,
    profanity_filter: true,
    punctuate: true,
    redact: true,
    replace: true,
    sample_rate: true,
    search: true,
    sentiment: true,
    smart_format: true,
    summarize: true,
    tag: "tag1",
    topics: true,
    utt_split: true,
    utterances: true,
    version: true
});
```

--------------------------------

### List distribution credentials with client.selfHosted.v1.distributionCredentials.list

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/20-onprem-credentials.html

Listens for clicks on the list button. Validates that a project ID is entered, then calls `client.selfHosted.v1.distributionCredentials.list(projectId)` to fetch all credentials. Logs the JSON response on success or the error message and body on failure, and re-enables the button in a finally block.

```javascript
listButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  output.textContent = '';
  listButton.disabled = true;
  try {
    const data = await client.selfHosted.v1.distributionCredentials.list(projectId);
    log(\`✓ Credentials:\n${JSON.stringify(data, null, 2)}\`, 'success');
  } catch (error) {
    log(\`✗ Error: ${error.message}\`, 'error');
    if (error.body) log(\`Error details: ${JSON.stringify(error.body, null, 2)}\`, 'error');
  } finally {
    listButton.disabled = false;
  }
});
```

--------------------------------

### Get a specific credential with client.selfHosted.v1.distributionCredentials.get

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/20-onprem-credentials.html

Listens for clicks on the get button. Prompts for a credential ID, then calls `client.selfHosted.v1.distributionCredentials.get(projectId, credentialId)` to retrieve a specific credential. Logs the JSON response or an error, and re-enables the button in a finally block.

```javascript
getButton.addEventListener('click', async () => {
  const client = getClient();
  if (!client) return;
  const projectId = projectIdInput.value.trim();
  if (!projectId) {
    log('Please enter a project ID', 'error');
    return;
  }
  const credentialId = prompt('Enter credential ID:');
  if (!credentialId) return;
  output.textContent = '';
  getButton.disabled = true;
  try {
    const data = await client.selfHosted.v1.distributionCredentials.get(projectId, credentialId);
    log(\`✓ Credentials:\n${JSON.stringify(data, null, 2)}\`, 'success');
  } catch (error) {
    log(\`✗ Error: ${error.message}\`, 'error');
    if (error.body) log(\`Error details: ${JSON.stringify(error.body, null, 2)}\`, 'error');
  } finally {
    getButton.disabled = false;
  }
});
```

--------------------------------

### Run via Makefile

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/tests/browser/README.md

Execute browser tests using the provided Makefile command.

```bash
make test:browser
```

--------------------------------

### Get Key

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/examples/browser/14-management-keys.html

Retrieves details of a specific API key.

```APIDOC
## Get Key

### Description
Retrieves details of a specific API key.

### Method
GET

### Endpoint
/manage/v1/projects/{project_id}/keys/{key_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **key_id** (string) - Required - The ID of the API key.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **id** (string) - The API key ID.
- **comment** (string) - The comment associated with the key.
- **scopes** (array) - The scopes granted to the key.
- **tags** (array) - The tags associated with the key.
- **created** (string) - The creation timestamp.

#### Response Example
{
  "id": "key_id",
  "comment": "My API key",
  "scopes": ["usage:write"],
  "tags": ["production"],
  "created": "2023-01-01T00:00:00Z"
}
```

--------------------------------

### Run all browser tests

Source: https://github.com/deepgram/deepgram-js-sdk/blob/main/tests/browser/README.md

Execute the full suite of browser tests.

```bash
pnpm test:browser
```
Tokens:
Raw