@spencerls/react-native-nfc 1.0.4 → 1.0.6

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,10 +1,103 @@
 import * as react_native_nfc_manager from 'react-native-nfc-manager';
 import { TagEvent, NfcTech, NdefRecord } from 'react-native-nfc-manager';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PropsWithChildren } from 'react';
+
+declare const operations$2: {
+    transceive(data: number[]): Promise<number[]>;
+};
+
+declare const utils$2: {};
+
+declare namespace index$2 {
+  export { operations$2 as operations, utils$2 as utils };
+}
 
 type StrictTagEvent = TagEvent & {
     id: string;
 };
 
+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$1: {
+    readonly tech: NfcTech.NfcV | 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;
+    };
+    /**
+     * Combine multiple flag bits into one byte.
+     * Example: Flags.ADDRESSED | Flags.HIGH_DATA_RATE
+     */
+    readonly flags: (...bits: number[]) => number;
+    /**
+     * Convert tag.id hex string (MSB->LSB) into reversed byte array (LSB->MSB)
+     * ISO15693 requires reversed UID for addressed commands.
+     */
+    readonly reverseUid: (tagIdHex: string) => number[];
+    /**
+     * Build READ_SINGLE_BLOCK command.
+     * FLAGS: addressed + high data rate by default.
+     */
+    readonly buildReadBlock: (uidReversed: number[], blockNumber: number) => number[];
+    /**
+     * Build WRITE_SINGLE_BLOCK command.
+     * Note: data must match the block size (usually 4 or 8 bytes).
+     */
+    readonly buildWriteBlock: (uidReversed: number[], blockNumber: number, data: Uint8Array) => number[];
+    /**
+     * Build GET_SYSTEM_INFO command.
+     */
+    readonly buildGetSystemInfo: (uidReversed: number[]) => number[];
+    /**
+     * Parse a READ_SINGLE_BLOCK response.
+     * Response format:
+     *  - byte[0] = status (0x00 = success)
+     *  - byte[1..] = block payload bytes
+     */
+    readonly parseReadResponse: (resp: number[]) => Uint8Array;
+    /**
+     * Parse WRITE_SINGLE_BLOCK response.
+     * Successful write has resp[0] === 0x00.
+     */
+    readonly parseWriteResponse: (resp: number[]) => void;
+    /**
+     * Parse GET_SYSTEM_INFO response.
+     * Returns: UID, DSFID, AFI, numberOfBlocks, blockSize, manufacturer
+     */
+    readonly parseSystemInfo: (resp: number[]) => any;
+    /** Identify common manufacturers based on UID prefix */
+    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 };
+}
+
 type NfcMode = "idle" | "starting" | "active" | "stopping" | "technology";
 
 interface NfcState {
@@ -16,12 +109,20 @@ 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) => void): Promise<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;
@@ -77,95 +178,28 @@ declare const nfc: {
     };
 };
 
-declare const operations$2: {
-    transceive(data: number[]): Promise<number[]>;
-};
-
-declare const utils$2: {};
-
-declare namespace index$2 {
-  export { operations$2 as operations, utils$2 as utils };
+interface NfcContextValue {
+    state: NfcState;
+    service: typeof nfcService;
 }
+declare function NfcProvider({ children }: PropsWithChildren): react_jsx_runtime.JSX.Element;
+declare function useNfcContext(): NfcContextValue;
 
-declare const operations$1: {
-    writeNdef(records: NdefRecord[]): Promise<void>;
-    writeTextNdef(text: string): Promise<void>;
-    writeUriNdef(uri: string): Promise<void>;
-};
-
-declare const utils$1: {};
+declare function useNfc(onTag: (tagId: string) => void, options: {
+    cooldownMs?: number;
+    flags: number;
+}): void;
 
-declare namespace index$1 {
-  export { operations$1 as operations, utils$1 as utils };
-}
-
-declare const operations: {
-    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 function useNfcReader(): {
+    start: (flags: number, onTag: (tag: TagEvent) => void, cooldownMs?: number) => void;
+    stop: () => void;
 };
 
-declare const utils: {
-    readonly tech: NfcTech.NfcV | 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;
-    };
-    /**
-     * Combine multiple flag bits into one byte.
-     * Example: Flags.ADDRESSED | Flags.HIGH_DATA_RATE
-     */
-    readonly flags: (...bits: number[]) => number;
-    /**
-     * Convert tag.id hex string (MSB->LSB) into reversed byte array (LSB->MSB)
-     * ISO15693 requires reversed UID for addressed commands.
-     */
-    readonly reverseUid: (tagIdHex: string) => number[];
-    /**
-     * Build READ_SINGLE_BLOCK command.
-     * FLAGS: addressed + high data rate by default.
-     */
-    readonly buildReadBlock: (uidReversed: number[], blockNumber: number) => number[];
-    /**
-     * Build WRITE_SINGLE_BLOCK command.
-     * Note: data must match the block size (usually 4 or 8 bytes).
-     */
-    readonly buildWriteBlock: (uidReversed: number[], blockNumber: number, data: Uint8Array) => number[];
-    /**
-     * Build GET_SYSTEM_INFO command.
-     */
-    readonly buildGetSystemInfo: (uidReversed: number[]) => number[];
-    /**
-     * Parse a READ_SINGLE_BLOCK response.
-     * Response format:
-     *  - byte[0] = status (0x00 = success)
-     *  - byte[1..] = block payload bytes
-     */
-    readonly parseReadResponse: (resp: number[]) => Uint8Array;
-    /**
-     * Parse WRITE_SINGLE_BLOCK response.
-     * Successful write has resp[0] === 0x00.
-     */
-    readonly parseWriteResponse: (resp: number[]) => void;
-    /**
-     * Parse GET_SYSTEM_INFO response.
-     * Returns: UID, DSFID, AFI, numberOfBlocks, blockSize, manufacturer
-     */
-    readonly parseSystemInfo: (resp: number[]) => any;
-    /** Identify common manufacturers based on UID prefix */
-    readonly detectManufacturer: (uid: string) => string;
-};
+declare function useNfcState(): NfcState;
 
-declare const index_operations: typeof operations;
-declare const index_utils: typeof utils;
-declare namespace index {
-  export { index_operations as operations, index_utils as utils };
-}
+declare function useNfcTechnology(): {
+    writeNdef: (records: NdefRecord[]) => Promise<void>;
+    runWithTech: (tech: NfcTech | NfcTech[], fn: () => Promise<void>) => Promise<void>;
+};
 
-export { type NfcMode, type NfcState, index$1 as ndef, nfc, index$2 as nfcA, nfcService, index as nfcV };
+export { type NfcMode, NfcProvider, type NfcState, nfc, index$2 as nfcA, index as nfcNdef, nfcService, index$1 as nfcV, useNfc, useNfcContext, useNfcReader, useNfcState, useNfcTechnology };