Feat: Core SDK improvements necessary for token gated mini apps

.changeset/few-dolphins-know.md

@@ -0,0 +1,15 @@
+---
+"@mod-protocol/react-ui-shadcn": minor
+"web": minor
+"@mod-protocol/react": minor
+"@mod-protocol/core": minor
+"@miniapps/zora-nft-minter": patch
+"@miniapps/giphy-picker": patch
+"@mod-protocol/react-editor": patch
+"@miniapps/nft-minter": patch
+"@miniapps/chatgpt": patch
+"api": patch
+"docs": patch
+---
+
+Adds the combobox, select, textarea mod elements. Adds `Model Definitions` to Manifests. Adds the `ethPersonalSign` action. Adds `json-ld` indexing to metadata. Adds a `loadingLabel` prop to buttons

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.disableAutomaticTypeAcquisition": true
+}

docs/pages/create-mini-app/reference.mdx

@@ -27,10 +27,21 @@ type ModManifest = {
   custodyAddress: string;
   /** A valid url pointing to an image file, it should be a square */
   logo: string;
+  /** should be the same as the package version */
   version: string;
+  /**
+   * A Map of unique ids to json-schema.org definitions. Used to define a new standard data model for use in this or other Mini-apps.
+   * Most useful when used in conjunction with json-ld that utilizes these data models
+   */
+  modelDefinitions?: Record<string, JSONSchema7>;
+  /** Interface this Mini-app exposes, if any, for Content Creation */
   creationEntrypoints?: ModElement[];
+  /** Interface this Mini-app exposes, if any, for Content Rendering */
   contentEntrypoints?: ModConditionalElement[];
+  /** A definition map of reusable elements, using their id as the key */
   elements?: Record<string, ModElement[]>;
+  /** Permissions requested by the Mini-app */
+  permissions?: Array<"user.wallet.address" | "web3.eth.personal.sign">;
 };
 ```
 
@@ -72,11 +83,38 @@ export type ModElement =
       elements?: string | ElementOrConditionalFlow[];
       onload?: ModEvent;
     }
+  | {
+      ref?: string;
+      type: "select";
+      options: Array<{ label: string; value: any }>;
+      placeholder?: string;
+      isClearable?: boolean;
+      onchange?: ModEvent;
+      onsubmit?: ModEvent;
+    }
+  | {
+      type: "combobox";
+      ref?: string;
+      isClearable?: boolean;
+      placeholder?: string;
+      optionsRef?: string;
+      valueRef?: string;
+      onload?: ModEvent;
+      onpick?: ModEvent;
+      onchange?: ModEvent;
+    }
+  | {
+      ref?: string;
+      type: "textarea";
+      placeholder?: string;
+      onchange?: ModEvent;
+      onsubmit?: ModEvent;
+    }
   | {
       ref?: string;
       type: "input";
       placeholder?: string;
-      clearable?: boolean;
+      isClearable?: boolean;
       onchange?: ModEvent;
       onsubmit?: ModEvent;
     }

docs/pages/metadata-cache.mdx

@@ -6,7 +6,9 @@ The metadata cache can be used to retrieve Open Graph metadata for embeds in cas
 
 It makes use of the [Metadata Indexer](https://github.com/mod-protocol/mod/tree/main/examples/metadata-indexer), an open source and self-hostable service that indexes casts, embeds, and their metadata.
 
-## Usage
+We are hosting a free instance of the Metadata indexer that can be reached at https://api.modprotocol.org/api/cast-embeds-metadata
+
+## `/api/cast-embeds-metadata`
 
 Fetching metadata from the cache is as simple as making a POST request to the following endpoint with a list of cast hashes in the body.
 
@@ -58,8 +60,8 @@ This will return a JSON object with the following structure:
       "metadata": {
         "title": "Example Title",
         "description": "Example Description",
-        "image": { 
-          url: "https://example.com/image.png"
+        "image": {
+          "url": "https://example.com/image.png"
         }
         // ...
       }
@@ -73,8 +75,86 @@ Returned metadata objects conform to the `UrlMetadata` type. This can then be us
 ```typescript
 import { UrlMetadata } from "@mod-protocol/core";
 
-cast.embeds.map((embed, index) => {
-  const embedData: UrlMetadata = metadataResponse[cast.hash][index]
-  return <RenderEmbed embed={embedData} />
-})
-```
+cast.embeds.map((embed) => {
+  const metadata: UrlMetadata = metadataResponse[cast.hash][embed.url];
+  return <RenderEmbed metadata={metadata} />;
+});
+```
+
+## `/api/cast-embeds-metadata/by-url`
+
+Fetching metadata from the cache by url is as simple as making a POST request to the following endpoint with a list of urls in the body.
+
+<Tabs items={["Shell", "JS (fetch)", "Node.js v18+ (fetch)"]}>
+  <Tabs.Tab>
+    ```bash
+    curl --request POST \
+    --url https://api.modprotocol.org/api/cast-embeds-metadata/by-url \
+    --header 'Content-Type: application/json' \
+    --data '["https://google.com","https://twitter.com"]'
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```js
+    const request = await fetch("https://api.modprotocol.org/api/cast-embeds-metadata/by-url", {
+      body: JSON.stringify(["https://google.com","https://twitter.com"]),
+      method: 'POST',
+      headers: {
+        'Content-Type': "application/json"
+      }
+    });
+    const metadata = await request.json();
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```js
+    const request = await fetch("https://api.modprotocol.org/api/cast-embeds-metadata/by-url", {
+      body: JSON.stringify(["https://google.com","https://twitter.com"]),
+      method: 'POST',
+      headers: {
+        'Content-Type': "application/json"
+      }
+    });
+    const metadata = await request.json();
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+This will return a JSON object with the following structure:
+
+```json
+{
+  "https://google.com": {
+    "image": {
+      "url": "https://www.google.com/images/branding/googleg/1x/googleg_standard_color_128dp.png",
+      "height": 128,
+      "width": 128
+    },
+    "description": "Celebrate Native American Heritage Month with Google",
+    "title": "Google",
+    "publisher": "google.com",
+    "logo": {
+      "url": "https://www.google.com/favicon.ico"
+    },
+    "mimeType": "text/html; charset=UTF-8"
+  },
+  "https://twitter.com": {
+    "description": "From breaking news and entertainment to sports and politics, get the full story with all the live commentary.",
+    "title": "@ on Twitter",
+    "publisher": "Twitter",
+    "logo": {
+      "url": "https://abs.twimg.com/favicons/twitter.3.ico"
+    },
+    "mimeType": "text/html; charset=utf-8"
+  }
+}
+```
+
+Returned metadata objects conform to the `UrlMetadata` type. This can then be used to render embeds in a cast.
+
+```typescript
+import { UrlMetadata } from "@mod-protocol/core";
+
+const metadata: UrlMetadata = metadataResponse[embed.url];
+return <RenderEmbed metadata={metadata} />;
+```

examples/api/.env.example

@@ -6,4 +6,7 @@ MICROLINK_API_KEY="REQUIRED"
 OPENSEA_API_KEY="REQUIRED"
 CHATGPT_API_SECRET="REQUIRED"
 NEYNAR_API_SECRET="REQUIRED"
-LIVEPEER_API_SECRET="REQUIRED"
+LIVEPEER_API_SECRET="REQUIRED"
+DATABASE_URL="REQUIRED"
+# Must be funded with MATIC on Mumbai for Irys https://mumbaifaucet.com/
+PRIVATE_KEY="REQUIRED"

examples/api/package.json

@@ -10,16 +10,22 @@
     "lint": "next lint"
   },
   "dependencies": {
+    "@irys/sdk": "^0.0.4",
+    "@lit-protocol/lit-node-client": "^3.0.24",
+    "@lit-protocol/types": "^2.2.61",
     "@mod-protocol/core": "^0.0.2",
     "@reservoir0x/reservoir-sdk": "^1.8.4",
     "@vercel/postgres-kysely": "^0.6.0",
     "chatgpt": "^5.2.5",
+    "cheerio": "^1.0.0-rc.12",
     "kysely": "^0.26.3",
     "next": "^13.5.6",
     "open-graph-scraper": "^6.3.2",
     "pg": "^8.11.3",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react-dom": "^18.2.0",
+    "siwe": "^1.1.6",
+    "uint8arrays": "^3.0.0"
   },
   "devDependencies": {
     "@types/node": "^17.0.12",
@@ -35,4 +41,4 @@
     "tsconfig": "*",
     "typescript": "^5.2.2"
   }
-}
+}

examples/api/src/app/api/cast-embeds-metadata/by-url/route.ts

@@ -0,0 +1,130 @@
+export const dynamic = "force-dynamic";
+
+import { NextResponse, NextRequest } from "next/server";
+import { NFTMetadata, UrlMetadata } from "@mod-protocol/core";
+import { db } from "../lib/db";
+import { chainById } from "../lib/chain-index";
+
+export async function POST(request: NextRequest) {
+  try {
+    const urls = await request.json();
+
+    // todo: consider normalizing urls here? currently clients are responsible for doing this.
+
+    // Fetch metadata for each url
+    const metadata = await db
+      .selectFrom("url_metadata")
+      .where("url_metadata.url", "in", urls)
+      .leftJoin(
+        "nft_metadata",
+        "nft_metadata.id",
+        "url_metadata.nft_metadata_id"
+      )
+      .leftJoin(
+        "nft_collections",
+        "url_metadata.nft_collection_id",
+        "nft_collections.id"
+      )
+      .select([
+        /* Select all columns with aliases to prevent collisions */
+
+        // URL metadata
+        "url_metadata.image_url as url_image_url",
+        "url_metadata.image_height as url_image_height",
+        "url_metadata.image_width as url_image_width",
+        "url_metadata.alt as url_alt",
+        "url_metadata.url as url_url",
+        "url_metadata.description as url_description",
+        "url_metadata.title as url_title",
+        "url_metadata.publisher as url_publisher",
+        "url_metadata.logo_url as url_logo_url",
+        "url_metadata.mime_type as url_mime_type",
+        "url_metadata.nft_collection_id as nft_collection_id",
+        "url_metadata.nft_metadata_id as nft_metadata_id",
+
+        // NFT Collection metadata
+        "nft_collections.creator_address as collection_creator_address",
+        "nft_collections.description as collection_description",
+        "nft_collections.image_url as collection_image_url",
+        "nft_collections.item_count as collection_item_count",
+        "nft_collections.mint_url as collection_mint_url",
+        "nft_collections.name as collection_name",
+        "nft_collections.open_sea_url as collection_open_sea_url",
+        "nft_collections.owner_count as collection_owner_count",
+
+        // NFT metadata
+        "nft_metadata.token_id as nft_token_id",
+        "nft_metadata.media_url as nft_media_url",
+      ])
+      .execute();
+
+    const rowsFormatted = metadata.map((row) => {
+      let nftMetadata: NFTMetadata | undefined;
+
+      if (row.nft_collection_id) {
+        const [, , prefixAndChainId, prefixAndContractAddress, tokenId] =
+          row.nft_collection_id.split("/");
+
+        const [, chainId] = prefixAndChainId.split(":");
+        const [, contractAddress] = prefixAndContractAddress.split(":");
+
+        const chain = chainById[chainId];
+
+        nftMetadata = {
+          mediaUrl: row.nft_media_url || undefined,
+          tokenId: row.nft_token_id || undefined,
+          collection: {
+            chain: chain.network,
+            contractAddress,
+            creatorAddress: row.collection_creator_address,
+            description: row.collection_description,
+            id: row.nft_collection_id,
+            imageUrl: row.collection_image_url,
+            itemCount: row.collection_item_count,
+            mintUrl: row.collection_mint_url,
+            name: row.collection_name,
+            openSeaUrl: row.collection_open_sea_url || undefined,
+            ownerCount: row.collection_owner_count || undefined,
+            creator: undefined, // TODO: Look up farcaster user by FID
+          },
+        };
+      }
+
+      const urlMetadata: UrlMetadata = {
+        image: row.url_image_url
+          ? {
+              url: row.url_image_url,
+              height: row.url_image_height || undefined,
+              width: row.url_image_width || undefined,
+            }
+          : undefined,
+        alt: row.url_alt || undefined,
+        description: row.url_description || undefined,
+        title: row.url_title || undefined,
+        publisher: row.url_publisher || undefined,
+        logo: row.url_logo_url ? { url: row.url_logo_url } : undefined,
+        mimeType: row.url_mime_type || undefined,
+        nft: nftMetadata,
+      };
+
+      return {
+        url: row.url_url,
+        urlMetadata,
+      };
+    });
+
+    const metadataByUrl: {
+      [key: string]: UrlMetadata;
+    } = rowsFormatted.reduce((acc, cur) => {
+      return {
+        ...acc,
+        [cur.url]: cur.urlMetadata,
+      };
+    }, {});
+
+    return NextResponse.json(metadataByUrl);
+  } catch (err) {
+    console.error(err);
+    return NextResponse.json({ message: err.message }, { status: err.status });
+  }
+}