Package Exports

@theventures/caret

Readme

@theventures/caret

Unofficial Node.js API client for the Caret HTTP API

Caret is a meeting transcription and note management service. This library provides a convenient way to interact with the Caret API from Node.js applications.

Installation

npm install @theventures/caret

yarn add @theventures/caret

pnpm add @theventures/caret

bun add @theventures/caret

Quick Start

import { Caret } from '@theventures/caret';

const caret = new Caret({
  apiKey: 'sk-caret-api-xxxxxxxxxxxxxxxxxxxx'
});

// List all notes
const notes = await caret.notes.list();
console.log(notes);

// Get a specific note
const note = await caret.notes.get('note_id');
console.log(note);

Authentication

You can provide your API key in several ways:

Environment Variable (Recommended)

export CARET_API_KEY="sk-caret-api-xxxxxxxxxxxxxxxxxxxx"

const caret = new Caret(); // Automatically uses CARET_API_KEY

Constructor Option

const caret = new Caret({
  apiKey: 'sk-caret-api-xxxxxxxxxxxxxxxxxxxx'
});

Configuration

const caret = new Caret({
  apiKey: 'sk-caret-api-xxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://api.caret.so/v1', // default
  timeout: 30000, // 30 seconds (default)
  maxRetries: 3 // default
});

API Resources

Notes

The notes resource allows you to manage meeting notes and transcripts.

// List all notes with optional filtering
const notes = await caret.notes.list({
  limit: 10,
  offset: 0
});

// Retrieve a specific note
const note = await caret.notes.get('note_id');

// Update a note
const updatedNote = await caret.notes.update('note_id', {
  title: 'New Title',
  userWrittenNote: 'Updated content'
});

Rate Limits

The client automatically handles rate limiting based on your Caret plan:

Free: 60 requests per minute
Pro: 120 requests per minute
Enterprise: 300 requests per minute

When rate limits are exceeded, the client will automatically retry with exponential backoff.

Error Handling

The library provides specific error types for different API error conditions:

import { 
  CaretAPIError, 
  RateLimitError, 
  AuthenticationError,
  NotFoundError 
} from '@theventures/caret';

try {
  const note = await caret.notes.get('invalid_id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Note not found');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limit exceeded');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof CaretAPIError) {
    console.log('API error:', error.message);
  }
}

TypeScript Support

This library is written in TypeScript and provides comprehensive type definitions:

import type { Note, NoteStatus, NoteVisibility } from '@theventures/caret';

const note: Note = await caret.notes.get('note_id');
console.log(note.title); // Fully typed

Requirements

Node.js 18 or higher
TypeScript 5.0 or higher (if using TypeScript)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

This is an unofficial client library. For issues with the Caret API itself, please contact Caret support.

For issues with this library:

Check existing GitHub issues
Create a new issue with a clear description
Include code examples and error messages when applicable

About

This package is published by TheVentures, the investment company behind At Inc. (the company that operates Caret).

Built with AI

This library was built entirely through vibe coding. The entire codebase was developed primarily using Claude Code, demonstrating the power of AI-assisted development in creating production-ready software.

JSPM