web-launch-kit 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Park Jungyoung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,294 @@
+![npm](https://img.shields.io/npm/v/web-launch-kit)
+![bundle size](https://img.shields.io/bundlephobia/minzip/web-launch-kit)
+![types](https://img.shields.io/npm/types/web-launch-kit)
+
+*[English](./README.md) · 한국어*
+
+# web-launch-kit
+
+웹에서 **외부 앱**과 **통신 인텐트**를 실행하는 TypeScript 라이브러리. 딥링크·커스텀 스킴,
+안드로이드 `intent://`, iOS 유니버설 링크, 앱스토어·웹스토어 폴백을 다루며 후보를 순서대로
+시도해 하나가 성공할 때까지 진행합니다. `tel`, `sms`, `mailto`, 파일 선택기, 시스템 설정
+딥링크도 포함합니다.
+
+```bash
+npm install web-launch-kit
+```
+
+번들은 자체 완결형이라(OS·로케일 감지가 인라인됨) 다른 스크립트가 필요 없습니다.
+
+## API 한눈에 보기
+
+`LaunchKit`은 싱글톤입니다.
+
+| 멤버 | 시그니처 | 설명 |
+| --- | --- | --- |
+| `LaunchKit.version` | `string` | 설치된 패키지 버전 |
+| `LaunchKit.SettingType` | `enum` | 설정 화면: `General`, `Network`, `Display`, `Appearance`, `Accessibility`, `Battery`, `Datetime`, `Language`, `Accounts`, `Storage` |
+| `LaunchKit.app(options?)` | `Promise<AppOpenedBy>` | 가능한 최선의 경로로 앱을 실행하고, 어떤 경로로 열렸는지 반환 |
+| `LaunchKit.telephone(options?)` | `Promise<void>` | 전화 앱 열기 (`tel:`) |
+| `LaunchKit.message(options?)` | `Promise<void>` | 문자 작성 열기 (`sms:`) |
+| `LaunchKit.mail(options?)` | `Promise<void>` | 메일 작성 열기 (`mailto:`) |
+| `LaunchKit.map(options?)` | `Promise<void>` | 검색어·좌표·경로로 지도 열기. OS별 네이티브 앱과 Google Maps 웹 폴백 |
+| `LaunchKit.filepicker(options?)` | `Promise<File[]>` | 파일 또는 디렉터리 선택 (File System Access API, input 폴백) |
+| `LaunchKit.setting(type?)` | `Promise<void>` | 지원되는 환경에서 시스템 설정 화면 열기 |
+| `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` getter와 비동기 `getTrackId` / `getProductId` |
+
+`AppOpenedBy`는 `"scheme"`, `"universal"`, `"intent"`, `"fallback"`, `"store"` 중 하나입니다.
+
+---
+
+## ESM
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+await LaunchKit.telephone({ to: '+821012345678' })
+```
+
+## CommonJS
+
+번들이 `exports: "named"`로 빌드되어 싱글톤은 `.default` 아래에 있습니다.
+
+```js
+const { default: LaunchKit } = require('web-launch-kit')
+
+LaunchKit.telephone({ to: '+821012345678' })
+```
+
+## UMD (브라우저 `<script>`)
+
+전역 `LaunchKit`은 네임스페이스 객체이고 싱글톤은 `LaunchKit.default`입니다.
+`SettingType`은 `LaunchKit.SettingType`으로도 접근할 수 있습니다.
+
+```html
+<script src="https://unpkg.com/web-launch-kit/dist/launch-kit.umd.min.js"></script>
+<script>
+    document.querySelector('#call').addEventListener('click', function () {
+        window.LaunchKit.default.telephone({to: '+821012345678'})
+    })
+</script>
+```
+
+## TypeScript
+
+싱글톤의 형태는 `LaunchKitInstance`로 export되고, 모든 옵션 객체에 이름이 붙어 있습니다 —
+`AppOpenOptions`, `AndroidAppInfo`, `IOSAppInfo`, `WindowsAppInfo`, `MacOSAppInfo`,
+`TelephoneOptions`, `MessageOptions`, `MailOptions`, `MapOptions`, `FilepickerOptions`.
+`SettingType`은 값 export이고 `AppOpenedBy`는 타입입니다.
+
+```ts
+import LaunchKit, {
+  SettingType,
+  type AppOpenOptions,
+  type AppOpenedBy,
+} from 'web-launch-kit'
+
+const options: AppOpenOptions = {
+  ios: { universal: 'https://example.com/profile/42', bundleId: 'com.example.myapp' },
+}
+
+const openedBy: AppOpenedBy = await LaunchKit.app(options)
+
+if (LaunchKit.utils.canOpenSetting) await LaunchKit.setting(SettingType.Network)
+```
+
+## 앱 실행
+
+`app()`은 플랫폼별 옵션을 받고 현재 OS에 해당하는 블록만 사용합니다. 후보 목록을 순서대로
+만들어 하나가 앱을 실행할 때까지 시도하고, 성공한 경로를 반환합니다.
+
+```mermaid
+flowchart TD
+    A([LaunchKit.app called]) --> B{Detect OS via PlatformKit}
+    B -->|unknown| E1([Reject: unsupported OS])
+    B -->|android| AND
+    B -->|ios| IOS
+    B -->|windows| WIN
+    B -->|macos| MAC
+
+    subgraph AND["android · resolveOptions"]
+        A1{"intent given, but scheme /<br/>packageName / fallback missing?"}
+        A1 -->|yes| A2["parseIntentURL:<br/>derive scheme · packageName · fallback"]
+        A1 -->|no| A3
+        A2 --> A3{"scheme given, but intent missing?"}
+        A3 -->|yes| A4["createIntentURL:<br/>scheme + packageName + fallback"]
+        A3 -->|no| A5
+        A4 --> A5["Priority list:<br/>intent (if canOpenIntent) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
+    end
+
+    subgraph IOS["ios · resolveOptions"]
+        I1{"bundleId given, but trackId missing?"}
+        I1 -->|yes| I2["getTrackId:<br/>iTunes lookup API (bundleId ⭢ trackId)"]
+        I1 -->|no| I3
+        I2 --> I3["Priority list:<br/>universal (if canOpenUniversal) ⭢ scheme (if canOpenScheme)<br/>⭢ fallback ⭢ app store (if canOpenScheme) ⭢ web store"]
+    end
+
+    subgraph WIN["windows · resolveOptions"]
+        W1{"packageFamilyName given,<br/>but productId missing?"}
+        W1 -->|yes| W2["getProductId:<br/>packageFamilyName ⭢ productId"]
+        W1 -->|no| W3
+        W2 --> W3["Priority list:<br/>scheme ⭢ fallback<br/>⭢ app store ⭢ web store (by productId)"]
+    end
+
+    subgraph MAC["macos · resolveOptions"]
+        M1{"bundleId given, but trackId missing?"}
+        M1 -->|yes| M2["getTrackId:<br/>iTunes lookup API (bundleId ⭢ trackId)"]
+        M1 -->|no| M3
+        M2 --> M3["Priority list:<br/>scheme ⭢ fallback<br/>⭢ app store ⭢ web store (by trackId)"]
+    end
+
+    AND --> P
+    IOS --> P
+    WIN --> P
+    MAC --> P
+
+    P{"Any URL candidates?"} -->|no| E2([Reject: no openable URL candidates])
+    P -->|yes| Q{"Next candidate type?"}
+    Q -->|"function fallback"| R["Invoke fallback function"] --> G
+    Q -->|"URL string"| O["openURL(index, url, timeout)"]
+    O --> F{Opened?}
+    F -->|yes| G(["Resolve AppOpenedBy:<br/>'intent' · 'universal' · 'scheme' · 'fallback' · 'store'"])
+    F -->|no| H{"Candidates remaining?"}
+    H -->|yes| Q
+    H -->|no| E3(["Reject: all attempted URLs failed<br/>(error lists every tried URL)"])
+
+    subgraph openURL["openURL · app-switch detection"]
+        T0["Register blur + visibilitychange listeners"] --> T1{"Document focused?"}
+        T1 -->|no| T2["restoreFocus:<br/>window ⭢ body ⭢ hidden input"]
+        T1 -->|yes| T3
+        T2 --> T3{"Environment?"}
+        T3 -->|cordova| T4["InAppBrowser.open / window.open ('_system')"]
+        T3 -->|browser| T5{"userActivation active<br/>or first attempt?"}
+        T5 -->|yes| T6["top.location.href = url"]
+        T5 -->|no| T7["Hidden anchor + synthetic click"]
+        T6 --> T8["+ hidden iframe (removed after 500ms)"]
+        T7 --> T8
+        T4 --> T9
+        T8 --> T9{"blur / hidden fired?"}
+        T9 -->|"yes ⭢ wait focus"| T10([resolve: app opened])
+        T9 -->|"no, until timeout"| T11([reject: app not detected])
+    end
+
+    O -.->|delegates to| T0
+```
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+const openedBy = await LaunchKit.app({
+  android: {
+    scheme: 'myapp://profile/42',
+    packageName: 'com.example.myapp',
+    allowAppStore: true,
+    allowWebStore: true,
+  },
+  ios: {
+    universal: 'https://example.com/profile/42',
+    scheme: 'myapp://profile/42',
+    bundleId: 'com.example.myapp', // 스토어 폴백용 trackId 로 변환됩니다
+    allowAppStore: true,
+  },
+})
+
+console.log(openedBy) // "universal" | "scheme" | "intent" | "fallback" | "store"
+```
+
+플랫폼별 필드: 안드로이드는 `intent` / `scheme` / `packageName` / `fallback`(scheme ⇄ intent는
+서로에게서 유도됩니다), iOS는 `universal` / `scheme` / `bundleId` / `trackId`, Windows는
+`scheme` / `packageFamilyName` / `productId`, macOS는 `scheme` / `bundleId` / `trackId`를
+받습니다. 모두 `fallback`, `timeout`, `allowAppStore`, `allowWebStore`를 함께 받습니다.
+
+안드로이드와 iOS는 `assumeAllowedInApp`을 추가로 받습니다. 파트너 화이트리스트로 동작하는
+인앱 브라우저(예: 웨이보)에 앱이 등록되어 있을 때만 `true`로 선언하세요. 그러면 그 환경에서
+scheme·유니버설 링크 후보가 유지됩니다. 완전히 차단된 웹뷰나 OS 버전 요구사항은 이 옵션으로
+우회되지 않습니다.
+
+## 통신 인텐트
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+await LaunchKit.telephone({ to: '+821012345678' })
+
+await LaunchKit.message({ to: '+821012345678', body: 'hello' })
+
+await LaunchKit.mail({
+  to: ['a@example.com', 'b@example.com'],
+  cc: 'c@example.com',
+  subject: 'Hi',
+  body: 'from web-launch-kit',
+})
+```
+
+## 파일 선택기
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+// 파일 (가능하면 showOpenFilePicker, 아니면 <input type=file> 폴백)
+const files = await LaunchKit.filepicker({ accept: ['image/*', '.pdf'], multiple: true })
+
+// 디렉터리 (재귀 탐색, webkitRelativePath 가 채워집니다)
+const tree = await LaunchKit.filepicker({ directory: true })
+```
+
+## 지도
+
+`map()`은 검색어·좌표·경로 중 하나를 받아 현재 OS에 맞는 URL을 만듭니다
+(iOS/macOS는 `maps://`, 안드로이드는 `geo:`, Windows는 `bingmaps:`). 웹에서는 Google Maps로
+폴백합니다.
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+// 장소 검색
+await LaunchKit.map({ query: 'Seoul City Hall' })
+
+// 라벨이 붙은 핀으로 좌표 표시
+await LaunchKit.map({ coordinate: [37.5665, 126.9780], label: 'Seoul City Hall', zoom: 15 })
+
+// 경로 안내 (origin 을 생략하면 현재 위치가 기본값)
+await LaunchKit.map({ directions: { destination: 'Seoul Station', origin: [37.5665, 126.9780] } })
+```
+
+`query` / `coordinate` / `directions` 중 하나만 주세요. 여러 개가 설정되면 `directions`,
+`coordinate`, `query` 순으로 우선합니다. `coordinate`와 함께 준 `label`은 iOS/macOS/Windows에서
+이름 붙은 핀으로 표시되고, 안드로이드에서는 무시됩니다 — Google Maps 외의 `geo:` 핸들러가
+라벨 형식을 검색어로 잘못 해석하기 때문입니다. 안드로이드 `geo:`에는 표준 경로 안내가 없어서
+경로는 Google Maps 폴백을 쓰고, Windows도 지도 앱이 단종되어 `bingmaps:`가 대개 웹 폴백으로
+넘어갑니다.
+
+## 시스템 설정
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+if (LaunchKit.utils.canOpenSetting) {
+  await LaunchKit.setting(LaunchKit.SettingType.Network)
+}
+```
+
+---
+
+## 참고
+
+- **딥링크에는 실제 사용자 제스처가 필요합니다.** 유니버설 링크와 커스텀 스킴은 프로그램에서
+  임의로 호출하거나 동일 출처 컨텍스트에서 호출하면 신뢰할 수 없습니다 — 앱을 여는 대신 웹으로
+  폴백합니다. `app()`은 클릭/탭 핸들러 안에서 호출하세요.
+- **`app()`이 반환하는 것은 경로이지 실행 보증이 아닙니다.** 감지는 OS별 타임아웃을 둔
+  포커스·가시성 휴리스틱에 기반합니다. `AppOpenedBy`가 반환됐다는 건 그 후보가 시도되었고
+  페이지가 백그라운드로 전환된 것처럼 보였다는 뜻이지, 확정된 실행 확인은 아닙니다.
+- **`utils.getTrackId` / `getProductId`는 비동기**이고 미리 호출해도 안전합니다. 제스처 전에
+  id를 확보해두면 `app()`이 그 조회를 인라인으로 하지 않습니다.
+- **스토어 id 조회는 외부 API에 의존합니다**(iTunes Lookup, Microsoft display catalog).
+  1시간 캐시되며 실패는 예외가 아니라 `undefined`로 resolve됩니다.
+- **인앱 브라우저는 후보 단위로 걸러집니다.** 실행이 차단된 웹뷰(WeChat, QQ, Qzone, Baidu,
+  그리고 파트너가 아닌 웨이보) 안에서는 커스텀 스킴·`intent://`·`market://` 같은 스토어 스킴이
+  타임아웃을 소진하지 않고 미리 제외됩니다. 그래서 체인이 곧바로 `fallback` / 웹스토어로
+  떨어집니다. 화이트리스트에 등록된 파트너 앱은 `assumeAllowedInApp: true`로 되돌립니다.
+- **`map()`은 각 후보에 OS별 타임아웃**을 사용합니다.
+
+## 브라우저 지원
+
+**IE 9**까지 동작합니다.

package/README.md

@@ -2,6 +2,8 @@
 ![bundle size](https://img.shields.io/bundlephobia/minzip/web-launch-kit)
 ![types](https://img.shields.io/npm/types/web-launch-kit)
 
+*English · [한국어](./README.ko.md)*
+
 # web-launch-kit
 
 A TypeScript library for launching **external apps** and **communication intents**
@@ -37,6 +39,61 @@ The bundle is self-contained (OS/locale detection is inlined) — no peer script
 
 ---
 
+## ESM
+
+```js
+import LaunchKit from 'web-launch-kit'
+
+await LaunchKit.telephone({ to: '+821012345678' })
+```
+
+## CommonJS
+
+The bundle is built with `exports: "named"`, so the singleton lives under `.default`:
+
+```js
+const { default: LaunchKit } = require('web-launch-kit')
+
+LaunchKit.telephone({ to: '+821012345678' })
+```
+
+## UMD (browser `<script>`)
+
+The global `LaunchKit` is a namespace object; the singleton is `LaunchKit.default`.
+`SettingType` is also reachable as `LaunchKit.SettingType`.
+
+```html
+<script src="https://unpkg.com/web-launch-kit/dist/launch-kit.umd.min.js"></script>
+<script>
+    document.querySelector('#call').addEventListener('click', function () {
+        window.LaunchKit.default.telephone({to: '+821012345678'})
+    })
+</script>
+```
+
+## TypeScript
+
+The singleton shape is exported as `LaunchKitInstance`, and every option object has a
+named type: `AppOpenOptions`, `AndroidAppInfo`, `IOSAppInfo`, `WindowsAppInfo`,
+`MacOSAppInfo`, `TelephoneOptions`, `MessageOptions`, `MailOptions`, `MapOptions`,
+`FilepickerOptions`. `SettingType` is a value export; `AppOpenedBy` is a type.
+
+```ts
+import LaunchKit, {
+  SettingType,
+  type AppOpenOptions,
+  type AppOpenedBy,
+} from 'web-launch-kit'
+
+const options: AppOpenOptions = {
+  ios: { universal: 'https://example.com/profile/42', bundleId: 'com.example.myapp' },
+}
+
+const openedBy: AppOpenedBy = await LaunchKit.app(options)
+
+if (LaunchKit.utils.canOpenSetting) await LaunchKit.setting(SettingType.Network)
+```
+
 ## Launching an app
 
 `app()` takes per-platform options and only acts on the block matching the current
@@ -215,21 +272,6 @@ if (LaunchKit.utils.canOpenSetting) {
 }
 ```
 
-## CommonJS / UMD
-
-The bundle is built with `exports: "named"`, so the singleton lives under `.default`:
-
-```js
-const { default: LaunchKit } = require('web-launch-kit')
-```
-
-```html
-<script src="https://unpkg.com/web-launch-kit/dist/launch-kit.umd.min.js"></script>
-<script>
-    window.LaunchKit.default.telephone({ to: '+821012345678' })
-</script>
-```
-
 ---
 
 ## Notes
@@ -240,8 +282,8 @@ const { default: LaunchKit } = require('web-launch-kit')
 - **`app()` resolves with the route, not a guarantee of launch.** Detection relies on
   focus/visibility heuristics with per-OS timeouts; a resolved `AppOpenedBy` means that
   candidate was attempted and the page appeared to background, not a hard confirmation.
-- **`utils.getTrackId` / `getProductId` are async**; the named `getTrackId` / `getProductId`
-  exports are synchronous (blocking XHR) and intended for internal/legacy use.
+- **`utils.getTrackId` / `getProductId` are async** and safe to call ahead of time —
+  resolving an id before the gesture keeps `app()` from looking it up inline.
 - **Store-id lookups depend on remote APIs** (iTunes Lookup, Microsoft display catalog)
   and are cached for one hour; failures resolve to `undefined` rather than throwing.
 - **In-app browsers are gated per candidate.** Inside webviews that block launches
@@ -251,3 +293,7 @@ const { default: LaunchKit } = require('web-launch-kit')
   (the only routes that work there). Whitelisted partner apps opt back in with
   `assumeAllowedInApp: true`.
 - **`map()` uses the per-OS timeout** for each candidate.
+
+## Browser support
+
+Runs down to **IE 9**.

package/dist/index.d.ts

@@ -1,54 +1,3 @@
-declare global {
-    interface Document {
-        webkitVisibilityState?: 'hidden' | 'visible';
-        mozVisibilityState?: 'hidden' | 'visible';
-        msVisibilityState?: 'hidden' | 'visible';
-        webkitHidden?: boolean;
-        mozHidden?: boolean;
-        msHidden?: boolean;
-    }
-    interface FileSystemDirectoryHandle {
-        values(): AsyncIterableIterator<FileSystemHandle>;
-    }
-    interface SymbolConstructor {
-        readonly asyncIterator: symbol;
-    }
-    var showOpenFilePicker: (options?: OpenFilePickerOptions) => Promise<FileSystemFileHandle[]>;
-    var showDirectoryPicker: (options?: OpenDirectoryPickerOptions) => Promise<FileSystemDirectoryHandle>;
-    var cordova: CordovaPlugin | undefined;
-}
-interface OpenFilePickerOptions {
-    excludeAcceptAllOption?: boolean;
-    id?: string;
-    multiple?: boolean;
-    startIn?: OpenPickerStartIn;
-    types?: {
-        description?: string;
-        accept: Record<string, string[]>;
-    }[];
-}
-interface OpenDirectoryPickerOptions {
-    id?: string;
-    mode?: 'read' | 'readwrite';
-    startIn?: OpenPickerStartIn;
-}
-interface IteratorYieldResult<TYield> {
-    done?: false;
-    value: TYield;
-}
-interface IteratorReturnResult<TReturn> {
-    done: true;
-    value: TReturn;
-}
-interface AsyncIterator<T, TReturn = any, TNext = any> {
-    next(...[value]: [] | [TNext]): Promise<IteratorResult<T, TReturn>>;
-    return?(value?: TReturn | PromiseLike<TReturn>): Promise<IteratorResult<T, TReturn>>;
-    throw?(e?: any): Promise<IteratorResult<T, TReturn>>;
-}
-interface AsyncIterableIterator<T, TReturn = any, TNext = any> extends AsyncIterator<T, TReturn, TNext> {
-    [Symbol.asyncIterator](): AsyncIterableIterator<T, TReturn, TNext>;
-}
-type IteratorResult<T, TReturn = any> = IteratorYieldResult<T> | IteratorReturnResult<TReturn>;
 declare type URLCandidate = URL | string;
 declare type URLCandidateOrFallback = URLCandidate | (() => any);
 declare type URLStringOrFallback = string | (() => any);
@@ -66,12 +15,6 @@ declare enum SettingType {
     Accounts = "accounts",
     Storage = "storage"
 }
-interface CordovaPlugin {
-    InAppBrowser?: CordovaInAppBrowser;
-}
-interface CordovaInAppBrowser {
-    open(url?: string | URL, target?: string, features?: string): WindowProxy | null;
-}
 declare interface AppInfo {
     scheme?: URLCandidate;
     fallback?: URLCandidateOrFallback;