@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',
})

Publisher Management

Use secretKey in trusted server runtimes for publisher workflows such as game management, import formats, import jobs, record upserts/deletes, file-backed imports, and exports.

const client = new CardDBClient({ secretKey: process.env.CARDDB_SECRET_KEY })

const game = await client.games.create({
  publisherId: 'publisher_uuid',
  key: 'tcg',
  name: 'Example TCG',
})

const upsert = await client.records.upsertBatch({
  gameId: game.id,
  datasetKey: 'cards',
  records: [{ code: 'CARD-001', name: 'Example Card' }],
})

if (upsert.job) {
  await client.imports.waitForJob(upsert.job.id)
}

const exportJob = await client.exports.run({ gameId: game.id, datasetKey: 'cards' })
await client.exports.waitForJob(exportJob.id)

See the main README for direct payload, uploaded file, source URL, advanced schema-creating import, bulk delete preview/execution, export URL refresh, and release-prep examples. See publisher-content-pipeline.example.ts for a CI/CD-style content sync script.

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