web-launch-kit 0.0.5 → 0.0.6

package/README.ko.md

@@ -30,13 +30,20 @@ npm install web-launch-kit
 | `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.map(options?)` | `Promise<AppOpenedBy>` | 검색어·좌표·경로로 지도 열기. 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"` 중 하나입니다.
 
+`app()`과 `map()`은 `LaunchError`로 reject합니다 — 필드 두 개가 붙은 실제 `Error`입니다.
+
+| 필드 | 타입 | 설명 |
+| --- | --- | --- |
+| `code` | `"unsupported-os" \| "no-candidates" \| "all-failed"` | 실패 사유 |
+| `attempted` | `readonly LaunchAttempt[]` | 시도한 모든 후보의 `{ by, url, index, total }` |
+
 ---
 
 ## ESM
@@ -200,6 +207,21 @@ console.log(openedBy) // "universal" | "scheme" | "intent" | "fallback" | "store
 `scheme` / `packageFamilyName` / `productId`, macOS는 `scheme` / `bundleId` / `trackId`를
 받습니다. 모두 `fallback`, `timeout`, `allowAppStore`, `allowWebStore`를 함께 받습니다.
 
+`onAttempt`는 각 후보 시도 직전에 동기로 호출됩니다. 대기 UI를 여기서 그리세요 — 그러지
+않으면 타임아웃 동안 화면에 아무 변화가 없습니다.
+
+```js
+await LaunchKit.app({
+  android: { scheme: 'myapp://profile/42', packageName: 'com.example.myapp', allowWebStore: true },
+  onAttempt({ by, index, total }) {
+    setStatus(by === 'store' ? '스토어로 이동합니다' : '앱을 여는 중… (' + (index + 1) + '/' + total + ')')
+  },
+})
+```
+
+이미 진행 중인 호출이 있으면 **같은 프로미스를 반환**합니다. 연타해도 두 번째 체인이 첫 번째
+내비게이션을 덮어쓰는 일이 없습니다.
+
 안드로이드와 iOS는 `assumeAllowedInApp`을 추가로 받습니다. 파트너 화이트리스트로 동작하는
 인앱 브라우저(예: 웨이보)에 앱이 등록되어 있을 때만 `true`로 선언하세요. 그러면 그 환경에서
 scheme·유니버설 링크 후보가 유지됩니다. 완전히 차단된 웹뷰나 OS 버전 요구사항은 이 옵션으로
@@ -234,6 +256,9 @@ const files = await LaunchKit.filepicker({ accept: ['image/*', '.pdf'], multiple
 const tree = await LaunchKit.filepicker({ directory: true })
 ```
 
+취소하면 `[]`로 resolve합니다. `cancel` 이벤트가 있는 엔진은 즉시 알려주고, 나머지는 값이 빈
+상태로 포커스가 돌아오는 것으로 판별하므로 조금 더 걸립니다.
+
 ## 지도
 
 `map()`은 검색어·좌표·경로 중 하나를 받아 현재 OS에 맞는 URL을 만듭니다
@@ -298,15 +323,20 @@ if (LaunchKit.utils.canOpenSetting) {
 - **`app()`이 반환하는 것은 경로이지 실행 보증이 아닙니다.** 감지는 OS별 타임아웃을 둔
   포커스·가시성 휴리스틱에 기반합니다. `AppOpenedBy`가 반환됐다는 건 그 후보가 시도되었고
   페이지가 백그라운드로 전환된 것처럼 보였다는 뜻이지, 확정된 실행 확인은 아닙니다.
-- **`utils.getTrackId` / `getProductId`는 비동기**이고 미리 호출해도 안전합니다. 제스처 전에
-  id를 확보해두면 `app()`이 그 조회를 인라인으로 하지 않습니다.
+- **`utils.getTrackId` / `getProductId`는 비동기**이고 1시간 캐시됩니다. 페이지 초기화 때
+  한 번 호출해두면 `app()`이 id를 인라인으로 조회하지 않습니다. `app()`은 사용자 제스처 안에서
+  실행돼야 하므로, id가 없으면 `await`으로 user activation을 잃는 대신 동기로 조회합니다.
+  `trackId` / `productId`를 직접 주면 조회 자체가 생략됩니다.
 - **스토어 id 조회는 외부 API에 의존합니다**(iTunes Lookup, Microsoft display catalog).
   1시간 캐시되며 실패는 예외가 아니라 `undefined`로 resolve됩니다.
 - **인앱 브라우저는 후보 단위로 걸러집니다.** 실행이 차단된 웹뷰(WeChat, QQ, Qzone, Baidu,
   그리고 파트너가 아닌 웨이보) 안에서는 커스텀 스킴·`intent://`·`market://` 같은 스토어 스킴이
   타임아웃을 소진하지 않고 미리 제외됩니다. 그래서 체인이 곧바로 `fallback` / 웹스토어로
   떨어집니다. 화이트리스트에 등록된 파트너 앱은 `assumeAllowedInApp: true`로 되돌립니다.
-- **`map()`은 각 후보에 OS별 타임아웃**을 사용합니다.
+- **`map()`은 각 후보에 OS별 타임아웃**을 사용하고, `app()`처럼 성공한 경로를 반환합니다.
+- **웹 폴백은 내비게이션 시점에 resolve합니다.** `fallback`이나 웹스토어 후보는 문서 자체를
+  교체하므로 기다릴 앱 전환이 없습니다. 이동을 시작하는 즉시 resolve하며, 이동이 성공한 뒤에
+  reject되는 일이 없습니다.
 
 ## 브라우저 지원
 

package/README.md

@@ -31,13 +31,20 @@ The bundle is self-contained (OS/locale detection is inlined) — no peer script
 | `LaunchKit.telephone(options?)` | `Promise<void>` | Open the dialer (`tel:`) |
 | `LaunchKit.message(options?)` | `Promise<void>` | Open the SMS composer (`sms:`) |
 | `LaunchKit.mail(options?)` | `Promise<void>` | Open the mail composer (`mailto:`) |
-| `LaunchKit.map(options?)` | `Promise<void>` | Open a map by query, coordinate, or directions; native app per-OS with a Google Maps web fallback |
+| `LaunchKit.map(options?)` | `Promise<AppOpenedBy>` | Open a map by query, coordinate, or directions; native app per-OS with a Google Maps web fallback |
 | `LaunchKit.filepicker(options?)` | `Promise<File[]>` | Pick files or a directory (File System Access API, with input fallback) |
 | `LaunchKit.setting(type?)` | `Promise<void>` | Open a system-settings pane where supported |
 | `LaunchKit.utils` | object | `canOpenIntent` / `canOpenUniversal` / `canOpenSetting` getters, plus async `getTrackId` / `getProductId` |
 
 `AppOpenedBy` is one of: `"scheme"`, `"universal"`, `"intent"`, `"fallback"`, `"store"`.
 
+`app()` and `map()` reject with a `LaunchError` — a real `Error` carrying two extra fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `code` | `"unsupported-os" \| "no-candidates" \| "all-failed"` | Why it failed |
+| `attempted` | `readonly LaunchAttempt[]` | `{ by, url, index, total }` for every candidate tried |
+
 ---
 
 ## ESM
@@ -202,6 +209,21 @@ Per-platform fields: Android accepts `intent` / `scheme` / `packageName` / `fall
 macOS accepts `scheme` / `bundleId` / `trackId`. All accept `fallback`, `timeout`,
 `allowAppStore`, `allowWebStore`. 
 
+`onAttempt` fires synchronously before each candidate, which is where you drive the waiting
+UI — there is otherwise nothing on screen for the length of the timeout.
+
+```js
+await LaunchKit.app({
+  android: { scheme: 'myapp://profile/42', packageName: 'com.example.myapp', allowWebStore: true },
+  onAttempt({ by, index, total }) {
+    setStatus(by === 'store' ? '스토어로 이동합니다' : '앱을 여는 중… (' + (index + 1) + '/' + total + ')')
+  },
+})
+```
+
+A second call while one is still running returns the same promise, so a double tap cannot
+start a second chain that navigates over the first.
+
 Android and iOS additionally accept
 `assumeAllowedInApp` — declare it `true` only when your app is whitelisted by a
 partner-gated in-app browser (e.g. Weibo) so scheme / universal-link candidates are
@@ -236,6 +258,9 @@ const files = await LaunchKit.filepicker({ accept: ['image/*', '.pdf'], multiple
 const tree = await LaunchKit.filepicker({ directory: true })
 ```
 
+Cancelling resolves with `[]`. Engines with a `cancel` event report it immediately; the rest
+are detected by regaining focus with an empty value, which takes a moment longer.
+
 ## Maps
 
 `map()` takes an intent — a search query, a coordinate, or a route — and builds the
@@ -301,8 +326,10 @@ if (LaunchKit.utils.canOpenSetting) {
 - **`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** and safe to call ahead of time —
-  resolving an id before the gesture keeps `app()` from looking it up inline.
+- **`utils.getTrackId` / `getProductId` are async** and cached for an hour, so calling one
+  during page setup keeps `app()` from resolving the id inline. `app()` must run inside a
+  user gesture, so when the id is missing it looks it up synchronously rather than awaiting
+  and losing user activation. Passing `trackId` / `productId` directly skips it entirely.
 - **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
@@ -311,7 +338,11 @@ if (LaunchKit.utils.canOpenSetting) {
   burning their timeouts, so the chain falls straight through to `fallback` / web store
   (the only routes that work there). Whitelisted partner apps opt back in with
   `assumeAllowedInApp: true`.
-- **`map()` uses the per-OS timeout** for each candidate.
+- **`map()` uses the per-OS timeout** for each candidate, and resolves with the route that
+  worked just like `app()`.
+- **Web fallbacks resolve on navigation.** A `fallback` or web-store candidate replaces the
+  document, so there is no app switch to wait for — those resolve as soon as the navigation
+  is issued instead of risking a rejection after the move already succeeded.
 
 ## Browser support
 

package/dist/index.d.ts

@@ -3,6 +3,17 @@ declare type URLCandidateOrFallback = URLCandidate | (() => any);
 declare type URLStringOrFallback = string | (() => any);
 declare type OpenPickerStartIn = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';
 declare type AppOpenedBy = 'scheme' | 'universal' | 'intent' | 'fallback' | 'store';
+declare type LaunchErrorCode = 'unsupported-os' | 'no-candidates' | 'all-failed';
+declare interface LaunchAttempt {
+    readonly by: AppOpenedBy;
+    readonly url: string;
+    readonly index: number;
+    readonly total: number;
+}
+declare interface LaunchError extends Error {
+    readonly code: LaunchErrorCode;
+    readonly attempted: readonly LaunchAttempt[];
+}
 declare enum SettingType {
     General = "general",
     Network = "network",
@@ -46,6 +57,7 @@ declare interface AppOpenOptions {
     ios?: IOSAppInfo;
     windows?: WindowsAppInfo;
     macos?: MacOSAppInfo;
+    onAttempt?: (attempt: LaunchAttempt) => void;
 }
 declare interface TelephoneOptions {
     to?: string;
@@ -78,6 +90,7 @@ declare interface MapOptions {
     };
     zoom?: number;
     fallback?: URLStringOrFallback;
+    onAttempt?: (attempt: LaunchAttempt) => void;
 }
 interface LaunchKitUtils {
     get canOpenIntent(): boolean;
@@ -96,11 +109,11 @@ interface LaunchKitInstance {
     telephone(options?: TelephoneOptions): Promise<void>;
     message(options?: MessageOptions): Promise<void>;
     mail(options?: MailOptions): Promise<void>;
-    map(options?: MapOptions): Promise<void>;
+    map(options?: MapOptions): Promise<AppOpenedBy>;
     filepicker(options?: FilepickerOptions): Promise<File[]>;
     setting(type?: SettingType): Promise<void>;
 }
 declare const LaunchKit: LaunchKitInstance;
 
 export { SettingType, LaunchKit as default };
-export type { AndroidAppInfo, AppInfo, AppOpenOptions, AppOpenedBy, FilepickerOptions, IOSAppInfo, LaunchKitInstance, MacOSAppInfo, MailOptions, MapOptions, MessageOptions, OpenPickerStartIn, TelephoneOptions, URLCandidate, URLCandidateOrFallback, URLStringOrFallback, WindowsAppInfo };
+export type { AndroidAppInfo, AppInfo, AppOpenOptions, AppOpenedBy, FilepickerOptions, IOSAppInfo, LaunchAttempt, LaunchError, LaunchErrorCode, LaunchKitInstance, MacOSAppInfo, MailOptions, MapOptions, MessageOptions, OpenPickerStartIn, TelephoneOptions, WindowsAppInfo };

package/dist/launch-kit.cjs

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var version$3 = "0.0.5";
+var version$3 = "0.0.6";
 var packageJSON$3 = {
 	version: version$3};
 
@@ -1898,6 +1898,7 @@ var GLOBAL = getGlobal$1();
 var NAVIGATOR = GLOBAL.navigator;
 var CLEANUP_INPUT_ELEMENT = null;
 var DEBUG = false;
+var APP_IN_FLIGHT = null;
 function createTypeGuard(tag) {
     return function (value) {
         return Object.prototype.toString.call(value) === '[object ' + tag + ']';
@@ -2114,7 +2115,8 @@ function resolveFocusEventConfig() {
         };
     }
 }
-function openURL(tried, url, timeout) {
+function openURL(tried, url, timeout, terminal) {
+    if (terminal === void 0) { terminal = false; }
     var config = resolveFocusEventConfig();
     var top = getTopmostWindow();
     var topDocument = top.document;
@@ -2152,6 +2154,8 @@ function openURL(tried, url, timeout) {
                 }
             }
         }
+        if (terminal)
+            return;
         try {
             iframe = createHiddenElement('iframe');
             iframe.src = url;
@@ -2170,6 +2174,17 @@ function openURL(tried, url, timeout) {
         catch (_) {
         }
     }
+    if (terminal) {
+        return new Promise(function (resolve, reject) {
+            try {
+                open();
+                resolve();
+            }
+            catch (_) {
+                reject();
+            }
+        });
+    }
     return new Promise(function (resolve, reject) {
         if (DEBUG)
             debugger;
@@ -2251,11 +2266,78 @@ function openURL(tried, url, timeout) {
         }
     });
 }
+var FUNCTION_FALLBACK_LABEL = '[function fallback]';
+var CANCEL_DELAY = 1000;
+function createLaunchError(code, message, attempted) {
+    var error = new Error(message);
+    var holder = error;
+    holder['code'] = code;
+    holder['attempted'] = attempted;
+    return error;
+}
+function isWebURL(url) {
+    return /^https?:\/\//i.test(url);
+}
+function isTerminalCandidate(by, url) {
+    return (by === 'fallback' || by === 'store') && isWebURL(url);
+}
+function notifyAttempt(onAttempt, attempt) {
+    if (typeof onAttempt !== 'function')
+        return;
+    try {
+        onAttempt(attempt);
+    }
+    catch (_) {
+    }
+}
+function describeAttempts(attempted) {
+    var routes = [];
+    for (var i = 0; i < attempted.length; i++)
+        routes.push(attempted[i].by);
+    return ' ' + attempted.length + ' candidate(s) attempted (' + joining(routes, undefined, ' \u2b62 ') + '). Read error.attempted for the URLs.';
+}
+function runCandidates(candidates, timeout, onAttempt, failure) {
+    return new Promise(function (resolve, reject) {
+        var attempted = [];
+        var total = candidates.length;
+        function step(index) {
+            if (index >= total)
+                return reject(createLaunchError('all-failed', failure + describeAttempts(attempted), attempted));
+            var by = candidates[index][0];
+            var url = candidates[index][1];
+            var attempt = {
+                by: by,
+                url: typeof url === 'string' ? url : FUNCTION_FALLBACK_LABEL,
+                index: index,
+                total: total,
+            };
+            attempted.push(attempt);
+            notifyAttempt(onAttempt, attempt);
+            if (typeof url !== 'string') {
+                try {
+                    url();
+                }
+                catch (_) {
+                    return step(index + 1);
+                }
+                return resolve(by);
+            }
+            openURL(index, url, timeout, isTerminalCandidate(by, url))
+                .then(function () {
+                resolve(by);
+            })
+                .catch(function () {
+                step(index + 1);
+            });
+        }
+        step(0);
+    });
+}
 function resolveOptions(option) {
     var resolved = [];
     var os = PlatformKit.os.name;
     if (os === 'unknown')
-        throw new Error('Cannot resolve app open options: unsupported or undetected OS. (userAgent: "' + PlatformKit.userAgent + '")');
+        throw createLaunchError('unsupported-os', 'Cannot resolve app open options: unsupported or undetected OS. (userAgent: "' + PlatformKit.userAgent + '")', []);
     var scheme;
     var fallback;
     var allowAppStore;
@@ -2685,7 +2767,7 @@ function resolveFile(module) {
                     done(true);
                 else
                     done(false);
-            }, 1000);
+            }, CANCEL_DELAY);
         }
         function onvisibilitychange() {
             if (!isDocumentHidden())
@@ -2817,6 +2899,8 @@ var LaunchKit = {
     },
     app: function (options) {
         if (options === void 0) { options = {}; }
+        if (APP_IN_FLIGHT !== null)
+            return APP_IN_FLIGHT;
         var resolved;
         try {
             resolved = resolveOptions(options);
@@ -2827,39 +2911,15 @@ var LaunchKit = {
         var urls = resolved[0];
         var timeout = resolved[1];
         if (urls.length === 0)
-            return Promise.reject(new Error('No openable URL candidates were resolved for the current OS ("' + PlatformKit.os.name + '"). Provide at least one of: scheme, intent, universal, fallback, or store id for this platform.'));
-        return new Promise(function (resolve, reject) {
-            var tried = [];
-            function openURLSequential(index) {
-                if (index === void 0) { index = 0; }
-                if (index >= urls.length)
-                    return reject(new Error('Failed to open the application using all available URLs.\n\n' + 'Attempted URLs:\n' + joining(tried, undefined, '\n↓\n')));
-                var entry = urls[index];
-                var by = entry[0];
-                var url = entry[1];
-                if (typeof url === 'string') {
-                    tried[index] = url;
-                    return openURL(index, url, timeout)
-                        .then(function () {
-                        resolve(by);
-                    })
-                        .catch(function () {
-                        openURLSequential(index + 1);
-                    });
-                }
-                else {
-                    tried[index] = '[function fallback]';
-                    try {
-                        url();
-                    }
-                    catch (_) {
-                        return openURLSequential(index + 1);
-                    }
-                    resolve(by);
-                }
-            }
-            return openURLSequential();
-        });
+            return Promise.reject(createLaunchError('no-candidates', 'No openable URL candidates were resolved for the current OS ("' + PlatformKit.os.name + '"). Provide at least one of: scheme, intent, universal, fallback, or store id for this platform.', []));
+        var attempt = runCandidates(urls, timeout, options.onAttempt, 'Failed to open the application.');
+        function release() {
+            if (APP_IN_FLIGHT === attempt)
+                APP_IN_FLIGHT = null;
+        }
+        APP_IN_FLIGHT = attempt;
+        attempt.then(release, release);
+        return attempt;
     },
     telephone: function (options) {
         if (options === void 0) { options = {}; }
@@ -2909,7 +2969,7 @@ var LaunchKit = {
     map: function (options) {
         if (options === void 0) { options = {}; }
         var params = [];
-        var urls = [];
+        var candidates = [];
         var url = '';
         switch (PlatformKit.os.name) {
             case 'android':
@@ -2927,7 +2987,7 @@ var LaunchKit = {
                     params.push('z=' + options.zoom);
                 if (params.length > 0)
                     url = url + '?' + joining(params, undefined, '&');
-                urls.push(url);
+                candidates.push(['scheme', url]);
                 break;
             case 'ios':
             case 'macos':
@@ -2947,7 +3007,7 @@ var LaunchKit = {
                 }
                 if (typeof options.zoom !== 'undefined')
                     params.push('z=' + options.zoom);
-                urls.push('maps://?' + joining(params, undefined, '&'));
+                candidates.push(['scheme', 'maps://?' + joining(params, undefined, '&')]);
                 break;
             case 'windows':
                 if (typeof options.directions !== 'undefined') {
@@ -2963,10 +3023,10 @@ var LaunchKit = {
                 }
                 if (typeof options.zoom !== 'undefined')
                     params.push('lvl=' + options.zoom);
-                urls.push('bingmaps:?' + joining(params, undefined, '&'));
+                candidates.push(['scheme', 'bingmaps:?' + joining(params, undefined, '&')]);
         }
         if (typeof options.fallback !== 'undefined') {
-            urls.push(stripURL(options.fallback));
+            candidates.push(['fallback', stripURL(options.fallback)]);
         }
         else {
             var params_1 = ['api=1'];
@@ -2974,7 +3034,7 @@ var LaunchKit = {
                 params_1.push('destination=' + encodeMapValue(options.directions.destination));
                 if (typeof options.directions.origin !== 'undefined')
                     params_1.push('origin=' + encodeMapValue(options.directions.origin));
-                urls.push('https://www.google.com/maps/dir/?' + joining(params_1, undefined, '&'));
+                candidates.push(['fallback', 'https://www.google.com/maps/dir/?' + joining(params_1, undefined, '&')]);
             }
             else {
                 if (typeof options.coordinate !== 'undefined')
@@ -2983,34 +3043,10 @@ var LaunchKit = {
                     params_1.push('query=' + escapeURIComponentString(options.query));
                 if (typeof options.zoom !== 'undefined')
                     params_1.push('zoom=' + options.zoom);
-                urls.push('https://www.google.com/maps/search/?' + joining(params_1, undefined, '&'));
+                candidates.push(['fallback', 'https://www.google.com/maps/search/?' + joining(params_1, undefined, '&')]);
             }
         }
-        return new Promise(function (resolve, reject) {
-            var tried = [];
-            function openURLSequential(index) {
-                if (index === void 0) { index = 0; }
-                if (index >= urls.length)
-                    return reject(new Error('Failed to open a map using all available URLs.\n\nAttempted URLs:\n' + joining(tried, undefined, '\n↓\n')));
-                var url = urls[index];
-                if (typeof url === 'string') {
-                    tried[index] = url;
-                    return openURL(index, url, getDefaultTimeout())
-                        .then(function () {
-                        resolve();
-                    })
-                        .catch(function () {
-                        openURLSequential(index + 1);
-                    });
-                }
-                else {
-                    tried[index] = '[function fallback]';
-                    url();
-                    resolve();
-                }
-            }
-            return openURLSequential();
-        });
+        return runCandidates(candidates, getDefaultTimeout(), options.onAttempt, 'Failed to open a map.');
     },
     filepicker: function (options) {
         if (options === void 0) { options = {}; }