ink-framework-contacts 0.0.0-stage → 0.1.0-alpha.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ink-native.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "modules": {
+    "*": ["contacts"]
+  }
+}

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "ink-framework-contacts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.16",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "ink": "npm:ink-framework@0.1.0-alpha.16"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/contacts"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts",
+    "*.md"
+  ]
+}

package/src/decode.ts

@@ -0,0 +1,51 @@
+import { NativeError } from "ink/native";
+import type { Contact, ContactDetails, LabeledValue } from "./index";
+
+const LISTS = ["phones", "emails", "addresses", "websites", "events"] as const;
+
+function isContact(value: unknown): value is Contact {
+  return typeof value === "object" && value !== null
+    && typeof Reflect.get(value, "id") === "string" && typeof Reflect.get(value, "name") === "string";
+}
+
+function isLabeledValue(value: unknown): value is LabeledValue {
+  return typeof value === "object" && value !== null
+    && typeof Reflect.get(value, "label") === "string" && typeof Reflect.get(value, "value") === "string";
+}
+
+export function decodeContactPage(json: string, offset: number): { contacts: Contact[]; next: number | null } {
+  const page: unknown = JSON.parse(json);
+  if (typeof page !== "object" || page === null) throw new NativeError("protocol", "Invalid contact list");
+  const contacts: unknown = Reflect.get(page, "contacts");
+  const next: unknown = Reflect.get(page, "next");
+  if (!Array.isArray(contacts) || !contacts.every(isContact) || !(next === null || typeof next === "number" && Number.isSafeInteger(next))) {
+    throw new NativeError("protocol", "Invalid contact list");
+  }
+  if (next !== null && next <= offset) throw new NativeError("protocol", "Contact pagination did not advance");
+  return { contacts, next };
+}
+
+/** Joins pages into one list. A contact that moves between pages while they load is kept once, where it first appeared. */
+export async function collectContacts(load: (offset: number) => Promise<string>, signal?: AbortSignal): Promise<Contact[]> {
+  const contacts = new Map<string, Contact>();
+  for (let offset: number | null = 0; offset !== null;) {
+    signal?.throwIfAborted();
+    const page = decodeContactPage(await load(offset), offset);
+    for (const contact of page.contacts) contacts.set(contact.id, contact);
+    offset = page.next;
+  }
+  return [...contacts.values()];
+}
+
+export function decodeContactDetails(json: string): ContactDetails | null {
+  const contact: unknown = JSON.parse(json);
+  if (contact === null) return null;
+  if (!isContact(contact) || !LISTS.every(key => {
+    const list: unknown = Reflect.get(contact, key);
+    return Array.isArray(list) && list.every(isLabeledValue);
+  }) || !["organization", "note"].every(key => {
+    const text: unknown = Reflect.get(contact, key);
+    return text === null || typeof text === "string";
+  })) throw new NativeError("protocol", "Invalid contact details");
+  return contact as ContactDetails;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+import { callNative } from "ink/native";
+import { collectContacts, decodeContactDetails } from "./decode";
+
+export type Contact = { id: string; name: string };
+export type LabeledValue = { label: string; value: string };
+export type ContactDetails = {
+  id: string;
+  name: string;
+  phones: LabeledValue[];
+  emails: LabeledValue[];
+  addresses: LabeledValue[];
+  websites: LabeledValue[];
+  events: LabeledValue[];
+  organization: string | null;
+  note: string | null;
+};
+
+// Each page is one bridge message, capped at 1 MiB. Rows are typically 100–200 bytes, so most address books
+// take one call; Android also ends a page at 512 KiB, which covers unusually long names and lookup keys.
+const PAGE_SIZE = 2000;
+
+export const contacts = {
+  /** Every contact with a name, sorted by name. `query` filters names the way Android's contact search does. */
+  async list(options: { query?: string; signal?: AbortSignal } = {}): Promise<Contact[]> {
+    return collectContacts(offset => callNative("contacts", "list", { query: options.query, offset, limit: PAGE_SIZE }, { timeoutMs: 120_000, signal: options.signal }), options.signal);
+  },
+  /** Resolves with the contact's details, or null when it no longer exists. */
+  async get(id: string, options: { signal?: AbortSignal } = {}): Promise<ContactDetails | null> {
+    return decodeContactDetails(await callNative("contacts", "get", { id }, { signal: options.signal }));
+  },
+};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.