@carddb/node

CardDB client for Node.js, Bun, and Deno.

Installation

npm install @carddb/node
# or
bun add @carddb/node
# or
deno add npm:@carddb/node

Quick Start

import { CardDBClient, MemoryCache, gte, ilike } from '@carddb/node'

const client = new CardDBClient({
  secretKey: 'carddb_sk_xxx...', // Server-side API key
  cache: new MemoryCache(), // Optional in-memory 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)
}

App-Owned Decks

Use secretKey only in trusted server runtimes. App-owned deck helpers such as external-reference upsert and deck access token exchange require secretKey or the legacy apiKey option. If accessToken or publishableKey would be sent instead, those secret-only helpers fail before making a request.

const upsert = await client.decks.upsertByExternalRef({
  externalRef: 'metafy:guide:123:deck:456',
  idempotencyKey: 'sync-123',
  publisherSlug: 'pokemon',
  gameKey: 'tcg',
  title: 'Course Deck',
  accessMode: 'AUTHORIZED_TOKEN',
  discoverability: 'UNLISTED',
  entries: [{ datasetKey: 'cards', identifier: 'CARD-001', quantity: 4 }],
})

const exchange = await client.decks.exchangeAccessToken({
  deckId: upsert.deck.id,
  readMode: 'FULL',
  externalSubject: 'user_123',
})

MemoryCache

Simple in-memory cache with TTL support:

import { MemoryCache } from '@carddb/node'

const cache = new MemoryCache()

// Use with client
const client = new CardDBClient({
  cache,
  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 entries

For production multi-instance deployments, consider implementing a Redis-based cache using the Cache interface.

Full Documentation

See the main README for complete documentation.

License

MIT