@jskit-ai/mobile-capacitor 0.1.1

package/src/client/runtime/apiRequestClient.js

@@ -0,0 +1,136 @@
+const API_ROUTE_PREFIXES = Object.freeze([
+  "/api",
+  "/socket.io"
+]);
+
+function parseAbsoluteHttpUrl(url = "", {
+  apiBaseUrl = "",
+  emptyUrlMessage = "URL is required.",
+  missingApiBaseUrlMessage = "config.mobile.apiBaseUrl is required.",
+  invalidApiBaseUrlMessage = "config.mobile.apiBaseUrl must be a valid absolute URL.",
+  invalidApiBaseUrlProtocolMessage = "config.mobile.apiBaseUrl must use http or https.",
+  invalidUrlProtocolMessage = "URL must use http or https."
+} = {}) {
+  const normalizedUrl = String(url || "").trim();
+  if (!normalizedUrl) {
+    throw new Error(emptyUrlMessage);
+  }
+
+  let absoluteUrl = null;
+  try {
+    absoluteUrl = new URL(normalizedUrl);
+  } catch {}
+
+  if (absoluteUrl) {
+    const protocol = String(absoluteUrl.protocol || "").toLowerCase();
+    if (protocol !== "http:" && protocol !== "https:") {
+      throw new Error(invalidUrlProtocolMessage);
+    }
+    return absoluteUrl.toString();
+  }
+
+  const normalizedApiBaseUrl = String(apiBaseUrl || "").trim();
+  if (!normalizedApiBaseUrl) {
+    throw new Error(missingApiBaseUrlMessage);
+  }
+
+  let baseUrl;
+  try {
+    baseUrl = new URL(normalizedApiBaseUrl);
+  } catch {
+    throw new Error(invalidApiBaseUrlMessage);
+  }
+
+  const baseProtocol = String(baseUrl.protocol || "").toLowerCase();
+  if (baseProtocol !== "http:" && baseProtocol !== "https:") {
+    throw new Error(invalidApiBaseUrlProtocolMessage);
+  }
+
+  return new URL(normalizedUrl, baseUrl).toString();
+}
+
+function resolveCapacitorAbsoluteHttpUrl(url = "", apiBaseUrl = "", messages = {}) {
+  return parseAbsoluteHttpUrl(url, {
+    ...messages,
+    apiBaseUrl
+  });
+}
+
+function isCapacitorApiRequestTarget(url = "") {
+  const normalizedUrl = String(url || "").trim();
+  if (!normalizedUrl.startsWith("/")) {
+    return false;
+  }
+  return API_ROUTE_PREFIXES.some((prefix) => normalizedUrl === prefix || normalizedUrl.startsWith(`${prefix}/`));
+}
+
+function normalizeFetchInput(input = "") {
+  if (typeof input === "string") {
+    return Object.freeze({
+      rawUrl: input,
+      rebuild(nextUrl) {
+        return nextUrl;
+      }
+    });
+  }
+
+  if (typeof URL === "function" && input instanceof URL) {
+    return Object.freeze({
+      rawUrl: input.toString(),
+      rebuild(nextUrl) {
+        return nextUrl;
+      }
+    });
+  }
+
+  if (typeof Request === "function" && input instanceof Request) {
+    return Object.freeze({
+      rawUrl: String(input.url || ""),
+      rebuild(nextUrl) {
+        return new Request(nextUrl, input);
+      }
+    });
+  }
+
+  return Object.freeze({
+    rawUrl: "",
+    rebuild() {
+      return input;
+    }
+  });
+}
+
+function createCapacitorAwareFetch({
+  fetchImpl = globalThis.fetch,
+  adapter = null,
+  apiBaseUrl = ""
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("createCapacitorAwareFetch requires fetchImpl.");
+  }
+
+  return async function capacitorAwareFetch(input, init) {
+    if (adapter?.available !== true) {
+      return fetchImpl(input, init);
+    }
+
+    const normalizedInput = normalizeFetchInput(input);
+    if (!isCapacitorApiRequestTarget(normalizedInput.rawUrl)) {
+      return fetchImpl(input, init);
+    }
+
+    const resolvedUrl = resolveCapacitorAbsoluteHttpUrl(normalizedInput.rawUrl, apiBaseUrl, {
+      emptyUrlMessage: "Capacitor API request URL is required.",
+      missingApiBaseUrlMessage: "config.mobile.apiBaseUrl is required for Capacitor API requests.",
+      invalidUrlProtocolMessage: "Capacitor API request URL must use http or https."
+    });
+
+    return fetchImpl(normalizedInput.rebuild(resolvedUrl), init);
+  };
+}
+
+export {
+  createCapacitorAwareFetch,
+  isCapacitorApiRequestTarget,
+  resolveCapacitorAbsoluteHttpUrl
+};

package/src/client/runtime/globalCapacitorAppAdapter.js

@@ -0,0 +1,136 @@
+function resolveCapacitorAppPlugin(globalObject = globalThis) {
+  if (!globalObject || typeof globalObject !== "object") {
+    return null;
+  }
+
+  const pluginFromPlugins = globalObject?.Capacitor?.Plugins?.App;
+  if (pluginFromPlugins && typeof pluginFromPlugins === "object") {
+    return pluginFromPlugins;
+  }
+
+  const directPlugin = globalObject?.Capacitor?.App;
+  if (directPlugin && typeof directPlugin === "object") {
+    return directPlugin;
+  }
+
+  return null;
+}
+
+function createNoopCapacitorAppAdapter() {
+  return Object.freeze({
+    available: false,
+    async getInitialLaunchUrl() {
+      return "";
+    },
+    subscribeToLaunchUrls() {
+      return () => {};
+    },
+    subscribeToBackButton() {
+      return () => {};
+    },
+    async exitApp() {
+      return false;
+    }
+  });
+}
+
+function createGlobalCapacitorAppAdapter({ globalObject = globalThis, appPlugin = null } = {}) {
+  const plugin = appPlugin || resolveCapacitorAppPlugin(globalObject);
+  if (!plugin || typeof plugin !== "object") {
+    return createNoopCapacitorAppAdapter();
+  }
+
+  return Object.freeze({
+    available: typeof plugin.getLaunchUrl === "function" || typeof plugin.addListener === "function",
+    async getInitialLaunchUrl() {
+      if (typeof plugin.getLaunchUrl !== "function") {
+        return "";
+      }
+
+      const payload = await plugin.getLaunchUrl();
+      return String(payload?.url || "").trim();
+    },
+    subscribeToLaunchUrls(handler = () => {}) {
+      if (typeof plugin.addListener !== "function") {
+        return () => {};
+      }
+
+      let disposed = false;
+      let removeListener = null;
+
+      Promise.resolve(
+        plugin.addListener("appUrlOpen", (event = {}) => {
+          if (disposed) {
+            return;
+          }
+
+          handler(String(event?.url || "").trim());
+        })
+      )
+        .then((listenerHandle) => {
+          removeListener = listenerHandle;
+          if (disposed && typeof removeListener?.remove === "function") {
+            return removeListener.remove();
+          }
+          return null;
+        })
+        .catch(() => {});
+
+      return () => {
+        disposed = true;
+        if (typeof removeListener?.remove === "function") {
+          void removeListener.remove();
+        }
+      };
+    },
+    subscribeToBackButton(handler = () => {}) {
+      if (typeof plugin.addListener !== "function") {
+        return () => {};
+      }
+
+      let disposed = false;
+      let removeListener = null;
+
+      Promise.resolve(
+        plugin.addListener("backButton", (event = {}) => {
+          if (disposed) {
+            return;
+          }
+
+          handler({
+            canGoBack: event?.canGoBack === true
+          });
+        })
+      )
+        .then((listenerHandle) => {
+          removeListener = listenerHandle;
+          if (disposed && typeof removeListener?.remove === "function") {
+            return removeListener.remove();
+          }
+          return null;
+        })
+        .catch(() => {});
+
+      return () => {
+        disposed = true;
+        if (typeof removeListener?.remove === "function") {
+          void removeListener.remove();
+        }
+      };
+    },
+    async exitApp() {
+      if (typeof plugin.exitApp !== "function") {
+        return false;
+      }
+
+      await plugin.exitApp();
+      return true;
+    }
+  });
+}
+
+export {
+  createGlobalCapacitorAppAdapter,
+  createNoopCapacitorAppAdapter,
+  resolveCapacitorAppPlugin
+};

package/src/client/runtime/mobileCapacitorRuntime.js

@@ -0,0 +1,215 @@
+import { registerMobileLaunchRouting, resolveMobileConfig } from "@jskit-ai/kernel/client";
+import { createNoopCapacitorAppAdapter } from "./globalCapacitorAppAdapter.js";
+
+function extractPathname(value = "") {
+  const normalizedValue = String(value || "").trim();
+  if (!normalizedValue) {
+    return "";
+  }
+
+  try {
+    const parsed = new URL(normalizedValue, "https://jskit.invalid");
+    return String(parsed.pathname || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function normalizeCallbackCompleter(value = null) {
+  if (value && typeof value.completeFromUrl === "function") {
+    return value;
+  }
+
+  if (typeof value === "function") {
+    return Object.freeze({
+      completeFromUrl: value
+    });
+  }
+
+  return null;
+}
+
+function normalizeAuthGuardRuntime(value = null) {
+  if (
+    value &&
+    typeof value === "object" &&
+    typeof value.getState === "function" &&
+    (typeof value.initialize === "function" || typeof value.refresh === "function")
+  ) {
+    return value;
+  }
+
+  return null;
+}
+
+function isAuthCallbackTargetPath(targetPath = "", mobileConfig = {}) {
+  const callbackPath = String(mobileConfig?.auth?.callbackPath || "").trim();
+  if (!callbackPath) {
+    return false;
+  }
+
+  return extractPathname(targetPath) === callbackPath;
+}
+
+function createMobileCapacitorRuntime({
+  router,
+  mobileConfig = {},
+  adapter = createNoopCapacitorAppAdapter(),
+  placementRuntime = null,
+  authCallbackCompleter = null,
+  authGuardRuntime = null,
+  logger = null
+} = {}) {
+  if (!router || typeof router.replace !== "function") {
+    throw new TypeError("createMobileCapacitorRuntime requires router.replace().");
+  }
+
+  const resolvedMobileConfig = resolveMobileConfig({
+    mobile: mobileConfig
+  });
+  const resolvedAdapter = adapter && typeof adapter === "object" ? adapter : createNoopCapacitorAppAdapter();
+  const resolvedAuthCallbackCompleter = normalizeCallbackCompleter(authCallbackCompleter);
+  const resolvedAuthGuardRuntime = normalizeAuthGuardRuntime(authGuardRuntime);
+  let launchRouting = null;
+  let initialized = false;
+  let lastAppliedPath = "";
+  let authGuardReadyPromise = null;
+  let removeBackButtonListener = null;
+
+  async function ensureAuthGuardReady() {
+    if (!resolvedAuthGuardRuntime) {
+      return null;
+    }
+
+    if (authGuardReadyPromise) {
+      return authGuardReadyPromise;
+    }
+
+    authGuardReadyPromise = (async () => {
+      if (typeof resolvedAuthGuardRuntime.initialize === "function") {
+        return resolvedAuthGuardRuntime.initialize();
+      }
+      return resolvedAuthGuardRuntime.refresh();
+    })();
+
+    try {
+      return await authGuardReadyPromise;
+    } catch (error) {
+      authGuardReadyPromise = null;
+      throw error;
+    }
+  }
+
+  async function resolveTargetPath({ originalUrl = "", normalizedTargetPath = "" } = {}) {
+    if (!resolvedAuthCallbackCompleter || !isAuthCallbackTargetPath(normalizedTargetPath, resolvedMobileConfig)) {
+      return normalizedTargetPath;
+    }
+
+    const fallbackReturnTo = String(router.currentRoute?.value?.fullPath || "/").trim() || "/";
+    const authResult = await resolvedAuthCallbackCompleter.completeFromUrl({
+      url: originalUrl,
+      fallbackReturnTo,
+      placementContext: placementRuntime && typeof placementRuntime.getContext === "function"
+        ? placementRuntime.getContext()
+        : null,
+      defaultProvider:
+        resolvedAuthGuardRuntime && typeof resolvedAuthGuardRuntime.getState === "function"
+          ? String(resolvedAuthGuardRuntime.getState()?.oauthDefaultProvider || "")
+          : "",
+      refreshSession:
+        resolvedAuthGuardRuntime && typeof resolvedAuthGuardRuntime.refresh === "function"
+          ? () => resolvedAuthGuardRuntime.refresh()
+          : async () => null
+    });
+
+    if (authResult?.completed === true) {
+      return authResult.returnTo || fallbackReturnTo;
+    }
+
+    return normalizedTargetPath;
+  }
+
+  function createLaunchRouting() {
+    return registerMobileLaunchRouting({
+      router,
+      mobileConfig: resolvedMobileConfig,
+      getInitialLaunchUrl: () => resolvedAdapter.getInitialLaunchUrl(),
+      subscribeToLaunchUrls: (handler) => resolvedAdapter.subscribeToLaunchUrls(handler),
+      resolveTargetPath,
+      logger
+    });
+  }
+
+  function wireBackButtonHandling() {
+    if (typeof resolvedAdapter.subscribeToBackButton !== "function") {
+      return;
+    }
+    if (!router || typeof router.back !== "function") {
+      return;
+    }
+
+    removeBackButtonListener = resolvedAdapter.subscribeToBackButton(async (event = {}) => {
+      if (event?.canGoBack === true) {
+        router.back();
+        return;
+      }
+
+      if (typeof resolvedAdapter.exitApp === "function") {
+        await resolvedAdapter.exitApp();
+      }
+    });
+  }
+
+  async function initialize() {
+    if (initialized) {
+      return lastAppliedPath;
+    }
+
+    initialized = true;
+    await ensureAuthGuardReady();
+    launchRouting = createLaunchRouting();
+    wireBackButtonHandling();
+    lastAppliedPath = await launchRouting.initialize();
+    return lastAppliedPath;
+  }
+
+  async function applyIncomingUrl(url = "", reason = "manual") {
+    if (!launchRouting) {
+      await ensureAuthGuardReady();
+      launchRouting = createLaunchRouting();
+    }
+
+    lastAppliedPath = await launchRouting.applyIncomingUrl(url, reason);
+    return lastAppliedPath;
+  }
+
+  function dispose() {
+    if (launchRouting && typeof launchRouting.dispose === "function") {
+      launchRouting.dispose();
+    }
+    if (typeof removeBackButtonListener === "function") {
+      removeBackButtonListener();
+    }
+    launchRouting = null;
+    removeBackButtonListener = null;
+    initialized = false;
+  }
+
+  function getState() {
+    return Object.freeze({
+      initialized,
+      available: resolvedAdapter.available === true,
+      enabled: resolvedMobileConfig.enabled === true,
+      lastAppliedPath
+    });
+  }
+
+  return Object.freeze({
+    initialize,
+    applyIncomingUrl,
+    dispose,
+    getState
+  });
+}
+
+export { createMobileCapacitorRuntime };

package/src/client/runtime/oauthLaunchClient.js

@@ -0,0 +1,45 @@
+import { Browser } from "@capacitor/browser";
+import { resolveCapacitorAbsoluteHttpUrl } from "./apiRequestClient.js";
+
+function resolveCapacitorLaunchUrl(url = "", apiBaseUrl = "") {
+  return resolveCapacitorAbsoluteHttpUrl(url, apiBaseUrl, {
+    emptyUrlMessage: "OAuth launch URL is required.",
+    missingApiBaseUrlMessage: "config.mobile.apiBaseUrl is required to launch OAuth from the Capacitor shell.",
+    invalidUrlProtocolMessage: "OAuth launch URL must use http or https."
+  });
+}
+
+function createCapacitorAwareOAuthLaunchClient({
+  adapter = null,
+  browserPlugin = Browser,
+  location = null,
+  apiBaseUrl = ""
+} = {}) {
+  const resolvedLocation =
+    location || (typeof window === "object" && window?.location ? window.location : null);
+
+  return Object.freeze({
+    async open({ url = "" } = {}) {
+      const normalizedUrl = String(url || "").trim();
+      if (!normalizedUrl) {
+        throw new Error("OAuth launch URL is required.");
+      }
+
+      if (adapter?.available === true && browserPlugin && typeof browserPlugin.open === "function") {
+        await browserPlugin.open({
+          url: resolveCapacitorLaunchUrl(normalizedUrl, apiBaseUrl)
+        });
+        return true;
+      }
+
+      if (!resolvedLocation || typeof resolvedLocation.assign !== "function") {
+        throw new Error("Browser location.assign() is unavailable for OAuth launch.");
+      }
+
+      resolvedLocation.assign(normalizedUrl);
+      return true;
+    }
+  });
+}
+
+export { createCapacitorAwareOAuthLaunchClient, resolveCapacitorLaunchUrl };