@sherrylinks/slinks

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

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.

   // 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:

   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