akanjs 3.0.0-beta.9 → 3.0.0

package/vendor/@akanjs/native/plugins/camera/src/web.ts

@@ -0,0 +1,267 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { CameraApi, PermissionState, Photo, PickImagesOptions, TakePhotoOptions } from "./index.ts";
+
+const cancelled = () => new AkanNativeError("CANCELLED", "photo capture was cancelled");
+
+function isTouchPrimary(): boolean {
+  return window.matchMedia?.("(pointer: coarse)").matches ?? false;
+}
+
+type Output = Pick<TakePhotoOptions, "quality" | "maxWidth" | "maxHeight">;
+
+const jpegQuality = (output: Output) => Math.min(100, Math.max(1, output.quality ?? 90)) / 100;
+
+/** The largest size within the limits, keeping the aspect ratio. */
+function fit(width: number, height: number, output: Output): { width: number; height: number } {
+  const scale = Math.min(1, (output.maxWidth ?? width) / width, (output.maxHeight ?? height) / height);
+  return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+
+function checkOutput(output: Output): void {
+  if (
+    (output.maxWidth !== undefined && !(output.maxWidth >= 1)) ||
+    (output.maxHeight !== undefined && !(output.maxHeight >= 1))
+  ) {
+    throw new AkanNativeError("INVALID_ARGS", "maxWidth and maxHeight must be at least 1");
+  }
+}
+
+function toJpeg(canvas: HTMLCanvasElement, quality: number): Promise<Blob> {
+  return new Promise((resolve, reject) =>
+    canvas.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new AkanNativeError("INTERNAL", "could not encode the photo"))),
+      "image/jpeg",
+      quality,
+    ),
+  );
+}
+
+/**
+ * A picked file as the page gets it (index.ts): kept when it is a JPEG within the limits and no
+ * quality was asked for; otherwise decoded upright (createImageBitmap applies EXIF orientation),
+ * scaled, put on white and encoded as JPEG. A file the browser cannot decode stays as it is.
+ */
+async function normalized(file: File, output: Output): Promise<Photo> {
+  let bitmap: ImageBitmap;
+  try {
+    bitmap = await createImageBitmap(file, { imageOrientation: "from-image" });
+  } catch {
+    return { url: URL.createObjectURL(file), mime: file.type || "application/octet-stream", size: file.size }; 
+  }
+  try {
+    const size = fit(bitmap.width, bitmap.height, output);
+    
+    if (
+      file.type === "image/jpeg" &&
+      size.width === bitmap.width &&
+      size.height === bitmap.height &&
+      output.quality === undefined
+    ) {
+      return { url: URL.createObjectURL(file), mime: "image/jpeg", size: file.size, ...size };
+    }
+    const canvas = document.createElement("canvas");
+    canvas.width = size.width;
+    canvas.height = size.height;
+    const g = canvas.getContext("2d")!;
+    g.fillStyle = "#fff";
+    g.fillRect(0, 0, size.width, size.height);
+    g.drawImage(bitmap, 0, 0, size.width, size.height);
+    const blob = await toJpeg(canvas, jpegQuality(output));
+    return { url: URL.createObjectURL(blob), mime: "image/jpeg", size: blob.size, ...size };
+  } finally {
+    bitmap.close();
+  }
+}
+
+/** Must run synchronously inside the user's click: input.click() needs user activation. */
+function pickFile(capture: "user" | "environment" | null, output: Output): Promise<Photo> {
+  return pickFiles(capture, 1, output).then((photos) => photos[0]!);
+}
+
+function pickFiles(capture: "user" | "environment" | null, limit: number, output: Output): Promise<Photo[]> {
+  return new Promise((resolve, reject) => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = "image/*";
+    input.multiple = limit > 1;
+    if (capture) input.setAttribute("capture", capture);
+    input.style.display = "none";
+    
+    document.body.appendChild(input);
+    input.addEventListener(
+      "change",
+      async () => {
+        const files = [...(input.files ?? [])].slice(0, limit);
+        input.remove();
+        if (files.length === 0) return reject(cancelled());
+        try {
+          resolve(await Promise.all(files.map((file) => normalized(file, output))));
+        } catch (error) {
+          reject(AkanNativeError.from(error));
+        }
+      },
+      { once: true },
+    );
+    input.addEventListener(
+      "cancel",
+      () => {
+        input.remove();
+        reject(cancelled());
+      },
+      { once: true },
+    );
+    input.click();
+  });
+}
+
+function mediaError(error: unknown): AkanNativeError {
+  const name = (error as { name?: string })?.name;
+  if (name === "NotAllowedError" || name === "SecurityError")
+    return new AkanNativeError("PERMISSION_DENIED", "camera access was denied");
+  if (name === "NotFoundError" || name === "OverconstrainedError")
+    return new AkanNativeError("UNSUPPORTED", "no camera is available");
+  return AkanNativeError.from(error);
+}
+
+async function openStream(direction: "rear" | "front"): Promise<MediaStream> {
+  const devices = navigator.mediaDevices;
+  if (!devices?.getUserMedia)
+    throw new AkanNativeError("UNSUPPORTED", "getUserMedia is not available (insecure context?)");
+  try {
+    return await devices.getUserMedia({
+      video: { facingMode: direction === "front" ? "user" : "environment" },
+      audio: false,
+    });
+  } catch (error) {
+    
+    if ((error as { name?: string })?.name !== "OverconstrainedError") throw mediaError(error);
+    try {
+      return await devices.getUserMedia({ video: true, audio: false });
+    } catch (retry) {
+      throw mediaError(retry);
+    }
+  }
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(tag: K, style: string, attrs: Record<string, string> = {}) {
+  const node = document.createElement(tag);
+  
+  node.style.cssText = style;
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
+  return node;
+}
+
+async function captureWithPreview(options: TakePhotoOptions): Promise<Photo> {
+  const direction = options.direction ?? "rear";
+  const quality = jpegQuality(options);
+  const stream = await openStream(direction);
+
+  const root = el(
+    "div",
+    "position:fixed;inset:0;z-index:2147483647;background:#000;display:flex;flex-direction:column;font:16px system-ui,sans-serif",
+    { role: "dialog", "aria-label": "Camera" },
+  );
+  const video = el(
+    "video",
+    `flex:1;min-height:0;width:100%;object-fit:contain${direction === "front" ? ";transform:scaleX(-1)" : ""}`,
+    {
+      playsinline: "",
+      muted: "",
+      autoplay: "",
+    },
+  );
+  const bar = el(
+    "div",
+    "display:flex;align-items:center;justify-content:space-between;padding:16px 24px calc(16px + env(safe-area-inset-bottom))",
+  );
+  const cancel = el("button", "background:none;border:0;color:#fff;font:inherit;padding:8px;cursor:pointer", {
+    type: "button",
+  });
+  cancel.textContent = "Cancel";
+  const shutter = el(
+    "button",
+    "width:64px;height:64px;border-radius:50%;border:4px solid #fff;background:#fff;box-shadow:inset 0 0 0 3px #000;cursor:pointer",
+    { type: "button", "aria-label": "Take photo" },
+  );
+  const spacer = el("span", "width:60px");
+  bar.append(cancel, shutter, spacer);
+  root.append(video, bar);
+  video.srcObject = stream;
+  document.body.appendChild(root);
+
+  try {
+    await video.play().catch(() => {});
+    return await new Promise<Photo>((resolve, reject) => {
+      const onKey = (e: KeyboardEvent) => {
+        if (e.key === "Escape") finish(() => reject(cancelled()));
+      };
+      const finish = (settle: () => void) => {
+        window.removeEventListener("keydown", onKey);
+        settle();
+      };
+      window.addEventListener("keydown", onKey);
+      cancel.onclick = () => finish(() => reject(cancelled()));
+      shutter.onclick = () => {
+        if (!video.videoWidth || !video.videoHeight) return; 
+        const { width, height } = fit(video.videoWidth, video.videoHeight, options);
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        canvas.getContext("2d")!.drawImage(video, 0, 0, width, height);
+        canvas.toBlob(
+          (blob) =>
+            finish(() =>
+              blob
+                ? resolve({ url: URL.createObjectURL(blob), mime: "image/jpeg", size: blob.size, width, height })
+                : reject(new AkanNativeError("INTERNAL", "could not encode the photo")),
+            ),
+          "image/jpeg",
+          quality,
+        );
+      };
+    });
+  } finally {
+    for (const track of stream.getTracks()) track.stop();
+    root.remove();
+  }
+}
+
+async function queryPermission(): Promise<PermissionState> {
+  try {
+
+    const status = await navigator.permissions.query({ name: "camera" as PermissionName });
+    return status.state;
+  } catch {
+    return "prompt";
+  }
+}
+
+export const web = defineWebPlugin<CameraApi>({
+  methods: {
+    takePhoto(options = {}) {
+      checkOutput(options);
+      const source = options.source ?? "camera";
+      if (source === "library") return pickFile(null, options);
+      if (isTouchPrimary() || !navigator.mediaDevices?.getUserMedia) {
+        return pickFile(options.direction === "front" ? "user" : "environment", options);
+      }
+      return captureWithPreview(options);
+    },
+    pickImages(options: PickImagesOptions = {}) {
+      checkOutput(options);
+      const limit = Math.min(20, Math.max(1, Math.floor(options.limit ?? 10)));
+      return pickFiles(null, limit, options).then((photos) => ({ photos }));
+    },
+    checkPermission: async () => ({ camera: await queryPermission() }),
+    async requestPermission() {
+      try {
+        const stream = await openStream("rear");
+        for (const track of stream.getTracks()) track.stop();
+        return { camera: "granted" };
+      } catch (error) {
+        if (error instanceof AkanNativeError && error.code === "PERMISSION_DENIED") return { camera: "denied" };
+        throw error;
+      }
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/clipboard/android/ClipboardPlugin.kt

@@ -0,0 +1,51 @@
+package com.akanjs.plugins.clipboard
+
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.util.Log
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Plain text on the framework ClipboardManager.
+ * - Android 10+ hands out the clip only while the app has window focus. Without focus
+ *   getPrimaryClip() returns null, which looks like an empty clipboard, so check focus first and
+ *   report PERMISSION_DENIED.
+ * - Android 13+ shows its own "copied" confirmation: the page should not add a toast.
+ * - Clips that are not plain text (HTML, a content URI) are coerced to text as
+ *   capacitor-plugins/clipboard/…/Clipboard.java:56-66 does, off the main thread because
+ *   coerceToText may read the URI's content.
+ * - No clip label, as react-native ClipboardModule.kt:44.
+ * Arguments arrive decoded and checked by the generated ClipboardPluginSpec (PL-10).
+ */
+class ClipboardPlugin(private val context: AkanNativePluginContext) : ClipboardPluginSpec {
+    private val manager: ClipboardManager? get() = context.activity.getSystemService(ClipboardManager::class.java)
+
+    override fun writeText(args: ClipboardWriteTextArgs, reply: AkanNativeVoidReply) {
+        val manager = manager ?: return reply.reject(AkanNativeErrorCode.UNSUPPORTED, "no clipboard service")
+        manager.setPrimaryClip(ClipData.newPlainText(null, args.text))
+        reply.resolve()
+    }
+
+    override fun readText(reply: AkanNativeReply<ClipboardReadTextResult>) {
+        val manager = manager ?: return reply.reject(AkanNativeErrorCode.UNSUPPORTED, "no clipboard service")
+        if (!context.activity.hasWindowFocus()) {
+            return reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, "the clipboard can be read only while the app has focus")
+        }
+        val clip = manager.primaryClip
+        val item = if (clip != null && clip.itemCount > 0) clip.getItemAt(0) else null
+        val plain = item?.text
+        if (item == null || plain != null) return reply.resolve(ClipboardReadTextResult(text = plain?.toString() ?: ""))
+        Thread {
+            val text = try {
+                item.coerceToText(context.activity)?.toString() ?: ""
+            } catch (e: Exception) {
+                Log.w("AkanNative", "clipboard: coercing the clip to text failed", e)
+                ""
+            }
+            reply.resolve(ClipboardReadTextResult(text = text))
+        }.start()
+    }
+}

package/vendor/@akanjs/native/plugins/clipboard/ios/ClipboardPlugin.swift

@@ -0,0 +1,35 @@
+import UIKit
+
+/// Plain text on UIPasteboard.general.
+/// - iOS 16+ shows "Allow Paste?" when the app reads text another app copied, and `string` is nil
+///   after "Don't Allow". `hasStrings`/`hasURLs` never show the prompt, so "has text, but reading
+///   gave nil" is reported as PERMISSION_DENIED instead of an empty clipboard.
+/// - The read runs off the main thread so the web view keeps drawing while the prompt waits for
+///   an answer. Capacitor reads on its background "bridge" queue too
+///   (capacitor/ios/Capacitor/Capacitor/CapacitorBridge.swift:127, :525). UIPasteboard is
+///   NS_SWIFT_SENDABLE.
+/// - A pasteboard with only a URL (Safari's address bar) reads as the URL string, like
+///   capacitor-plugins/clipboard/ios/Sources/ClipboardPlugin/Clipboard.swift:47-62.
+/// Arguments arrive decoded and checked by the generated ClipboardPluginSpec (PL-10).
+final class ClipboardPlugin: ClipboardPluginSpec {
+    static let id = "clipboard"
+
+    init(context: AkanNativePluginContext) {}
+
+    func writeText(_ args: ClipboardWriteTextArgs, _ reply: AkanNativeReply<Void>) {
+        UIPasteboard.general.string = args.text
+        reply.resolve()
+    }
+
+    func readText(_ reply: AkanNativeReply<ClipboardReadTextResult>) {
+        let pasteboard = UIPasteboard.general
+        guard pasteboard.hasStrings || pasteboard.hasURLs else { return reply.resolve(ClipboardReadTextResult(text: "")) }
+        DispatchQueue.global(qos: .userInitiated).async {
+            if let text = pasteboard.string ?? pasteboard.url?.absoluteString {
+                reply.resolve(ClipboardReadTextResult(text: text))
+            } else {
+                reply.reject(.permissionDenied, "pasting from another app was not allowed")
+            }
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/clipboard/native-plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "clipboard",
+  "apiVersion": 1,
+  "methods": ["writeText", "readText"],
+  "events": [],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": "./src/desktop.ts",
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "ClipboardPlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.clipboard.ClipboardPlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/clipboard/src/desktop.ts

@@ -0,0 +1,66 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { type DesktopContext, defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { ClipboardApi } from "./index.ts";
+
+const UTF8 = { LC_ALL: "en_US.UTF-8", LANG: "en_US.UTF-8" };
+
+function checkText(text: unknown): string {
+  if (typeof text !== "string") throw new AkanNativeError("INVALID_ARGS", "text must be a string");
+  return text;
+}
+
+async function run(argv: string[], input?: string): Promise<string> {
+  const proc = Bun.spawn(argv, {
+    stdin: input === undefined ? "ignore" : new Blob([input]),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, ...UTF8 },
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) throw new AkanNativeError("INTERNAL", `${argv[0]} failed (${code}): ${err.trim()}`);
+  return out;
+}
+
+/**
+ * `pasteboard` is a pbcopy -pboard name; tests use "ruler" to leave the user's clipboard alone.
+ * `platform` lets tests check the shell ops of Windows and Linux on any OS.
+ */
+export function createDesktopClipboard(
+  pasteboard: "general" | "ruler" | "find" | "font" = "general",
+  platform: NodeJS.Platform = process.platform,
+) {
+  if (platform !== "darwin") {
+    return defineDesktopPlugin<ClipboardApi>({
+      id: "clipboard",
+      methods: {
+        async writeText(args, ctx: DesktopContext) {
+          await ctx.shell("clipboard.writeText", { text: checkText(args?.text) });
+        },
+        
+        readText: async (_args, ctx: DesktopContext) => ({
+          text: ((await ctx.shell("clipboard.readText")) as { text: string | null }).text ?? "",
+        }),
+      },
+    });
+  }
+  return defineDesktopPlugin<ClipboardApi>({
+    id: "clipboard",
+    methods: {
+      async writeText(args) {
+        await run(["/usr/bin/pbcopy", "-pboard", pasteboard], checkText(args?.text));
+      },
+      async readText() {
+        
+        return { text: await run(["/usr/bin/pbpaste", "-pboard", pasteboard, "-Prefer", "txt"]) };
+      },
+    },
+  });
+}
+
+export default createDesktopClipboard();

package/vendor/@akanjs/native/plugins/clipboard/src/index.ts

@@ -0,0 +1,72 @@
+
+
+import * as React from "react";
+import { AkanNativeError, definePlugin } from "../../../packages/core/src/index.ts";
+import { web } from "./web.ts";
+
+/**
+ * Plain text on the system clipboard.
+ *
+ * readText resolves `{ text: "" }` when the clipboard holds no text. It may reject:
+ * - PERMISSION_DENIED
+ *   - iOS 16+: the user answered "Don't Allow" to the paste prompt, shown when another app copied the text
+ *   - Android 10+: the app does not have window focus
+ *   - web: the browser refused (Chrome asks for clipboard-read permission, Safari and Firefox show a
+ *     "Paste" button that must be clicked, both need a user gesture)
+ * - UNSUPPORTED on the web without `navigator.clipboard.readText` (insecure http:// origin, older browsers)
+ *
+ * writeText needs a user gesture on the web (and a focused document in Chrome); without
+ * `navigator.clipboard` it falls back to `execCommand("copy")`, which also needs the gesture.
+ */
+export interface ClipboardApi {
+  writeText(args: { text: string }): Promise<void>;
+  readText(): Promise<{ text: string }>;
+}
+
+export const clipboard = definePlugin<ClipboardApi>("clipboard", {
+  methods: ["writeText", "readText"],
+  web,
+});
+
+export interface UseClipboard {
+  supported: boolean;
+  /** True for `resetAfter` ms after a successful copy, for "Copied" feedback next to the button. */
+  copied: boolean;
+  /** Last copy failure. */
+  error: AkanNativeError | null;
+  /** Copies text; resolves false (and sets `error`) instead of throwing. */
+  copy(text: string): Promise<boolean>;
+}
+
+/**
+ * Copy-button helper. Android 13+ already shows a system confirmation after copying, so show
+ * `copied` in place (e.g. the button label) rather than as an extra toast.
+ */
+export function useClipboard(options: { resetAfter?: number } = {}): UseClipboard {
+  const resetAfter = options.resetAfter ?? 2000;
+  const [copied, setCopied] = React.useState(false);
+  const [error, setError] = React.useState<AkanNativeError | null>(null);
+  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  React.useEffect(() => () => clearTimeout(timer.current), []);
+
+  const copy = React.useCallback(
+    async (text: string) => {
+      clearTimeout(timer.current);
+      try {
+        
+        await clipboard.writeText({ text });
+        setError(null);
+        setCopied(true);
+        timer.current = setTimeout(() => setCopied(false), resetAfter);
+        return true;
+      } catch (e) {
+        setCopied(false);
+        setError(AkanNativeError.from(e));
+        return false;
+      }
+    },
+    [resetAfter],
+  );
+
+  return { supported: clipboard.isSupported("writeText"), copied, error, copy };
+}

package/vendor/@akanjs/native/plugins/clipboard/src/web.ts

@@ -0,0 +1,69 @@
+import { AkanNativeError, defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { ClipboardApi } from "./index.ts";
+
+function checkText(text: unknown): string {
+  if (typeof text !== "string") throw new AkanNativeError("INVALID_ARGS", "text must be a string");
+  return text;
+}
+
+/** Copies through a temporary textarea. Only works inside a user gesture. */
+function legacyCopy(text: string): boolean {
+  if (typeof document === "undefined" || !document.body || typeof document.execCommand !== "function") return false;
+  const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const selection = document.getSelection();
+  const ranges = selection ? Array.from({ length: selection.rangeCount }, (_, i) => selection.getRangeAt(i)) : [];
+  const area = document.createElement("textarea");
+  area.value = text;
+  area.setAttribute("readonly", ""); 
+  
+  area.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;padding:0;border:0;opacity:0;font-size:16px";
+  document.body.appendChild(area);
+  let copied = false;
+  try {
+    area.select();
+    area.setSelectionRange(0, text.length); 
+    copied = document.execCommand("copy");
+  } catch {
+    copied = false;
+  } finally {
+    area.remove();
+    if (selection) {
+      selection.removeAllRanges();
+      for (const range of ranges) selection.addRange(range);
+    }
+    active?.focus({ preventScroll: true });
+  }
+  return copied;
+}
+
+export const web = defineWebPlugin<ClipboardApi>({
+  methods: {
+    writeText(args) {
+      const text = checkText(args?.text);
+      const api = typeof navigator === "undefined" ? undefined : navigator.clipboard;
+      if (typeof api?.writeText !== "function") {
+        if (legacyCopy(text)) return Promise.resolve();
+        throw new AkanNativeError("UNSUPPORTED", "the Clipboard API is not available here (insecure context?)");
+      }
+      return api.writeText(text).catch((error: unknown) => {
+        
+        if (legacyCopy(text)) return;
+        throw AkanNativeError.from(error); 
+      });
+    },
+    async readText() {
+      const api = typeof navigator === "undefined" ? undefined : navigator.clipboard;
+      if (typeof api?.readText !== "function") {
+        throw new AkanNativeError(
+          "UNSUPPORTED",
+          "reading the clipboard is not available here (insecure context or no Clipboard API)",
+        );
+      }
+      try {
+        return { text: await api.readText() };
+      } catch (error) {
+        throw AkanNativeError.from(error); 
+      }
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/contacts/android/ContactsPlugin.kt

@@ -0,0 +1,84 @@
+package com.akanjs.plugins.contacts
+
+import android.Manifest
+import android.provider.ContactsContract.CommonDataKinds.Phone
+import android.provider.ContactsContract.Contacts
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+
+/**
+ * The address book through ContactsContract, read-only. Two queries (contacts, then every phone row) joined in
+ * memory rather than one query per contact; they run on a worker thread because a large book takes seconds.
+ * Arguments arrive decoded and checked by the generated ContactsPluginSpec (PL-10).
+ */
+class ContactsPlugin(private val context: AkanNativePluginContext) : ContactsPluginSpec {
+    override fun checkPermission(reply: AkanNativeReply<ContactsCheckPermissionResult>) =
+        reply.resolve(ContactsCheckPermissionResult(contacts = permission()))
+
+    override fun requestPermission(reply: AkanNativeReply<ContactsRequestPermissionResult>) =
+        withPermission { reply.resolve(ContactsRequestPermissionResult(contacts = it)) }
+
+    override fun getContacts(args: ContactsGetContactsOptions, reply: AkanNativeReply<ContactsGetContactsResult>) {
+        val withName = args.projection?.name ?: true
+        val withPhones = args.projection?.phones ?: true
+        withPermission { state ->
+            if (state != ContactsPermissionState.GRANTED) {
+                reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, "contacts access was denied")
+                return@withPermission
+            }
+            Thread {
+                try {
+                    reply.resolve(ContactsGetContactsResult(contacts = read(withName, withPhones)))
+                } catch (e: Exception) {
+                    reply.reject(AkanNativeErrorCode.INTERNAL, "could not read contacts: ${e.message}")
+                }
+            }.start()
+        }
+    }
+
+    /** context.permissionState answers with one of the four AkanNativePermission strings. */
+    private fun permission(): ContactsPermissionState {
+        val state = context.permissionState(Manifest.permission.READ_CONTACTS)
+        return ContactsPermissionState.entries.first { it.json == state }
+    }
+
+    /** "denied" is a refusal the system will not show a dialog for again, so only the two prompt states ask. */
+    private fun withPermission(then: (ContactsPermissionState) -> Unit) {
+        val current = permission()
+        if (current != ContactsPermissionState.PROMPT && current != ContactsPermissionState.PROMPT_WITH_RATIONALE) {
+            then(current)
+            return
+        }
+        context.requestPermissions(arrayOf(Manifest.permission.READ_CONTACTS)) { then(permission()) }
+    }
+
+    private fun read(withName: Boolean, withPhones: Boolean): List<ContactsContact> {
+        val resolver = context.activity.contentResolver
+        val names = linkedMapOf<String, String?>()
+        resolver.query(
+            Contacts.CONTENT_URI,
+            arrayOf(Contacts._ID, Contacts.DISPLAY_NAME_PRIMARY),
+            null,
+            null,
+            Contacts.SORT_KEY_PRIMARY,
+        )?.use { cursor ->
+            while (cursor.moveToNext()) {
+                names[cursor.getLong(0).toString()] = if (withName) cursor.getString(1)?.takeIf { it.isNotEmpty() } else null
+            }
+        }
+        val phones = mutableMapOf<String, MutableList<ContactsContactPhone>>()
+        if (withPhones) {
+            resolver.query(Phone.CONTENT_URI, arrayOf(Phone.CONTACT_ID, Phone.NUMBER, Phone.TYPE, Phone.LABEL), null, null, null)
+                ?.use { cursor ->
+                    val resources = context.activity.resources
+                    while (cursor.moveToNext()) {
+                        val number = cursor.getString(1)?.takeIf { it.isNotEmpty() } ?: continue
+                        val label = if (cursor.isNull(2)) cursor.getString(3) else Phone.getTypeLabel(resources, cursor.getInt(2), cursor.getString(3)).toString()
+                        phones.getOrPut(cursor.getLong(0).toString()) { mutableListOf() }.add(ContactsContactPhone(number = number, label = label))
+                    }
+                }
+        }
+        return names.map { (id, name) -> ContactsContact(id = id, name = name, phones = phones[id] ?: emptyList()) }
+    }
+}