react-native-attachment-kit 1.0.2 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-attachment-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Native attachment kit for React Native — gallery picker, editor, image viewer and media gallery (Turbo Module)",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/NativeAttachmentKit.ts

@@ -16,6 +16,16 @@ export interface Spec extends TurboModule {
   
   getDefaultAnimationConfig(): Promise<Object>;
 
+  // 지도 뷰어 (위치 메시지)
+  openMapViewer(options: Object): Promise<void>;
+  updateMapViewerSourceRect(rect: Object): Promise<void>;
+  // 위치 메시지 지도 썸네일 (이 기기에서 그려 캐시)
+  renderLocationThumbnail(options: Object): Promise<Object>;
+  clearLocationThumbnailCache(): Promise<void>;
+  // 좌표 → 주소 (기기 지오코더, 디스크 캐시)
+  reverseGeocode(options: Object): Promise<Object>;
+  clearReverseGeocodeCache(): Promise<void>;
+
   // 미디어 갤러리 (사진 모아보기)
   openMediaGallery(options: Object): Promise<Object>;
   closeMediaGallery(galleryId: string): Promise<void>;

package/src/index.d.ts

@@ -1,56 +1,5 @@
-export interface ImageResult {
-  uri: string
-  width: number
-  height: number
-  type: string
-}
-
-export interface GalleryOptions {
-  maxSelection?: number
-  mediaType?: "photo" | "video" | "all"
-  quality?: number
-  allItemsText?: string
-  selectedItemsText?: string
-  doneButtonText?: string
-  recentsAlbumText?: string
-  languageCode?: string
-  autoCloseOnSelect?: boolean
-  /**
-   * 선택 방식.
-   * - 'single': 한 장 즉시 선택형 (기존 maxSelection 0/1 동작 — 탭하면 바로 반환, 편집 ON 이면 탭 → 편집 → 전송)
-   * - 'multi' : 체크(번호 배지) → (필요하면 편집) → 완료. maxSelection 이 1 이어도 멀티와 똑같이 동작하고,
-   *             1장일 때 다른 사진을 고르면 기존 선택과 교체됩니다. autoCloseOnSelect 는 무시되며 maxSelection 생략/1 미만이면 1장.
-   * 생략 시 기존 규칙으로 판단: autoCloseOnSelect 또는 maxSelection <= 1 → 단일, 그 외 멀티 (하위 호환)
-   */
-  selectionMode?: "single" | "multi"
-  enableEditor?: boolean // 단일 이미지 선택 시 편집기 활성화 여부
-  themeColor?: string // 테마 컬러 지정 (ex: "#FFEB3B")
-  onSelectionChange?: (event: SelectionChangeEvent) => void
-}
-
-export interface SelectionChangeEvent {
-  selectedCount: number
-  maxSelection: number
-}
-
-export interface RNAttachmentKit {
-  init(licenseKey: string): Promise<boolean>;
-  openGallery(options?: GalleryOptions): Promise<ImageResult[]>;
-  openEditor(options: EditorOptions): Promise<ImageResult>;
-  closeGallery(): Promise<boolean>
-  addSelectionChangeListener(listener: (event: SelectionChangeEvent) => void): () => void
-}
-
-/**
- * Returns true if using Turbo Module (New Architecture)
- */
-export const isUsingTurboModule: boolean
-
-/**
- * Returns true if using Legacy Native Module (Old Architecture)
- */
-export const isUsingLegacyModule: boolean
-
-declare const AttachmentKit: RNAttachmentKit
-
-export default AttachmentKit
+// package.json 의 "types" 는 src/index.ts 를 가리키므로 이 파일은 소비자에게 쓰이지 않습니다.
+// 예전엔 손으로 관리하던 복사본이 index.ts / types.ts 와 어긋나 있었기 때문에, 이제는 실제 export 를 그대로 재노출만 합니다.
+export * from "./types"
+export { default } from "./index"
+export * from "./index"

package/src/index.ts

@@ -1,4 +1,4 @@
-import { NativeModules, Platform, TurboModuleRegistry, NativeEventEmitter } from "react-native"
+import { NativeModules, Platform, TurboModuleRegistry, NativeEventEmitter, DeviceEventEmitter } from "react-native"
 import type { ImageResult, GalleryOptions, EditorOptions, SelectionChangeEvent, ViewerOptions, MediaGalleryOptions, MediaGalleryAppendPayload, MediaGalleryRemovePayload, Appearance } from "./types"
 
 const LINKING_ERROR = `The package 'react-native-attachment-kit' doesn't seem to be linked. Make sure: \n\n` + Platform.select({ ios: "- You have run 'pod install'\n", default: "" }) + "- You rebuilt the app after installing the package\n" + "- You are not using Expo Go\n"
@@ -15,6 +15,8 @@ try {
 
 let _defaultThemeColor = "#10b981";
 let _defaultLanguageCode = "en";
+/** setDefaults/init 에 넘긴 언어 코드 그대로 (예: "zh-Hans", "pt-BR") — 주소(역지오코딩)는 UI 언어 목록으로 줄이지 않음 */
+let _rawLanguageCode: string | null = null;
 let _defaultAppearance: Appearance = "system";
 
 /** "light" | "dark" 외의 값(생략·오타 포함)은 "system" */
@@ -64,7 +66,27 @@ if (!RNAttachmentKitModule) {
 // Create event emitter
 const eventEmitter = new NativeEventEmitter(RNAttachmentKitModule)
 
-export type { SelectionChangeEvent, Appearance } from "./types"
+/** 같은 화면을 중복으로 열려고 할 때 reject 하는 Error (code: "E_ALREADY_OPEN") */
+function alreadyOpenError(what: string): Error {
+  const err = new Error(`${what} is already open`)
+  ;(err as any).code = "E_ALREADY_OPEN"
+  return err
+}
+
+/**
+ * openGallery 가 아직 끝나지 않았는지. 네이티브는 갤러리 Promise 를 하나만 보관하므로(iOS currentGalleryVC,
+ * Android pickImagesPromise) 중복 호출하면 앞 호출의 Promise 가 영영 끝나지 않습니다 → JS 에서 먼저 막습니다.
+ */
+let _galleryOpen = false
+/** openEditor 도 Android 가 editImagePromise 하나만 보관하므로 같은 보호가 필요 */
+let _editorOpen = false
+/**
+ * asyncProcessing 모드의 onImageProcessed 구독. 이 모드에선 openGallery 가 끝난 뒤에도 이벤트가 오므로
+ * finally 에서 제거하지 않고, 다음 openGallery(asyncProcessing) 호출 때 이전 구독만 제거합니다 (최대 1개 유지).
+ */
+let _asyncImgProcessedSub: { remove: () => void } | null = null
+
+export type { SelectionChangeEvent, Appearance, AttachLocationResult, MapViewerOptions, ReverseGeocodeOptions, ReverseGeocodeResult, ReverseGeocodeErrorCode, AttachFileResult, AttachFileFailure, LocationThumbnailOptions, LocationThumbnailResult } from "./types"
 export type { MediaGalleryItem, MediaGalleryOptions, MediaGalleryGridSize, MediaGalleryGridSizeChangedEvent, MediaGalleryTheme, MediaGalleryViewerOptions, MediaGalleryDeleteOption, MediaGalleryItemDeletedEvent, MediaGalleryNeedPageEvent, MediaGalleryClosedEvent, MediaGalleryAppendPayload, MediaGalleryRemovePayload } from "./types"
 
 export interface RNAttachmentKit {
@@ -77,6 +99,21 @@ export interface RNAttachmentKit {
   openEditor(options: EditorOptions): Promise<ImageResult>
   openViewer(options: ViewerOptions): Promise<void>
   updateSourceRect(rect: import("./types").SourceRect): Promise<void>
+  /** 지도 뷰어. 닫히면 resolve */
+  openMapViewer(options: import("./types").MapViewerOptions): Promise<void>
+  /** 지도 뷰어가 열린 동안 말풍선 위치가 바뀌었을 때 (닫힐 때 돌아갈 자리) */
+  updateMapViewerSourceRect(rect: import("./types").SourceRect | null): Promise<void>
+  /** 위치 메시지 말풍선 지도 썸네일을 이 기기에서 그려 캐시 (같은 요청이면 캐시에서 바로) */
+  renderLocationThumbnail(options: import("./types").LocationThumbnailOptions): Promise<import("./types").LocationThumbnailResult>
+  /** renderLocationThumbnail 캐시 비우기 */
+  clearLocationThumbnailCache(): Promise<void>
+  /**
+   * 좌표 → 주소 (기기 지오코더, 무료). 언어는 languageCode 그대로 (생략하면 setDefaults 의 languageCode).
+   * 결과("결과 없음" 포함)는 디스크에 캐시. 오류는 ReverseGeocodeErrorCode 로 reject (캐시 안 함)
+   */
+  reverseGeocode(options: import("./types").ReverseGeocodeOptions): Promise<import("./types").ReverseGeocodeResult>
+  /** reverseGeocode 캐시 비우기 */
+  clearReverseGeocodeCache(): Promise<void>
   closeGallery(): Promise<boolean>
   addSelectionChangeListener(listener: (event: SelectionChangeEvent) => void): () => void
   getDefaultAnimationConfig(): Promise<{ galleryOpen: number, galleryClose: number, editorOpen: number, editorClose: number, viewerOpen: number, viewerClose: number }>
@@ -99,6 +136,7 @@ const AttachmentKit: RNAttachmentKit = {
     }
     if (options?.languageCode) {
       _defaultLanguageCode = normalizeLanguageCode(options.languageCode);
+      _rawLanguageCode = options.languageCode;
     }
     if (options?.appearance) {
       _defaultAppearance = normalizeAppearance(options.appearance);
@@ -111,7 +149,10 @@ const AttachmentKit: RNAttachmentKit = {
 
   setDefaults: (options: DefaultOptions): void => {
     if (options?.themeColor) _defaultThemeColor = options.themeColor
-    if (options?.languageCode) _defaultLanguageCode = normalizeLanguageCode(options.languageCode)
+    if (options?.languageCode) {
+      _defaultLanguageCode = normalizeLanguageCode(options.languageCode)
+      _rawLanguageCode = options.languageCode
+    }
     if (options?.appearance) _defaultAppearance = normalizeAppearance(options.appearance)
   },
 
@@ -121,21 +162,46 @@ const AttachmentKit: RNAttachmentKit = {
     if (!RNAttachmentKitModule) {
       throw new Error(LINKING_ERROR)
     }
+    // 이미 열려 있으면 네이티브를 건드리지 않고 바로 reject (앞 호출의 Promise 를 지키기 위해)
+    if (_galleryOpen) {
+      throw alreadyOpenError("Gallery")
+    }
+    _galleryOpen = true
 
     // 콜백 이벤트 임시 리스너 등록
     let subscriptionSelChange: any = null
     let subscriptionImgProcessed: any = null
-    
+
     if (options.onSelectionChange) {
       subscriptionSelChange = eventEmitter.addListener("onSelectionChange", options.onSelectionChange)
     }
     if (options.onImageProcessed) {
-      subscriptionImgProcessed = eventEmitter.addListener("onImageProcessed", options.onImageProcessed)
+      if (options.asyncProcessing) {
+        // async 모드: 이전 호출이 남겨 둔 구독을 먼저 제거해서 리스너가 쌓이지 않게 함
+        if (_asyncImgProcessedSub) {
+          try { _asyncImgProcessedSub.remove() } catch (e) { /* noop */ }
+          _asyncImgProcessedSub = null
+        }
+        subscriptionImgProcessed = eventEmitter.addListener("onImageProcessed", options.onImageProcessed)
+        _asyncImgProcessedSub = subscriptionImgProcessed
+      } else {
+        subscriptionImgProcessed = eventEmitter.addListener("onImageProcessed", options.onImageProcessed)
+      }
+    }
+    let subscriptionLocation: any = null
+    if (options.onLocationSelected) {
+      subscriptionLocation = eventEmitter.addListener("onLocationSelected", options.onLocationSelected)
+    }
+    let subscriptionFiles: any = null
+    if (options.onFilesSelected) {
+      const onFiles = options.onFilesSelected
+      // failed: 복사에 실패한 파일 목록 [{ name, error }] (없으면 undefined)
+      subscriptionFiles = eventEmitter.addListener("onFilesSelected", (e: any) => onFiles(e?.files ?? [], e?.failed ?? undefined))
     }
 
     try {
       // 이벤트 콜백은 네이티브로 전달하지 않음
-      const { onSelectionChange, onImageProcessed, ...restOptions } = options
+      const { onSelectionChange, onImageProcessed, onLocationSelected, onFilesSelected, ...restOptions } = options
       const nativeOptions = {
         themeColor: _defaultThemeColor,
         languageCode: _defaultLanguageCode,
@@ -147,10 +213,18 @@ const AttachmentKit: RNAttachmentKit = {
       const result = await RNAttachmentKitModule.openGallery(nativeOptions)
       return result
     } finally {
+      _galleryOpen = false
       // 갤러리가 닫히면 onSelectionChange 리스너 제거
       if (subscriptionSelChange) {
         subscriptionSelChange.remove()
       }
+      // 위치 이벤트는 openGallery 가 끝나기 전에 오므로 여기서 바로 제거
+      if (subscriptionLocation) {
+        subscriptionLocation.remove()
+      }
+      if (subscriptionFiles) {
+        subscriptionFiles.remove()
+      }
       // asyncProcessing 모드가 아닐 때만 onImageProcessed 리스너 제거 (async 모드에선 백그라운드 처리를 위해 유지해야 함)
       // 호출부에서 수동으로 제거하거나, 최종 완료 시 정리하는 구조가 필요할 수 있음
       if (!options.asyncProcessing && subscriptionImgProcessed) {
@@ -163,6 +237,11 @@ const AttachmentKit: RNAttachmentKit = {
     if (!RNAttachmentKitModule) {
       throw new Error(LINKING_ERROR)
     }
+    // Android 는 editImagePromise 를 하나만 보관해서 중복 호출 시 앞 Promise 가 끝나지 않음 → JS 에서 막음
+    if (_editorOpen) {
+      throw alreadyOpenError("Editor")
+    }
+    _editorOpen = true
     const mergedOptions = {
       themeColor: _defaultThemeColor,
       languageCode: _defaultLanguageCode,
@@ -171,7 +250,11 @@ const AttachmentKit: RNAttachmentKit = {
     }
     mergedOptions.languageCode = normalizeLanguageCode(mergedOptions.languageCode)
     mergedOptions.appearance = normalizeAppearance(mergedOptions.appearance)
-    return RNAttachmentKitModule.openEditor(mergedOptions)
+    try {
+      return await RNAttachmentKitModule.openEditor(mergedOptions)
+    } finally {
+      _editorOpen = false
+    }
   },
 
   openViewer: async (options: ViewerOptions): Promise<void> => {
@@ -225,34 +308,34 @@ const AttachmentKit: RNAttachmentKit = {
       })
     }
 
-    if (options.onViewerWillClose) {
-      const closeHandler = () => {
-        if (options.onViewerWillClose) {
-          options.onViewerWillClose()
-        }
-        if (subscriptionPageSelected) {
-          subscriptionPageSelected.remove()
-        }
-        if (subscriptionViewerOpened) {
-          subscriptionViewerOpened.remove()
-        }
-        if (subscriptionViewerWillClose) {
-          subscriptionViewerWillClose.remove()
-        }
-        if (deviceSubscriptionViewerWillClose) {
-          deviceSubscriptionViewerWillClose.remove()
-        }
-        if (subscriptionImageDeleted) {
-          subscriptionImageDeleted.remove()
-        }
-      };
+    // 네이티브 "onViewerWillClose"(iOS sendEvent / Android RCTDeviceEventEmitter) 는 앱이 콜백을 넘기지 않아도
+    // 항상 구독합니다 — 이 이벤트가 와야 onPageSelected / onImageDeleted 구독을 정리할 수 있기 때문입니다
+    // (예전엔 options.onViewerWillClose 가 없으면 구독을 안 해서 뷰어를 열 때마다 리스너가 누수됐음).
+    const closeHandler = () => {
+      if (options.onViewerWillClose) {
+        options.onViewerWillClose()
+      }
+      if (subscriptionPageSelected) {
+        subscriptionPageSelected.remove()
+      }
+      if (subscriptionViewerOpened) {
+        subscriptionViewerOpened.remove()
+      }
+      if (subscriptionViewerWillClose) {
+        subscriptionViewerWillClose.remove()
+      }
+      if (deviceSubscriptionViewerWillClose) {
+        deviceSubscriptionViewerWillClose.remove()
+      }
+      if (subscriptionImageDeleted) {
+        subscriptionImageDeleted.remove()
+      }
+    };
 
-      subscriptionViewerWillClose = eventEmitter.addListener("onViewerWillClose", closeHandler);
+    subscriptionViewerWillClose = eventEmitter.addListener("onViewerWillClose", closeHandler);
 
-      if (Platform.OS === "android") {
-        const { DeviceEventEmitter } = require("react-native");
-        deviceSubscriptionViewerWillClose = DeviceEventEmitter.addListener("onViewerWillClose", closeHandler);
-      }
+    if (Platform.OS === "android") {
+      deviceSubscriptionViewerWillClose = DeviceEventEmitter.addListener("onViewerWillClose", closeHandler);
     }
 
     try {
@@ -266,9 +349,14 @@ const AttachmentKit: RNAttachmentKit = {
       mergedOptions.languageCode = normalizeLanguageCode(mergedOptions.languageCode)
       mergedOptions.appearance = normalizeAppearance(mergedOptions.appearance)
       return await RNAttachmentKitModule.openViewer(mergedOptions)
-    } finally {
-      // Listeners are now removed inside the onViewerWillClose callback
+    } catch (e) {
+      // 뷰어가 아예 안 떴으면(reject) onViewerWillClose 가 오지 않으므로 여기서 구독 정리 (앱 콜백은 호출 안 함)
+      for (const sub of [subscriptionPageSelected, subscriptionViewerOpened, subscriptionImageDeleted, subscriptionViewerWillClose, deviceSubscriptionViewerWillClose]) {
+        try { sub?.remove() } catch (err) { /* noop */ }
+      }
+      throw e
     }
+    // 정상적으로 열렸으면 리스너는 onViewerWillClose 콜백 안에서 제거됨
   },
 
   updateSourceRect: async (rect: import("./types").SourceRect): Promise<void> => {
@@ -278,6 +366,71 @@ const AttachmentKit: RNAttachmentKit = {
     return RNAttachmentKitModule.updateSourceRect(rect)
   },
 
+  openMapViewer: async (options: import("./types").MapViewerOptions): Promise<void> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    const mergedOptions: Record<string, any> = {
+      themeColor: _defaultThemeColor,
+      languageCode: _defaultLanguageCode,
+      appearance: _defaultAppearance,
+      ...options,
+    }
+    // 주소를 안 넘기면 네이티브가 채움 — reverseGeocode 와 같은 캐시를 쓰도록 같은 언어(넘긴 그대로)
+    mergedOptions.addressLanguageCode = options.languageCode || _rawLanguageCode || _defaultLanguageCode
+    mergedOptions.languageCode = normalizeLanguageCode(mergedOptions.languageCode)
+    mergedOptions.appearance = normalizeAppearance(mergedOptions.appearance)
+    await RNAttachmentKitModule.openMapViewer(mergedOptions)
+  },
+
+  updateMapViewerSourceRect: async (rect: import("./types").SourceRect | null): Promise<void> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    return RNAttachmentKitModule.updateMapViewerSourceRect(rect ?? {})
+  },
+
+  renderLocationThumbnail: async (options: import("./types").LocationThumbnailOptions): Promise<import("./types").LocationThumbnailResult> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    const mergedOptions = {
+      themeColor: _defaultThemeColor,
+      appearance: _defaultAppearance,
+      ...options,
+    }
+    mergedOptions.appearance = normalizeAppearance(mergedOptions.appearance)
+    // 내 위치는 둘 다 있을 때만
+    if (typeof mergedOptions.myLatitude !== "number" || typeof mergedOptions.myLongitude !== "number") {
+      delete mergedOptions.myLatitude
+      delete mergedOptions.myLongitude
+    }
+    return RNAttachmentKitModule.renderLocationThumbnail(mergedOptions)
+  },
+
+  clearLocationThumbnailCache: async (): Promise<void> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    return RNAttachmentKitModule.clearLocationThumbnailCache()
+  },
+
+  reverseGeocode: async (options: import("./types").ReverseGeocodeOptions): Promise<import("./types").ReverseGeocodeResult> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    const languageCode = options.languageCode || _rawLanguageCode || _defaultLanguageCode
+    const r = await RNAttachmentKitModule.reverseGeocode({ latitude: options.latitude, longitude: options.longitude, languageCode })
+    return { address: r?.address ?? null, shortAddress: r?.shortAddress ?? null, cached: !!r?.cached }
+  },
+
+  clearReverseGeocodeCache: async (): Promise<void> => {
+    if (!RNAttachmentKitModule) {
+      throw new Error(LINKING_ERROR)
+    }
+    return RNAttachmentKitModule.clearReverseGeocodeCache()
+  },
+
   closeGallery: async (): Promise<boolean> => {
     if (!RNAttachmentKitModule) {
       throw new Error(LINKING_ERROR)

package/src/types.ts

@@ -61,10 +61,217 @@ export interface GalleryOptions {
   asyncProcessing?: boolean // 완전 비동기 이벤트 리턴 여부
   onSelectionChange?: (event: SelectionChangeEvent) => void
   onImageProcessed?: (event: any) => void
+  /**
+   * 갤러리 아래에 첨부 메뉴(갤러리 / 위치 / 파일)를 보여줍니다. 기본 false.
+   * 위치 탭: iOS 는 Apple 지도(키 필요 없음), Android 는 Google 지도 — 앱의 AndroidManifest 에
+   * `com.google.android.geo.API_KEY` meta-data 가 있어야 지도가 그려집니다 (주소 변환은 기기 내장 Geocoder).
+   */
+  showAttachMenu?: boolean
+  /**
+   * 위치 보내기 때 지도 캡처 이미지를 만들지 (기본 true = 예전과 같음).
+   * false 면 캡처 없이 위치 정보만 바로 보냅니다 — AttachLocationResult 에 imageUri/imagePath/imageWidth/imageHeight 가 없고,
+   * imageSpanMeters 는 캡처했을 때와 같은 값이 옵니다. 받는 쪽은 renderLocationThumbnail 로 썸네일을 그립니다.
+   */
+  captureLocationImage?: boolean
+  /**
+   * (Android) 첨부 메뉴 바의 아래 여백 조정 (dp).
+   * attachMenuSinkIntoNav: 바가 내비게이션 바 영역으로 내려앉는 정도. 기본 12 (지금 모양). 0 이면 내비게이션 바 바로 위.
+   * attachMenuMinBottomMargin: 화면 아래와의 최소 간격. 기본 8.
+   * iOS 는 무시.
+   */
+  attachMenuSinkIntoNav?: number
+  attachMenuMinBottomMargin?: number
+  /**
+   * 위치 탭에서 위치를 보냈을 때 호출됩니다. 이때 openGallery 는 빈 배열로 끝납니다.
+   */
+  onLocationSelected?: (location: AttachLocationResult) => void
+  /**
+   * 파일 탭에서 파일을 보냈을 때 호출됩니다 (앱 캐시/임시 폴더로 복사된 파일). 이때 openGallery 는 빈 배열로 끝납니다.
+   * Android 는 시스템 파일 선택기(내부 저장 공간 탐색), iOS 는 파일 앱 선택기를 씁니다.
+   * 복사에 실패한 파일이 있으면 두 번째 인자 failed 로 { name, error } 목록이 옵니다 (없으면 undefined).
+   * 복사본은 iOS tmp/AttachmentKitFiles, Android cache/AttachmentKitFiles 에 있고 24시간이 지난 것은 다음 갤러리 열기 때 지워지므로 바로 옮기거나 업로드하세요.
+   */
+  onFilesSelected?: (files: AttachFileResult[], failed?: AttachFileFailure[]) => void
   openDuration?: number
   closeDuration?: number
 }
 
+/** 첨부 메뉴 > 파일 에서 복사에 실패한 파일 */
+export interface AttachFileFailure {
+  /** 원래 파일 이름 */
+  name: string
+  /** 실패 사유 (네이티브 오류 메시지) */
+  error: string
+}
+
+/** 첨부 메뉴 > 파일 에서 보낸 파일 (앱 캐시/임시 폴더로 복사본) */
+export interface AttachFileResult {
+  /** file:// URI */
+  uri: string
+  /** 파일 경로 */
+  path: string
+  /** 원래 파일 이름 */
+  name: string
+  /** 바이트 */
+  size: number
+  mimeType: string
+}
+
+/** 첨부 메뉴 > 위치 에서 보낸 위치 */
+export interface AttachLocationResult {
+  latitude: number
+  longitude: number
+  /** 정확도(m). 내 현재 위치를 보낼 때만 */
+  accuracy?: number
+  /** 장소 이름 (장소를 골랐을 때) */
+  title?: string
+  /** 주소 */
+  address?: string
+  /** 내 현재 위치를 보냈는지 (false = 지도에서 옮긴 위치 또는 장소) */
+  isCurrentLocation: boolean
+  /** 보낸 지점의 지도 캡처 (세로형 480×1040 webp (9:19.5), 내 위치 점 없이 핀만). 캡처 실패 시 없음 */
+  imageUri?: string
+  imagePath?: string
+  imageWidth?: number
+  imageHeight?: number
+  /** 보낸 위치와 별개로, 보낸 순간의 내 현재 위치 (권한이 있고 위치를 알 때만) */
+  currentLatitude?: number
+  currentLongitude?: number
+  /** 내 현재 위치 정확도(m) */
+  currentAccuracy?: number
+  /** 지도 이미지에 내 위치 점을 그렸는지 ("내 위치 공유" 토글 — 기본 끔, 선택은 기기에 기억) */
+  includesMyLocation?: boolean
+  /** 마커 종류 (지도 뷰어가 같은 아이콘을 그리도록): "current" 내 위치 / "pin" 지도에서 옮긴 지점 / "place" 장소 */
+  markerType?: 'current' | 'pin' | 'place'
+  /** (iOS) 장소 종류 — MKPointOfInterestCategory rawValue. 장소일 때만 */
+  placeCategory?: string
+  /** 보낸 이미지 가로가 덮는 실제 거리(m) — 지도 뷰어를 같은 축척으로 열 때 (captureLocationImage: false 여도 옴) */
+  imageSpanMeters?: number
+}
+
+/**
+ * 위치 메시지 말풍선 지도 썸네일 — 이 기기에서 위치 정보만으로 그려 캐시합니다.
+ * AttachLocationResult 값을 그대로 넘기면 보낸 화면과 같은 마커·축척으로 그립니다.
+ */
+export interface LocationThumbnailOptions {
+  latitude: number
+  longitude: number
+  /** 썸네일 가로 (dp/pt). 결과 이미지는 기기 배율을 곱한 px */
+  width: number
+  /** 썸네일 세로 (dp/pt). aspect 를 주면 생략 (aspect 가 우선) */
+  height?: number
+  /**
+   * 세로를 가로에서 계산: "square" 1:1 / "portrait" 9:19.5 (보내는 지도 이미지와 같은 비율) /
+   * "device" 이 기기 화면 세로 비율 (지도 뷰어를 열 때 말풍선 이미지가 화면을 꼭 맞게 채움).
+   * 생략하면 height 를 그대로 씁니다.
+   */
+  aspect?: 'square' | 'portrait' | 'device'
+  /**
+   * 결과 이미지 최대 크기 (px). 비율을 유지한 채 이 안에 들어가게 줄입니다.
+   * 둘 다 생략하면 512 × 512, 하나만 주면 다른 쪽은 제한하지 않습니다.
+   * 예: width 170 + aspect "device" + maxWidth 512 + maxHeight 1152 → 3배 기기에서 약 510×1105 px (세로가 512 로 잘리지 않음)
+   */
+  maxWidth?: number
+  /** 결과 이미지 최대 세로 (px). maxWidth 참고 */
+  maxHeight?: number
+  /** AttachLocationResult.markerType — 마커 아이콘 */
+  markerType?: 'current' | 'pin' | 'place'
+  /** (iOS 아이콘) AttachLocationResult.placeCategory */
+  placeCategory?: string
+  /** 썸네일 가로가 덮는 실제 거리(m). AttachLocationResult.imageSpanMeters. 없으면 400 */
+  spanMeters?: number
+  /**
+   * 보낸 쪽이 "내 위치 공유"를 켰을 때(includesMyLocation)의 내 위치 — 있으면 파란 점을 그리고
+   * 두 점이 다 들어오게 범위를 넓힙니다. 공유를 안 켰으면 넘기지 마세요.
+   */
+  myLatitude?: number
+  myLongitude?: number
+  /** 마커 색 (기본: setDefaults 의 themeColor) */
+  themeColor?: string
+  /** 지도 모드. "system" 은 지금 기기/앱 화면 모드. 생략하면 setDefaults 의 appearance */
+  appearance?: Appearance
+}
+
+export interface LocationThumbnailResult {
+  /** file:// (캐시 파일, webp) */
+  uri: string
+  path: string
+  /** 픽셀 크기 */
+  width: number
+  height: number
+  /** 캐시에서 바로 꺼냈는지 */
+  cached: boolean
+}
+
+/**
+ * 지도 뷰어 (위치 메시지를 눌렀을 때). AttachLocationResult 의 값을 그대로 넘기면 보낸 화면과 같은 마커·축척으로 열립니다.
+ * sourceRect + sourceImageUri 를 주면 말풍선 이미지가 화면을 채우며 지도로 바뀌고(스티키), 닫을 땐 반대로 돌아갑니다.
+ */
+/** 좌표 → 주소 (기기 지오코더, 무료). 결과는 디스크에 캐시됩니다 */
+export interface ReverseGeocodeOptions {
+  latitude: number
+  longitude: number
+  /**
+   * 주소 언어. 앱 언어 코드 그대로 ('ko', 'en', 'ja', 'zh-Hans', 'zh-TW', 'pt-BR' …) — 모듈 UI 언어 목록으로 줄이지 않습니다.
+   * 생략하면 setDefaults / init 의 languageCode (넘긴 그대로)
+   */
+  languageCode?: string
+}
+
+export interface ReverseGeocodeResult {
+  /** 전체 주소. 위치 탭 address 와 같은 형식 (시·도 시·군·구 동 도로 번지, 국가명 없음). 결과가 없으면 null */
+  address: string | null
+  /** 목록용 짧은 주소 (동/도로 + 번지). 없으면 null */
+  shortAddress: string | null
+  /** 디스크(또는 메모리) 캐시에서 바로 꺼냈는지 */
+  cached: boolean
+}
+
+/**
+ * reverseGeocode reject 코드
+ *  - E_INVALID_COORDINATE: 범위를 벗어난 좌표 / NaN
+ *  - E_GEOCODE_UNAVAILABLE: (Android) 기기에 Geocoder 가 없음
+ *  - E_GEOCODE_THROTTLED: 요청 제한(iOS 앱당 분당 약 50건 등) — 잠시 뒤 다시 시도
+ *  - E_GEOCODE_TIMEOUT: 지오코더가 8초 안에 답하지 않음
+ *  - E_GEOCODE_NETWORK: 오프라인
+ *  - E_GEOCODE_FAILED: 그 밖의 오류
+ * 오류는 캐시하지 않습니다
+ */
+export type ReverseGeocodeErrorCode =
+  | 'E_INVALID_COORDINATE' | 'E_GEOCODE_UNAVAILABLE' | 'E_GEOCODE_THROTTLED'
+  | 'E_GEOCODE_TIMEOUT' | 'E_GEOCODE_NETWORK' | 'E_GEOCODE_FAILED'
+
+export interface MapViewerOptions {
+  latitude: number
+  longitude: number
+  /** 장소 이름 */
+  title?: string
+  /** 주소. 생략하면 기기 지오코더로 채움 (reverseGeocode 와 같은 캐시, 언어는 languageCode ?? setDefaults 의 languageCode) */
+  address?: string
+  /** AttachLocationResult.markerType — 보낸 화면과 같은 마커 */
+  markerType?: 'current' | 'pin' | 'place'
+  /** (iOS) AttachLocationResult.placeCategory */
+  placeCategory?: string
+  /** AttachLocationResult.imageSpanMeters — 처음 축척을 말풍선 이미지와 맞춤 */
+  spanMeters?: number
+  /** "길찾기" 버튼 표시 (기본 true) */
+  showDirections?: boolean
+  /** 말풍선 이미지 위치 (measureInWindow 값 그대로, dp/pt). 있으면 스티키 애니메이션 */
+  sourceRect?: SourceRect
+  /**
+   * 말풍선 이미지 (https:// 또는 file://). 못 불러오면 이미지 없이 지도만 엶.
+   * sourceRect 와 비율이 달라도 됩니다 (예: 4:3 칸 + 화면 비율 이미지) — 칸 안에 가운데 크롭(cover)으로 그려
+   * 첫 프레임이 말풍선(resizeMode="cover")과 같고, 열리며 잘린 위아래가 펼쳐집니다 (닫을 땐 반대)
+   */
+  sourceImageUri?: string
+  /** 말풍선 이미지 라운드 (dp/pt, 기본 12) */
+  sourceCornerRadius?: number
+  /** 마커·버튼 색 (기본: setDefaults 의 themeColor) */
+  themeColor?: string
+  languageCode?: LanguageCode
+  appearance?: Appearance
+}
+
 export interface ViewerOptions {
   images: string[]
   placeholderImages?: string[]
@@ -187,17 +394,6 @@ export interface EditorOptions {
   closeDuration?: number
 }
 
-export interface RNAttachmentKit {
-  init(licenseKey: string): Promise<boolean>
-  openGallery(options?: GalleryOptions): Promise<ImageResult[]>
-  openEditor(options: EditorOptions): Promise<ImageResult>
-  openViewer(options: ViewerOptions): Promise<void>
-  updateViewerSourceRect(rect: SourceRect): Promise<void>
-  closeGallery(): Promise<boolean>
-  addSelectionChangeListener(listener: (event: SelectionChangeEvent) => void): () => void
-  getDefaultAnimationConfig(): Promise<{ galleryOpen: number, galleryClose: number, editorOpen: number, editorClose: number, viewerOpen: number, viewerClose: number }>
-}
-
 // MARK: - Media gallery (사진 모아보기)
 
 /** 갤러리 항목. 썸네일은 파일 경로만 주고받습니다(base64 금지). */