@spencerls/react-native-nfc 1.0.9 → 1.0.11

package/API.md

@@ -14,11 +14,10 @@ import {
 } from "@spencerls/react-native-nfc";
 
 import {
-  useNfc,
-  useNfcState,
-  useNfcReader,
-  useNfcTechnology,
-  NfcProvider
+  useNfcTech,
+  useNfcTechLoop,
+  useNfcTagEvent,
+  useNfcTagEventLoop,
 } from "@spencerls/react-native-nfc";
 ```
 
@@ -30,63 +29,106 @@ import {
 import { nfcService } from "@spencerls/react-native-nfc";
 ```
 
+The `nfcService` is a singleton that manages NFC operations using a job-based architecture with strategies for different operation types.
+
 ### Methods
 
-#### enableReaderMode_ANDROID(flags)
-Configures Android reader mode flags. Must be called before `startReader()` or `withTechnology()`.  
-No-op on iOS.
+#### startTech(tech, withTechnology, afterTechnology?, options?)
+
+Starts a one-shot technology session. Executes once and completes.
 
 ```ts
-nfcService.enableReaderMode_ANDROID(flags: number);
+await nfcService.startTech(
+  tech: NfcTech[],
+  withTechnology: () => Promise<void>,
+  afterTechnology?: () => Promise<void>,
+  options?: RegisterTagEventOpts
+): Promise<void>
 ```
 
 **Example:**
 ```ts
-import { NfcAdapter } from "react-native-nfc-manager";
+import { NfcTech } from "react-native-nfc-manager";
 
-nfcService.enableReaderMode_ANDROID(
-  NfcAdapter.FLAG_READER_NFC_V | NfcAdapter.FLAG_READER_NO_PLATFORM_SOUNDS
+await nfcService.startTech(
+  [NfcTech.NfcV],
+  async () => {
+    const tag = await nfcTag.getTag();
+    console.log("Tag ID:", tag.id);
+  }
 );
 ```
 
-#### startReader(onTag, options?)
-Starts platform reader mode.
+#### startTechLoop(tech, withTechnology, afterTechnology?, options?)
+
+Starts a continuous technology session loop. Automatically restarts after each tag interaction.
+
+```ts
+await nfcService.startTechLoop(
+  tech: NfcTech[],
+  withTechnology: () => Promise<void>,
+  afterTechnology?: () => Promise<void>,
+  options?: RegisterTagEventOpts
+): Promise<void>
+```
 
+**Example:**
 ```ts
-nfcService.startReader(
-  onTag?: (tag: TagEvent) => void,
-  options?: { cooldownMs?: number }
-)
+await nfcService.startTechLoop(
+  [NfcTech.Ndef],
+  async () => {
+    const tag = await nfcTag.getTag();
+    console.log("Tag detected:", tag.id);
+  }
+);
 ```
 
-#### stopReader()
-Stops reader mode.
+#### startTagEvent(onTag)
+
+Starts a one-shot tag event handler. Executes once when a tag is detected.
+
+```ts
+await nfcService.startTagEvent(
+  onTag: (tag: TagEvent) => Promise<void>
+): Promise<void>
+```
 
+**Example:**
 ```ts
-await nfcService.stopReader();
+await nfcService.startTagEvent(async (tag) => {
+  console.log("Tag ID:", tag.id);
+});
 ```
 
-#### withTechnology(tech, handler)
-Opens an iOS/Android technology session. Stops reader mode before starting.
+#### startTagEventLoop(onTag, options?)
 
+Starts a continuous tag event loop. Automatically restarts after each tag detection.
+
+```ts
+await nfcService.startTagEventLoop(
+  onTag: (tag: TagEvent) => Promise<void>,
+  options?: RegisterTagEventOpts
+): Promise<void>
+```
+
+**Example:**
 ```ts
-await nfcService.withTechnology(
-  tech: NfcTech | NfcTech[],
-  async () => { /* commands */ }
+await nfcService.startTagEventLoop(
+  async (tag) => {
+    console.log("Tag detected:", tag.id);
+  },
+  { readerModeFlags: ... }
 );
 ```
 
-#### getState()
-Returns the current state snapshot.
+#### stop()
+
+Stops all NFC operations and cleans up active sessions.
 
 ```ts
-{ mode, tag }
+await nfcService.stop(): Promise<void>
 ```
 
-#### subscribe(listener)
-Attach a state listener; returns an unsubscribe function.
-
----
 
 # Namespace API: `nfc`
 
@@ -357,7 +399,7 @@ Builder.record(init: {
 
 # Low-Level Tag Modules
 
-These modules are used for advanced operations inside `withTechnology` sessions.
+These modules are used for advanced operations inside technology sessions.
 
 ## `nfcTag`
 
@@ -375,7 +417,7 @@ await nfcTag.getTag(): Promise<TagEvent>
 
 **Example:**
 ```ts
-await nfc.service.withTechnology(NfcTech.NfcV, async () => {
+await nfc.service.startTech([NfcTech.NfcV], async () => {
   const tag = await nfcTag.getTag();
   console.log("Tag ID:", tag.id);
 });
@@ -389,11 +431,11 @@ await nfc.service.withTechnology(NfcTech.NfcV, async () => {
 import { nfcVTag } from "@spencerls/react-native-nfc";
 ```
 
-Low-level NFC-V operations. Use inside `withTechnology` sessions.
+Low-level NFC-V operations. Use inside technology sessions.
 
 ### Properties
 
-- `tech`: NfcTech constant for NFC-V (use with `withTechnology`)
+- `tech`: NfcTech constant for NFC-V (use with technology sessions)
 - `utils`: ISO15693 utility functions
 
 ### Methods
@@ -450,9 +492,9 @@ await nfcVTag.transceive(bytes: number[]): Promise<number[]>
 
 **Example:**
 ```ts
-import { nfcTag, nfcVTag } from "@spencerls/react-native-nfc";
+import { nfc, nfcTag, nfcVTag } from "@spencerls/react-native-nfc";
 
-await nfc.service.withTechnology(nfcVTag.tech, async () => {
+await nfc.service.startTech(nfcVTag.tech, async () => {
   const tag = await nfcTag.getTag();
   if (!tag?.id) throw new Error("No tag detected");
   
@@ -469,11 +511,11 @@ await nfc.service.withTechnology(nfcVTag.tech, async () => {
 import { nfcNdefTag } from "@spencerls/react-native-nfc";
 ```
 
-Low-level NDEF operations. Use inside `withTechnology` sessions.
+Low-level NDEF operations. Use inside technology sessions.
 
 ### Properties
 
-- `tech`: NfcTech constant for NDEF (use with `withTechnology`)
+- `tech`: NfcTech constant for NDEF (use with technology sessions)
 
 ### Methods
 
@@ -491,9 +533,9 @@ await nfcNdefTag.write(records: NdefRecord[]): Promise<void>
 
 **Example:**
 ```ts
-import { nfcNdefTag } from "@spencerls/react-native-nfc";
+import { nfc, nfcNdefTag } from "@spencerls/react-native-nfc";
 
-await nfc.service.withTechnology(nfcNdefTag.tech, async () => {
+await nfc.service.startTech(nfcNdefTag.tech, async () => {
   const message = await nfcNdefTag.readMessage();
   console.log("Records:", message.ndefMessage);
 });
@@ -511,96 +553,159 @@ import { ... } from "@spencerls/react-native-nfc";
 
 ---
 
-## useNfc(onTag, options)
-
-Automatically starts reader mode on mount and stops on unmount.
+## useNfcTech(tech, withTechnology, afterTechnology?, options?)
 
-**Note:** Call `nfcService.enableReaderMode_ANDROID(flags)` before using this hook on Android.
+One-shot technology session. Executes once when triggered.
 
 ```ts
-useNfc(
-  (tagId: string) => { ... },
-  {
-    cooldownMs?: number
-  }
+const { startTech } = useNfcTech(
+  tech: NfcTech[],
+  withTechnology: () => Promise<void>,
+  afterTechnology?: () => Promise<void>,
+  options?: RegisterTagEventOpts
 );
 ```
 
 **Example:**
 ```ts
-import { nfcService } from "@spencerls/react-native-nfc";
-import { NfcAdapter } from "react-native-nfc-manager";
-
-// Call once at app startup
-nfcService.enableReaderMode_ANDROID(NfcAdapter.FLAG_READER_NFC_V);
+import { useNfcTech, nfcTag } from "@spencerls/react-native-nfc";
+import { NfcTech } from "react-native-nfc-manager";
 
-// Then use the hook
-useNfc((tagId) => {
-  console.log("Scanned:", tagId);
-}, { cooldownMs: 800 });
+function ScanButton() {
+  const { startTech } = useNfcTech(
+    [NfcTech.NfcV],
+    async () => {
+      const tag = await nfcTag.getTag();
+      console.log("Tag ID:", tag.id);
+    }
+  );
+
+  return <Button title="Scan" onPress={startTech} />;
+}
+```
+
+**With afterTechnology callback:**
+```ts
+const { startTech } = useNfcTech(
+  [NfcTech.NfcV],
+  async () => {
+    const tag = await nfcTag.getTag();
+    console.log("Tag ID:", tag.id);
+  },
+  async () => {
+    console.log("Scan complete");
+  }
+);
 ```
 
 ---
 
-## useNfcState()
+## useNfcTechLoop(tech, withTechnology, afterTechnology?, options?)
 
-Access current NFC state:
+Continuous technology session loop. Automatically restarts after each tag interaction.
 
-```tsx
-const { mode, tag } = useNfcState();
+```ts
+const { start, stop, isRunning } = useNfcTechLoop(
+  tech: NfcTech[],
+  withTechnology: () => Promise<void>,
+  afterTechnology?: () => Promise<void>,
+  options?: RegisterTagEventOpts
+);
 ```
 
----
-
-## useNfcReader()
-
-Manual control over reader mode.
-
-**Note:** Call `nfcService.enableReaderMode_ANDROID(flags)` before calling `start()` on Android.
-
+**Example:**
 ```ts
-const { start, stop } = useNfcReader();
+import { useNfcTechLoop, nfcTag } from "@spencerls/react-native-nfc";
+import { NfcTech } from "react-native-nfc-manager";
 
-// start signature:
-start(onTag?: (tag: TagEvent) => void, options?: { cooldownMs?: number })
+function ContinuousScanScreen() {
+  const { start, stop, isRunning } = useNfcTechLoop(
+    [NfcTech.Ndef],
+    async () => {
+      const tag = await nfcTag.getTag();
+      console.log("Tag detected:", tag.id);
+    }
+  );
+
+  return (
+    <View>
+      <Button title={isRunning ? "Stop" : "Start"} onPress={isRunning ? stop : start} />
+      <Text>{isRunning ? "Scanning..." : "Idle"}</Text>
+    </View>
+  );
+}
+```
+
+**With afterTechnology callback:**
+```ts
+const { start, stop, isRunning } = useNfcTechLoop(
+  [NfcTech.Ndef],
+  async () => {
+    const tag = await nfcTag.getTag();
+    console.log("Tag detected:", tag.id);
+  },
+  async () => {
+    console.log("Waiting for next tag...");
+  }
+);
 ```
 
 ---
 
-## useNfcTechnology()
+## useNfcTagEvent(onTag)
 
-Runs an NFC technology session (NfcV, Ndef, etc).
+One-shot tag event handler. Executes once when a tag is detected.
 
 ```ts
-await runWithTech([NfcTech.NfcV], async () => {
-  const info = await nfc.v.getSystemInfoNfcV();
-});
+const { startTech } = useNfcTagEvent(
+  onTag: (tag: TagEvent) => Promise<void>
+);
 ```
 
----
-
-# NfcProvider
+**Example:**
+```ts
+import { useNfcTagEvent } from "@spencerls/react-native-nfc";
 
-Optional provider that exposes service state to React tree.
+function QuickScan() {
+  const { startTech } = useNfcTagEvent(async (tag) => {
+    console.log("Tag ID:", tag.id);
+  });
 
-```tsx
-<NfcProvider>
-  <App />
-</NfcProvider>
+  return <Button title="Quick Scan" onPress={startTech} />;
+}
 ```
 
 ---
 
-# Types
+## useNfcTagEventLoop(onTag, options?)
 
-All types are exported from `@spencerls/react-native-nfc/nfc`.
+Continuous tag event loop. Automatically restarts after each tag detection.
 
-Notable types:
+```ts
+const { start, stop, isRunning } = useNfcTagEventLoop(
+  onTag: (tag: TagEvent) => Promise<void>,
+  options?: RegisterTagEventOpts
+);
+```
 
+**Example:**
 ```ts
-NfcState
-NfcMode
-TagEvent
+import { useNfcTagEventLoop } from "@spencerls/react-native-nfc";
+
+function MonitorScreen() {
+  const { start, stop, isRunning } = useNfcTagEventLoop(
+    async (tag) => {
+      console.log("Tag detected:", tag.id);
+    }
+  );
+
+  return (
+    <View>
+      <Button title={isRunning ? "Stop Monitoring" : "Start Monitoring"} 
+              onPress={isRunning ? stop : start} />
+    </View>
+  );
+}
 ```
 
 ---
@@ -621,11 +726,11 @@ await nfc.ndef.write(records);
 
 ### Low-Level (Advanced)
 
-Use tag modules (`nfcTag`, `nfcVTag`, `nfcNdefTag`) inside `withTechnology` for complex operations.
+Use `nfc.service.startTech()` with tag modules for complex custom operations.
 
 ```ts
 // ✅ Advanced: custom multi-block read
-await nfc.service.withTechnology(nfcVTag.tech, async () => {
+await nfc.service.startTech(nfcVTag.tech, async () => {
   const tag = await nfcTag.getTag();
   if (!tag?.id) throw new Error("No NFC-V tag detected");
   
@@ -639,21 +744,43 @@ await nfc.service.withTechnology(nfcVTag.tech, async () => {
     offset += block.length;
   }
   
-  return buffer;
+  console.log("Data:", buffer);
 });
 ```
 
+## One-Shot vs Loop
+
+### One-Shot Operations
+
+Use for single tag interactions (scan once and done):
+
+```ts
+const { startTech } = useNfcTech(...);
+// or
+const { startTech } = useNfcTagEvent(...);
+```
+
+### Continuous Loops
+
+Use for monitoring or multiple sequential tag interactions:
+
+```ts
+const { start, stop, isRunning } = useNfcTechLoop(...);
+// or
+const { start, stop, isRunning } = useNfcTagEventLoop(...);
+```
+
 ---
 
 # Internal Notes
 
-- **Android reader mode flags** must be configured via `enableReaderMode_ANDROID()` before starting reader mode or using technology sessions.
-- iOS automatically restarts reader mode after each scan.
-- Android waits for cooldown before accepting next scan.
-- Technology sessions interrupt reader mode safely and auto-restart when done.
-- `NfcTech` enums must be used. Do not pass raw strings.
+- All APIs are 100% cross-platform (iOS and Android).
+- Technology sessions are automatically managed and cleaned up.
+- Hooks automatically stop sessions on component unmount.
+- The service uses a job-based architecture with retry mechanisms.
 - High-level `nfc.*` operations automatically manage technology sessions.
-- Low-level tag modules require manual `withTechnology` wrapping.
+- For custom operations, use `nfc.service.startTech()` with low-level tag modules.
+- Loop operations automatically restart after each tag interaction.
 
 ---