@xivdyetools/core 1.3.7

package/dist/types/index.d.ts

@@ -0,0 +1,409 @@
+/**
+ * @xivdyetools/core - Shared Type Definitions
+ *
+ * Type definitions for color science and FFXIV dyes
+ *
+ * @module types
+ */
+export type { Logger } from './logger.js';
+export { NoOpLogger, ConsoleLogger } from './logger.js';
+/**
+ * RGB color representation
+ * @example { r: 255, g: 0, b: 0 } // Red
+ */
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * HSV color representation (Hue, Saturation, Value)
+ * @example { h: 0, s: 100, v: 100 } // Bright red
+ */
+export interface HSV {
+    h: number;
+    s: number;
+    v: number;
+}
+/**
+ * Hexadecimal color string (branded type for type safety)
+ * Per R-1: Branded types prevent type confusion
+ * @example "#FF0000"
+ */
+export type HexColor = string & {
+    readonly __brand: 'HexColor';
+};
+/**
+ * Helper to create branded HexColor type with validation
+ * Per R-1: Validates hex format before creating branded type
+ * @throws {Error} If hex format is invalid
+ */
+export declare function createHexColor(hex: string): HexColor;
+/**
+ * Dye ID (branded type for type safety)
+ * Per R-1: Prevents accidental mixing with other numbers
+ */
+export type DyeId = number & {
+    readonly __brand: 'DyeId';
+};
+/**
+ * Helper to create branded DyeId type with validation
+ * Per R-1: Validates dye ID is in valid range (1-200)
+ */
+export declare function createDyeId(id: number): DyeId | null;
+/**
+ * Hue value (0-360 degrees, branded type)
+ * Per R-1: Prevents mixing with other angle values
+ */
+export type Hue = number & {
+    readonly __brand: 'Hue';
+};
+/**
+ * Helper to create branded Hue type with normalization
+ * Per R-1: Normalizes hue to 0-360 range
+ */
+export declare function createHue(hue: number): Hue;
+/**
+ * Saturation value (0-100 percent, branded type)
+ * Per R-1: Prevents mixing with other percentage values
+ */
+export type Saturation = number & {
+    readonly __brand: 'Saturation';
+};
+/**
+ * Helper to create branded Saturation type with clamping
+ * Per R-1: Clamps saturation to 0-100 range
+ */
+export declare function createSaturation(saturation: number): Saturation;
+/**
+ * Vision types supported by accessibility checker
+ */
+export type VisionType = 'normal' | 'deuteranopia' | 'protanopia' | 'tritanopia' | 'achromatopsia';
+/**
+ * 3x3 transformation matrix for colorblindness simulation
+ * [row][column] indexing for RGB to RGB transformation
+ */
+export type Matrix3x3 = [
+    [
+        number,
+        number,
+        number
+    ],
+    [
+        number,
+        number,
+        number
+    ],
+    [
+        number,
+        number,
+        number
+    ]
+];
+/**
+ * Colorblindness transformation matrices (Brettel 1997)
+ */
+export interface ColorblindMatrices {
+    deuteranopia: Matrix3x3;
+    protanopia: Matrix3x3;
+    tritanopia: Matrix3x3;
+    achromatopsia: Matrix3x3;
+}
+/**
+ * FFXIV dye object with color and metadata
+ */
+export interface Dye {
+    itemID: number;
+    id: number;
+    name: string;
+    hex: string;
+    rgb: RGB;
+    hsv: HSV;
+    category: string;
+    acquisition: string;
+    cost: number;
+    isMetallic: boolean;
+    isPastel: boolean;
+    isDark: boolean;
+    isCosmic: boolean;
+}
+/**
+ * Localized dye with optional translated name
+ */
+export interface LocalizedDye extends Dye {
+    localizedName?: string;
+}
+/**
+ * Supported locale codes
+ */
+export type LocaleCode = 'en' | 'ja' | 'de' | 'fr' | 'ko' | 'zh';
+/**
+ * Translation keys for UI labels
+ */
+export type TranslationKey = 'dye' | 'dark' | 'metallic' | 'pastel' | 'cosmic' | 'cosmicExploration' | 'cosmicFortunes';
+/**
+ * Harmony type keys
+ */
+export type HarmonyTypeKey = 'complementary' | 'analogous' | 'triadic' | 'splitComplementary' | 'tetradic' | 'square' | 'monochromatic' | 'compound' | 'shades';
+/**
+ * FFXIV Job keys for localization
+ */
+export type JobKey = 'paladin' | 'warrior' | 'darkKnight' | 'gunbreaker' | 'whiteMage' | 'scholar' | 'astrologian' | 'sage' | 'monk' | 'dragoon' | 'ninja' | 'samurai' | 'reaper' | 'viper' | 'bard' | 'machinist' | 'dancer' | 'blackMage' | 'summoner' | 'redMage' | 'pictomancer' | 'blueMage';
+/**
+ * FFXIV Grand Company keys for localization
+ */
+export type GrandCompanyKey = 'maelstrom' | 'twinAdder' | 'immortalFlames';
+/**
+ * Locale data structure matching generated JSON files
+ */
+export interface LocaleData {
+    locale: LocaleCode;
+    meta: {
+        version: string;
+        generated: string;
+        dyeCount: number;
+    };
+    labels: Record<TranslationKey, string>;
+    dyeNames: Record<string, string>;
+    categories: Record<string, string>;
+    acquisitions: Record<string, string>;
+    metallicDyeIds: number[];
+    harmonyTypes: Record<HarmonyTypeKey, string>;
+    visionTypes: Record<VisionType, string>;
+    jobNames: Record<JobKey, string>;
+    grandCompanyNames: Record<GrandCompanyKey, string>;
+}
+/**
+ * Locale preference for resolving user's preferred language
+ * Priority: explicit > guild > system > fallback
+ */
+export interface LocalePreference {
+    /** Explicit user selection (highest priority) */
+    explicit?: LocaleCode;
+    /** Guild/server preference (Discord only) */
+    guild?: string;
+    /** User's system language */
+    system?: string;
+    /** Fallback locale (always 'en') */
+    fallback: LocaleCode;
+}
+/**
+ * Universalis API response for item prices
+ */
+export interface PriceData {
+    itemID: number;
+    currentAverage: number;
+    currentMinPrice: number;
+    currentMaxPrice: number;
+    lastUpdate: number;
+}
+/**
+ * Cached API data with TTL and integrity checking
+ */
+export interface CachedData<T> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+    version?: string;
+    checksum?: string;
+}
+/**
+ * Preset palette category identifiers
+ */
+export type PresetCategory = 'jobs' | 'grand-companies' | 'seasons' | 'events' | 'aesthetics' | 'community';
+/**
+ * Metadata for a preset category
+ */
+export interface CategoryMeta {
+    /** Category identifier */
+    id?: string;
+    /** Display name (localized) */
+    name: string;
+    /** Category description */
+    description: string;
+    /** Optional icon/emoji */
+    icon?: string;
+}
+/**
+ * A preset color palette
+ */
+export interface PresetPalette {
+    /** Unique identifier (e.g., "job-rdm", "season-autumn") */
+    id: string;
+    /** Display name (e.g., "Red Mage") */
+    name: string;
+    /** Category this preset belongs to */
+    category: PresetCategory;
+    /** Brief description of the palette */
+    description: string;
+    /** Array of dye itemIDs (3-5 dyes) */
+    dyes: number[];
+    /** Searchable tags */
+    tags: string[];
+    /** Credit for community submissions */
+    author?: string;
+    /** Version for future updates */
+    version?: string;
+}
+/**
+ * Preset with resolved Dye objects
+ */
+export interface ResolvedPreset extends PresetPalette {
+    /** Full Dye objects for each dye ID */
+    resolvedDyes: (Dye | null)[];
+}
+/**
+ * Full preset data structure
+ */
+export interface PresetData {
+    /** Data format version */
+    version: string;
+    /** Last update timestamp */
+    lastUpdated: string;
+    /** Category metadata */
+    categories: Record<PresetCategory, CategoryMeta>;
+    /** All preset palettes */
+    palettes: PresetPalette[];
+}
+/**
+ * Status of a community preset submission
+ */
+export type PresetStatus = 'pending' | 'approved' | 'rejected' | 'flagged';
+/**
+ * Community preset with voting and moderation data
+ * Extended version of PresetPalette for API responses
+ */
+export interface CommunityPreset {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Brief description */
+    description: string;
+    /** Category this preset belongs to */
+    category_id: PresetCategory;
+    /** Array of dye item IDs (2-5 dyes) */
+    dyes: number[];
+    /** Searchable tags */
+    tags: string[];
+    /** Discord user ID of author (null for curated) */
+    author_discord_id: string | null;
+    /** Display name of author at submission time */
+    author_name: string | null;
+    /** Number of votes */
+    vote_count: number;
+    /** Moderation status */
+    status: PresetStatus;
+    /** True for official/curated presets */
+    is_curated: boolean;
+    /** ISO 8601 creation timestamp */
+    created_at: string;
+    /** ISO 8601 last update timestamp */
+    updated_at: string;
+}
+/**
+ * Data required to submit a new preset
+ */
+export interface PresetSubmission {
+    /** Name (2-50 characters) */
+    name: string;
+    /** Description (10-200 characters) */
+    description: string;
+    /** Category */
+    category_id: PresetCategory;
+    /** Array of dye item IDs (2-5 dyes) */
+    dyes: number[];
+    /** Tags (0-10 tags, max 30 chars each) */
+    tags: string[];
+    /** Submitter's Discord user ID */
+    author_discord_id: string;
+    /** Submitter's display name */
+    author_name: string;
+}
+/**
+ * Response when listing presets
+ */
+export interface PresetListResponse {
+    /** Array of presets */
+    presets: CommunityPreset[];
+    /** Total count (for pagination) */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Results per page */
+    limit: number;
+    /** True if more pages available */
+    has_more: boolean;
+}
+/**
+ * Response when submitting a preset
+ */
+export interface PresetSubmitResponse {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The created preset (if new) */
+    preset?: CommunityPreset;
+    /** The existing preset (if duplicate) */
+    duplicate?: CommunityPreset;
+    /** Whether a vote was added to duplicate */
+    vote_added?: boolean;
+    /** Moderation result */
+    moderation_status?: 'approved' | 'pending';
+}
+/**
+ * Response when voting on a preset
+ */
+export interface VoteResponse {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Updated vote count */
+    new_vote_count: number;
+    /** True if user already voted */
+    already_voted?: boolean;
+}
+/**
+ * Filters for listing presets
+ */
+export interface PresetFilters {
+    /** Filter by category */
+    category?: PresetCategory;
+    /** Search term */
+    search?: string;
+    /** Filter by status */
+    status?: PresetStatus;
+    /** Sort order */
+    sort?: 'popular' | 'recent' | 'name';
+    /** Page number */
+    page?: number;
+    /** Results per page */
+    limit?: number;
+    /** Filter by curated status */
+    is_curated?: boolean;
+}
+/**
+ * Severity levels for application errors
+ */
+export type ErrorSeverity = 'critical' | 'error' | 'warning' | 'info';
+/**
+ * Custom error class with severity and code
+ */
+export declare class AppError extends Error {
+    code: string;
+    severity: ErrorSeverity;
+    constructor(code: string, message: string, severity?: ErrorSeverity);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error codes for different failure scenarios
+ */
+export declare enum ErrorCode {
+    INVALID_HEX_COLOR = "INVALID_HEX_COLOR",
+    INVALID_RGB_VALUE = "INVALID_RGB_VALUE",
+    DYE_NOT_FOUND = "DYE_NOT_FOUND",
+    DATABASE_LOAD_FAILED = "DATABASE_LOAD_FAILED",
+    INVALID_INPUT = "INVALID_INPUT",
+    API_CALL_FAILED = "API_CALL_FAILED",
+    LOCALE_LOAD_FAILED = "LOCALE_LOAD_FAILED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/types/index.js

@@ -0,0 +1,87 @@
+/**
+ * @xivdyetools/core - Shared Type Definitions
+ *
+ * Type definitions for color science and FFXIV dyes
+ *
+ * @module types
+ */
+export { NoOpLogger, ConsoleLogger } from './logger.js';
+/**
+ * Helper to create branded HexColor type with validation
+ * Per R-1: Validates hex format before creating branded type
+ * @throws {Error} If hex format is invalid
+ */
+export function createHexColor(hex) {
+    // Basic validation - must be #RRGGBB or #RGB format
+    if (!/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/.test(hex)) {
+        throw new Error(`Invalid hex color format: ${hex}. Expected #RRGGBB or #RGB format.`);
+    }
+    // Normalize to uppercase #RRGGBB
+    const normalized = hex.length === 4
+        ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`.toUpperCase()
+        : hex.toUpperCase();
+    return normalized;
+}
+/**
+ * Helper to create branded DyeId type with validation
+ * Per R-1: Validates dye ID is in valid range (1-200)
+ */
+export function createDyeId(id) {
+    if (!Number.isInteger(id) || id < 1 || id > 200) {
+        return null;
+    }
+    return id;
+}
+/**
+ * Helper to create branded Hue type with normalization
+ * Per R-1: Normalizes hue to 0-360 range
+ */
+export function createHue(hue) {
+    // Normalize to 0-360 range
+    const normalized = ((hue % 360) + 360) % 360;
+    return normalized;
+}
+/**
+ * Helper to create branded Saturation type with clamping
+ * Per R-1: Clamps saturation to 0-100 range
+ */
+export function createSaturation(saturation) {
+    const clamped = Math.max(0, Math.min(100, saturation));
+    return clamped;
+}
+/**
+ * Custom error class with severity and code
+ */
+export class AppError extends Error {
+    constructor(code, message, severity = 'error') {
+        super(message);
+        this.code = code;
+        this.severity = severity;
+        this.name = 'AppError';
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            severity: this.severity,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Error codes for different failure scenarios
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["INVALID_HEX_COLOR"] = "INVALID_HEX_COLOR";
+    ErrorCode["INVALID_RGB_VALUE"] = "INVALID_RGB_VALUE";
+    ErrorCode["DYE_NOT_FOUND"] = "DYE_NOT_FOUND";
+    ErrorCode["DATABASE_LOAD_FAILED"] = "DATABASE_LOAD_FAILED";
+    ErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    ErrorCode["API_CALL_FAILED"] = "API_CALL_FAILED";
+    ErrorCode["LOCALE_LOAD_FAILED"] = "LOCALE_LOAD_FAILED";
+    ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiCxD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,oDAAoD;IACpD,IAAI,CAAC,oCAAoC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,6BAA6B,GAAG,oCAAoC,CAAC,CAAC;IACxF,CAAC;IACD,iCAAiC;IACjC,MAAM,UAAU,GACd,GAAG,CAAC,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE;QACzE,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;IACxB,OAAO,UAAsB,CAAC;AAChC,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAW,CAAC;AACrB,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,2BAA2B;IAC3B,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAC7C,OAAO,UAAiB,CAAC;AAC3B,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IACvD,OAAO,OAAqB,CAAC;AAC/B,CAAC;AA+YD;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YACS,IAAY,EACnB,OAAe,EACR,WAA0B,OAAO;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QAJR,SAAI,GAAJ,IAAI,CAAQ;QAEZ,aAAQ,GAAR,QAAQ,CAAyB;QAGxC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,SASX;AATD,WAAY,SAAS;IACnB,oDAAuC,CAAA;IACvC,oDAAuC,CAAA;IACvC,4CAA+B,CAAA;IAC/B,0DAA6C,CAAA;IAC7C,4CAA+B,CAAA;IAC/B,gDAAmC,CAAA;IACnC,sDAAyC,CAAA;IACzC,4CAA+B,CAAA;AACjC,CAAC,EATW,SAAS,KAAT,SAAS,QASpB"}

package/dist/types/logger.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @xivdyetools/core - Logger Interface
+ *
+ * Injectable logger interface for library consumers to customize logging behavior.
+ * Prevents library code from polluting consumer application logs.
+ *
+ * @module types/logger
+ */
+/**
+ * Logger interface for customizable logging
+ *
+ * Implement this interface to control how the library logs messages.
+ * By default, the library uses a no-op logger that suppresses all output.
+ *
+ * @example Using the console logger
+ * ```typescript
+ * import { ConsoleLogger, DyeService } from 'xivdyetools-core';
+ *
+ * // Enable console logging for debugging
+ * const dyeService = new DyeService({ logger: ConsoleLogger });
+ * ```
+ *
+ * @example Creating a custom logger
+ * ```typescript
+ * const myLogger: Logger = {
+ *     info: (msg) => myLoggingFramework.info(`[xivdyetools] ${msg}`),
+ *     warn: (msg) => myLoggingFramework.warn(`[xivdyetools] ${msg}`),
+ *     error: (msg, error) => myLoggingFramework.error(`[xivdyetools] ${msg}`, error),
+ *     debug: (msg) => myLoggingFramework.debug(`[xivdyetools] ${msg}`),
+ * };
+ * ```
+ */
+export interface Logger {
+    /**
+     * Log an informational message
+     * @param message - Message to log
+     */
+    info: (message: string) => void;
+    /**
+     * Log a warning message
+     * @param message - Message to log
+     */
+    warn: (message: string) => void;
+    /**
+     * Log an error message
+     * @param message - Message to log
+     * @param error - Optional error object for additional context
+     */
+    error: (message: string, error?: unknown) => void;
+    /**
+     * Log a debug message (optional, typically suppressed in production)
+     * @param message - Message to log
+     */
+    debug?: (message: string) => void;
+}
+/**
+ * No-op logger that suppresses all output
+ *
+ * This is the default logger used by the library to prevent
+ * polluting consumer application logs.
+ *
+ * @example
+ * ```typescript
+ * // Default behavior - no console output
+ * const service = new DyeService();
+ * ```
+ */
+export declare const NoOpLogger: Logger;
+/**
+ * Console logger for development and debugging
+ *
+ * Use this when you want to see library log messages in the console.
+ * Prefixes all messages with [xivdyetools] for easy identification.
+ *
+ * @example
+ * ```typescript
+ * import { ConsoleLogger, DyeService } from 'xivdyetools-core';
+ *
+ * // Enable verbose logging during development
+ * const dyeService = new DyeService({ logger: ConsoleLogger });
+ * ```
+ */
+export declare const ConsoleLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/types/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC;;;OAGG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC;;;;OAIG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,EAAE,MAKxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,EAAE,MAW3B,CAAC"}

package/dist/types/logger.js

@@ -0,0 +1,54 @@
+/**
+ * @xivdyetools/core - Logger Interface
+ *
+ * Injectable logger interface for library consumers to customize logging behavior.
+ * Prevents library code from polluting consumer application logs.
+ *
+ * @module types/logger
+ */
+/**
+ * No-op logger that suppresses all output
+ *
+ * This is the default logger used by the library to prevent
+ * polluting consumer application logs.
+ *
+ * @example
+ * ```typescript
+ * // Default behavior - no console output
+ * const service = new DyeService();
+ * ```
+ */
+export const NoOpLogger = {
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    debug: () => { },
+};
+/**
+ * Console logger for development and debugging
+ *
+ * Use this when you want to see library log messages in the console.
+ * Prefixes all messages with [xivdyetools] for easy identification.
+ *
+ * @example
+ * ```typescript
+ * import { ConsoleLogger, DyeService } from 'xivdyetools-core';
+ *
+ * // Enable verbose logging during development
+ * const dyeService = new DyeService({ logger: ConsoleLogger });
+ * ```
+ */
+export const ConsoleLogger = {
+    info: (message) => console.info(`[xivdyetools] ${message}`),
+    warn: (message) => console.warn(`[xivdyetools] ${message}`),
+    error: (message, error) => {
+        if (error) {
+            console.error(`[xivdyetools] ${message}`, error);
+        }
+        else {
+            console.error(`[xivdyetools] ${message}`);
+        }
+    },
+    debug: (message) => console.debug(`[xivdyetools] ${message}`),
+};
+//# sourceMappingURL=logger.js.map

package/dist/types/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/types/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqDH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,OAAO,EAAE,CAAC;IACnE,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,OAAO,EAAE,CAAC;IACnE,KAAK,EAAE,CAAC,OAAe,EAAE,KAAe,EAAE,EAAE;QAC1C,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,iBAAiB,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QACnD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,iBAAiB,OAAO,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,iBAAiB,OAAO,EAAE,CAAC;CACtE,CAAC"}