# deckofcards-api

> Unofficial wrapper for Deck of Cards API

Latest version **3.1.0** (published 2025-11-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install deckofcards-api
pnpm add deckofcards-api
yarn add deckofcards-api
bun add deckofcards-api
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.1.0 |
| Published | 2025-11-15 |
| First published | 2018-05-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 14.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Cydney Mikel |
| Maintainers | cydneymikel |
| Keywords | deck, cards, card deck, deck of cards, deck of cards api |

## Links

- npm: https://www.npmjs.com/package/deckofcards-api
- Repository: https://github.com/cydneymikel/deckofcards-api
- Homepage: https://github.com/cydneymikel/deckofcards-api#readme
- Issues: https://github.com/cydneymikel/deckofcards-api/issues
- npm.io page: https://npm.io/package/deckofcards-api

## Dependencies (1)

- [superagent](https://npm.io/package/superagent.md) ^10.2.3

## Recent versions

- 3.1.0 (latest) — 2025-11-15
- 3.0.0 — 2025-11-10
- 2.0.0 — 2023-03-22
- 1.0.0 — 2018-05-30

## README

# deckofcards-api

[![Tests](https://github.com/cydneymikel/deckofcards-api/actions/workflows/test.yml/badge.svg)](https://github.com/cydneymikel/deckofcards-api/actions/workflows/test.yml)
[![npm version](https://badge.fury.io/js/deckofcards-api.svg)](https://www.npmjs.com/package/deckofcards-api)

Unofficial Node.js Library for interacting with the Deck of Cards API. (https://deckofcardsapi.com/)

## Quick Start

```bash
npm install deckofcards-api
```

```javascript
import * as cards from 'deckofcards-api';

// Create and shuffle a deck
const deck = await cards.deck({ shuffle: true });

// Draw some cards
const drawn = await cards.draw(deck.deck_id, { count: 2 });
console.log(`Drew: ${drawn.cards.map((c) => c.code).join(', ')}`);
```

## Usage Examples

### Create a Deck

```javascript
// Basic deck
const deck = await cards.deck();

// With options
const customDeck = await cards.deck({
  shuffle: true, // Shuffle the deck
  deck_count: 2, // Use 2 decks (104 cards)
  jokers_enabled: true // Include jokers (2 per deck)
});
```

### Draw Cards

```javascript
// Draw 5 cards
const result = await cards.draw(deck.deck_id, { count: 5 });

// Draw specific cards
const specificCards = await cards.draw(deck.deck_id, {
  cards: ['AS', 'KS', 'QD', 'JC', '10H']
});
```

### Manage Piles

Shuffle the pile.

```javascript
import * as cards from 'deckofcards-api';

const deck = await cards.deck();
const pileName = 'discards';
await cards.pile(deck.deck_id, pileName).shuffle();
```

##### pile(deckId, pileName).show()

Show cards in the pile.

```javascript
import * as cards from 'deckofcards-api';

const deck = await cards.deck();
const pileName = 'discards';
await cards.pile(deck.deck_id, pileName).show();
```

##### pile(deckId, pileName).return(options)

Return cards from a pile back to the deck.

```javascript
import * as cards from 'deckofcards-api';

const deck = await cards.deck();
const pileName = 'discards';

// Return specific cards
await cards.pile(deck.deck_id, pileName).return({ cards: ['AS', 'KS'] });

// OR return all cards from pile
await cards.pile(deck.deck_id, pileName).return();
```

##### returnCards(deckId, options)

Return cards to the deck.

```javascript
import * as cards from 'deckofcards-api';

const deck = await cards.deck();

// Return specific cards to deck
await cards.returnCards(deck.deck_id, { cards: ['AS', 'KS'] });

// OR return all drawn cards
await cards.returnCards(deck.deck_id);
```

---
_Source: https://npm.io/package/deckofcards-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._