@orb-labs/orby-core-mini-react-native/README.md

React Native library for injecting Orby into dapps via WebView

# React Native Data Injection - Library for injecting Orby into Dapps

A React Native library for injecting Orby functionality into dapps via WebView, enabling seamless integration of Orby virtual nodes.

## Installation

```bash
npm install @orb-labs/orby-core-mini-react-native
```

or

```bash
yarn add @orb-labs/orby-core-mini-react-native
```

## File Structure

```
orbykit/orby-injector-for-dapps-react-native/
├── src/                                    # Source code
│   ├── OrbyInjectorForDapps.ts             # Core injector class
│   ├── orbyInjectionScriptForDapps.ts      # Injected script for WebView
│   ├── types.ts                            # Type definitions
│   └── index.ts                            # Module entry point
├── dist/                                   # Built distribution files
├── .gitignore                              # Git ignore rules
├── CHANGELOG.md                            # Changelog
├── LICENSE                                 # License
├── package.json                            # Package config
├── tsconfig.json                           # TypeScript config
└── README.md                               # Documentation
```

## Example Usage

1. At the root of your react native app, import and configure the library

```typescript
import { configureOrbyForDapps } from "@orb-labs/orby-core-mini-react-native";
configureOrbyForDapps("https://your-orby-rpc-url.com");
```

2. On startup, iterate through a list of all connected apps and call `bulkResetConnectedAppSessions` via hook or directly.

```typescript
import {
  bulkResetConnectedAppSessions,
  updateConnectedAppSession,
  removeConnectedAppSession,
} from "@orb-labs/orby-core-mini-react-native";

function MyComponent() {
  const promises = activeSessions?.map(
    async ({ host, address }: { host: string; address: `0x${string}` }) => {
      const account = new Account(
        validateAndFormatAddress(address),
        AccountType.EOA,
        VMType.EVM,
        undefined
      );

      const accountCluster = await baseMainnetClient.createAccountCluster([
        account,
      ]);

      return {
        appUrl: host,
        activeAccountClusterId: accountCluster?.accountClusterId,
      };
    }
  );

  const sessions = await Promise.all(promises);
  bulkResetConnectedAppSessions(sessions);

  // ... rest of component
}
```

3. Whenever an app is connected to the wallet, call the `updateConnectedAppSession` function, e.g.

```typescript
updateConnectedAppSession({
  appUrl: host,
  activeAccountClusterId: accountCluster?.accountClusterId,
});
```

4. Whenever an app is disconnected from the wallet, call the `removeConnectedAppSession` function, e.g.

```typescript
removeConnectedAppSession({
  appUrl: host,
});
```

5. Inject orby into the dapp browser webview using the convenient `injectOrbyIntoWebView` function:

```javascript
import React, { useRef } from "react";
import { WebView } from "react-native-webview";
import { injectOrbyIntoWebView } from "@orb-labs/orby-core-mini-react-native";

function WebViewComponent() {
  const webViewRef = useRef < WebView > null;

  // Get WebView props with Orby injection
  const webViewProps = injectOrbyIntoWebView(
    webViewRef,
    (event) => {
      // Your custom message handler
      console.log("Custom message:", event);
    },
    [
      // Additional scripts to inject (optional)
      'console.log("Additional script injected");',
    ]
  );

  return <WebView source={{ uri: tabUrl }} {...webViewProps} />;
}
```

Alternatively, you can manually configure the WebView:

```javascript
import React, { useEffect } from "react";
import { WebView } from "react-native-webview";
import {
  handleOrbyMessage,
  getOrbyInjectionScriptForDapps,
} from "@orb-labs/orby-core-mini-react-native";

function WebViewComponent() {
  const webViewRef = useRef < WebView > null;

  // Use the hook to get the injection script for the appUrl
  const orbyInjectionScriptForDapps = getOrbyInjectionScriptForDapps();

  return (
    <WebView
      ref={webViewRef}
      source={{ uri: tabUrl }}
      onMessage={(event) => {
        handleOrbyMessage(event, webViewRef);
        otherOnMessageHandler(event);
      }}
      injectedJavaScriptBeforeContentLoaded={`
          ${orbyInjectionScriptForDapps}
          ${otherInjectedJSContent}
        `}
    />
  );
}
```

## API Reference

### Core Functions

#### `configureOrbyForDapps(baseOrbyRpcUrl: string, requestTimeoutLength?: number)`

Configure the Orby injector for dapps with the base Orby RPC URL.

#### `getOrbyInjectionScriptForDapps()`

Fetches the injection script for dapps

#### `addConnectedAppSession(appSession: AppSession)`

Add a new connected app session.

#### `updateConnectedAppSession(appSession: AppSession)`

Update an existing connected app session.

#### `removeConnectedAppSession(appUrl: string)`

Remove a connected app session.

#### `bulkResetConnectedAppSessions(appSessions: AppSession[])`

Bulk reset connected app sessions.

#### `handleOrbyMessage(event: any, webViewRef: RefObject<any>)`

Handles messages from a webview meant for Orby virtual nodes.

#### `injectOrbyIntoWebView(webViewRef: RefObject<any>, onMessage?: (event: any) => void, additionalScripts?: string[])`

Convenient function to inject Orby functionality into a React Native WebView. Returns WebView props that include:

- `ref`: The WebView reference
- `injectedJavaScriptBeforeContentLoaded`: Combined Orby script with additional scripts
- `onMessage`: Message handler that processes Orby messages and calls the optional custom handler

---

For more details, see the source code and examples in the repository.

## Development

### Building the Package

```bash
yarn install
yarn build
```

This will compile the TypeScript source files into JavaScript and generate type definitions in the `dist/` folder.

### Local Development

To test the package locally:

```bash
yarn link
cd /path/to/your/react-native/project
yarn link
```

Remember to unlink when done:

```bash
yarn unlink @orb-labs/orby-core-mini-react-native
```

## Publishing to npm

1. Bump the package.json version

```
// package.json
version: "0.0.8-alpha" // change to "0.0.9-alpha"
```

2. Run yarn at the root of orby folder

```
yarn
```

3. Build

```
yarn workspace @orb-labs/orby-core-mini-react-native build
```

4. Login to npm

```
yarn npm login
```

4. Publish @orb-labs/orby-core-mini-react-native to npm

```
yarn workspace @orb-labs/orby-core-mini-react-native npm publish --access public
```