@adland/react 0.1.0

package/.eslintrc.js

@@ -0,0 +1,34 @@
+const { resolve } = require("node:path");
+
+const project = resolve(process.cwd(), "tsconfig.json");
+
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  extends: ["eslint:recommended", "turbo"],
+  plugins: ["only-warn"],
+  globals: {
+    React: true,
+    JSX: true,
+  },
+  env: {
+    node: true,
+  },
+  settings: {
+    "import/resolver": {
+      typescript: {
+        project,
+      },
+    },
+  },
+  ignorePatterns: [
+    // Ignore dotfiles
+    ".*.js",
+    "node_modules/",
+    "dist/",
+  ],
+  overrides: [
+    {
+      files: ["*.js?(x)", "*.ts?(x)"],
+    },
+  ],
+};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dan5py (git@dan5py.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @adland/react
+
+A simple React component library for tracking ad views and clicks with built-in support for Farcaster MiniApp SDK & AdLand ads.
+
+## Installation
+
+```bash
+npm install @adland/react
+# or
+pnpm add @adland/react
+# or
+yarn add @adland/react
+```
+
+## Usage
+
+```tsx
+import { Ad } from "@adland/react";
+
+function App() {
+  return (
+    <Ad owner="0x123..." adId="ad-1">
+      <img src="ad.jpg" alt="Advertisement" />
+    </Ad>
+  );
+}
+```
+
+## Features
+
+- 🎯 **Simple API**: Minimal configuration required
+- 📊 **View & Click Tracking**: Automatic view tracking with IntersectionObserver and click tracking
+- 🔐 **Farcaster SDK Integration**: Built-in support for Farcaster MiniApp SDK's `quickAuth` for authenticated requests
+- 🛡️ **Session-based Deduplication**: Prevents duplicate view tracking within the same browser session
+- 📦 **TypeScript Support**: Full TypeScript definitions included
+
+## API
+
+### `<Ad />` Component
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `owner` | `string` | **required** | The owner/creator address of the ad |
+| `adId` | `string` | **required** | Unique identifier for the ad |
+| `children` | `ReactNode` | **required** | The content to display in the ad |
+| `trackEndpoint` | `string` | `"/api/analytics/track"` | Custom endpoint for tracking requests |
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@adland/react",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@farcaster/miniapp-sdk": "0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^18.3.1",
+    "@typescript-eslint/eslint-plugin": "^7.13.1",
+    "@typescript-eslint/parser": "^7.13.1",
+    "@vercel/style-guide": "^6.0.0",
+    "eslint": "^8",
+    "eslint-config-turbo": "2.0.6",
+    "eslint-plugin-only-warn": "^1.1.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test:dev": "pnpm --filter @adland/react-dev dev",
+    "dev:app": "cd dev && pnpm dev",
+    "lint": "eslint ."
+  }
+}

package/src/components/Ad.tsx

@@ -0,0 +1,96 @@
+import { useEffect, useRef, useCallback } from "react";
+import { sendTrackRequest } from "../utils/sdk";
+
+export interface AdProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The owner/creator of the ad
+   */
+  owner: string;
+  /**
+   * Unique identifier for the ad
+   */
+  adId: string;
+  /**
+   * The content to display in the ad
+   */
+  children: React.ReactNode;
+  /**
+   * Custom endpoint for tracking requests (default: "/api/analytics/track")
+   */
+  trackEndpoint?: string;
+}
+
+/**
+ * Simple Ad component with built-in view and click tracking
+ * Uses Farcaster MiniApp SDK for authenticated tracking requests
+ *
+ * @example
+ * ```tsx
+ * <Ad owner="0x123..." adId="ad-1">
+ *   <img src="ad-image.jpg" alt="Advertisement" />
+ * </Ad>
+ * ```
+ */
+export function Ad({
+  owner,
+  adId,
+  children,
+  trackEndpoint = "/api/analytics/track",
+  ...props
+}: AdProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  const send = useCallback(
+    (type: "view" | "click") => {
+      sendTrackRequest(trackEndpoint, {
+        type,
+        adId,
+        adOwner: owner,
+      }).catch((error: unknown) => {
+        console.error(`[@adland/react] Failed to track ${type}:`, error);
+      });
+    },
+    [adId, owner, trackEndpoint],
+  );
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const key = `ad_view_${adId}`;
+
+    const obs = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0];
+        if (!entry?.isIntersecting) return;
+
+        const already = sessionStorage.getItem(key);
+        if (already) {
+          obs.unobserve(el);
+          return;
+        }
+
+        sessionStorage.setItem(key, "1");
+        send("view");
+        obs.unobserve(el);
+      },
+      {
+        threshold: 0.15, // more forgiving
+      },
+    );
+
+    obs.observe(el);
+    return () => obs.disconnect();
+  }, [adId, send]);
+
+  // CLICK tracking
+  const onClick = useCallback(() => {
+    send("click");
+  }, [send]);
+
+  return (
+    <div ref={ref} onClick={onClick} {...props}>
+      {children}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Main exports
+export { Ad } from "./components/Ad";
+export type { AdProps } from "./components/Ad";
+
+// Utility exports
+export {
+  isSdkReady,
+  sendTrackRequest,
+  checkSdkActionsReady,
+} from "./utils/sdk";

package/src/utils/sdk.ts

@@ -0,0 +1,101 @@
+import { sdk } from "@farcaster/miniapp-sdk";
+
+/**
+ * Checks if the SDK is ready and initialized
+ */
+export function isSdkReady(): boolean {
+  try {
+    // Check if SDK exists
+    if (!sdk) {
+      console.error("[@adland/react] SDK is not available");
+      return false;
+    }
+
+    // Check if quickAuth is available
+    if (!sdk.quickAuth) {
+      console.error(
+        "[@adland/react] SDK quickAuth is not available. Make sure the SDK is properly initialized.",
+      );
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    console.error("[@adland/react] Error checking SDK readiness:", error);
+    return false;
+  }
+}
+
+/**
+ * Sends a tracking request using the SDK's quickAuth
+ */
+export async function sendTrackRequest(
+  url: string,
+  data: {
+    type: "view" | "click";
+    adOwner: string;
+    adId: string;
+  },
+): Promise<Response> {
+  if (!isSdkReady()) {
+    console.error(
+      "[@adland/react] SDK is not ready. Cannot send tracking request.",
+    );
+    return Promise.reject(
+      new Error(
+        "[@adland/react] SDK is not ready. Cannot send tracking request.",
+      ),
+    );
+  }
+
+  try {
+    if (!sdk.quickAuth) {
+      throw new Error("[@adland/react] SDK quickAuth is not available");
+    }
+
+    return await sdk.quickAuth.fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-auth-type": "farcaster",
+      },
+      body: JSON.stringify(data),
+    });
+  } catch (error) {
+    console.error("[@adland/react] Error sending track request:", error);
+    throw error;
+  }
+}
+
+/**
+ * Checks if SDK actions are ready
+ */
+export async function checkSdkActionsReady(): Promise<boolean> {
+  try {
+    if (!sdk) {
+      console.error("[@adland/react] SDK is not available");
+      return false;
+    }
+
+    if (!sdk.actions) {
+      console.error("[@adland/react] SDK actions are not available");
+      return false;
+    }
+
+    // Check if ready() function exists
+    if (typeof sdk.actions.ready !== "function") {
+      console.error(
+        "[@adland/react] SDK actions.ready() is not available. Make sure the SDK is properly initialized.",
+      );
+      return false;
+    }
+
+    return true;
+  } catch (error) {
+    console.error(
+      "[@adland/react] Error checking SDK actions readiness:",
+      error,
+    );
+    return false;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["es2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@adland/react/*": ["./src/*"]
+    },
+    "outDir": "./dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "dev"]
+}
+

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  external: ["react", "react-dom", "@farcaster/miniapp-sdk"],
+});