akanjs 3.0.0-beta.21 → 3.0.0-beta.23

package/client/csrTypes.ts

@@ -288,7 +288,16 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
+
+export const csrContext = sharedContext<CsrContextType>("csr", {
+  history: { current: null },
+  topSafeAreaRef: { current: null },
+  bottomSafeAreaRef: { current: null },
+  prevPageContentRef: { current: null },
+  pageContentRef: { current: null },
+  frameRootRef: { current: null },
+  onBack: { current: {} },
+} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;

package/client/native.ts

@@ -6,6 +6,7 @@ export { AkanNativeError, fileBlob, releaseFile } from "../vendor/@akanjs/native
 export { app } from "../vendor/@akanjs/native/plugins/app/src/index.ts";
 export { appState } from "../vendor/@akanjs/native/plugins/app-state/src/index.ts";
 export type { Photo } from "../vendor/@akanjs/native/plugins/camera/src/index.ts";
+export type { Contact } from "../vendor/@akanjs/native/plugins/contacts/src/index.ts";
 export type { DeviceInfo } from "../vendor/@akanjs/native/plugins/device/src/index.ts";
 export { device } from "../vendor/@akanjs/native/plugins/device/src/index.ts";
 export { dialog } from "../vendor/@akanjs/native/plugins/dialog/src/index.ts";
@@ -25,6 +26,7 @@ export { secureStorage } from "../vendor/@akanjs/native/plugins/secure-storage/s
 export { browser, opener };
 
 export const loadCamera = () => import("../vendor/@akanjs/native/plugins/camera/src/index.ts");
+export const loadContacts = () => import("../vendor/@akanjs/native/plugins/contacts/src/index.ts");
 export const loadGeolocation = () => import("../vendor/@akanjs/native/plugins/geolocation/src/index.ts");
 export const loadIap = () => import("../vendor/@akanjs/native/plugins/iap/src/index.ts");
 

package/fetch/client/wsClient.ts

@@ -107,7 +107,12 @@ export class WsClient {
   #connect() {
     if (this.#destroyed) return;
 
-    this.#ws = new WebSocket(this.url);
+    try {
+      this.#ws = new WebSocket(this.url);
+    } catch (error) {
+      this.logger.error(`Cannot open a WebSocket to ${this.url}: ${error instanceof Error ? error.message : error}`);
+      return;
+    }
     this.#ws.binaryType = "arraybuffer";
     this.#ws.onopen = (e) => {
       this.#reconnectAttempts = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.21",
+  "version": "3.0.0-beta.23",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -741,6 +741,8 @@ export class AkanApp {
   async #proxyHttp(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response> {
     const child = await this.#pickReadyFederationChild(req);
     if (!child?.upstream || child.upstream.type !== "unix") return this.#respondWithUnavailable(req);
+    
+    const { socketPath } = child.upstream;
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
     const headers = makeAkanChildProxyHeaders(req, child.idx, server.requestIP(req));
@@ -750,7 +752,7 @@ export class AkanApp {
     const hopStart = traced ? performance.now() : 0;
     try {
       const upstreamRes = await fetch(upstreamUrl, {
-        unix: child.upstream.socketPath,
+        unix: socketPath,
         method: req.method,
         headers,
         body: req.method === "GET" || req.method === "HEAD" ? undefined : req.body,
@@ -761,7 +763,7 @@ export class AkanApp {
     } catch (error) {
       if (AkanApp.#isUpstreamOpenFailure(error)) {
         this.logger.error(
-          `Child ${child.idx}/${child.role} upstream is unreachable (${child.upstream.socketPath}); restarting`,
+          `Child ${child.idx}/${child.role} upstream is unreachable (${socketPath}); restarting`,
         );
         this.#scheduleChildRestart(child, child.proc, "upstream-open-failed");
         return AkanApp.#unavailableResponse(req, "Federation child upstream is unreachable; restarting");

package/server/resolver/signal.resolver.ts

@@ -5,6 +5,7 @@ import {
   type Cls,
   ENDPOINT_META,
   FIELD_META,
+  Float,
   getEnv,
   ID,
   INTERNAL_META,
@@ -14,7 +15,7 @@ import {
   SLICE_META,
 } from "akanjs/base";
 import { capitalize, cookieHeaderHasAuthToken, Logger } from "akanjs/common";
-import { deserialize, resolvePageLimit, resolvePageSkip, serialize } from "akanjs/constant";
+import { type ConstantField, deserialize, resolvePageLimit, resolvePageSkip, serialize } from "akanjs/constant";
 import { baseDocumentColumns, documentQueryHelper, getFilterSortByKey, type QueryFieldMap } from "akanjs/document";
 import {
   type AkanJob,
@@ -475,9 +476,11 @@ export class SignalResolver {
     }) {}
     return SliceEndpoint;
   }
-  
+
+  static readonly #clientOrderableTypes = new Set<unknown>([Int, Float, String, ID, Boolean, Date]);
   static #assertLiveSort(refName: string, key: string, sliceInfo: SliceInfo) {
-    const lightFields = (sliceInfo.light as unknown as { [FIELD_META]?: Record<string, unknown> })[FIELD_META] ?? {};
+    const lightFields =
+      (sliceInfo.light as unknown as { [FIELD_META]?: Record<string, ConstantField> })[FIELD_META] ?? {};
     for (const sortKey of sliceInfo.liveOption?.sort ?? []) {
       const sort = getFilterSortByKey(sliceInfo.filter, sortKey);
       if (!sort)
@@ -489,9 +492,12 @@ export class SignalResolver {
             `Live slice "${refName}.${key}" declares sort "${sortKey}" on "${path}", which is not in ` +
               `Light${capitalize(refName)}. A subscriber cannot order by a field it never receives.`,
           );
+        const { modelRef, isArray, isMap } = lightFields[path].getProps();
+        if (!isArray && !isMap && SignalResolver.#clientOrderableTypes.has(modelRef)) continue;
         SignalResolver.logger.warn(
-          `Live slice "${refName}.${key}" sorts by "${path}", which is stored inside the document rather than in a ` +
-            `column. SQLite and Postgres order those differently, so a client placing a row may disagree with the server.`,
+          `Live slice "${refName}.${key}" sorts "${sortKey}" by "${path}", which is not an Int, Float, String, ID, ` +
+            `Boolean or Date field, so a client placing a new row may disagree with the server. Sort by one of ` +
+            `those, or leave "${sortKey}" out of .live({ sort }) so the list refetches when a row arrives.`,
         );
       }
     }

package/service/predefinedAdaptor/sql/QueryCompiler.ts

@@ -37,9 +37,9 @@ export class QueryCompiler {
   }
 
   orderBy(sort: Record<string, 1 | -1> = { createdAt: -1 }) {
-    return Object.entries(sort)
-      .map(([path, direction]) => this.dialect.orderTerm(this.fieldExpr(path), direction))
-      .join(", ");
+    const terms = Object.entries(sort);
+    if (!terms.some(([path]) => path === "id")) terms.push(["id", terms.at(-1)?.[1] ?? -1]);
+    return terms.map(([path, direction]) => this.dialect.orderTerm(this.fieldExpr(path), direction)).join(", ");
   }
 
   fieldExpr(path: string) {

package/store/liveInsert.ts

@@ -30,31 +30,53 @@ export const livePlacementIndex = ({
   const sort = sorts?.[sortKey];
   if (!sort || !Object.keys(sort).length) return null;
   const paths = Object.entries(sort);
-  if (paths.some(([path]) => comparableOf(row[path]) === null)) return null;
-  const index = list.findIndex((item) => compareRows(row, item, paths) < 0);
+  if (paths.some(([path]) => comparableOf(row[path]) === undefined)) return null;
+  let orderable = true;
+  const index = list.findIndex((item) => {
+    const order = compareRows(row, item, paths);
+    orderable = order !== null;
+    return order === null || order < 0;
+  });
+  if (!orderable) return null;
   if (index !== -1) return index;
   
   if (cumulative) return hasMore ? null : list.length;
   return list.length < limit ? list.length : null;
 };
 
-const compareRows = (left: LiveSortableRow, right: LiveSortableRow, paths: [string, 1 | -1][]): number => {
+const compareRows = (left: LiveSortableRow, right: LiveSortableRow, paths: [string, 1 | -1][]): number | null => {
   for (const [path, direction] of paths) {
-    const a = comparableOf(left[path]);
-    const b = comparableOf(right[path]);
-    if (a === null || b === null) continue;
-    if (a === b) continue;
-    return (a < b ? -1 : 1) * direction;
+    const order = compareValues(comparableOf(left[path]), comparableOf(right[path]));
+    if (order !== 0) return order === null ? null : order * direction;
   }
-  return 0;
+  const order = compareValues(comparableOf(left.id), comparableOf(right.id));
+  return order === null ? null : order * (paths.at(-1)?.[1] ?? -1);
 };
 
-const comparableOf = (value: unknown): number | string | null => {
-  if (value === null || value === undefined) return null;
+const compareValues = (a: Comparable | undefined, b: Comparable | undefined): number | null => {
+  if (a === undefined || b === undefined) return null;
+  if (a === b) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (typeof a === "string" && typeof b === "string") return compareText(a, b);
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : 1;
+  return null;
+};
+
+const compareText = (a: string, b: string) => {
+  let idx = 0;
+  while (idx < a.length && idx < b.length && a[idx] === b[idx]) idx += 1;
+  return (a.codePointAt(idx) ?? -1) < (b.codePointAt(idx) ?? -1) ? -1 : 1;
+};
+
+type Comparable = number | string | null;
+
+const comparableOf = (value: unknown): Comparable | undefined => {
+  if (value === null) return null;
   if (typeof value === "number" || typeof value === "string") return value;
   if (typeof value === "boolean") return value ? 1 : 0;
   if (value instanceof Date) return value.getTime();
-  const valued: unknown = (value as { valueOf?: () => unknown }).valueOf?.();
+  const valued: unknown = (value as { valueOf?: () => unknown } | undefined)?.valueOf?.();
   if (typeof valued === "number" || typeof valued === "string") return valued;
-  return null;
+  return undefined;
 };

package/types/client/native.d.ts

@@ -4,6 +4,7 @@ export { AkanNativeError, fileBlob, releaseFile } from "../vendor/@akanjs/native
 export { app } from "../vendor/@akanjs/native/plugins/app/src/index.d.ts";
 export { appState } from "../vendor/@akanjs/native/plugins/app-state/src/index.d.ts";
 export type { Photo } from "../vendor/@akanjs/native/plugins/camera/src/index.d.ts";
+export type { Contact } from "../vendor/@akanjs/native/plugins/contacts/src/index.d.ts";
 export type { DeviceInfo } from "../vendor/@akanjs/native/plugins/device/src/index.d.ts";
 export { device } from "../vendor/@akanjs/native/plugins/device/src/index.d.ts";
 export { dialog } from "../vendor/@akanjs/native/plugins/dialog/src/index.d.ts";
@@ -17,6 +18,7 @@ export { push } from "../vendor/@akanjs/native/plugins/push/src/index.d.ts";
 export { secureStorage } from "../vendor/@akanjs/native/plugins/secure-storage/src/index.d.ts";
 export { browser, opener };
 export declare const loadCamera: () => Promise<typeof import("../vendor/@akanjs/native/plugins/camera/src/index.d.ts")>;
+export declare const loadContacts: () => Promise<typeof import("../vendor/@akanjs/native/plugins/contacts/src/index.d.ts")>;
 export declare const loadGeolocation: () => Promise<typeof import("../vendor/@akanjs/native/plugins/geolocation/src/index.d.ts")>;
 export declare const loadIap: () => Promise<typeof import("../vendor/@akanjs/native/plugins/iap/src/index.d.ts")>;
 /** Inside an iOS or Android shell of the native runtime; a mobile target opened in a browser is not. */

package/types/ui/Data/Item.d.ts

@@ -1,4 +1,4 @@
-import type { Dayjs } from "akanjs/base";
+import { type Dayjs } from "akanjs/base";
 import { type DataAction, type DataColumn } from "akanjs/client";
 import type { SliceMeta } from "akanjs/fetch";
 import type { ReactNode } from "react";
@@ -7,7 +7,7 @@ export declare const convToAntdColumn: (column: DataColumn<any>) => {
     dataIndex: string;
     title: string;
     responsive: readonly ["md", "lg", "xl"] | undefined;
-    render: ((value: any, model: any) => ReactNode) | undefined;
+    render: ((value: unknown) => string | import("react/jsx-runtime").JSX.Element) | ((value: any, model: any) => ReactNode);
 } | {
     key: string;
     dataIndex: string;
@@ -24,8 +24,8 @@ export declare const convToAntdColumn: (column: DataColumn<any>) => {
     key: string;
     dataIndex: string;
     title: string;
+    render: (value: unknown) => string | import("react/jsx-runtime").JSX.Element;
     responsive?: undefined;
-    render?: undefined;
 };
 interface ItemProps<T extends string, Full extends {
     id: string;

package/types/vendor/@akanjs/native/plugins/contacts/src/index.d.ts

@@ -0,0 +1,43 @@
+/** "prompt-with-rationale" is Android's: asked and refused once, so the app should explain before asking again. */
+export type PermissionState = "granted" | "denied" | "prompt" | "prompt-with-rationale";
+export interface ContactPhone {
+    /** As the address book stores it: no normalization, so "010-1234-5678" and "+82 10 1234 5678" both occur. */
+    number: string;
+    /** The label shown in the system Contacts app ("mobile", "home", a custom one), localized; null when unlabeled. */
+    label: string | null;
+}
+export interface Contact {
+    /** Stable for this contact on this device only. */
+    id: string;
+    /** The display name the system Contacts app shows; null when not projected or the contact has none. */
+    name: string | null;
+    /** Empty when not projected. */
+    phones: ContactPhone[];
+}
+/** What to read for each contact. Both default to true; leave out what the screen does not need. */
+export interface GetContactsOptions {
+    projection?: {
+        name?: boolean;
+        phones?: boolean;
+    };
+}
+/**
+ * Reads the device's address book (iOS Contacts, Android ContactsContract); there is no web or desktop
+ * implementation, so every call there rejects with UNSUPPORTED.
+ * - "granted" on iOS 18 also covers limited access: getContacts returns only the contacts the user shared.
+ * - getContacts asks for permission first when it was never asked, and rejects with PERMISSION_DENIED when
+ *   denied. INTERNAL when NSContactsUsageDescription is missing (iOS kills an app that asks without it).
+ */
+export interface ContactsApi {
+    checkPermission(): Promise<{
+        contacts: PermissionState;
+    }>;
+    /** Shows the system prompt when the state is "prompt" or "prompt-with-rationale"; otherwise returns the state. */
+    requestPermission(): Promise<{
+        contacts: PermissionState;
+    }>;
+    getContacts(options?: GetContactsOptions): Promise<{
+        contacts: Contact[];
+    }>;
+}
+export declare const contacts: import("../../../packages/core/src/plugin.ts").Plugin<ContactsApi, {}>;

package/types/vendor/@akanjs/native/plugins/contacts/src.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.d.ts";

package/ui/Data/Item.tsx

@@ -1,5 +1,5 @@
 "use client";
-import type { Dayjs } from "akanjs/base";
+import { type Dayjs, dayjs } from "akanjs/base";
 import { cn, type DataAction, type DataColumn, usePage } from "akanjs/client";
 import { capitalize } from "akanjs/common";
 import type { BaseObject } from "akanjs/constant";
@@ -15,6 +15,9 @@ import { Popconfirm } from "../Popconfirm";
 import { RecentTime } from "../RecentTime";
 import { dictLabel, formatCell } from "./dataText";
 
+const renderCell = (value: unknown) =>
+  value instanceof Date || dayjs.isDayjs(value) ? <RecentTime date={value} /> : formatCell(value);
+
 export const convToAntdColumn = (column: DataColumn<any>) => {
   if (typeof column !== "string")
     return {
@@ -22,7 +25,7 @@ export const convToAntdColumn = (column: DataColumn<any>) => {
       dataIndex: column.key as string,
       title: capitalize(column.key as string),
       responsive: column.responsive ? (["md", "lg", "xl"] as const) : undefined,
-      render: column.render,
+      render: column.render ?? renderCell,
     };
   else if (
     [
@@ -62,7 +65,7 @@ export const convToAntdColumn = (column: DataColumn<any>) => {
       title: capitalize(column),
       render: (role: string) => <RoleTags role={role} />,
     };
-  else return { key: column, dataIndex: column, title: capitalize(column) };
+  else return { key: column, dataIndex: column, title: capitalize(column), render: renderCell };
 };
 
 interface ItemProps<T extends string, Full extends { id: string }, Light extends { id: string }> {

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()) }
+    }
+}

package/vendor/@akanjs/native/plugins/contacts/ios/ContactsPlugin.swift

@@ -0,0 +1,86 @@
+import Contacts
+import Foundation
+
+/// The address book through CNContactStore, read-only.
+/// - Enumeration blocks until every contact is read, so it runs on a background queue with a store of its own.
+/// - iOS 18 limited access reports as "granted": the store then enumerates only the contacts the user shared.
+/// Arguments arrive decoded and checked by the generated ContactsPluginSpec (PL-10).
+final class ContactsPlugin: ContactsPluginSpec {
+    static let id = "contacts"
+    private let context: AkanNativePluginContext
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    private static var permission: ContactsPermissionState {
+        switch CNContactStore.authorizationStatus(for: .contacts) {
+        case .authorized: .granted
+        case .denied, .restricted: .denied
+        case .notDetermined: .prompt
+        case .limited: .granted
+        @unknown default: .denied
+        }
+    }
+
+    /// Asking for contacts without NSContactsUsageDescription gets the app killed by TCC.
+    private static var hasUsageDescription: Bool {
+        Bundle.main.object(forInfoDictionaryKey: "NSContactsUsageDescription") != nil
+    }
+
+    func checkPermission(_ reply: AkanNativeReply<ContactsCheckPermissionResult>) {
+        reply.resolve(ContactsCheckPermissionResult(contacts: Self.permission))
+    }
+
+    func requestPermission(_ reply: AkanNativeReply<ContactsRequestPermissionResult>) {
+        withPermission(reply) { reply.resolve(ContactsRequestPermissionResult(contacts: $0)) }
+    }
+
+    func getContacts(_ args: ContactsGetContactsOptions, _ reply: AkanNativeReply<ContactsGetContactsResult>) {
+        let withName = args.projection?.name ?? true
+        let withPhones = args.projection?.phones ?? true
+        withPermission(reply) { state in
+            guard state == .granted else { return reply.reject(.permissionDenied, "contacts access was denied") }
+            DispatchQueue.global(qos: .userInitiated).async {
+                do {
+                    reply.resolve(ContactsGetContactsResult(contacts: try Self.read(name: withName, phones: withPhones)))
+                } catch {
+                    reply.reject(.internalError, "could not read contacts: \(error.localizedDescription)")
+                }
+            }
+        }
+    }
+
+    /// Resolves with the state after the prompt, or the current one when there is nothing to ask.
+    private func withPermission<T>(_ reply: AkanNativeReply<T>, _ then: @escaping @Sendable (ContactsPermissionState) -> Void) {
+        guard Self.permission == .prompt else { return then(Self.permission) }
+        guard Self.hasUsageDescription else {
+            return reply.reject(.internalError, "Info.plist has no NSContactsUsageDescription")
+        }
+        CNContactStore().requestAccess(for: .contacts) { _, _ in
+            DispatchQueue.main.async { then(Self.permission) }
+        }
+    }
+
+    nonisolated private static func read(name: Bool, phones: Bool) throws -> [ContactsContact] {
+        var keys: [CNKeyDescriptor] = []
+        if name { keys.append(CNContactFormatter.descriptorForRequiredKeys(for: .fullName)) }
+        if phones { keys.append(CNContactPhoneNumbersKey as CNKeyDescriptor) }
+        let request = CNContactFetchRequest(keysToFetch: keys)
+        request.sortOrder = .userDefault
+        var result: [ContactsContact] = []
+        try CNContactStore().enumerateContacts(with: request) { contact, _ in
+            let display = name ? CNContactFormatter.string(from: contact, style: .fullName) : nil
+            let numbers = phones
+                ? contact.phoneNumbers.map { labeled in
+                    ContactsContactPhone(
+                        number: labeled.value.stringValue,
+                        label: labeled.label.map { CNLabeledValue<CNPhoneNumber>.localizedString(forLabel: $0) }
+                    )
+                }
+                : []
+            result.append(ContactsContact(id: contact.identifier, name: display?.isEmpty == false ? display : nil, phones: numbers))
+        }
+        return result
+    }
+}

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

@@ -0,0 +1,22 @@
+{
+  "id": "contacts",
+  "apiVersion": 1,
+  "methods": ["checkPermission", "requestPermission", "getContacts"],
+  "events": [],
+  "codegen": true,
+  "web": null,
+  "desktop": null,
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "ContactsPlugin",
+    "frameworks": ["Contacts"],
+    "infoPlist": {
+      "NSContactsUsageDescription": "Read your contacts."
+    }
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.contacts.ContactsPlugin",
+    "permissions": ["android.permission.READ_CONTACTS"]
+  }
+}

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

@@ -0,0 +1,43 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+
+/** "prompt-with-rationale" is Android's: asked and refused once, so the app should explain before asking again. */
+export type PermissionState = "granted" | "denied" | "prompt" | "prompt-with-rationale";
+
+export interface ContactPhone {
+  /** As the address book stores it: no normalization, so "010-1234-5678" and "+82 10 1234 5678" both occur. */
+  number: string;
+  /** The label shown in the system Contacts app ("mobile", "home", a custom one), localized; null when unlabeled. */
+  label: string | null;
+}
+
+export interface Contact {
+  /** Stable for this contact on this device only. */
+  id: string;
+  /** The display name the system Contacts app shows; null when not projected or the contact has none. */
+  name: string | null;
+  /** Empty when not projected. */
+  phones: ContactPhone[];
+}
+
+/** What to read for each contact. Both default to true; leave out what the screen does not need. */
+export interface GetContactsOptions {
+  projection?: { name?: boolean; phones?: boolean };
+}
+
+/**
+ * Reads the device's address book (iOS Contacts, Android ContactsContract); there is no web or desktop
+ * implementation, so every call there rejects with UNSUPPORTED.
+ * - "granted" on iOS 18 also covers limited access: getContacts returns only the contacts the user shared.
+ * - getContacts asks for permission first when it was never asked, and rejects with PERMISSION_DENIED when
+ *   denied. INTERNAL when NSContactsUsageDescription is missing (iOS kills an app that asks without it).
+ */
+export interface ContactsApi {
+  checkPermission(): Promise<{ contacts: PermissionState }>;
+  /** Shows the system prompt when the state is "prompt" or "prompt-with-rationale"; otherwise returns the state. */
+  requestPermission(): Promise<{ contacts: PermissionState }>;
+  getContacts(options?: GetContactsOptions): Promise<{ contacts: Contact[] }>;
+}
+
+export const contacts = definePlugin<ContactsApi>("contacts", {
+  methods: ["checkPermission", "requestPermission", "getContacts"],
+});