@spines/sdk

SPINES SDK

Official TypeScript SDK for the SPINES API — identify books from bookshelf photos and build structured, explorable collections.

Installation

npm install @spines/sdk

Quick Start

import { SpinesClient } from '@spines/sdk';

const spines = new SpinesClient({ apiKey: 'gtspn_live_...' });

// Search for books
const results = await spines.books.search({ query: 'Sapiens' });
console.log(results.data);

// List public collections
const collections = await spines.collections.list({ sort: 'popular', limit: 10 });

// Start a bookshelf recognition job
const job = await spines.recognition.start({
  image_url: 'https://example.com/shelf.jpg',
  title: 'My Bookshelf',
});
console.log(job.job_id); // poll with spines.recognition.status(job.job_id)

Available Resources

Resource	Methods
spines.books	search, get, pairings, collections
spines.collections	list, get, create, update, delete, books, addBook, removeBook
spines.personas	list, get
spines.categories	list
spines.readingLists	list, add, update, remove
spines.recognition	start, status
spines.profile	get, update, credits

Error Handling

All API errors throw a SpinesError with structured details:

import { SpinesClient, SpinesError } from '@spines/sdk';

const spines = new SpinesClient({ apiKey: 'gtspn_live_...' });

try {
  await spines.books.get('non-existent-id');
} catch (err) {
  if (err instanceof SpinesError) {
    console.error(err.status);    // 404
    console.error(err.code);      // "NOT_FOUND"
    console.error(err.message);   // "Book not found"
    console.error(err.requestId); // "req_abc123"
  }
}

Configuration

const spines = new SpinesClient({
  apiKey: 'gtspn_live_...',           // Required — your API key
  baseUrl: 'https://getspines.com/api/v1', // Optional — defaults to production
});

Pagination

List endpoints return cursor-based paginated responses:

let cursor: string | undefined;

do {
  const page = await spines.collections.list({ limit: 20, cursor });
  for (const collection of page.data) {
    console.log(collection.title);
  }
  cursor = page.meta.has_more ? (page.meta.next_cursor ?? undefined) : undefined;
} while (cursor);

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5.3+ recommended

Documentation

Full API reference and guides: getspines.com/developers

License

MIT