@ait-co/polyfill 0.1.1

package/dist/shims/vibrate.js

@@ -0,0 +1,135 @@
+//#region src/detect.ts
+/**
+* Environment detection: are we running inside Apps in Toss, or a plain browser?
+*
+* Strategy: feature-sniff `@apps-in-toss/web-framework`. The SDK is declared as
+* an **optional** peer dependency. If it resolves and exposes a known export,
+* we assume we can route calls through it; otherwise we fall back to the
+* browser's native implementation in each shim.
+*
+* We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK
+* function during detection (could prompt permission dialogs, fire analytics,
+* etc.).
+*/
+let cached;
+/**
+* Returns `true` iff we detect we are running in an environment where the
+* Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.
+*
+* Async because we use dynamic `import()` to probe the optional peer dep
+* without forcing it into the consumer's bundle.
+*/
+async function isTossEnvironment() {
+	const force = globalThis.__AIT_POLYFILL_FORCE__;
+	if (force === "toss") return true;
+	if (force === "browser") return false;
+	if (cached !== void 0) return cached;
+	cached = typeof (await loadTossSdk())?.getClipboardText === "function";
+	return cached;
+}
+/**
+* Lazy SDK accessor — returns the module if available, else `null`. Callers
+* are expected to `await` and null-check. Never throws.
+*/
+async function loadTossSdk() {
+	try {
+		return await import("@apps-in-toss/web-framework");
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/shims/vibrate.ts
+/**
+* `navigator.vibrate` shim.
+*
+* Inside Apps in Toss → best-effort mapping to SDK `generateHapticFeedback`:
+*   - `vibrate(0)` → no-op (web standard: cancels pending vibration)
+*   - `vibrate(number)`: short (< 40ms) → `tickWeak`, long (≥ 40ms) → `basicMedium`
+*   - `vibrate(number[])`: iterate "on" segments (even indices) as `tap` pulses
+*
+* Outside Apps in Toss → defers to the browser's native `navigator.vibrate`,
+* or returns `false` when unavailable (matches the spec — browsers that don't
+* support vibration simply return `false`).
+*
+* Caveats (documented in CLAUDE.md as the known lossy trade-off):
+*   - SDK haptics are qualitative ("tickWeak", "basicMedium"), not millisecond
+*     durations. The shim approximates intensity from duration but cannot
+*     reproduce exact patterns.
+*   - Arrays are fired sequentially via `setTimeout`; gaps between pulses are
+*     honoured only as "time until the next tap", not as silent-vs-vibrating.
+*   - `vibrate` is spec'd as **synchronous**; the SDK call is async. We return
+*     `true` immediately (fire-and-forget). Errors from the SDK are swallowed.
+*/
+const BACKUP_KEY = Symbol.for("@ait-co/polyfill/vibrate.original");
+const HAD_KEY = Symbol.for("@ait-co/polyfill/vibrate.hadOriginal");
+const SHORT_VIBRATION_MS = 40;
+async function haptic(type) {
+	const fn = (await loadTossSdk())?.generateHapticFeedback;
+	if (typeof fn === "function") try {
+		await fn({ type });
+	} catch {}
+}
+function durationToHaptic(duration) {
+	return duration < SHORT_VIBRATION_MS ? "tickWeak" : "basicMedium";
+}
+function vibrateShim(pattern) {
+	const arr = Array.isArray(pattern) ? pattern : [pattern];
+	if (arr.length === 0 || arr.every((n) => n === 0)) {
+		(async () => {
+			if (!await isTossEnvironment()) navigator[BACKUP_KEY]?.call(navigator, pattern);
+		})();
+		return true;
+	}
+	(async () => {
+		if (await isTossEnvironment()) {
+			if (!Array.isArray(pattern)) {
+				await haptic(durationToHaptic(pattern));
+				return;
+			}
+			for (let i = 0; i < pattern.length; i += 2) {
+				const on = pattern[i];
+				if (on === void 0) break;
+				if (on > 0) await haptic("tap");
+				const pause = pattern[i + 1];
+				if (typeof pause === "number" && pause > 0) await new Promise((r) => setTimeout(r, pause));
+			}
+			return;
+		}
+		navigator[BACKUP_KEY]?.call(navigator, pattern);
+	})();
+	return true;
+}
+function installVibrateShim() {
+	if (typeof navigator === "undefined") return () => {};
+	const host = navigator;
+	if (BACKUP_KEY in host) return () => uninstallVibrateShim();
+	const nav = navigator;
+	host[BACKUP_KEY] = nav.vibrate;
+	host[HAD_KEY] = "vibrate" in nav;
+	Object.defineProperty(navigator, "vibrate", {
+		value: vibrateShim,
+		configurable: true,
+		writable: true
+	});
+	return uninstallVibrateShim;
+}
+function uninstallVibrateShim() {
+	if (typeof navigator === "undefined") return;
+	const host = navigator;
+	if (!(BACKUP_KEY in host)) return;
+	const original = host[BACKUP_KEY];
+	const had = host[HAD_KEY];
+	delete navigator.vibrate;
+	if (had && navigator.vibrate !== original) Object.defineProperty(navigator, "vibrate", {
+		value: original,
+		configurable: true,
+		writable: true
+	});
+	delete host[BACKUP_KEY];
+	delete host[HAD_KEY];
+}
+//#endregion
+export { installVibrateShim, uninstallVibrateShim };
+
+//# sourceMappingURL=vibrate.js.map

package/dist/shims/vibrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vibrate.js","names":[],"sources":["../../src/detect.ts","../../src/shims/vibrate.ts"],"sourcesContent":["/**\n * Environment detection: are we running inside Apps in Toss, or a plain browser?\n *\n * Strategy: feature-sniff `@apps-in-toss/web-framework`. The SDK is declared as\n * an **optional** peer dependency. If it resolves and exposes a known export,\n * we assume we can route calls through it; otherwise we fall back to the\n * browser's native implementation in each shim.\n *\n * We deliberately avoid UA sniffing (spoofable) and avoid calling any SDK\n * function during detection (could prompt permission dialogs, fire analytics,\n * etc.).\n */\n\nlet cached: boolean | undefined;\n\n/**\n * Reset the cached detection result. Primarily for tests.\n */\nexport function resetDetection(): void {\n  cached = undefined;\n}\n\n/**\n * Synchronous read of the cached detection result. Returns:\n *   - `true` / `false` if an override is active or the async detection has\n *     already resolved\n *   - `undefined` if detection hasn't run yet\n *\n * Used by spec-sync APIs (e.g. `navigator.canShare`) that can't `await`\n * detection.\n */\nexport function isTossEnvironmentCached(): boolean | undefined {\n  const force = globalThis.__AIT_POLYFILL_FORCE__;\n  if (force === 'toss') return true;\n  if (force === 'browser') return false;\n  return cached;\n}\n\n/**\n * Returns `true` iff we detect we are running in an environment where the\n * Apps in Toss SDK (`@apps-in-toss/web-framework`) is present and usable.\n *\n * Async because we use dynamic `import()` to probe the optional peer dep\n * without forcing it into the consumer's bundle.\n */\nexport async function isTossEnvironment(): Promise<boolean> {\n  // Override check precedes cache so `devtools` / tests can flip the result\n  // mid-session without a `resetDetection()` call.\n  const force = globalThis.__AIT_POLYFILL_FORCE__;\n  if (force === 'toss') return true;\n  if (force === 'browser') return false;\n\n  if (cached !== undefined) return cached;\n\n  const mod = await loadTossSdk();\n  // Presence of a well-known export is our smoke test.\n  cached = typeof mod?.getClipboardText === 'function';\n  return cached;\n}\n\n/**\n * Lazy SDK accessor — returns the module if available, else `null`. Callers\n * are expected to `await` and null-check. Never throws.\n */\nexport async function loadTossSdk(): Promise<typeof import('@apps-in-toss/web-framework') | null> {\n  try {\n    return await import('@apps-in-toss/web-framework');\n  } catch {\n    return null;\n  }\n}\n","/**\n * `navigator.vibrate` shim.\n *\n * Inside Apps in Toss → best-effort mapping to SDK `generateHapticFeedback`:\n *   - `vibrate(0)` → no-op (web standard: cancels pending vibration)\n *   - `vibrate(number)`: short (< 40ms) → `tickWeak`, long (≥ 40ms) → `basicMedium`\n *   - `vibrate(number[])`: iterate \"on\" segments (even indices) as `tap` pulses\n *\n * Outside Apps in Toss → defers to the browser's native `navigator.vibrate`,\n * or returns `false` when unavailable (matches the spec — browsers that don't\n * support vibration simply return `false`).\n *\n * Caveats (documented in CLAUDE.md as the known lossy trade-off):\n *   - SDK haptics are qualitative (\"tickWeak\", \"basicMedium\"), not millisecond\n *     durations. The shim approximates intensity from duration but cannot\n *     reproduce exact patterns.\n *   - Arrays are fired sequentially via `setTimeout`; gaps between pulses are\n *     honoured only as \"time until the next tap\", not as silent-vs-vibrating.\n *   - `vibrate` is spec'd as **synchronous**; the SDK call is async. We return\n *     `true` immediately (fire-and-forget). Errors from the SDK are swallowed.\n */\n\nimport { isTossEnvironment, loadTossSdk } from '../detect.js';\n\nconst BACKUP_KEY = Symbol.for('@ait-co/polyfill/vibrate.original');\nconst HAD_KEY = Symbol.for('@ait-co/polyfill/vibrate.hadOriginal');\n\ninterface BackupHost {\n  [BACKUP_KEY]?: ((pattern: VibratePattern) => boolean) | undefined;\n  [HAD_KEY]?: boolean;\n}\n\nconst SHORT_VIBRATION_MS = 40;\n\ntype HapticType =\n  | 'tickWeak'\n  | 'tap'\n  | 'tickMedium'\n  | 'softMedium'\n  | 'basicWeak'\n  | 'basicMedium'\n  | 'success'\n  | 'error'\n  | 'wiggle'\n  | 'confetti';\n\nasync function haptic(type: HapticType): Promise<void> {\n  const sdk = await loadTossSdk();\n  const fn = (sdk as { generateHapticFeedback?: unknown } | null)?.generateHapticFeedback;\n  if (typeof fn === 'function') {\n    try {\n      await (fn as (o: { type: HapticType }) => Promise<void>)({ type });\n    } catch {\n      // Best-effort; spec-level `vibrate` cannot surface errors.\n    }\n  }\n}\n\nfunction durationToHaptic(duration: number): HapticType {\n  return duration < SHORT_VIBRATION_MS ? 'tickWeak' : 'basicMedium';\n}\n\nfunction vibrateShim(pattern: VibratePattern): boolean {\n  // Matches the spec: `vibrate(0)` or `vibrate([])` cancels pending vibration.\n  // We can't cancel an in-flight SDK haptic (no cancel API), but we still\n  // forward the cancel to the browser fallback so native vibration stops.\n  const arr = Array.isArray(pattern) ? pattern : [pattern];\n  if (arr.length === 0 || arr.every((n) => n === 0)) {\n    void (async () => {\n      if (!(await isTossEnvironment())) {\n        const host = navigator as unknown as BackupHost;\n        host[BACKUP_KEY]?.call(navigator, pattern);\n      }\n    })();\n    return true;\n  }\n\n  void (async () => {\n    if (await isTossEnvironment()) {\n      if (!Array.isArray(pattern)) {\n        await haptic(durationToHaptic(pattern));\n        return;\n      }\n      // Even indices = \"on\" durations, odd indices = pauses. `pattern[i]` is\n      // `number | undefined` under `noUncheckedIndexedAccess`; the `undefined`\n      // case only arises on out-of-bounds, which our length bound prevents.\n      for (let i = 0; i < pattern.length; i += 2) {\n        const on = pattern[i];\n        if (on === undefined) break;\n        if (on > 0) {\n          await haptic('tap');\n        }\n        const pause = pattern[i + 1];\n        if (typeof pause === 'number' && pause > 0) {\n          await new Promise<void>((r) => setTimeout(r, pause));\n        }\n      }\n      return;\n    }\n    const host = navigator as unknown as BackupHost;\n    const original = host[BACKUP_KEY];\n    original?.call(navigator, pattern);\n  })();\n\n  return true;\n}\n\nexport function installVibrateShim(): () => void {\n  if (typeof navigator === 'undefined') {\n    return () => {};\n  }\n\n  const host = navigator as unknown as BackupHost;\n  if (BACKUP_KEY in host) {\n    return () => uninstallVibrateShim();\n  }\n\n  const nav = navigator as Navigator & { vibrate?: (p: VibratePattern) => boolean };\n  host[BACKUP_KEY] = nav.vibrate;\n  host[HAD_KEY] = 'vibrate' in nav;\n\n  Object.defineProperty(navigator, 'vibrate', {\n    value: vibrateShim,\n    configurable: true,\n    writable: true,\n  });\n\n  return uninstallVibrateShim;\n}\n\nexport function uninstallVibrateShim(): void {\n  if (typeof navigator === 'undefined') return;\n  const host = navigator as unknown as BackupHost;\n  if (!(BACKUP_KEY in host)) return;\n\n  const original = host[BACKUP_KEY];\n  const had = host[HAD_KEY];\n  // Prototype-safe restore: delete the instance override first, then only\n  // redefine on the instance if the original was an own property the\n  // prototype doesn't provide — prevents permanent shadowing of a prototype\n  // `vibrate` getter on real browsers.\n  delete (navigator as unknown as { vibrate?: (p: VibratePattern) => boolean }).vibrate;\n  if (had && navigator.vibrate !== original) {\n    Object.defineProperty(navigator, 'vibrate', {\n      value: original,\n      configurable: true,\n      writable: true,\n    });\n  }\n  delete host[BACKUP_KEY];\n  delete host[HAD_KEY];\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,IAAI;;;;;;;;AAgCJ,eAAsB,oBAAsC;CAG1D,MAAM,QAAQ,WAAW;AACzB,KAAI,UAAU,OAAQ,QAAO;AAC7B,KAAI,UAAU,UAAW,QAAO;AAEhC,KAAI,WAAW,KAAA,EAAW,QAAO;AAIjC,UAAS,QAFG,MAAM,aAAa,GAEV,qBAAqB;AAC1C,QAAO;;;;;;AAOT,eAAsB,cAA4E;AAChG,KAAI;AACF,SAAO,MAAM,OAAO;SACd;AACN,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AC5CX,MAAM,aAAa,OAAO,IAAI,oCAAoC;AAClE,MAAM,UAAU,OAAO,IAAI,uCAAuC;AAOlE,MAAM,qBAAqB;AAc3B,eAAe,OAAO,MAAiC;CAErD,MAAM,MADM,MAAM,aAAa,GACkC;AACjE,KAAI,OAAO,OAAO,WAChB,KAAI;AACF,QAAO,GAAkD,EAAE,MAAM,CAAC;SAC5D;;AAMZ,SAAS,iBAAiB,UAA8B;AACtD,QAAO,WAAW,qBAAqB,aAAa;;AAGtD,SAAS,YAAY,SAAkC;CAIrD,MAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;AACxD,KAAI,IAAI,WAAW,KAAK,IAAI,OAAO,MAAM,MAAM,EAAE,EAAE;AACjD,GAAM,YAAY;AAChB,OAAI,CAAE,MAAM,mBAAmB,CAChB,WACR,aAAa,KAAK,WAAW,QAAQ;MAE1C;AACJ,SAAO;;AAGT,EAAM,YAAY;AAChB,MAAI,MAAM,mBAAmB,EAAE;AAC7B,OAAI,CAAC,MAAM,QAAQ,QAAQ,EAAE;AAC3B,UAAM,OAAO,iBAAiB,QAAQ,CAAC;AACvC;;AAKF,QAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK,GAAG;IAC1C,MAAM,KAAK,QAAQ;AACnB,QAAI,OAAO,KAAA,EAAW;AACtB,QAAI,KAAK,EACP,OAAM,OAAO,MAAM;IAErB,MAAM,QAAQ,QAAQ,IAAI;AAC1B,QAAI,OAAO,UAAU,YAAY,QAAQ,EACvC,OAAM,IAAI,SAAe,MAAM,WAAW,GAAG,MAAM,CAAC;;AAGxD;;AAEW,YACS,aACZ,KAAK,WAAW,QAAQ;KAChC;AAEJ,QAAO;;AAGT,SAAgB,qBAAiC;AAC/C,KAAI,OAAO,cAAc,YACvB,cAAa;CAGf,MAAM,OAAO;AACb,KAAI,cAAc,KAChB,cAAa,sBAAsB;CAGrC,MAAM,MAAM;AACZ,MAAK,cAAc,IAAI;AACvB,MAAK,WAAW,aAAa;AAE7B,QAAO,eAAe,WAAW,WAAW;EAC1C,OAAO;EACP,cAAc;EACd,UAAU;EACX,CAAC;AAEF,QAAO;;AAGT,SAAgB,uBAA6B;AAC3C,KAAI,OAAO,cAAc,YAAa;CACtC,MAAM,OAAO;AACb,KAAI,EAAE,cAAc,MAAO;CAE3B,MAAM,WAAW,KAAK;CACtB,MAAM,MAAM,KAAK;AAKjB,QAAQ,UAAsE;AAC9E,KAAI,OAAO,UAAU,YAAY,SAC/B,QAAO,eAAe,WAAW,WAAW;EAC1C,OAAO;EACP,cAAc;EACd,UAAU;EACX,CAAC;AAEJ,QAAO,KAAK;AACZ,QAAO,KAAK"}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@ait-co/polyfill",
+  "version": "0.1.1",
+  "description": "Polyfill so you can build Apps in Toss mini-apps with standard Web APIs (navigator.clipboard, navigator.geolocation, ...) instead of the proprietary SDK",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./clipboard": {
+      "types": "./dist/shims/clipboard.d.ts",
+      "import": "./dist/shims/clipboard.js"
+    },
+    "./geolocation": {
+      "types": "./dist/shims/geolocation.d.ts",
+      "import": "./dist/shims/geolocation.js"
+    },
+    "./share": {
+      "types": "./dist/shims/share.d.ts",
+      "import": "./dist/shims/share.js"
+    },
+    "./vibrate": {
+      "types": "./dist/shims/vibrate.d.ts",
+      "import": "./dist/shims/vibrate.js"
+    },
+    "./network": {
+      "types": "./dist/shims/network.d.ts",
+      "import": "./dist/shims/network.js"
+    },
+    "./detect": {
+      "types": "./dist/detect.d.ts",
+      "import": "./dist/detect.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "peerDependencies": {
+    "@apps-in-toss/web-framework": ">=2.4.0 <3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@apps-in-toss/web-framework": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apps-in-toss/web-framework": "2.4.7",
+    "@biomejs/biome": "2.4.12",
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^24.0.0",
+    "jsdom": "^29.0.2",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "keywords": [
+    "apps-in-toss",
+    "toss",
+    "mini-app",
+    "polyfill",
+    "web-api"
+  ],
+  "packageManager": "pnpm@10.33.0",
+  "license": "BSD-3-Clause",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apps-in-toss-community/polyfill"
+  },
+  "homepage": "https://www.npmjs.com/package/@ait-co/polyfill",
+  "bugs": {
+    "url": "https://github.com/apps-in-toss-community/polyfill/issues"
+  }
+}