@my-swu/simulator-client 0.1.0

package/dist/resources/card-deck-json.js

@@ -0,0 +1,164 @@
+import { jsonBody, jsonHeaders } from '../http/json.js';
+import { referenceLabel, requireResolvedCardId } from './card-resolution.js';
+/**
+ * Converts one my-swu JSON deck export into simulator deck input.
+ *
+ * Token cards (the Credit or Force token, …) can ride along in deck
+ * exports but are not deck cards — deck and sideboard entries that only
+ * resolve to a token are skipped instead of failing the import.
+ */
+export async function convertDeckJson(requester, input, options) {
+    const deckJson = parseDeckJson(input);
+    const pending = collectPendingDeckJsonReferences(deckJson);
+    const resolutions = await requester.request('resolve-card-ids-response', '/api/cards/resolve', {
+        body: jsonBody(requester.validate('resolve-card-ids-request', {
+            references: pending.map(item => item.reference),
+        })),
+        headers: jsonHeaders(),
+        method: 'POST',
+    }, options).then(response => response.resolutions);
+    const leaders = [];
+    let base;
+    const cards = [];
+    const sideboard = [];
+    pending.forEach((item, index) => {
+        if (item.section === 'leader' || item.section === 'base') {
+            const cardId = requireResolvedCardId(resolutions[index], referenceLabel(item.reference));
+            if (item.section === 'leader') {
+                leaders.push(cardId);
+            }
+            else {
+                base = cardId;
+            }
+            return;
+        }
+        const cardId = pickDeckCardId(resolutions[index], referenceLabel(item.reference));
+        if (cardId == null) {
+            return;
+        }
+        if (item.section === 'deck') {
+            cards.push(...Array.from({ length: item.count }, () => cardId));
+        }
+        else {
+            sideboard.push(...Array.from({ length: item.count }, () => cardId));
+        }
+    });
+    return {
+        ...(leaders.length === 1 ? { leader: leaders[0] } : {}),
+        leaders: leaders.length > 1 ? leaders : [],
+        ...(base == null ? {} : { base }),
+        cards,
+        sideboard,
+    };
+}
+/**
+ * Resolves one deck/sideboard entry, skipping token-only references.
+ *
+ * Returns `undefined` when the entry only matches token cards so the
+ * caller can strip it from the converted deck. When a token shares a
+ * printed number with a regular card, the regular card wins.
+ */
+function pickDeckCardId(resolution, label) {
+    if (resolution == null || resolution.matches.length === 0) {
+        throw new Error(`card reference ${label} was not found`);
+    }
+    const deckMatches = resolution.matches.filter(match => match.cardType !== 'token');
+    const [deckMatch] = deckMatches;
+    if (deckMatches.length === 1 && deckMatch != null) {
+        return deckMatch.cardId;
+    }
+    if (deckMatch == null) {
+        return undefined;
+    }
+    const matches = deckMatches
+        .map(match => `${match.cardId} (${match.cardType}: ${match.title})`)
+        .join(', ');
+    throw new Error(`card reference ${label} is ambiguous: ${matches}`);
+}
+/**
+ * Collects card references from one my-swu JSON deck by deck section.
+ */
+function collectPendingDeckJsonReferences(deckJson) {
+    const pending = [];
+    if (deckJson.leader != null) {
+        pending.push({
+            count: 1,
+            reference: referenceFromDeckJsonId(deckJson.leader.id, ['leader']),
+            section: 'leader',
+        });
+    }
+    if (deckJson.secondleader != null) {
+        pending.push({
+            count: 1,
+            reference: referenceFromDeckJsonId(deckJson.secondleader.id, ['leader']),
+            section: 'leader',
+        });
+    }
+    if (deckJson.base != null) {
+        pending.push({
+            count: 1,
+            reference: referenceFromDeckJsonId(deckJson.base.id, ['base']),
+            section: 'base',
+        });
+    }
+    for (const entry of deckJson.deck ?? []) {
+        pending.push({
+            count: entryCount(entry),
+            reference: referenceFromDeckJsonId(entry.id, ['unit', 'event', 'upgrade', 'token']),
+            section: 'deck',
+        });
+    }
+    for (const entry of deckJson.sideboard ?? []) {
+        pending.push({
+            count: entryCount(entry),
+            reference: referenceFromDeckJsonId(entry.id, ['unit', 'event', 'upgrade', 'token']),
+            section: 'sideboard',
+        });
+    }
+    return pending;
+}
+/**
+ * Parses one deck JSON object or JSON string.
+ */
+function parseDeckJson(input) {
+    if (typeof input !== 'string') {
+        return input;
+    }
+    const parsed = JSON.parse(input);
+    if (parsed == null || typeof parsed !== 'object') {
+        throw new Error('deck JSON must be an object');
+    }
+    return parsed;
+}
+/**
+ * Converts one `SET_001` deck JSON id into a card-reference lookup.
+ */
+function referenceFromDeckJsonId(id, cardTypes) {
+    const match = /^([A-Za-z0-9]+)_(\d+)$/.exec(id.trim());
+    if (match == null) {
+        throw new Error(`deck JSON card id must use SET_001 form: ${id}`);
+    }
+    const setCode = match[1];
+    const cardNumberText = match[2];
+    if (setCode == null || cardNumberText == null) {
+        throw new Error(`deck JSON card id must use SET_001 form: ${id}`);
+    }
+    const cardNumber = Number.parseInt(cardNumberText, 10);
+    if (!Number.isSafeInteger(cardNumber) || cardNumber <= 0) {
+        throw new Error(`deck JSON card id has invalid card number: ${id}`);
+    }
+    return {
+        setCode: setCode.toUpperCase(),
+        cardNumber,
+        cardTypes,
+    };
+}
+/**
+ * Returns one positive card count from a deck JSON entry.
+ */
+function entryCount(entry) {
+    if (!Number.isInteger(entry.count) || entry.count <= 0) {
+        throw new Error(`deck JSON card count must be a positive integer for ${entry.id}`);
+    }
+    return entry.count;
+}

package/dist/resources/card-resolution.d.ts

@@ -0,0 +1,9 @@
+import type { CardIdResolution, CardReferenceInput } from './card-types.js';
+/**
+ * Returns the unique resolved card id or throws a useful import error.
+ */
+export declare function requireResolvedCardId(resolution: CardIdResolution | undefined, label: string): number;
+/**
+ * Formats one card reference for importer error messages.
+ */
+export declare function referenceLabel(reference: CardReferenceInput): string;

package/dist/resources/card-resolution.js

@@ -0,0 +1,21 @@
+/**
+ * Returns the unique resolved card id or throws a useful import error.
+ */
+export function requireResolvedCardId(resolution, label) {
+    if (resolution == null || resolution.matches.length === 0) {
+        throw new Error(`card reference ${label} was not found`);
+    }
+    if (resolution.cardId == null) {
+        const matches = resolution.matches
+            .map(match => `${match.cardId} (${match.cardType}: ${match.title})`)
+            .join(', ');
+        throw new Error(`card reference ${label} is ambiguous: ${matches}`);
+    }
+    return resolution.cardId;
+}
+/**
+ * Formats one card reference for importer error messages.
+ */
+export function referenceLabel(reference) {
+    return `${reference.setCode}_${String(reference.cardNumber).padStart(3, '0')}`;
+}

package/dist/resources/card-resource.d.ts

@@ -0,0 +1,157 @@
+import type { SimulatorRequestOptions } from '../http/options.js';
+import type { EngineHttpRequester } from '../http/request.js';
+import type { CardIdResolution, CardMetadata, CardReferenceInput, DeckInput, DeckJson } from './card-types.js';
+/**
+ * Card metadata and deck import API methods.
+ *
+ * Use this resource to fetch canonical display metadata and convert my-swu
+ * JSON deck exports before creating a match.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const requestedCardMetadata = await simulatorClient.cards.get([46102, 308])
+ * console.log(requestedCardMetadata.map(card => card.title))
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids
+ * @see https://simulator-sdk.my-swu.com/guide/client-api
+ */
+export interface CardsResource {
+    /**
+     * Fetches canonical metadata for the requested card ids.
+     *
+     * Use this when snapshots or deck lists only contain card ids and your UI
+     * needs titles, aspects, traits, cost, rules text, or other display metadata.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const requestedCardMetadata = await simulatorClient.cards.get([46102, 308])
+     * console.log(requestedCardMetadata.map(card => card.title))
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/card-ids
+     */
+    get(ids: number[], options?: SimulatorRequestOptions): Promise<CardMetadata[]>;
+    /**
+     * Lists canonical production card metadata for every card identity.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const catalog = await simulatorClient.cards.catalog()
+     * console.log(catalog.length)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/client-api
+     */
+    catalog(options?: SimulatorRequestOptions): Promise<CardMetadata[]>;
+    /**
+     * Converts a my-swu JSON deck export into simulator deck input.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const importedDeck = await simulatorClient.cards.convertDeckJson({
+     *   leader: { id: 'SOR_001', count: 1 },
+     *   base: { id: 'SOR_025', count: 1 },
+     *   deck: [{ id: 'SOR_010', count: 3 }],
+     * })
+     *
+     * console.log(importedDeck.cards.length)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/card-ids#json-deck-imports
+     */
+    convertDeckJson(deckJson: DeckJson | string, options?: SimulatorRequestOptions): Promise<DeckInput>;
+    /**
+     * Resolves one set-code/card-number reference into one card id.
+     *
+     * This helper throws when the reference is not found or stays ambiguous after
+     * applying `cardTypes`.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const krennicCardId = await simulatorClient.cards.resolveId({
+     *   setCode: 'SOR',
+     *   cardNumber: 1,
+     *   cardTypes: [
+     *     'leader',
+     *   ],
+     * })
+     *
+     * console.log(krennicCardId)
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/card-ids#resolving-card-ids
+     */
+    resolveId(reference: CardReferenceInput, options?: SimulatorRequestOptions): Promise<number>;
+    /**
+     * Resolves set-code/card-number references through the simulator card cache.
+     *
+     * Use this for bulk deck imports so you can show all not-found and ambiguous
+     * references together instead of failing at the first issue.
+     *
+     * @example
+     * ```ts
+     * import { createSimulatorClient } from '@my-swu/simulator-client'
+     *
+     * const simulatorClient = createSimulatorClient({
+     *   baseUrl: 'http://127.0.0.1:4000',
+     * })
+     *
+     * const cardIdResolutions = await simulatorClient.cards.resolveIds([
+     *   {
+     *     setCode: 'SOR',
+     *     cardNumber: 1,
+     *     cardTypes: [
+     *       'leader',
+     *     ],
+     *   },
+     *   {
+     *     setCode: 'SOR',
+     *     cardNumber: 25,
+     *     cardTypes: [
+     *       'base',
+     *     ],
+     *   },
+     * ])
+     *
+     * console.log(cardIdResolutions.map(result => result.cardId))
+     * ```
+     *
+     * @see https://simulator-sdk.my-swu.com/guide/card-ids#resolving-card-ids
+     */
+    resolveIds(references: CardReferenceInput[], options?: SimulatorRequestOptions): Promise<CardIdResolution[]>;
+}
+/**
+ * Creates the cards resource client from the shared HTTP requester.
+ */
+export declare function createCardsResource(requester: EngineHttpRequester): CardsResource;

package/dist/resources/card-resource.js

@@ -0,0 +1,28 @@
+import { jsonBody, jsonHeaders } from '../http/json.js';
+import { convertDeckJson } from './card-deck-json.js';
+import { referenceLabel, requireResolvedCardId } from './card-resolution.js';
+/**
+ * Creates the cards resource client from the shared HTTP requester.
+ */
+export function createCardsResource(requester) {
+    const resolveIds = (references, options) => requester.request('resolve-card-ids-response', '/api/cards/resolve', {
+        body: jsonBody(requester.validate('resolve-card-ids-request', { references })),
+        headers: jsonHeaders(),
+        method: 'POST',
+    }, options).then(response => response.resolutions);
+    return {
+        catalog: options => requester.request('cards-response', '/api/cards/catalog', {}, options)
+            .then(response => response.cards),
+        convertDeckJson: (deckJson, options) => convertDeckJson(requester, deckJson, options),
+        get: (ids, options) => {
+            const query = new URLSearchParams({ ids: ids.join(',') });
+            return requester.request('cards-response', `/api/cards?${query.toString()}`, {}, options)
+                .then(response => response.cards);
+        },
+        resolveId: async (reference, options) => {
+            const [resolution] = await resolveIds([reference], options);
+            return requireResolvedCardId(resolution, referenceLabel(reference));
+        },
+        resolveIds,
+    };
+}

package/dist/resources/card-types.d.ts

@@ -0,0 +1,203 @@
+import type { CardMetadataView } from '../generated/types/cards-response.js';
+import type { DeckInput as GeneratedDeckInput } from '../generated/types/create-match-request.js';
+import type { CardReferenceInput as GeneratedCardReferenceInput, CardType } from '../generated/types/resolve-card-ids-request.js';
+import type { CardIdResolutionView } from '../generated/types/resolve-card-ids-response.js';
+/**
+ * Canonical card metadata returned by `cards.get()`.
+ *
+ * Use this type when rendering names, traits, aspects, rules text, or other
+ * stable card display data for card ids that appear in decks, snapshots, and
+ * commands.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, type CardMetadata } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const requestedCardMetadata: CardMetadata[] =
+ *   await simulatorClient.cards.get([46102, 308])
+ * console.log(requestedCardMetadata[0]?.title)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids
+ */
+export type CardMetadata = CardMetadataView;
+/**
+ * Deck payload accepted by match creation and join calls.
+ *
+ * The same shape is used for Premier, Eternal, Trilogy, Draft, Sealed, Twin
+ * Suns, and AI opponent decks. The server validates format-specific legality
+ * when the deck is submitted.
+ *
+ * @example
+ * ```ts
+ * import type { DeckInput } from '@my-swu/simulator-client'
+ *
+ * const premierDeck: DeckInput = {
+ *   leader: 46102,
+ *   leaders: [],
+ *   base: 308,
+ *   cards: Array.from({ length: 50 }, () => 45),
+ *   sideboard: [],
+ * }
+ *
+ * console.log(premierDeck.cards.length)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/deckbuilding-formats
+ */
+export type DeckInput = GeneratedDeckInput;
+/**
+ * Set-code/card-number lookup input.
+ *
+ * Use this for imports from deck tools that identify cards as `SOR_001` or as
+ * separate set code plus printed card number values.
+ *
+ * @example
+ * ```ts
+ * import type { CardReferenceInput } from '@my-swu/simulator-client'
+ *
+ * const leaderReference: CardReferenceInput = {
+ *   setCode: 'SOR',
+ *   cardNumber: 1,
+ *   cardTypes: [
+ *     'leader',
+ *   ],
+ * }
+ *
+ * console.log(leaderReference.setCode)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids#resolving-card-ids
+ */
+export type CardReferenceInput = GeneratedCardReferenceInput;
+/**
+ * Set-code/card-number lookup result.
+ *
+ * `cardId` is present only when the lookup produced exactly one match. When it
+ * is missing, inspect `matches` to show a not-found or ambiguous-reference UI.
+ *
+ * @example
+ * ```ts
+ * import { createSimulatorClient, type CardIdResolution } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ * })
+ *
+ * const [leaderResolution]: CardIdResolution[] =
+ *   await simulatorClient.cards.resolveIds([
+ *     {
+ *       setCode: 'SOR',
+ *       cardNumber: 1,
+ *       cardTypes: [
+ *         'leader',
+ *       ],
+ *     },
+ *   ])
+ * console.log(leaderResolution?.cardId)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids#resolving-card-ids
+ */
+export type CardIdResolution = CardIdResolutionView;
+/**
+ * Card type labels accepted by card reference lookup.
+ *
+ * Pass these when a set number can refer to more than one card type, such as
+ * leaders, bases, or tokens sharing printed numbers.
+ *
+ * @example
+ * ```ts
+ * import type { CardReferenceType } from '@my-swu/simulator-client'
+ *
+ * const leaderOnly: CardReferenceType[] = [
+ *   'leader',
+ * ]
+ * console.log(leaderOnly.includes('leader'))
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids#resolving-card-ids
+ */
+export type CardReferenceType = CardType;
+/**
+ * One card entry in my-swu JSON deck exports.
+ *
+ * @example
+ * ```ts
+ * import type { DeckJsonCard } from '@my-swu/simulator-client'
+ *
+ * const exportedCard: DeckJsonCard = {
+ *   id: 'SOR_010',
+ *   count: 3,
+ * }
+ *
+ * console.log(exportedCard.id)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids#json-deck-imports
+ */
+export interface DeckJsonCard {
+    /**
+     * Exported card id in `SET_001` form.
+     */
+    id: string;
+    /**
+     * Number of copies in this section.
+     */
+    count: number;
+}
+/**
+ * my-swu JSON deck export shape accepted by `cards.convertDeckJson()`.
+ *
+ * Unknown `metadata` contents and `reserve` cards are ignored because they are
+ * deckbuilder annotations, not simulator deck input.
+ *
+ * @example
+ * ```ts
+ * import type { DeckJson } from '@my-swu/simulator-client'
+ *
+ * const exportedDeck: DeckJson = {
+ *   leader: { id: 'SOR_001', count: 1 },
+ *   base: { id: 'SOR_025', count: 1 },
+ *   deck: [{ id: 'SOR_010', count: 3 }],
+ * }
+ *
+ * console.log(exportedDeck.deck?.length)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/card-ids#json-deck-imports
+ */
+export interface DeckJson {
+    /**
+     * Optional deck metadata. Ignored by simulator deck conversion.
+     */
+    metadata?: unknown;
+    /**
+     * Primary leader entry.
+     */
+    leader?: DeckJsonCard | null;
+    /**
+     * Optional second leader entry used by Twin Suns exports.
+     */
+    secondleader?: DeckJsonCard | null;
+    /**
+     * Base entry.
+     */
+    base?: DeckJsonCard | null;
+    /**
+     * Main-deck card entries.
+     */
+    deck?: DeckJsonCard[];
+    /**
+     * Sideboard entries.
+     */
+    sideboard?: DeckJsonCard[];
+    /**
+     * Reserved cards from deckbuilding notes. Ignored by simulator deck conversion.
+     */
+    reserve?: DeckJsonCard[];
+}

package/dist/resources/card-types.js

@@ -0,0 +1 @@
+export {};

package/dist/resources/cards.d.ts

@@ -0,0 +1,3 @@
+export type { CardIdResolution, CardMetadata, CardReferenceInput, CardReferenceType, DeckInput, DeckJson, DeckJsonCard, } from './card-types.js';
+export type { CardsResource } from './card-resource.js';
+export { createCardsResource } from './card-resource.js';

package/dist/resources/cards.js

@@ -0,0 +1 @@
+export { createCardsResource } from './card-resource.js';