@carddb/browser

CardDB client for browsers.

Installation

npm install @carddb/browser
# or
bun add @carddb/browser

Quick Start

import { CardDBClient, BrowserCache, gte, ilike } from '@carddb/browser'

const client = new CardDBClient({
  publishableKey: 'carddb_pk_xxx...', // Browser-safe public key
  cache: new BrowserCache(), // Optional localStorage-based caching
  defaultPublisher: 'pokemon',
  defaultGame: 'tcg',
})

// Search for cards with filtering
const cards = await client.records.search({
  datasetKey: 'cards',
  filter: (f) => f.where('hp', gte(100)).where('name', ilike('%pikachu%')),
})

// Iterate through all results (auto-paginates)
for await (const card of cards) {
  console.log(card.data.name)
}

Use accessToken instead of publishableKey for user-authorized OAuth deck workflows. secretKey is server-only and the browser client rejects it at construction time. The browser client also rejects legacy apiKey because it is ambiguous and can accidentally expose a secret key; use publishableKey explicitly for public browser reads.

Publisher management helpers such as games.create, records.upsertBatch, imports.run, exports.run, and files.requestUpload require a server-side secret credential and should be called from @carddb/node in a trusted backend, not directly from browser code. Keep content pipelines, source URL imports, uploaded file imports, bulk deletes, and exports on the server side.

const client = new CardDBClient({
  accessToken: oauthAccessToken,
})

const decks = await client.decks.listMine()
const updated = await client.decks.updateMetadata(deck.id, {
  expectedDraftRevision: deck.draftRevision,
  title: 'Updated title',
})

BrowserCache

Browser-based cache using localStorage or sessionStorage:

import { BrowserCache } from '@carddb/browser'

// localStorage (default, persistent across sessions)
const persistentCache = new BrowserCache()

// sessionStorage (cleared when tab closes)
const sessionCache = new BrowserCache({ storage: 'sessionStorage' })

// Custom key prefix (default: 'carddb:')
const customCache = new BrowserCache({ prefix: 'myapp:carddb:' })

// Use with client
const client = new CardDBClient({
  cache: persistentCache,
  cacheTtl: 300, // 5 minutes default
  cacheTtls: {
    publishers: 3600, // 1 hour for publishers
    records: 60, // 1 minute for records
  },
})

// Manual cache management
cache.cleanup() // Remove expired entries
cache.clear() // Clear all CardDB entries
cache.size // Number of cached entries

Bundle Size

The browser package is optimized for minimal bundle size. Tree-shaking is fully supported.

Full Documentation

See the main README for complete documentation.

License

MIT