@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 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',
  // Omit entries to preserve an existing deck's entries on update.
  // Pass [] to explicitly create or replace with an empty decklist.
  entries: [{ datasetKey: 'cards', identifier: 'CARD-001', quantity: 4 }],
})

const exchange = await client.decks.exchangeToken({
  deckId: upsert.deck.id,
  scopes: ['DECK_PUBLISHED_READ'],
  representation: 'DETAILED',
  externalSubject: 'user_123',
})

const tokenClient = new CardDBClient({ accessToken: exchange.token })
const deck = await tokenClient.decks.getPublished(upsert.deck.id)

Direct Signed Deck Tokens

Trusted server runtimes can also mint direct signed deck tokens locally after registering an issuer public key in CardDB.

import {
  generateDirectDeckTokenKeyPair,
  signDirectDeckToken,
} from '@carddb/node'

const keyPair = generateDirectDeckTokenKeyPair()

console.log(keyPair.publicKeyBase64) // Register this on directSigningKey.publicKey

const token = await signDirectDeckToken({
  issuerId: 'issuer_uuid',
  deckId: 'deck_uuid',
  apiApplicationId: 'app_uuid',
  keyId: 'prod-2026-01',
  privateKey: keyPair.privateKeyPem,
  scopes: ['DECK_PUBLISHED_READ'],
  representation: 'DETAILED',
  subject: 'user_123',
  expiresAt: new Date(Date.now() + 15 * 60 * 1000),
})

Use an Ed25519 private key in PEM or PKCS#8 DER form. Keep the private key server-side; CardDB only stores the matching public key on the trusted issuer.

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