DeviceLibrary — @gj-kit/expo-media

A public interface from @gj-kit/expo-media. The signature below is taken directly from the 0.6.1 release declaration.

Verified import example

import { DeviceLibrary } from '@gj-kit/expo-media';

Signature, parameters, and return type

interface DeviceLibrary {
    /** 순수 조회. 요청하지 않는다. */
    getPermission(): Promise<MediaPermission>;
    /**
     * 권한 합성 규칙의 **유일한 거처**(§5.4-④(c), G17):
     * 조회 → `!granted && canAskAgain`일 때만 요청 → `accessPrivileges === 'limited'` 매핑
     * (마지막 매핑은 어댑터 몫 — §3.3).
     *
     * ⚠ raw `requestPermission()`은 **공개하지 않는다**. `canAskAgain`을 무시하는 재요청이
     * 정확히 iOS UI 데드록(재요청해도 아무 일도 일어나지 않아 화면이 영원히 기다린다)의 원인이며,
     * 골든패스에 그 문을 두면 반드시 누군가 그 문으로 들어간다. 필요한 소비자는
     * `DeviceLibraryAdapter.requestPermission()`을 직접 쓴다.
     */
    ensurePermission(): Promise<MediaPermission>;
    fetchPage(input?: {
        readonly albumId?: string | null | undefined;
        readonly after?: string | undefined;
        readonly pageSize?: number | undefined;
        readonly kinds?: readonly MediaKind[] | undefined;
    } | undefined): Promise<DeviceAssetPage>;
    /** ⚠ core가 `count > 0` 필터 + count 내림차순 정렬을 **수행한다**(§5.4-④(d)). */
    fetchAlbums(): Promise<readonly DeviceAlbum[]>;
    /**
     * 하드닝된 자산정보 조회 — 그리드/스캐너/업로드가 공유하는 단일 관문(§5.7.5, G9 승격).
     * 기본값은 iCloud 다운로드 없음 + 15s 데드라인, 옵트인 시 60s(§7 하드닝 6).
     * 데드라인 초과는 `MediaError('device-timeout')`이며, 어댑터 실패는 URL·원본 예외를
     * 신뢰하지 않고 새 `MediaError('device-library-failed')`로 정규화한다.
     *
     * ⚠ 이 메서드를 공개하지 않으면 동기화 스캐너가 자체 조회를 짜게 되고, 그 순간 15초 데드라인과
     * `downloadFromNetwork: false` 기본값이 **스캔 경로에서만** 사라진다 — 하드닝 6의 조용한 절반 소멸.
     */
    getAssetInfo(assetId: string, options?: {
        readonly downloadFromICloud?: boolean | undefined;
        readonly infoTimeoutMs?: number | undefined;
        readonly downloadTimeoutMs?: number | undefined;
    } | undefined): Promise<DeviceAssetInfo>;
    /**
     * 원본 바이트 위치만 필요한 경로(동기화 엔진)용. 전신 `resolveDeviceAssetSourceForUpload`.
     * iCloud 가드 · 이중 타임아웃 · iOS 캐시 실체화(§7 하드닝 2·6).
     */
    resolveForUpload(asset: DeviceAssetRef, options?: DeviceResolveOptions | undefined): Promise<ResolvedDeviceAsset>;
    /**
     * 화면 경로용. 전신 `resolveDeviceAssetForUpload`(G4).
     *
     * ⚠ 후보 목록에 `asset.uri`를 **자동으로 덧붙인다**(전신 devicePhotoLibrary.ts:355-359).
     *   최종 순서: `[info.localUri, info.uri, asset.uri, ...options.extraCandidates]`
     *   이 자동 후보가 §7.1 「정보 조회 실패 시 폴백 후보 생존」 규칙을 실제로 발화시키는 값이다 —
     *   전신 주석 "the picker keeps the original asset.uri"(286-288)가 가리키는 정확한 경로다.
     *   저장된 `asset.uri`는 업로드 파이프라인이 읽을 수 없는 `ph://` 참조일 수 있으므로 원본
     *   바이트와 EXIF를 다시 해석한 뒤 피커 형태로 넘긴다(전신 341-343 주석).
     */
    resolvePickedAsset(asset: DeviceAsset, options?: DeviceResolveOptions | undefined): Promise<ResolvedPickedAsset>;
}

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/expo-media
• Version: 0.6.1
• Public entry: .
• Source: GitHub