Interface ICardResource

Namespace

TcgDex.Resources

Assembly

TcgDex.CSharpSdk.dll

Reads cards.

public interface ICardResource

Methods

GetAsync(string, CancellationToken)

Fetches a single card by identifier.

Task<Card?> GetAsync(string id, CancellationToken cancellationToken = default)

Parameters

id string

The card id, for example "swsh3-136".

cancellationToken CancellationToken

Cancels the request.

Returns

Task<Card?>

The card, or null if no card has that id.

ListAsync(CancellationToken)

Lists cards in brief form.

Task<IReadOnlyList<CardBrief>> ListAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels the request.

Returns

Task<IReadOnlyList<CardBrief>>

Every card, as briefs.

Remarks

List responses carry only id, localId, name and image. Category, rarity and trainerType require fetching the full card.

ListAsync(CardQuery, CancellationToken)

Lists the cards matching a query.

Task<IReadOnlyList<CardBrief>> ListAsync(CardQuery query, CancellationToken cancellationToken = default)

Parameters

query CardQuery

Filters, sorting and pagination.

cancellationToken CancellationToken

Cancels the request.

Returns

Task<IReadOnlyList<CardBrief>>

The matching cards, as briefs.

Remarks

The API reports no total count, so a page shorter than the requested size is the only signal that the results are exhausted.

Exceptions

ArgumentNullException

query is null.

SearchDetailedAsync(CardFilter, int?, int?, CancellationToken)

Searches for cards and returns each one fully detailed in a single request, using GraphQL.

Task<IReadOnlyList<Card>> SearchDetailedAsync(CardFilter filter, int? page = null, int? itemsPerPage = null, CancellationToken cancellationToken = default)

Parameters

filter CardFilter

Equality filters. GraphQL supports no other kind.

page int?

Optional 1-based page number.

itemsPerPage int?

Optional page size.

cancellationToken CancellationToken

Cancels the request.

Returns

Task<IReadOnlyList<Card>>

The matching cards, fully populated.

Remarks

Use this to avoid N+1: TcgDex.Resources.ICardResource.ListAsync(TcgDex.Querying.CardQuery,System.Threading.CancellationToken) returns briefs, so fetching full detail for a 12-card result costs 13 requests against REST versus 1 here.

Three limits come with it, all imposed by the GraphQL endpoint rather than by this SDK: results are always English regardless of the configured language, filters are equality-only, and TcgDex.Models.Card.Pricing is never populated. When any of those matter, use the REST path instead.

Exceptions

ArgumentNullException

filter is null.

TcgDexApiException

The query failed or the server reported errors.

StreamAsync(CardQuery, int, CancellationToken)

Streams every card matching a query, fetching pages as they are consumed.

IAsyncEnumerable<CardBrief> StreamAsync(CardQuery query, int pageSize = 100, CancellationToken cancellationToken = default)

Parameters

query CardQuery

Filters and sorting. Any page set on it is ignored.

pageSize int

How many results to fetch per request.

cancellationToken CancellationToken

Stops enumeration and cancels the in-flight request.

Returns

IAsyncEnumerable<CardBrief>

An async sequence over every match.

Remarks

The API reports no total count and sends no pagination headers, so the end of the results can only be detected by receiving a page shorter than requested. Hand-rolling that loop is easy to get subtly wrong; this does it once.

Pages are fetched lazily, so breaking out of the loop early stops the requests. Nothing is buffered beyond the current page.

Exceptions

ArgumentNullException

query is null.

ArgumentOutOfRangeException

pageSize is less than one.