ink-framework-lightos 0.0.0-stage → 0.1.0-alpha.2

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,14 @@
+{
+  "version": 1,
+  "modules": {
+    "src/index.ts": [
+      "light-sdk"
+    ],
+    "src/ringtone.ts": [
+      "light-sdk-ringtone"
+    ],
+    "src/push.ts": [
+      "light-sdk-push"
+    ]
+  }
+}

package/package.json

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

package/src/index.ts

@@ -0,0 +1,62 @@
+import { callNative, NativeError } from "ink/native";
+
+export type Permission = "camera" | "microphone" | "location-approximate" | "location-precise" | "notifications" | "photos" | "videos" | "photos-and-videos" | "audio-files";
+export type PermissionStatus = "granted" | "denied" | "blocked";
+export interface HostPreferences { hapticsEnabled: boolean }
+export interface KeyboardOptions {
+  emojis: string | null;
+  displayVoice: boolean;
+  enableKeyAnimation: boolean;
+  swipeEnabled: boolean | null;
+}
+async function permission(operation: string, name: Permission, signal?: AbortSignal): Promise<PermissionStatus> {
+  const value = await callNative("permissions", operation, { permission: name }, { timeoutMs: 120_000, signal });
+  if (value !== "granted" && value !== "denied" && value !== "blocked") throw new NativeError("protocol", "Invalid permission result");
+  return value;
+}
+
+export const lightos = {
+  async getPreferences(): Promise<HostPreferences> {
+    const value: unknown = JSON.parse(await callNative("light-sdk", "preferences", ""));
+    if (typeof value !== "object" || value === null || !("hapticsEnabled" in value)
+      || typeof value.hapticsEnabled !== "boolean") throw new NativeError("protocol", "Invalid host preferences");
+    return { hapticsEnabled: value.hapticsEnabled };
+  },
+  async getKeyboardOptions(): Promise<KeyboardOptions> {
+    const value: unknown = JSON.parse(await callNative("light-sdk", "keyboard-options", ""));
+    if (typeof value !== "object" || value === null
+      || !("displayVoice" in value) || typeof value.displayVoice !== "boolean"
+      || !("enableKeyAnimation" in value) || typeof value.enableKeyAnimation !== "boolean"
+      || ("emojisAsString" in value && value.emojisAsString !== null && typeof value.emojisAsString !== "string")
+      || ("swipeEnabled" in value && value.swipeEnabled !== null && typeof value.swipeEnabled !== "boolean")) {
+      throw new NativeError("protocol", "Invalid host keyboard options");
+    }
+    return {
+      emojis: "emojisAsString" in value && typeof value.emojisAsString === "string" ? value.emojisAsString : null,
+      displayVoice: value.displayVoice,
+      enableKeyAnimation: value.enableKeyAnimation,
+      swipeEnabled: "swipeEnabled" in value && typeof value.swipeEnabled === "boolean" ? value.swipeEnabled : null,
+    };
+  },
+  async getVersion(): Promise<string> {
+    const version = await callNative("light-sdk", "version", "");
+    if (!version.trim()) throw new NativeError("protocol", "Host returned an empty version");
+    return version;
+  },
+  getPermission(name: Permission, { signal }: { signal?: AbortSignal } = {}) { return permission("status", name, signal); },
+  requestPermission(name: Permission, { signal }: { signal?: AbortSignal } = {}) { return permission("request", name, signal); },
+  async canScheduleExact(): Promise<boolean> {
+    const value = await callNative("notifications", "exact-status", {});
+    if (value !== "granted" && value !== "denied") throw new NativeError("protocol", "Invalid exact alarm permission result");
+    return value === "granted";
+  },
+  async requestExactPermission(): Promise<void> {
+    await callNative("notifications", "request-exact-permission", {});
+  },
+  async openDialler({ phoneNumber }: { phoneNumber: string }): Promise<void> {
+    if (!phoneNumber.trim() || phoneNumber.length > 64 || /[\u0000-\u001f\u007f-\u009f]/.test(phoneNumber)) {
+      throw new TypeError("Phone number must contain 1–64 characters without control characters");
+    }
+    await callNative("light-sdk", "open-dialler", { phoneNumber });
+  },
+};

package/src/push.ts

@@ -0,0 +1,122 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { callNative, NativeError } from "ink/native";
+import { attachNativeController } from "ink/native/controller";
+
+export interface PushMessage {
+  id: string;
+  groupKey: string;
+  title: string;
+  body: string;
+  route: string;
+  receivedAt: number;
+}
+export interface PushState {
+  status: "idle" | "registering" | "synchronising" | "ready" | "error";
+  endpoint: string;
+  registeredAt: number;
+  openedKey: string;
+  messages: readonly PushMessage[];
+  error: Error | null;
+}
+export interface PushRegistration {
+  url: string;
+  bearerToken?: string;
+  encryptionKey?: string;
+}
+export interface PushOptions {
+  foregroundGroup?: string | null;
+}
+const initial: PushState = { status: "idle", endpoint: "", registeredAt: 0, openedKey: "", messages: [], error: null };
+function fields(value: unknown) {
+  if (typeof value !== "object" || value === null) throw new NativeError("protocol", "Invalid push state");
+  return {
+    text(name: string) {
+      const field: unknown = Reflect.get(value, name);
+      if (typeof field !== "string") throw new NativeError("protocol", `Invalid push ${name}`);
+      return field;
+    },
+    time(name: string) {
+      const field: unknown = Reflect.get(value, name);
+      if (typeof field !== "number" || !Number.isSafeInteger(field) || field < 0) throw new NativeError("protocol", `Invalid push ${name}`);
+      return field;
+    },
+  };
+}
+function decodeMessage(value: unknown): PushMessage {
+  const item = fields(value);
+  return { id: item.text("id"), groupKey: item.text("groupKey"), title: item.text("title"), body: item.text("body"), route: item.text("route"), receivedAt: item.time("receivedAtMs") };
+}
+function decode(value: unknown): PushState {
+  const field = fields(value);
+  const status = field.text("status");
+  if (status !== "idle" && status !== "registering" && status !== "synchronising" && status !== "ready" && status !== "error") throw new NativeError("protocol", "Invalid push status");
+  if (typeof value !== "object" || value === null || !("messages" in value) || !Array.isArray(value.messages)) throw new NativeError("protocol", "Invalid push messages");
+  let error: Error | null = null;
+  if (status === "error") {
+    if (!("error" in value) || typeof value.error !== "object" || value.error === null) throw new NativeError("protocol", "Invalid push error");
+    const detail = fields(value.error);
+    error = new NativeError(detail.text("kind"), detail.text("message"), "retryable" in value.error && value.error.retryable === true);
+  }
+  return { status, endpoint: field.text("endpoint"), registeredAt: field.time("registeredAtMs"), openedKey: field.text("openedKey"), error,
+    messages: value.messages.map(decodeMessage) };
+}
+
+export function usePush({ foregroundGroup = null }: PushOptions = {}) {
+  const [state, setState] = useState(initial);
+  const [ready, setReady] = useState(false);
+  const controller = useRef<ReturnType<typeof attachNativeController> | null>(null);
+  useEffect(() => {
+    setState(initial);
+    setReady(false);
+    const fail = (error: unknown) => setState({ ...initial, status: "error", error: error instanceof Error ? error : new Error(String(error)) });
+    const attachment = attachNativeController("notifications", { kind: "light-push" }, value => {
+      try { setState(decode(value)); } catch (error) { fail(error); }
+    });
+    controller.current = attachment;
+    void attachment.ready.then(() => {
+      if (controller.current === attachment) setReady(true);
+    }, error => { if (controller.current === attachment) fail(error); });
+    return () => {
+      controller.current = null;
+      void attachment.dispose().catch(error => console.error("Could not release push inbox", error));
+    };
+  }, []);
+  useEffect(() => {
+    const attachment = controller.current;
+    if (!attachment) return;
+    let active = true;
+    void attachment.call("foreground", { groupKey: foregroundGroup }).catch(error => {
+      if (active) setState(current => ({ ...current, status: "error", error: error instanceof Error ? error : new Error(String(error)) }));
+    });
+    return () => { active = false; };
+  }, [foregroundGroup]);
+  const commands = useMemo(() => {
+    const call = async (operation: string, payload: unknown = {}) => {
+      if (!controller.current) throw new NativeError("unavailable", "Push inbox is not attached");
+      await controller.current.call(operation, payload);
+    };
+    return {
+      register: (options: PushRegistration) => call("register", options),
+      retry: () => call("retry"), unregister: () => call("unregister"),
+      dismiss: (groupKey: string) => call("dismiss", { groupKey }), clear: () => call("clear"),
+      notifyForeground: (groupKey: string) => call("foreground-message", { groupKey }),
+    };
+  }, []);
+  return { state, ready, ...commands };
+}
+
+export interface PushDelivery { messages: readonly PushMessage[]; cancelled: readonly string[] }
+export function decodePushDelivery(value: unknown): PushDelivery {
+  if (typeof value !== "object" || value === null || !("messages" in value) || !Array.isArray(value.messages)
+    || !("cancelled" in value) || !Array.isArray(value.cancelled)) throw new TypeError("Invalid push delivery");
+  return {
+    messages: value.messages.map(decodeMessage),
+    cancelled: value.cancelled.map((key: unknown) => {
+      if (typeof key !== "string") throw new TypeError("Invalid cancelled push group");
+      return key;
+    }),
+  };
+}
+export async function setPushTask(task: { id: string } | null): Promise<void> {
+  await callNative("background", "set-push-task", { task: task?.id ?? null });
+}

package/src/ringtone.ts

@@ -0,0 +1,17 @@
+import { callNative, NativeError } from "ink/native";
+
+export type RingtoneKind = "ringtone" | "notification" | "alarm";
+
+export async function installRingtone(
+  source: string,
+  kind: RingtoneKind = "ringtone",
+  { signal }: { signal?: AbortSignal } = {},
+): Promise<void> {
+  const value: unknown = JSON.parse(await callNative("light-sdk", "install-ringtone", { source, kind }, { signal }));
+  if (typeof value !== "object" || value === null || !("status" in value)) throw new NativeError("protocol", "Invalid ringtone result");
+  if (value.status === "installed") return;
+  if (value.status !== "error" || !("error" in value) || typeof value.error !== "object" || value.error === null
+    || !("kind" in value.error) || typeof value.error.kind !== "string"
+    || !("message" in value.error) || typeof value.error.message !== "string") throw new NativeError("protocol", "Invalid ringtone error");
+  throw new NativeError(value.error.kind, value.error.message, "retryable" in value.error && value.error.retryable === true);
+}

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.