@kafitra/lynx-device-info 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @kafitra/lynx-device-info
+
+Lynx Native Module for accessing Android device information. Provides a Promise-based API for retrieving device brand, model, and SDK version.
+
+## Installation
+
+```bash
+# npm
+npm install @kafitra/lynx-device-info
+
+# pnpm
+pnpm add @kafitra/lynx-device-info
+
+# In a monorepo workspace
+pnpm add @kafitra/lynx-device-info@workspace:*
+```
+
+## Android Setup
+
+### 1. Register the Native Module
+
+In your Android host app's initialization code (e.g., `Application.onCreate()` or your Lynx setup), register the module:
+
+```java
+import com.kafitra.lynxdeviceinfo.LynxDeviceInfoModule;
+
+// Register the native module with Lynx runtime
+LynxEnv.inst().registerModule("LynxDeviceInfo", LynxDeviceInfoModule.class);
+```
+
+### 2. Add the module dependency
+
+In your Android host app's `build.gradle`:
+
+```gradle
+dependencies {
+    implementation project(':lynx-device-info')
+}
+```
+
+Or if using the published package, include the `android/` directory in your build.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { DeviceInfo } from "@kafitra/lynx-device-info";
+
+// All methods return Promises
+const brand = await DeviceInfo.getBrand(); // "Samsung"
+const model = await DeviceInfo.getModel(); // "Galaxy S24"
+const sdkVersion = await DeviceInfo.getSDKVersion(); // 34
+```
+
+### Usage with React (Lynx)
+
+```tsx
+import { useState, useEffect } from "@lynx-js/react";
+import { DeviceInfo } from "@kafitra/lynx-device-info";
+
+function App() {
+  const [brand, setBrand] = useState("Loading...");
+  const [model, setModel] = useState("Loading...");
+  const [sdk, setSdk] = useState<number | null>(null);
+  const [error, setError] = useState(false);
+
+  useEffect(() => {
+    async function loadDeviceInfo() {
+      try {
+        const b = await DeviceInfo.getBrand();
+        const m = await DeviceInfo.getModel();
+        const s = await DeviceInfo.getSDKVersion();
+        setBrand(b);
+        setModel(m);
+        setSdk(s);
+      } catch (e) {
+        setError(true);
+      }
+    }
+    loadDeviceInfo();
+  }, []);
+
+  if (error) {
+    return <text>⚠ Native module not registered</text>;
+  }
+
+  return (
+    <view>
+      <text>Brand: {brand}</text>
+      <text>Model: {model}</text>
+      <text>SDK: {sdk}</text>
+    </view>
+  );
+}
+```
+
+## API Reference
+
+| Method            | Return Type       | Description                       |
+| ----------------- | ----------------- | --------------------------------- |
+| `getBrand()`      | `Promise<string>` | Device brand (e.g., "Samsung")    |
+| `getModel()`      | `Promise<string>` | Device model (e.g., "Galaxy S24") |
+| `getSDKVersion()` | `Promise<number>` | Android SDK version (e.g., 34)    |
+
+## Error Handling
+
+The library provides two levels of error handling:
+
+1. **Module not registered**: If `LynxDeviceInfoModule` is not registered in the Android host, importing the module will throw:
+
+   ```
+   [@kafitra/lynx-device-info] Native module not linked.
+   Please register LynxDeviceInfoModule in Android host.
+   ```
+
+2. **Method failure**: If any individual method call fails, the Promise rejects with a descriptive error:
+   ```
+   [lynx-device-info] Failed to get brand: <original error>
+   ```
+
+## Troubleshooting
+
+### "Native module not linked" error
+
+**Cause**: `LynxDeviceInfoModule` was not registered in your Android host app.
+
+**Fix**: Add the registration call in your app's initialization:
+
+```java
+LynxEnv.inst().registerModule("LynxDeviceInfo", LynxDeviceInfoModule.class);
+```
+
+### Methods return "unknown"
+
+**Cause**: The Android `Build` class returned null for the requested property. This can happen on emulators or non-standard devices.
+
+**Fix**: This is expected behavior — the module gracefully falls back to `"unknown"` instead of crashing.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,21 @@
+apply plugin: 'com.android.library'
+
+android {
+    namespace 'com.kafitra.lynxdeviceinfo'
+    compileSdkVersion 34
+
+    defaultConfig {
+        minSdkVersion 21
+        targetSdkVersion 34
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+}
+
+dependencies {
+    // Lynx SDK should be provided by the host app
+    compileOnly 'com.lynx:lynx-sdk:+'
+}

package/android/src/main/java/com/kafitra/lynxdeviceinfo/LynxDeviceInfoModule.java

@@ -0,0 +1,69 @@
+package com.kafitra.lynxdeviceinfo;
+
+import android.content.Context;
+import android.os.Build;
+
+import com.lynx.jsbridge.LynxModule;
+import com.lynx.jsbridge.LynxMethod;
+
+/**
+ * LynxDeviceInfoModule — Lynx Native Module for Android device information.
+ *
+ * Provides synchronous access to device brand, model, and SDK version
+ * through the Lynx Native Module system.
+ *
+ * <h3>Registration:</h3>
+ * <pre>
+ * LynxEnv.inst().registerModule("LynxDeviceInfo", LynxDeviceInfoModule.class);
+ * </pre>
+ */
+public class LynxDeviceInfoModule extends LynxModule {
+
+    public LynxDeviceInfoModule(Context context) {
+        super(context);
+    }
+
+    /**
+     * Returns the device brand (manufacturer brand name).
+     * Falls back to "unknown" if the value is null.
+     *
+     * @return Device brand string, e.g., "Samsung", "Google", "Xiaomi"
+     */
+    @LynxMethod
+    public String getBrand() {
+        try {
+            return Build.BRAND != null ? Build.BRAND : "unknown";
+        } catch (Exception e) {
+            return "unknown";
+        }
+    }
+
+    /**
+     * Returns the device model name.
+     * Falls back to "unknown" if the value is null.
+     *
+     * @return Device model string, e.g., "Galaxy S24", "Pixel 8"
+     */
+    @LynxMethod
+    public String getModel() {
+        try {
+            return Build.MODEL != null ? Build.MODEL : "unknown";
+        } catch (Exception e) {
+            return "unknown";
+        }
+    }
+
+    /**
+     * Returns the Android SDK version number.
+     *
+     * @return SDK version integer, e.g., 34 for Android 14
+     */
+    @LynxMethod
+    public int getSDKVersion() {
+        try {
+            return Build.VERSION.SDK_INT;
+        } catch (Exception e) {
+            return -1;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Public API — Promise-based wrappers around the native module.
+ */
+import type { DeviceInfoInterface } from "./types";
+/**
+ * DeviceInfo provides Promise-based access to Android device information
+ * through the Lynx Native Module system.
+ *
+ * @example
+ * ```ts
+ * import { DeviceInfo } from '@kafitra/lynx-device-info';
+ *
+ * const brand = await DeviceInfo.getBrand();   // "Samsung"
+ * const model = await DeviceInfo.getModel();   // "Galaxy S24"
+ * const sdk   = await DeviceInfo.getSDKVersion(); // 34
+ * ```
+ */
+export declare const DeviceInfo: DeviceInfoInterface;
+export type { DeviceInfoInterface, NativeLynxDeviceInfo } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,EAAE,mBA8BxB,CAAC;AAGF,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Public API — Promise-based wrappers around the native module.
+ */
+import { NativeDeviceInfo } from "./native";
+/**
+ * DeviceInfo provides Promise-based access to Android device information
+ * through the Lynx Native Module system.
+ *
+ * @example
+ * ```ts
+ * import { DeviceInfo } from '@kafitra/lynx-device-info';
+ *
+ * const brand = await DeviceInfo.getBrand();   // "Samsung"
+ * const model = await DeviceInfo.getModel();   // "Galaxy S24"
+ * const sdk   = await DeviceInfo.getSDKVersion(); // 34
+ * ```
+ */
+export const DeviceInfo = {
+    async getBrand() {
+        try {
+            return NativeDeviceInfo.getBrand();
+        }
+        catch (e) {
+            throw new Error(`[lynx-device-info] Failed to get brand: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    },
+    async getModel() {
+        try {
+            return NativeDeviceInfo.getModel();
+        }
+        catch (e) {
+            throw new Error(`[lynx-device-info] Failed to get model: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    },
+    async getSDKVersion() {
+        try {
+            return NativeDeviceInfo.getSDKVersion();
+        }
+        catch (e) {
+            throw new Error(`[lynx-device-info] Failed to get SDK version: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,2CAA2C,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACxF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC;YACH,OAAO,gBAAgB,CAAC,QAAQ,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,2CAA2C,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CACxF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,IAAI,CAAC;YACH,OAAO,gBAAgB,CAAC,aAAa,EAAE,CAAC;QAC1C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,iDAAiD,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAC9F,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/native.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Native module declaration and access layer.
+ * Accesses the LynxDeviceInfo module from the Lynx runtime's NativeModules global.
+ */
+import type { NativeLynxDeviceInfo } from "./types";
+/**
+ * The validated native module instance.
+ */
+export declare const NativeDeviceInfo: NativeLynxDeviceInfo;
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAwBpD;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,oBAAwC,CAAC"}

package/dist/native.js

@@ -0,0 +1,23 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Native module declaration and access layer.
+ * Accesses the LynxDeviceInfo module from the Lynx runtime's NativeModules global.
+ */
+/**
+ * Retrieve and validate the LynxDeviceInfo native module.
+ * Throws a descriptive error if the module is not registered.
+ */
+function getNativeModule() {
+    if (!NativeModules?.LynxDeviceInfo) {
+        throw new Error("[@kafitra/lynx-device-info] Native module not linked. " +
+            "Please register LynxDeviceInfoModule in your Android host:\n\n" +
+            '  LynxEnv.inst().registerModule("LynxDeviceInfo", LynxDeviceInfoModule.class);');
+    }
+    return NativeModules.LynxDeviceInfo;
+}
+/**
+ * The validated native module instance.
+ */
+export const NativeDeviceInfo = getNativeModule();
+//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;GAGG;AACH,SAAS,eAAe;IACtB,IAAI,CAAC,aAAa,EAAE,cAAc,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,wDAAwD;YACtD,gEAAgE;YAChE,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,aAAa,CAAC,cAAc,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAyB,eAAe,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Type definitions for the DeviceInfo native module.
+ */
+/**
+ * Interface for the Lynx DeviceInfo native module methods.
+ */
+export interface DeviceInfoInterface {
+    /** Returns the device brand (e.g., "Samsung", "Google") */
+    getBrand(): Promise<string>;
+    /** Returns the device model (e.g., "Galaxy S24", "Pixel 8") */
+    getModel(): Promise<string>;
+    /** Returns the Android SDK version number (e.g., 34) */
+    getSDKVersion(): Promise<number>;
+}
+/**
+ * Raw native module shape as exposed by Lynx runtime.
+ * These methods are synchronous at the native level.
+ */
+export interface NativeLynxDeviceInfo {
+    getBrand(): string;
+    getModel(): string;
+    getSDKVersion(): number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5B,+DAA+D;IAC/D,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5B,wDAAwD;IACxD,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,IAAI,MAAM,CAAC;IACnB,aAAa,IAAI,MAAM,CAAC;CACzB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @kafitra/lynx-device-info
+ *
+ * Type definitions for the DeviceInfo native module.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kafitra/lynx-device-info",
+  "version": "0.1.0",
+  "description": "Lynx Native Module for accessing Android device information",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "android"
+  ],
+  "peerDependencies": {
+    "lynx": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "rimraf": "^5.0.0"
+  },
+  "keywords": [
+    "lynx",
+    "native-module",
+    "device-info",
+    "android"
+  ],
+  "author": "Kafitra",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kafitra/lynx-native.git",
+    "directory": "packages/lynx-device-info"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist"
+  }
+}