@pokemontcgapi/sdk 0.1.0

package/dist/errors.js

@@ -0,0 +1,116 @@
+/**
+ * Gerarchia degli errori.
+ *
+ * Sottoclassi e non un solo tipo con un campo `code`, per una ragione pratica:
+ * chi integra scrive `catch (e) { if (e instanceof RateLimited) ... }`, e con un
+ * tipo solo dovrebbe confrontare stringhe — cioe' riscrivere a mano la
+ * tassonomia che noi gia' conosciamo, sbagliando i nomi.
+ *
+ * `QuotaExceeded` e' separato da `RateLimited` di proposito: sembrano lo stesso
+ * errore (entrambi 429) ma si trattano in modo opposto. Un rate limit passa
+ * aspettando; una quota mensile finita non passa mai, e riprovare e' solo un
+ * modo di consumare tempo. Il retry automatico di questo client riprova il
+ * primo e non riprova mai il secondo.
+ */
+export class PokemonTcgApiError extends Error {
+    /** Codice stabile della tassonomia, es. `CARD_NOT_FOUND`. */
+    code;
+    status;
+    /**
+     * Sempre valorizzato quando la risposta e' passata dall'API: e' l'unica cosa
+     * che il supporto puo' cercare nei log. Va incluso in ogni bug report.
+     */
+    requestId;
+    details;
+    constructor(status, body) {
+        super(`${body.code}: ${body.message}`);
+        this.name = new.target.name;
+        this.code = body.code;
+        this.status = status;
+        this.requestId = body.request_id;
+        this.details = body.details;
+    }
+}
+/** 401 — chiave assente, malformata o revocata. */
+export class AuthenticationError extends PokemonTcgApiError {
+}
+/** 403 — la chiave e' valida ma non puo' fare questa cosa. */
+export class PermissionDeniedError extends PokemonTcgApiError {
+}
+/** 402 / UPGRADE_REQUIRED — serve un piano superiore. */
+export class UpgradeRequiredError extends PokemonTcgApiError {
+    /** Finestra concessa dal piano corrente, quando l'API la dichiara. */
+    get permittedWindow() {
+        return this.details?.['permitted_window'];
+    }
+}
+/** 404 — la risorsa non esiste. Non e' un errore di rete: non si riprova. */
+export class NotFoundError extends PokemonTcgApiError {
+}
+/** 400 / 422 — la richiesta e' sbagliata. `field` dice quale parametro. */
+export class InvalidRequestError extends PokemonTcgApiError {
+    get field() {
+        const value = this.details?.['field'];
+        return typeof value === 'string' ? value : undefined;
+    }
+}
+/** 429 con Retry-After: passa aspettando. */
+export class RateLimitedError extends PokemonTcgApiError {
+    /** Secondi da aspettare, dall'header `Retry-After`, se c'era. */
+    retryAfter;
+    constructor(status, body, retryAfter) {
+        super(status, body);
+        this.retryAfter = retryAfter;
+    }
+}
+/** 429 per quota di periodo esaurita: NON passa aspettando, e non si riprova. */
+export class QuotaExceededError extends PokemonTcgApiError {
+}
+/** 5xx. */
+export class ServerError extends PokemonTcgApiError {
+}
+/** La richiesta non e' mai arrivata: DNS, TLS, socket. */
+export class ApiConnectionError extends Error {
+    /** `override` perche' Error dichiara gia' `cause` da ES2022. */
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'ApiConnectionError';
+        this.cause = cause;
+    }
+}
+/** La richiesta e' stata abbandonata da noi dopo `timeout`. */
+export class ApiTimeoutError extends ApiConnectionError {
+    constructor(timeoutMs, cause) {
+        super(`Request timed out after ${timeoutMs}ms`, cause);
+        this.name = 'ApiTimeoutError';
+    }
+}
+/**
+ * Dal corpo dell'errore alla classe giusta.
+ *
+ * Si guarda PRIMA il `code` e poi lo status: lo status dice la famiglia, il
+ * code dice il caso, e i due casi che contano davvero (limite contro quota)
+ * condividono lo stesso status.
+ */
+export function toApiError(status, body, retryAfter) {
+    const code = body.code;
+    if (code === 'QUOTA_EXCEEDED' || code === 'MONTHLY_QUOTA_EXCEEDED')
+        return new QuotaExceededError(status, body);
+    if (code === 'UPGRADE_REQUIRED' || status === 402)
+        return new UpgradeRequiredError(status, body);
+    if (status === 429)
+        return new RateLimitedError(status, body, retryAfter);
+    if (status === 401)
+        return new AuthenticationError(status, body);
+    if (status === 403)
+        return new PermissionDeniedError(status, body);
+    if (status === 404 || code.endsWith('_NOT_FOUND'))
+        return new NotFoundError(status, body);
+    if (status >= 500)
+        return new ServerError(status, body);
+    if (status >= 400)
+        return new InvalidRequestError(status, body);
+    return new PokemonTcgApiError(status, body);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { HttpClient, Page, type ClientOptions } from './client.js';
+import type { Artist, BatchResult, Card, CardInclude, CardListParams, CardSet, CatalogStatus, Health, IdentifyOptions, ListParams, Locale, SetListParams, VisionResponse } from './types.js';
+export * from './errors.js';
+export * from './types.js';
+export { Page } from './client.js';
+export type { ClientOptions } from './client.js';
+/**
+ * Client di pokemontcgapi.com.
+ *
+ * Le risorse rispecchiano i path (`client.cards.get`, `client.sets.cards`) cosi'
+ * che passare dalla documentazione al codice non richieda una tabella di
+ * conversione. Ogni metodo di lista torna una `Page`, che e' anche un
+ * `AsyncIterable`: si itera e la paginazione sparisce.
+ *
+ * ```ts
+ * const client = new PokemonTcgApi({ apiKey: process.env.PTCG_API_KEY });
+ *
+ * const card = await client.cards.get('base1-4', { include: ['prices'] });
+ * console.log(card.name, card.index_eur);
+ *
+ * for await (const set of client.sets.list({ region: 'JP' })) {
+ *   console.log(set.code, set.name, set.release_date);
+ * }
+ * ```
+ */
+export declare class PokemonTcgApi {
+    private readonly http;
+    readonly cards: CardsResource;
+    readonly sets: SetsResource;
+    readonly artists: ArtistsResource;
+    readonly reference: ReferenceResource;
+    readonly vision: VisionResource;
+    constructor(options?: ClientOptions);
+    /** Conteggi di catalogo e freschezza per fonte. */
+    status(): Promise<CatalogStatus>;
+    /** Liveness. Separato da `status()`: un ingest fermo non e' un servizio giu'. */
+    health(): Promise<Health>;
+}
+declare class CardsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Ricerca sul catalogo. Torna la prima pagina, iterabile fino in fondo. */
+    search(params?: CardListParams): Promise<Page<Card>>;
+    /** Una carta per id. Accetta sia l'id nostro sia l'id alternativo. */
+    get(id: string, params?: {
+        select?: readonly string[];
+        include?: readonly CardInclude[];
+        lang?: Locale;
+    }): Promise<Card>;
+    /**
+     * Fino a 100 id in una richiesta.
+     *
+     * La risposta porta `requested` e `found`: gli id che non esistono vengono
+     * semplicemente omessi da `data`, non segnalati uno per uno. Confrontare i due
+     * numeri e' l'unico modo di accorgersene, quindi il tipo li espone entrambi.
+     */
+    batch(ids: readonly string[], params?: {
+        select?: readonly string[];
+        include?: readonly CardInclude[];
+        lang?: Locale;
+    }): Promise<BatchResult<Card>>;
+}
+declare class SetsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Elenco dei set. `region` e' il filtro che vale la pena conoscere: `JP`
+     * restituisce le uscite giapponesi, che sono la parte piu' grande del
+     * catalogo e non sono traduzioni di quelle occidentali.
+     */
+    list(params?: SetListParams): Promise<Page<CardSet>>;
+    /** Un set per codice, slug o id alternativo. */
+    get(code: string): Promise<CardSet>;
+    /** Le carte di un set, in ordine di collezione. */
+    cards(code: string, params?: CardListParams): Promise<Page<Card>>;
+}
+declare class ArtistsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params?: ListParams): Promise<Page<Artist>>;
+    get(slug: string): Promise<Artist>;
+}
+/**
+ * I vocabolari chiusi, per popolare i filtri di una UI senza indovinare le
+ * stringhe.
+ *
+ * `subtypes()` oggi torna una lista VUOTA: la colonna esiste ma non e'
+ * popolata su nessuna carta. Il metodo resta perche' il giorno in cui lo sara'
+ * non serve una nuova versione dell'SDK — ma non costruirci sopra una UI che
+ * assume almeno un elemento.
+ */
+declare class ReferenceResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    private list;
+    types(): Promise<readonly string[]>;
+    /** Vuoto al 2026-08-27. Vedi la nota sulla classe. */
+    subtypes(): Promise<readonly string[]>;
+    supertypes(): Promise<readonly string[]>;
+    rarities(): Promise<readonly string[]>;
+}
+/**
+ * Riconoscimento di una carta da una fotografia.
+ *
+ * Costa 25 crediti a chiamata contro l'uno di una lettura: e' l'unica rotta che
+ * non restituisce una riga ma l'esito del confronto con l'intero indice delle
+ * immagini. Vale la pena saperlo prima di metterla in un ciclo.
+ */
+declare class VisionResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Manda una foto, ricevi i candidati in ordine.
+     *
+     * `image` accetta qualunque cosa `FormData` sappia allegare: un `Blob`, un
+     * `File` da un `<input capture="environment">`, o un `Uint8Array` che viene
+     * avvolto qui.
+     *
+     * **Leggi `decision` prima di `id`.** `id` e' valorizzato solo su `match`; su
+     * `ambiguous` e' `null` di proposito, perche' due stampe della stessa
+     * illustrazione dall'immagine sola non sono distinguibili e sceglierne una
+     * significa sbagliare meta' delle volte, proprio sulle carte che valgono di
+     * piu'. Se il tuo flusso sa da che set viene — chi inventaria una busta
+     * appena aperta lo sa — passalo in `set`: e' cio' che scioglie il pareggio.
+     *
+     * ```ts
+     * const { data } = await client.vision.identify(file, { set: 'sv3' });
+     * if (data.decision === 'match') add(data.id!);
+     * else showPicker(data.candidates);
+     * ```
+     */
+    identify(image: Blob | Uint8Array | ArrayBuffer, options?: IdentifyOptions): Promise<VisionResponse>;
+}
+export default PokemonTcgApi;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,202 @@
+import { HttpClient, Page } from './client.js';
+export * from './errors.js';
+export * from './types.js';
+export { Page } from './client.js';
+/**
+ * Client di pokemontcgapi.com.
+ *
+ * Le risorse rispecchiano i path (`client.cards.get`, `client.sets.cards`) cosi'
+ * che passare dalla documentazione al codice non richieda una tabella di
+ * conversione. Ogni metodo di lista torna una `Page`, che e' anche un
+ * `AsyncIterable`: si itera e la paginazione sparisce.
+ *
+ * ```ts
+ * const client = new PokemonTcgApi({ apiKey: process.env.PTCG_API_KEY });
+ *
+ * const card = await client.cards.get('base1-4', { include: ['prices'] });
+ * console.log(card.name, card.index_eur);
+ *
+ * for await (const set of client.sets.list({ region: 'JP' })) {
+ *   console.log(set.code, set.name, set.release_date);
+ * }
+ * ```
+ */
+export class PokemonTcgApi {
+    http;
+    cards;
+    sets;
+    artists;
+    reference;
+    vision;
+    constructor(options = {}) {
+        this.http = new HttpClient(options);
+        this.cards = new CardsResource(this.http);
+        this.sets = new SetsResource(this.http);
+        this.artists = new ArtistsResource(this.http);
+        this.reference = new ReferenceResource(this.http);
+        this.vision = new VisionResource(this.http);
+    }
+    /** Conteggi di catalogo e freschezza per fonte. */
+    status() {
+        return this.http.get('/v1/status');
+    }
+    /** Liveness. Separato da `status()`: un ingest fermo non e' un servizio giu'. */
+    health() {
+        return this.http.get('/v1/health');
+    }
+}
+class CardsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Ricerca sul catalogo. Torna la prima pagina, iterabile fino in fondo. */
+    async search(params = {}) {
+        const body = await this.http.get('/v1/cards', { ...params });
+        return new Page(this.http, body);
+    }
+    /** Una carta per id. Accetta sia l'id nostro sia l'id alternativo. */
+    get(id, params = {}) {
+        return this.http.get(`/v1/cards/${encodeURIComponent(id)}`, { ...params });
+    }
+    /**
+     * Fino a 100 id in una richiesta.
+     *
+     * La risposta porta `requested` e `found`: gli id che non esistono vengono
+     * semplicemente omessi da `data`, non segnalati uno per uno. Confrontare i due
+     * numeri e' l'unico modo di accorgersene, quindi il tipo li espone entrambi.
+     */
+    batch(ids, params = {}) {
+        if (ids.length === 0)
+            return Promise.resolve({ data: [], requested: 0, found: 0 });
+        if (ids.length > 100) {
+            throw new RangeError(`batch() accepts at most 100 ids, received ${ids.length}. Chunk the list.`);
+        }
+        return this.http.get('/v1/cards/batch', { ids, ...params });
+    }
+}
+class SetsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Elenco dei set. `region` e' il filtro che vale la pena conoscere: `JP`
+     * restituisce le uscite giapponesi, che sono la parte piu' grande del
+     * catalogo e non sono traduzioni di quelle occidentali.
+     */
+    async list(params = {}) {
+        const body = await this.http.get('/v1/sets', { ...params });
+        return new Page(this.http, body);
+    }
+    /** Un set per codice, slug o id alternativo. */
+    get(code) {
+        return this.http.get(`/v1/sets/${encodeURIComponent(code)}`);
+    }
+    /** Le carte di un set, in ordine di collezione. */
+    async cards(code, params = {}) {
+        const body = await this.http.get(`/v1/sets/${encodeURIComponent(code)}/cards`, { ...params });
+        return new Page(this.http, body);
+    }
+}
+class ArtistsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async list(params = {}) {
+        const body = await this.http.get('/v1/artists', { ...params });
+        return new Page(this.http, body);
+    }
+    get(slug) {
+        return this.http.get(`/v1/artists/${encodeURIComponent(slug)}`);
+    }
+}
+/**
+ * I vocabolari chiusi, per popolare i filtri di una UI senza indovinare le
+ * stringhe.
+ *
+ * `subtypes()` oggi torna una lista VUOTA: la colonna esiste ma non e'
+ * popolata su nessuna carta. Il metodo resta perche' il giorno in cui lo sara'
+ * non serve una nuova versione dell'SDK — ma non costruirci sopra una UI che
+ * assume almeno un elemento.
+ */
+class ReferenceResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async list(path) {
+        const body = await this.http.get(path);
+        return body.data;
+    }
+    types() {
+        return this.list('/v1/types');
+    }
+    /** Vuoto al 2026-08-27. Vedi la nota sulla classe. */
+    subtypes() {
+        return this.list('/v1/subtypes');
+    }
+    supertypes() {
+        return this.list('/v1/supertypes');
+    }
+    rarities() {
+        return this.list('/v1/rarities');
+    }
+}
+/**
+ * Riconoscimento di una carta da una fotografia.
+ *
+ * Costa 25 crediti a chiamata contro l'uno di una lettura: e' l'unica rotta che
+ * non restituisce una riga ma l'esito del confronto con l'intero indice delle
+ * immagini. Vale la pena saperlo prima di metterla in un ciclo.
+ */
+class VisionResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Manda una foto, ricevi i candidati in ordine.
+     *
+     * `image` accetta qualunque cosa `FormData` sappia allegare: un `Blob`, un
+     * `File` da un `<input capture="environment">`, o un `Uint8Array` che viene
+     * avvolto qui.
+     *
+     * **Leggi `decision` prima di `id`.** `id` e' valorizzato solo su `match`; su
+     * `ambiguous` e' `null` di proposito, perche' due stampe della stessa
+     * illustrazione dall'immagine sola non sono distinguibili e sceglierne una
+     * significa sbagliare meta' delle volte, proprio sulle carte che valgono di
+     * piu'. Se il tuo flusso sa da che set viene — chi inventaria una busta
+     * appena aperta lo sa — passalo in `set`: e' cio' che scioglie il pareggio.
+     *
+     * ```ts
+     * const { data } = await client.vision.identify(file, { set: 'sv3' });
+     * if (data.decision === 'match') add(data.id!);
+     * else showPicker(data.candidates);
+     * ```
+     */
+    async identify(image, options = {}) {
+        const form = new FormData();
+        form.set('image', toBlob(image), 'card');
+        if (options.topK !== undefined)
+            form.set('top_k', String(options.topK));
+        if (options.set !== undefined)
+            form.set('set', options.set);
+        if (options.region !== undefined)
+            form.set('region', options.region);
+        // Nessun content-type esplicito: il boundary del multipart lo scrive fetch,
+        // e impostarlo a mano produce un corpo che il server non riesce a separare.
+        return this.http.post('/v1/vision/identify', form);
+    }
+}
+/** Porta i byte grezzi in un Blob, lasciando passare cio' che gia' lo e'. */
+function toBlob(image) {
+    if (image instanceof Blob)
+        return image;
+    // Il tipo generico e non `image/jpeg`: il formato lo riconosce il server dai
+    // magic byte, e dichiarare quello sbagliato sarebbe peggio che tacere.
+    return new Blob([image], { type: 'application/octet-stream' });
+}
+export default PokemonTcgApi;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}