@spencerls/react-native-nfc 1.0.4 → 1.0.5

package/API.md

@@ -0,0 +1,214 @@
+# @spencerls/react-native-nfc – API Reference
+
+This document describes the complete public API surface of the NFC package.
+
+All exports come from:
+
+```ts
+import { nfc, nfcService } from "@spencerls/react-native-nfc";
+import {
+  useNfc,
+  useNfcState,
+  useNfcReader,
+  useNfcTechnology,
+  NfcProvider
+} from "@spencerls/react-native-nfc";
+```
+
+---
+
+# Core Service: `nfcService`
+
+```ts
+import { nfcService } from "@spencerls/react-native-nfc";
+```
+
+### Methods
+
+#### startReader(flags, onTag, options?)
+Starts platform reader mode.
+
+```ts
+nfcService.startReader(
+  flags: number,
+  onTag: (tag: TagEvent) => void,
+  options?: { cooldownMs?: number }
+)
+```
+
+#### stopReader()
+Stops reader mode.
+
+```ts
+await nfcService.stopReader();
+```
+
+#### withTechnology(tech, handler)
+Opens an iOS/Android technology session. Stops reader mode before starting.
+
+```ts
+await nfcService.withTechnology(
+  tech: NfcTech | NfcTech[],
+  async () => { /* commands */ }
+);
+```
+
+#### getState()
+Returns the current state snapshot.
+
+```ts
+{ mode, tag }
+```
+
+#### subscribe(listener)
+Attach a state listener; returns an unsubscribe function.
+
+---
+
+# Namespace API: `nfc`
+
+```ts
+import { nfc } from "@spencerls/react-native-nfc";
+```
+
+`nfc` is a namespaced, easy-to-use interface:
+
+```
+nfc.service        (NfcService instance)
+nfc.v.*            NFC-V operations
+nfc.a.*            NFC-A operations
+nfc.ndef.*         NDEF operations
+```
+
+---
+
+# NFC-V Namespace: `nfc.v`
+
+High-level ISO15693 helpers and raw operations.
+
+```ts
+nfc.v.getSystemInfoNfcV()
+nfc.v.readSingleBlock(uid, blockNumber)
+nfc.v.readMultipleBlocks(uid, start, count)
+nfc.v.writeSingleBlock(uid, blockNumber, data)
+nfc.v.getSecurityStatus(uid, blockNumber)
+```
+
+---
+
+# NFC-A Namespace: `nfc.a`
+
+```ts
+nfc.a.transceive(bytes)
+nfc.a.getAtqa()
+nfc.a.getSak()
+```
+
+---
+
+# NDEF Namespace: `nfc.ndef`
+
+```ts
+nfc.ndef.parse(bytes)
+nfc.ndef.encode(records)
+nfc.ndef.utils.*
+```
+
+---
+
+# React Hooks
+
+All hooks live under:
+
+```ts
+import { ... } from "@spencerls/react-native-nfc";
+```
+
+---
+
+## useNfc(onTag, options)
+
+Automatically starts reader mode on mount and stops on unmount.
+
+```ts
+useNfc(
+  (tagId: string) => { ... },
+  {
+    flags?: number,
+    cooldownMs?: number
+  }
+);
+```
+
+---
+
+## useNfcState()
+
+Access current NFC state:
+
+```tsx
+const { mode, tag } = useNfcState();
+```
+
+---
+
+## useNfcReader()
+
+Manual control over reader mode.
+
+```ts
+const { start, stop } = useNfcReader();
+```
+
+---
+
+## useNfcTechnology()
+
+Runs an NFC technology session (NfcV, Ndef, etc).
+
+```ts
+await runWithTech([NfcTech.NfcV], async () => {
+  const info = await nfc.v.getSystemInfoNfcV();
+});
+```
+
+---
+
+# NfcProvider
+
+Optional provider that exposes service state to React tree.
+
+```tsx
+<NfcProvider>
+  <App />
+</NfcProvider>
+```
+
+---
+
+# Types
+
+All types are exported from `@spencerls/react-native-nfc/nfc`.
+
+Notable types:
+
+```ts
+NfcState
+NfcMode
+TagEvent
+```
+
+---
+
+# Internal Notes
+
+- iOS automatically restarts reader mode after each scan.
+- Android waits for cooldown before accepting next scan.
+- Technology sessions interrupt reader mode safely.
+- `NfcTech` enums must be used. Do not pass raw strings.
+
+---
+
+# License
+
+MIT © Spencer Smith

package/README.md

@@ -1,63 +1,174 @@
-# @spencer/nfc
+# @spencerls/react-native-nfc
 
-An easy, clean, React-friendly NFC service built on `react-native-nfc-manager`.
+A clean, React-friendly, cross-platform NFC layer built on top of  
+`react-native-nfc-manager`.
+
+This package provides:
+
+- A unified NFC service (`nfcService`)
+- High-level protocol namespaces (`nfc.v`, `nfc.a`, `nfc.ndef`)
+- Automatic iOS reader restarts
+- Safe Android reader handling
+- Optional React hooks and provider
+- Technology sessions for NDEF/NfcV/NfcA and raw commands
+
+The API is designed to be stable, predictable, and easy to use across iOS and Android.
+
+---
 
 ## Installation
 
 ```bash
-npm install @spencer/nfc
-# or
-yarn add @spencer/nfc
+npm install @spencerls/react-native-nfc
+npm install react-native-nfc-manager
 ```
 
-## Requires:
+Works with:
+
+- React Native 0.74+
+- Expo (Bare / Prebuild)
+- iOS 13+ (Core NFC)
+- Android API 21+
+
+---
+
+## Basic Usage (Reader Mode)
 
-`react-native-nfc-manager`
+```tsx
+import { useNfc, useNfcState } from "@spencerls/react-native-nfc";
+import { NfcAdapter } from "react-native-nfc-manager";
+
+export default function ScannerScreen() {
+  const { mode } = useNfcState();
+
+  useNfc((tagId) => {
+    console.log("Scanned:", tagId);
+  }, {
+    flags:
+      NfcAdapter.FLAG_READER_NFC_V |
+      NfcAdapter.FLAG_READER_NO_PLATFORM_SOUNDS,
+    cooldownMs: 800
+  });
+
+  return (
+    <View>
+      <Text>NFC Mode: {mode}</Text>
+    </View>
+  );
+}
+```
 
-React Native 0.74+ or Expo (Bare / Prebuild)
+---
 
-## Usage
+## Manual Reader Control
 
 ```tsx
-import { nfc } from "@spencer/nfc";
-import { Ndef, NfcAdapter } from "react-native-nfc-manager";
-
-export default function Example() {
-  const { nfcState } = useNfc();
-
-  useEffect(() => {
-    nfc.service.startReader(
-      NfcAdapter.FLAG_READER_NFC_V | NfcAdapter.FLAG_READER_NO_PLATFORM_SOUNDS,
-      async (tag) => {
-        console.log("Tag:", tag);
-        await nfc.service.stopReader();
-        await nfc.service.writeNdef([Ndef.textRecord("Hello NFC!")]);
-      }
+import { useNfcReader } from "@spencerls/react-native-nfc";
+import { NfcAdapter } from "react-native-nfc-manager";
+
+export default function Screen() {
+  const { start, stop } = useNfcReader();
+
+  const begin = () => {
+    start(
+      NfcAdapter.FLAG_READER_NFC_V,
+      (tag) => {
+        console.log("Tag:", tag.id);
+      },
+      1200
     );
+  };
+
+  return <Button title="Start" onPress={begin} />;
+}
+```
+
+---
+
+## Technology Sessions (NfcTech.*)
+
+Always use `NfcTech` enums.  
+Do not pass raw strings.
+
+```tsx
+import { nfc } from "@spencerls/react-native-nfc";
+import { useNfcTechnology } from "@spencerls/react-native-nfc";
+import { NfcTech } from "react-native-nfc-manager";
+
+export function ReadSystemInfo() {
+  const { runWithTech } = useNfcTechnology();
 
-    return () => nfc.service.stopReader();
-  }, []);
-
-  const start = async () => {
-    await nfc.v
-      .getSystemInfoNfcV()
-      .then((i) => {
-        console.log("info:", i);
-      })
-      .catch((e) => {
-        console.error("error:", e);
-      });
+  const readInfo = async () => {
+    await runWithTech([NfcTech.NfcV], async () => {
+      const info = await nfc.v.getSystemInfoNfcV();
+      console.log(info);
+    });
   };
 
+  return <Button title="Read NFC-V Info" onPress={readInfo} />;
+}
+```
+
+---
+
+## NDEF Read/Write
+
+```tsx
+import { useNfcTechnology } from "@spencerls/react-native-nfc";
+import { NfcTech, Ndef, NfcManager } from "react-native-nfc-manager";
+
+export default function WriteScreen() {
+  const { runWithTech } = useNfcTechnology();
+
+  const writeHello = async () => {
+    await runWithTech([NfcTech.Ndef], async () => {
+      const bytes = Ndef.encodeMessage([
+        Ndef.textRecord("Hello NFC!")
+      ]);
+      await NfcManager.ndefHandler.writeNdefMessage(bytes);
+    });
+  };
+
+  return <Button title="Write NDEF" onPress={writeHello} />;
+}
+```
+
+---
+
+## Namespace API
+
+```ts
+import { nfc } from "@spencerls/react-native-nfc";
+
+await nfc.v.getSystemInfoNfcV();
+await nfc.v.readSingleBlock(uid, 0);
+
+await nfc.a.transceive(rawBytes);
+
+await nfc.ndef.parse(ndefBytes);
+
+nfc.service.startReader(...);
+nfc.service.withTechnology(...);
+```
+
+---
+
+## Global Provider (Optional)
+
+```tsx
+import { NfcProvider } from "@spencerls/react-native-nfc";
+
+export default function App() {
   return (
-    <View style={{ padding: 100 }}>
-      <Text style={{ color: "#999" }}>NFC Mode: {nfcState.mode}</Text>
-      <Button title="Scan Tag" onPress={start} />
-    </View>
+    <NfcProvider>
+      <RootApp />
+    </NfcProvider>
   );
 }
 ```
 
+---
+
 ## License
 
 MIT © Spencer Smith

package/dist/index.d.mts

@@ -1,82 +1,6 @@
 import * as react_native_nfc_manager from 'react-native-nfc-manager';
 import { TagEvent, NfcTech, NdefRecord } from 'react-native-nfc-manager';
 
-type StrictTagEvent = TagEvent & {
-    id: string;
-};
-
-type NfcMode = "idle" | "starting" | "active" | "stopping" | "technology";
-
-interface NfcState {
-    mode: NfcMode;
-    tag: TagEvent | null;
-}
-
-type NfcListener = (state: NfcState) => void;
-declare class NfcService {
-    private state;
-    private listeners;
-    constructor();
-    private setState;
-    getState(): NfcState;
-    subscribe(fn: NfcListener): () => void;
-    startReader(readerModeFlags: number, onTag?: (tag: TagEvent) => void): Promise<void>;
-    stopReader(): Promise<void>;
-    withTechnology<T>(tech: NfcTech | NfcTech[], handler: () => Promise<T>): Promise<T>;
-}
-declare const nfcService: NfcService;
-
-/**
- * NFC root namespace providing access to:
- * - NfcService
- * - ISO15693 NFC-V ops
- * - NFC-A ops
- * - NDEF operations
- */
-declare const nfc: {
-    readonly service: NfcService;
-    /** ISO15693 protocol helpers and high-level operations */
-    readonly v: {
-        readonly utils: {
-            readonly tech: react_native_nfc_manager.NfcTech.NfcV | react_native_nfc_manager.NfcTech[];
-            readonly Flags: {
-                readonly HIGH_DATA_RATE: 2;
-                readonly ADDRESSED: 32;
-            };
-            readonly Commands: {
-                readonly READ_SINGLE_BLOCK: 32;
-                readonly WRITE_SINGLE_BLOCK: 33;
-                readonly GET_SYSTEM_INFO: 43;
-            };
-            readonly flags: (...bits: number[]) => number;
-            readonly reverseUid: (tagIdHex: string) => number[];
-            readonly buildReadBlock: (uidReversed: number[], blockNumber: number) => number[];
-            readonly buildWriteBlock: (uidReversed: number[], blockNumber: number, data: Uint8Array) => number[];
-            readonly buildGetSystemInfo: (uidReversed: number[]) => number[];
-            readonly parseReadResponse: (resp: number[]) => Uint8Array;
-            readonly parseWriteResponse: (resp: number[]) => void;
-            readonly parseSystemInfo: (resp: number[]) => any;
-            readonly detectManufacturer: (uid: string) => string;
-        };
-        readonly withVTag: <T>(handler: (tag: StrictTagEvent) => Promise<T>) => Promise<T>;
-        readonly writeBlockNfcV: (blockNumber: number, data: Uint8Array) => Promise<void>;
-        readonly readBlockNfcV: (blockNumber: number) => Promise<Uint8Array<ArrayBufferLike>>;
-        readonly getSystemInfoNfcV: () => Promise<any>;
-    };
-    /** NFC-A / Type 2 helpers and operations */
-    readonly a: {
-        readonly utils: {};
-        readonly transceive: (data: number[]) => Promise<number[]>;
-    };
-    /** NDEF read/write utilities and operations */
-    readonly ndef: {
-        readonly utils: {};
-        readonly writeNdef: (records: react_native_nfc_manager.NdefRecord[]) => Promise<void>;
-        readonly writeTextNdef: (text: string) => Promise<void>;
-        readonly writeUriNdef: (uri: string) => Promise<void>;
-    };
-};
-
 declare const operations$2: {
     transceive(data: number[]): Promise<number[]>;
 };
@@ -87,26 +11,18 @@ declare namespace index$2 {
   export { operations$2 as operations, utils$2 as utils };
 }
 
-declare const operations$1: {
-    writeNdef(records: NdefRecord[]): Promise<void>;
-    writeTextNdef(text: string): Promise<void>;
-    writeUriNdef(uri: string): Promise<void>;
+type StrictTagEvent = TagEvent & {
+    id: string;
 };
 
-declare const utils$1: {};
-
-declare namespace index$1 {
-  export { operations$1 as operations, utils$1 as utils };
-}
-
-declare const operations: {
+declare const operations$1: {
     withVTag<T>(handler: (tag: StrictTagEvent) => Promise<T>): Promise<T>;
     writeBlockNfcV(blockNumber: number, data: Uint8Array): Promise<void>;
     readBlockNfcV(blockNumber: number): Promise<Uint8Array<ArrayBufferLike>>;
     getSystemInfoNfcV(): Promise<any>;
 };
 
-declare const utils: {
+declare const utils$1: {
     readonly tech: NfcTech.NfcV | NfcTech[];
     readonly Flags: {
         readonly HIGH_DATA_RATE: 2;
@@ -162,10 +78,102 @@ declare const utils: {
     readonly detectManufacturer: (uid: string) => string;
 };
 
+declare namespace index$1 {
+  export { operations$1 as operations, utils$1 as utils };
+}
+
+declare const operations: {
+    writeNdef(records: NdefRecord[]): Promise<void>;
+    writeTextNdef(text: string): Promise<void>;
+    writeUriNdef(uri: string): Promise<void>;
+};
+
+declare const utils: {};
+
 declare const index_operations: typeof operations;
 declare const index_utils: typeof utils;
 declare namespace index {
   export { index_operations as operations, index_utils as utils };
 }
 
-export { type NfcMode, type NfcState, index$1 as ndef, nfc, index$2 as nfcA, nfcService, index as nfcV };
+type NfcMode = "idle" | "starting" | "active" | "stopping" | "technology";
+
+interface NfcState {
+    mode: NfcMode;
+    tag: TagEvent | null;
+}
+
+type NfcListener = (state: NfcState) => void;
+declare class NfcService {
+    private state;
+    private listeners;
+    private isProcessingTag;
+    private currentOnTag?;
+    private currentCooldownMs;
+    private lastUsedReaderFlags;
+    constructor();
+    private setState;
+    getState(): NfcState;
+    subscribe(fn: NfcListener): () => void;
+    startReader(readerModeFlags: number, onTag?: (tag: TagEvent) => Promise<void> | void, options?: {
+        cooldownMs?: number;
+    }): Promise<void>;
+    stopReader(): Promise<void>;
+    private _resetReaderState;
+    private _restartIosReader;
+    withTechnology<T>(tech: NfcTech | NfcTech[], handler: () => Promise<T>): Promise<T>;
+}
+declare const nfcService: NfcService;
+
+/**
+ * NFC root namespace providing access to:
+ * - NfcService
+ * - ISO15693 NFC-V ops
+ * - NFC-A ops
+ * - NDEF operations
+ */
+declare const nfc: {
+    readonly service: NfcService;
+    /** ISO15693 protocol helpers and high-level operations */
+    readonly v: {
+        readonly utils: {
+            readonly tech: react_native_nfc_manager.NfcTech.NfcV | react_native_nfc_manager.NfcTech[];
+            readonly Flags: {
+                readonly HIGH_DATA_RATE: 2;
+                readonly ADDRESSED: 32;
+            };
+            readonly Commands: {
+                readonly READ_SINGLE_BLOCK: 32;
+                readonly WRITE_SINGLE_BLOCK: 33;
+                readonly GET_SYSTEM_INFO: 43;
+            };
+            readonly flags: (...bits: number[]) => number;
+            readonly reverseUid: (tagIdHex: string) => number[];
+            readonly buildReadBlock: (uidReversed: number[], blockNumber: number) => number[];
+            readonly buildWriteBlock: (uidReversed: number[], blockNumber: number, data: Uint8Array) => number[];
+            readonly buildGetSystemInfo: (uidReversed: number[]) => number[];
+            readonly parseReadResponse: (resp: number[]) => Uint8Array;
+            readonly parseWriteResponse: (resp: number[]) => void;
+            readonly parseSystemInfo: (resp: number[]) => any;
+            readonly detectManufacturer: (uid: string) => string;
+        };
+        readonly withVTag: <T>(handler: (tag: StrictTagEvent) => Promise<T>) => Promise<T>;
+        readonly writeBlockNfcV: (blockNumber: number, data: Uint8Array) => Promise<void>;
+        readonly readBlockNfcV: (blockNumber: number) => Promise<Uint8Array<ArrayBufferLike>>;
+        readonly getSystemInfoNfcV: () => Promise<any>;
+    };
+    /** NFC-A / Type 2 helpers and operations */
+    readonly a: {
+        readonly utils: {};
+        readonly transceive: (data: number[]) => Promise<number[]>;
+    };
+    /** NDEF read/write utilities and operations */
+    readonly ndef: {
+        readonly utils: {};
+        readonly writeNdef: (records: react_native_nfc_manager.NdefRecord[]) => Promise<void>;
+        readonly writeTextNdef: (text: string) => Promise<void>;
+        readonly writeUriNdef: (uri: string) => Promise<void>;
+    };
+};
+
+export { type NfcMode, type NfcState, nfc, index$2 as nfcA, index as nfcNdef, nfcService, index$1 as nfcV };