npm package: @sherrylinks/slinks
Description: [![npm version](https://badge.fury.io/js/%40sherrylinks%2Fslinks.svg)](https://badge.fury.io/js/%40sherrylinks%2Fslinks)
Author: Sherry Labs
Latest version: 0.11.33-beta

# @sherrylinks/slinks

[![npm version](https://badge.fury.io/js/%40sherrylinks%2Fslinks.svg)](https://badge.fury.io/js/%40sherrylinks%2Fslinks)

React components, hooks, adapters, and utilities for integrating SherryLinks Triggers into web applications and browser extensions.

## Overview

Slinks provides the tools to easily embed SherryLinks functionality. It allows you to:

- Render Triggers based on metadata using the `Trigger`.
- Integrate with EVM wallets using Wagmi via the `useWagmiAdapter`.
- Use a dedicated adapter (`SherryExtensionAdapter`) for browser extension environments.
- Detect and process SherryLinks URLs found on web pages.
- Observe platforms like Twitter/X to automatically enhance links with Trigger previews or buttons (`twitterObserverEVM`).

## Installation

```bash
npm install @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom
# or
yarn add @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom
# or
pnpm add @sherrylinks/slinks @sherrylinks/slinks-core wagmi viem @tanstack/react-query react react-dom
```

**Note:** `@sherrylinks/slinks-core`, `react`, `react-dom`, `wagmi`, `viem`, and `@tanstack/react-query` are peer dependencies.

## Basic Usage (React App)

1.  **Import CSS:** Import the necessary styles in your main application file.

    ```typescript
    // e.g., in src/main.tsx or src/App.tsx
    import '@sherrylinks/slinks/index.css';
    ```

2.  **Set up Wagmi:** Ensure your application is wrapped with `WagmiProvider` and `QueryClientProvider`.

3.  **Use the Adapter and Component:**

    ```jsx
    import { Trigger, useWagmiAdapter } from '@sherrylinks/slinks';
    import { createMetadata, ValidatedMetadata } from '@sherrylinks/sdk'; // Assuming SDK provides validation
    import '@sherrylinks/slinks/index.css'; // Don't forget the CSS!

    // Your Trigger Metadata (fetch or define it)
    const rawMetadata = { /* ... your metadata object ... */ };

    function MyComponent() {
      const adapter = useWagmiAdapter(); // Hook to get wallet interaction functions

      // Validate metadata (example using a hypothetical SDK function)
      let validatedMetadata: ValidatedMetadata | undefined;
      try {
        validatedMetadata = createMetadata(rawMetadata);
      } catch (error) {
        console.error("Invalid Metadata:", error);
        // Handle invalid metadata case
      }

      if (!validatedMetadata) {
        return <div>Error loading Trigger metadata.</div>;
      }

      return (
        <div>
          <h1>My App with Slinks</h1>
          <Trigger
            metadata={validatedMetadata}
            adapter={adapter}
            // securityState can be 'trusted', 'unknown', 'malicious' based on directory lookup
            securityState="trusted"
          />
        </div>
      );
    }

    export default MyComponent;
    ```

## Key Features & Exports

- **Components:**
  - `Trigger`: Renders the main Trigger UI based on metadata.
  - `WalletButton`: A simple button component for wallet connection flows.
  - `SlinksPreview`: (If exported) A component to show a preview based on a URL.
- **Hooks:**
  - `useWagmiAdapter`: Provides a `SherryAdapter` instance integrated with Wagmi for wallet interactions (connect, sign, send transaction, etc.).
- **Adapters:**
  - `SherryAdapter`: Interface defining the required wallet interaction methods.
  - `SherryExtensionAdapter`: An adapter specifically designed for use within browser extensions, communicating via `chrome.runtime.sendMessage`.
- **Utilities:**
  - `detectSherryUrl`: Checks if a URL is potentially a SherryLink.
  - `fetchSlinksMetadata`: Fetches metadata from a given URL.
  - `sanitizeText`, `processUrlWithAction`: URL processing helpers.
- **Extension Integration:**
  - `setupTwitterObserverEVM`: Initializes an observer for Twitter/X to find and enhance links.
  - `handleNewNode`: Function called by the observer when a potential link node is found.

## Browser Environment & Polyfills

This library aims to work in modern browser environments, including browser extensions. It uses `tsup` for bundling and includes necessary polyfills (like `Buffer`) for browser compatibility. See `CONTRIBUTING.md` for more details on the build process and polyfill strategy if you encounter issues.

## License

MIT