cards api

[atrieongithubappdev]

Background:

We need to integrate a Deck of Cards API into the memory-matching-game so the app can fetch randomized card decks and card images at runtime instead of using hard-coded/static assets. The Deck of Cards API (e.g., https://deckofcardsapi.com/) is a lightweight public API that supports creating shuffled decks, drawing cards, reshuffling, and obtaining card images.

Acceptance criteria:

1. The game can request a new shuffled deck and draw the required number of cards for a game session.

2. Card objects returned by the API are mapped to the game's internal card model (id, suit, value, imageUrl, matched:boolean).

3. The UI displays card images retrieved from the API and handles loading states and errors gracefully.

4. Unit tests or integration tests are added for the deck-fetching logic and card mapping.

Suggested steps to implement:

1. Create a DeckService module

2. Implement API client functions

3. Deck creation flow

4. Drawing cards and mapping to game model

5. Caching and retries

6. Error handling and loading states

7. Tests

8. Documentation

9. Optional: local fallback for offline or rate-limit situations

Implementation details (examples):

1. Create a DeckService module

• Add a new file src/services/deckService.ts (or .js depending on project stack).

• Export functions: createShuffledDeck(), drawCards(deckId, count), shuffleDeck(deckId), returnToDeck(deckId).

2. Implement API client functions

• createShuffledDeck(): POST/GET to https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1

• drawCards(deckId, count): GET https://deckofcardsapi.com/api/deck/{deckId}/draw/?count={count}

• Example response fields to use: deck_id, remaining, cards[]. Each card has code, image, images, value, suit.

• Map the API response to the game's card model. Example mapping:

  • id: card.code

  • suit: card.suit

  • value: card.value

  • imageUrl: card.image (use images.svg or images.png as fallback)

  • matched: false

3. Deck creation flow

• On game start, call createShuffledDeck() to get deck_id.

• Call drawCards(deck_id, neededCount) to fetch the card set for the board.

• For a matching game, ensure pairs are created: if API returns unique cards, duplicate each card object to create pairings and then shuffle locally.

4. Drawing cards and mapping to game model

• After drawing, transform cards to internal model and duplicate for pairs.

• Shuffle the combined array before setting game state.

5. Caching and retries

• Cache deck_id and fetched cards for the session in memory (no need to persist across reloads unless desired).

• Implement exponential backoff retries for transient network errors.

6. Error handling and loading states

• Show a loading spinner when fetching deck/cards.

• If fetching fails, surface a friendly error and provide a retry button.

• Fallback: use a bundled local deck JSON if API is unreachable.

7. Tests

• Unit test mapping function: given a sample API response, assert correct transformation to internal model.

• Integration test for DeckService using mocked fetch responses to validate createShuffledDeck() and drawCards().

8. Documentation

• Update README or docs/ deck-integration.md with the integration steps, endpoints used, example responses, and testing instructions.

9. Optional: local fallback

• Include a small local JSON file with card objects and images to use when the API is down or offline.

Security/Notes:

• The Deck of Cards API is public and does not require authentication for basic usage.

• Respect rate limits and add a simple client-side throttle if the game will create decks rapidly.

• Ensure image URLs are served over HTTPS.

Developer tasks (suggested GitHub issues/subtasks):

• Implement DeckService and client functions

• Integrate deck fetching into game start flow

• Map API cards to internal model and create pairs

• Add UI loading and error states

• Add unit and integration tests

• Add documentation and example usage

Example pseudo-code (JavaScript/TypeScript):

async function createShuffledDeck() {
const res = await fetch('https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1');
const data = await res.json();
return data.deck_id;
}

async function drawCards(deckId, count) {
const res = await fetch(https://deckofcardsapi.com/api/deck/${deckId}/draw/?count=${count});
const data = await res.json();
return data.cards.map(c => ({
id: c.code,
suit: c.suit,
value: c.value,
imageUrl: c.image,
matched: false,
}));
}

Notes for reviewers:

• Please confirm the preferred file locations and naming conventions for services in this repo.

• If the team prefers a different card provider (or using local assets), we can adjust the implementation accordingly.