Documentation

Everything you need to get started with @verbatims/sdk

Installation

npm install @verbatims/sdk

Requires Node.js 18+ and zod as a runtime dependency. Nuxt module is optional.

Usage

Create a client with your API key, then access any resource through its dedicated accessor.

Client setup

TypeScript

import { VerbatimsClient } from '@verbatims/sdk'

const vb = new VerbatimsClient('vbt_your_api_key')

// List quotes
const { data } = await vb.quotes.list({ language: 'fr', limit: 10 })

// Get a single quote
const quote = await vb.quotes.get(42)

// Create a quote
const created = await vb.quotes.create({
  name: 'Life is what happens when you're busy making other plans.',
  author_id: 1,
  language: 'en',
})

Resources

Each resource exposes methods for common CRUD operations and pagination.

Resource	Methods
vb.quotes	`list` `get` `create` `update` `delete` `paginate`
vb.authors	`list` `get` `create` `update` `paginate`
vb.references	`list` `get` `create` `update` `paginate`
vb.tags	`list` `paginate`
vb.collections	`create` `addQuote` `removeQuote`
vb.search	`query` `paginate`

Quotes

List with filters

const { data, pagination } = await vb.quotes.list({
  language: 'fr',
  limit: 20,
  page: 1,
  author_id: 42,
  tag: 'wisdom',
  sort_by: 'likes_count',
  sort_order: 'desc',
})

Create

const quote = await vb.quotes.create({
  name: 'The only true wisdom is in knowing you know nothing.',
  language: 'en',
  author_id: 1,
  tags: [1, 2],
})

Authors

List and get

// List authors
const { data } = await vb.authors.list({ search: 'einstein' })

// Get by ID
const author = await vb.authors.get(1)

Search

Full-text search

// Full-text search across quotes, authors, references
const { data } = await vb.search.query({
  q: 'life',
  type: 'quotes',
  limit: 10,
})

Collections

Create and manage

// Create a collection
const collection = await vb.collections.create({
  name: 'Favorites',
  is_public: true,
})

// Add a quote
await vb.collections.addQuote(collection.data.id, 42)

// Remove a quote
await vb.collections.removeQuote(collection.data.id, 42)

Pagination

Every list method accepts page and limit params and returns a pagination meta object. Use the paginate() async generator for seamless iteration.

Async generator

// Iterate through all pages
for await (const quote of vb.quotes.paginate({ language: 'fr' })) {
  console.log(quote.id, quote.name)
}

for await (const author of vb.authors.paginate({ search: 'einstein' })) {
  console.log(author.name)
}

for await (const result of vb.search.paginate({ q: 'life', type: 'quotes' })) {
  console.log(result.name)
}

Nuxt module

The package ships an optional Nuxt 4 module that auto-imports composables for convenient access.

nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@verbatims/sdk/nuxt/module'],
})

In any component

// Auto-imported composables
const { data } = await useQuotes({ language: 'fr', limit: 10 })
const results = await useSearchQuotes({ q: 'life', type: 'quotes' })

Set your API key via runtimeConfig.verbatimsApiKey in nuxt.config.ts.

Error handling

The SDK throws typed errors for every HTTP status. Catch specific errors for fine-grained control.

Error	Status	Description
ValidationError	400	Invalid request data
AuthError	401	Missing or invalid API key
ForbiddenError	403	Access denied
NotFoundError	404	Resource not found
RateLimitError	429	Too many requests
VerbatimsError	—	Generic API error (catch-all)

Error handling example

import {
  VerbatimsError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  AuthError,
  ForbiddenError,
} from '@verbatims/sdk'

try {
  const quote = await vb.quotes.get(999)
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Quote not found')
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${err.retryAfter}s`)
  } else if (err instanceof ValidationError) {
    console.log('Validation failed:', err.errors)
  }
}