@charzing/vehicle-utils 0.1.1 → 0.2.1

package/dist/cjs/index.d.ts

@@ -1,3 +1,5 @@
+import { Firestore } from 'firebase/firestore';
+
 /**
  * 브랜드 관련 타입 정의
  */
@@ -79,7 +81,7 @@ type ModelSlug = string;
 /**
  * 모델 매핑 결과
  */
-interface ModelMapping {
+interface ModelMapping$1 {
     /** Firestore ID (소문자, 하이픈) */
     firestoreId: ModelId;
     /** 한글 모델명 */
@@ -450,12 +452,63 @@ declare function getStorageBrandName(brandId: BrandId): StorageBrandName;
  * // }
  * ```
  */
-declare function getBrandMapping(brandInput: string): BrandMapping;
+declare function getBrandMapping$1(brandInput: string): BrandMapping;
 /**
  * 지원되는 모든 브랜드 ID 목록
  */
 declare const SUPPORTED_BRANDS: BrandId[];
 
+/**
+ * 동적 브랜드 매핑 시스템
+ *
+ * Firestore에서 실시간으로 브랜드 정보를 조회하여 캐싱
+ * 새로운 브랜드 추가 시 코드 수정 불필요
+ */
+
+/**
+ * Firestore에서 브랜드 정보를 조회하여 캐시 초기화
+ *
+ * @param firestore - Firestore 인스턴스
+ *
+ * @example
+ * ```typescript
+ * import { initializeBrandMappings } from '@charzing/vehicle-utils';
+ * import { db } from './firebase';
+ *
+ * // 앱 시작 시 한 번만 호출
+ * await initializeBrandMappings(db);
+ * ```
+ */
+declare function initializeBrandMappings(firestore: Firestore): Promise<void>;
+/**
+ * 브랜드 매핑 정보 조회
+ *
+ * @param brandInput - 브랜드명 (한글/영문/ID 모두 가능)
+ * @returns 브랜드 매핑 정보 또는 null
+ *
+ * @throws {Error} 초기화되지 않은 경우
+ *
+ * @example
+ * ```typescript
+ * getBrandMapping('현대');    // { firestoreId: 'hyundai', ... }
+ * getBrandMapping('HYUNDAI'); // { firestoreId: 'hyundai', ... }
+ * getBrandMapping('hyundai'); // { firestoreId: 'hyundai', ... }
+ * ```
+ */
+declare function getBrandMapping(brandInput: string): BrandMapping | null;
+/**
+ * 초기화 상태 확인
+ */
+declare function isInitialized$1(): boolean;
+/**
+ * 캐시 초기화 (테스트용)
+ */
+declare function resetCache$1(): void;
+/**
+ * 캐시된 브랜드 수
+ */
+declare function getCachedBrandCount(): number;
+
 /**
  * 모델 매핑 유틸리티
  *
@@ -559,156 +612,103 @@ declare function getModelSlug(modelInput: string): ModelSlug;
  * // }
  * ```
  */
-declare function getModelMapping(modelInput: string, englishName?: string, koreanName?: string): ModelMapping;
+declare function getModelMapping$1(modelInput: string, englishName?: string, koreanName?: string): ModelMapping$1;
 
 /**
- * 이미지 파일명 생성 유틸리티
+ * 동적 모델 매핑 시스템
  *
- * 표준 파일명 규칙: {brandSlug}__{modelSlug}__{year}__{trimSlug}.png
+ * Firestore에서 실시간으로 모델 정보를 조회하여 캐싱
+ * 새로운 모델 추가 시 코드 수정 불필요
  */
 
 /**
- * 차량 이미지 파일명 생성
- *
- * @param params - 차량 이미지 파라미터
- * @param extension - 파일 확장자 (기본: 'png')
- * @returns 이미지 파일명
- *
- * @example
- * ```typescript
- * generateImageFilename({
- *   brand: 'hyundai',
- *   model: 'ioniq-5',
- *   year: 2024
- * });
- * // 'hyundai__ioniq-5__2024.png'
- *
- * generateImageFilename({
- *   brand: 'mini',
- *   model: 'cooper',
- *   year: 2025,
- *   trim: 'jcw'
- * });
- * // 'mini__cooper__2025__jcw.png'
- *
- * generateImageFilename({
- *   brand: 'Tesla',
- *   model: 'Model 3',
- *   year: 2024,
- *   trim: 'Highland'
- * }, 'webp');
- * // 'tesla__model-3__2024__highland.webp'
- * ```
+ * 모델 매핑 정보
  */
-declare function generateImageFilename(params: VehicleImageParams, extension?: 'png' | 'jpg' | 'webp'): ImageFilename;
+interface ModelMapping {
+    firestoreId: string;
+    koreanName: string;
+    englishName: string;
+    storageName: string;
+    brandId: string;
+}
 /**
- * 파일명에서 차량 정보 추출
+ * Firestore에서 모델 정보를 조회하여 캐시 초기화
  *
- * @param filename - 이미지 파일명
- * @returns 차량 정보 또는 null
+ * @param firestore - Firestore 인스턴스
+ * @param brandIds - 초기화할 브랜드 ID 목록 (생략 시 모든 브랜드)
  *
  * @example
  * ```typescript
- * parseImageFilename('hyundai__ioniq-5__2024.png');
- * // { brand: 'hyundai', model: 'ioniq-5', year: 2024 }
+ * // 모든 브랜드의 모델 초기화
+ * await initializeModelMappings(db);
  *
- * parseImageFilename('mini__cooper__2025__jcw.png');
- * // { brand: 'mini', model: 'cooper', year: 2025, trim: 'jcw' }
+ * // 특정 브랜드만 초기화
+ * await initializeModelMappings(db, ['hyundai', 'kia']);
  * ```
  */
-declare function parseImageFilename(filename: string): VehicleImageParams | null;
+declare function initializeModelMappings(firestore: Firestore, brandIds?: string[]): Promise<void>;
 /**
- * 파일명 검증
+ * 모델 매핑 정보 조회
+ *
+ * @param brandId - 브랜드 ID
+ * @param modelInput - 모델명 (한글/영문/ID 모두 가능)
+ * @returns 모델 매핑 정보 또는 null
  *
- * @param filename - 검증할 파일명
- * @returns 유효 여부
+ * @throws {Error} 초기화되지 않은 경우
  *
  * @example
  * ```typescript
- * isValidImageFilename('hyundai__ioniq-5__2024.png'); // true
- * isValidImageFilename('invalid-filename.png'); // false
+ * getModelMapping('hyundai', '아이오닉 5');   // { firestoreId: 'ioniq-5', ... }
+ * getModelMapping('hyundai', 'IONIQ-5');     // { firestoreId: 'ioniq-5', ... }
+ * getModelMapping('hyundai', 'ioniq-5');     // { firestoreId: 'ioniq-5', ... }
  * ```
  */
-declare function isValidImageFilename(filename: string): boolean;
-
+declare function getModelMapping(brandId: string, modelInput: string): ModelMapping | null;
 /**
- * 이미지 URL 생성 유틸리티
+ * 브랜드의 모든 모델 조회
  *
- * Firebase Storage URL 생성 및 Fallback 처리
+ * @param brandId - 브랜드 ID
+ * @returns 모델 매핑 배열
+ */
+declare function getBrandModels(brandId: string): ModelMapping[];
+/**
+ * 초기화 상태 확인
+ */
+declare function isInitialized(): boolean;
+/**
+ * 캐시 초기화 (테스트용)
+ */
+declare function resetCache(): void;
+/**
+ * 캐시된 모델 수
  */
+declare function getCachedModelCount(): number;
 
 /**
- * 차량 이미지 URL 생성
+ * Firebase Storage 차량 이미지 URL/경로 생성 유틸리티
  *
- * @param params - 차량 이미지 파라미터
- * @param options - URL 생성 옵션
- * @returns 이미지 다운로드 URL
- *
- * @example
- * ```typescript
- * generateVehicleImageUrl({
- *   brand: 'hyundai',
- *   model: 'ioniq-5',
- *   year: 2024
- * });
- * // 'https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
- * //  vehicle-images%2FHYUNDAI%2FIONIQ-5%2F2024%2Fhyundai__ioniq-5__2024.png?alt=media'
- *
- * generateVehicleImageUrl({
- *   brand: 'mini',
- *   model: 'cooper',
- *   year: 2025,
- *   trim: 'jcw'
- * });
- * // 'https://firebasestorage.googleapis.com/v0/b/charzing-d1600.firebasestorage.app/o/
- * //  vehicle-images%2FMINI%2FCOOPER%2F2025%2Fmini__cooper__2025__jcw.png?alt=media'
- * ```
+ * ⚠️ 주의: 이 파일은 순수 함수만 포함합니다.
+ * Firebase SDK나 업로드 로직은 포함하지 않습니다.
  */
-declare function generateVehicleImageUrl(params: VehicleImageParams, options?: ImageUrlOptions): string;
+interface ImagePathParams {
+    brandId: string;
+    modelId: string;
+    year: number;
+    trim?: string;
+}
 /**
- * 차량 이미지 경로 정보 가져오기
- *
- * @param params - 차량 이미지 파라미터
- * @param options - URL 생성 옵션
- * @returns 이미지 경로 정보
- *
- * @example
- * ```typescript
- * getVehicleImagePath({
- *   brand: 'hyundai',
- *   model: 'ioniq-5',
- *   year: 2024
- * });
- * // {
- * //   fullPath: 'vehicle-images/HYUNDAI/IONIQ-5/2024/hyundai__ioniq-5__2024.png',
- * //   directory: 'vehicle-images/HYUNDAI/IONIQ-5/2024',
- * //   filename: 'hyundai__ioniq-5__2024.png',
- * //   downloadUrl: 'https://...'
- * // }
- * ```
+ * 차량 이미지 파일명 생성
+ * 예: kia__niro-ev__2022__standard.png
  */
-declare function getVehicleImagePath(params: VehicleImageParams, options?: ImageUrlOptions): ImagePath;
+declare function generateImageFilename(params: ImagePathParams): string;
 /**
- * Fallback 이미지 URL 목록 생성
- *
- * @param params - 차량 이미지 파라미터
- * @param options - URL 생성 옵션
- * @returns Fallback URL 목록 (우선순위 순)
- *
- * @example
- * ```typescript
- * generateFallbackUrls({
- *   brand: 'mini',
- *   model: 'cooper',
- *   year: 2025,
- *   trim: 'jcw'
- * });
- * // [
- * //   'https://.../mini__cooper__2025__jcw.png',     // 트림 이미지
- * //   'https://.../mini__cooper__2025.png',          // 기본 모델 이미지
- * // ]
- * ```
+ * Storage 경로 생성 (업로드용)
+ * 예: vehicle-images/KIA/NIRO-EV/2022/kia__niro-ev__2022__standard.png
+ */
+declare function generateStoragePath(params: ImagePathParams): string;
+/**
+ * 완전한 Firebase Storage URL 생성 (읽기용)
  */
-declare function generateFallbackUrls(params: VehicleImageParams, options?: ImageUrlOptions): string[];
+declare function generateVehicleImageUrl(params: ImagePathParams): string;
 
-export { type BatteryInfo, type Brand, type BrandId, type BrandMapping, type CompletedVehicle, type DriveType, type FirebaseStorageConfig, type ImageFallbackOptions, type ImageFallbackStrategy, type ImageFilename, type ImagePath, type ImageUrlOptions, type Model, type ModelId, type ModelMapping, type ModelSlug, SUPPORTED_BRANDS, type StorageBrandName, type TrimId, type TrimMapping, type TrimSlug, type UserVehicle, type VehicleDetails, type VehicleImageParams, type VehicleModel, type VehicleTrim, type VehicleVariant, convertKoreanToEnglish, findBestModelMatch, generateFallbackUrls, generateImageFilename, generateVehicleImageUrl, getBrandMapping, getBrandNameEnglish, getBrandNameKorean, getModelMapping, getModelSlug, getStorageBrandName, getVehicleImagePath, isValidImageFilename, normalizeBrandId, normalizeModelId, parseImageFilename, toSlug };
+export { type BatteryInfo, type Brand, type BrandId, type BrandMapping, type CompletedVehicle, type DriveType, type FirebaseStorageConfig, type ImageFallbackOptions, type ImageFallbackStrategy, type ImageFilename, type ImagePath, type ImagePathParams, type ImageUrlOptions, type Model, type ModelId, type ModelMapping$1 as ModelMapping, type ModelSlug, SUPPORTED_BRANDS, type StorageBrandName, type TrimId, type TrimMapping, type TrimSlug, type UserVehicle, type VehicleDetails, type VehicleImageParams, type VehicleModel, type VehicleTrim, type VehicleVariant, convertKoreanToEnglish, findBestModelMatch, generateImageFilename, generateStoragePath, generateVehicleImageUrl, getBrandMapping$1 as getBrandMapping, getBrandModels, getBrandNameEnglish, getBrandNameKorean, getCachedBrandCount, getCachedModelCount, getBrandMapping as getDynamicBrandMapping, getModelMapping as getDynamicModelMapping, getModelMapping$1 as getModelMapping, getModelSlug, getStorageBrandName, initializeBrandMappings, initializeModelMappings, isInitialized$1 as isBrandMappingInitialized, isInitialized as isModelMappingInitialized, normalizeBrandId, normalizeModelId, resetCache$1 as resetBrandCache, resetCache as resetModelCache, toSlug };