agentkit-cleanweb 0.0.0-stage → 1.0.0

package/src/provider.ts

@@ -0,0 +1,149 @@
+import {
+  CleanWebContentSchema,
+  CleanPdfSchema,
+  CleanYoutubeSchema,
+  OracleGroundingSchema,
+  ManageVaultSchema,
+} from "./types.js";
+import {
+  cleanWebContent,
+  cleanPdfResearch,
+  cleanYoutubeTranscript,
+  oracleGrounding,
+  manageX402Vault,
+  ActionInvocationOptions,
+} from "./actions.js";
+import { BASE_CHAIN_ID, BASE_SEPOLIA_CHAIN_ID } from "./constants.js";
+
+export interface CleanWebActionProviderConfig {
+  gatewayUrl?: string;
+  vaultKey?: string;
+  agentNonce?: string;
+  timeoutMs?: number;
+}
+
+export interface AgentKitAction<TArgs = unknown, TResult = unknown> {
+  name: string;
+  description: string;
+  schema: unknown;
+  invoke: (args: TArgs) => Promise<TResult>;
+}
+
+export interface NetworkLike {
+  chainId?: number | string;
+  networkId?: string;
+}
+
+export interface WalletProviderLike {
+  getAddress?: () => Promise<string> | string;
+  getNetwork?: () => Promise<NetworkLike> | NetworkLike;
+}
+
+/**
+ * Coinbase AgentKit CleanWeb Action Provider
+ * Drop-in Action Provider supplying 87% token-compressed web scraping,
+ * research PDF analysis, YouTube Gemini Flash intelligence, and Base EIP-712 oracle attestations.
+ */
+export class CleanWebActionProvider {
+  public readonly name = "cleanweb";
+  public readonly description =
+    "87% token noise reduction web scraper, academic PDF analyzer, YouTube Gemini video intelligence, and Base Mainnet EIP-712 signed oracle grounding.";
+
+  private config: CleanWebActionProviderConfig;
+
+  constructor(config: CleanWebActionProviderConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Verifies if the provider supports the given network.
+   * Native support for Base (8453), Base Sepolia (84532), and all EVM chains.
+   */
+  public supportsNetwork(network: NetworkLike): boolean {
+    if (!network || !network.chainId) return true;
+    const cid = Number(network.chainId);
+    return cid === BASE_CHAIN_ID || cid === BASE_SEPOLIA_CHAIN_ID || cid === 137 || cid === 42161;
+  }
+
+  /**
+   * Returns all 5 Action instances for Coinbase AgentKit runtime registration.
+   */
+  public getActions(walletProvider?: WalletProviderLike): AgentKitAction[] {
+    const opts: ActionInvocationOptions = {
+      gatewayUrl: this.config.gatewayUrl,
+      vaultKey: this.config.vaultKey,
+      agentNonce: this.config.agentNonce,
+      timeoutMs: this.config.timeoutMs,
+    };
+
+    return [
+      {
+        name: "cleanweb_clean_web_content",
+        description:
+          "Scrapes any target webpage URL and compresses noise/ads into 87% token-reduced clean Markdown for LLMs.",
+        schema: CleanWebContentSchema,
+        invoke: async (args) => {
+          const parsed = CleanWebContentSchema.parse(args);
+          return await cleanWebContent(parsed, opts);
+        },
+      },
+      {
+        name: "cleanweb_clean_pdf_research",
+        description:
+          "Extracts structured academic text, executive findings, and sections from online PDF whitepapers and reports.",
+        schema: CleanPdfSchema,
+        invoke: async (args) => {
+          const parsed = CleanPdfSchema.parse(args);
+          return await cleanPdfResearch(parsed, opts);
+        },
+      },
+      {
+        name: "cleanweb_clean_youtube_transcript",
+        description:
+          "Extracts high-precision subtitles and Google Gemini 3.8 Flash summary from YouTube videos without downloading media.",
+        schema: CleanYoutubeSchema,
+        invoke: async (args) => {
+          const parsed = CleanYoutubeSchema.parse(args);
+          return await cleanYoutubeTranscript(parsed, opts);
+        },
+      },
+      {
+        name: "cleanweb_oracle_grounding",
+        description:
+          "Discovers factual ground truth from the web and cryptographically signs an on-chain verifiable EIP-712 attestation for Base (8453).",
+        schema: OracleGroundingSchema,
+        invoke: async (args) => {
+          const parsed = OracleGroundingSchema.parse(args);
+          return await oracleGrounding(parsed, opts);
+        },
+      },
+      {
+        name: "cleanweb_manage_x402_vault",
+        description:
+          "Checks prefunded agent USDC vault balance, retrieves Base USDC deposit address, or inspects VIP pass entitlements.",
+        schema: ManageVaultSchema,
+        invoke: async (args) => {
+          const parsed = ManageVaultSchema.parse(args);
+          let addr = parsed.agentAddress;
+          if (!addr && walletProvider && typeof walletProvider.getAddress === "function") {
+            try {
+              addr = await walletProvider.getAddress();
+            } catch {
+              // fallback
+            }
+          }
+          return await manageX402Vault({ ...parsed, agentAddress: addr }, opts);
+        },
+      },
+    ];
+  }
+}
+
+/**
+ * Factory helper for clean instantiations
+ */
+export function cleanWebActionProvider(
+  config: CleanWebActionProviderConfig = {}
+): CleanWebActionProvider {
+  return new CleanWebActionProvider(config);
+}

package/src/types.ts

@@ -0,0 +1,168 @@
+import { z } from "zod";
+
+/**
+ * 1. Clean Web Content Schema
+ */
+export const CleanWebContentSchema = z
+  .object({
+    url: z.string().url().describe("The HTTP/HTTPS webpage URL to scrape and compress into clean Markdown"),
+    maxLength: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .default(50000)
+      .describe("Maximum character length for the returned markdown body (default 50,000)"),
+    includeLinks: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Whether to preserve relevant markdown links in the cleaned text"),
+  })
+  .strip()
+  .describe("Parameters for scraping and reducing webpage token noise by 87%");
+
+export type CleanWebContentParams = z.infer<typeof CleanWebContentSchema>;
+
+/**
+ * 2. Clean Research PDF Schema
+ */
+export const CleanPdfSchema = z
+  .object({
+    pdfUrl: z.string().url().describe("The direct URL of the PDF whitepaper, financial filing, or arXiv research report"),
+    maxPages: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .default(50)
+      .describe("Maximum number of pages to parse (1-100, default 50)"),
+  })
+  .strip()
+  .describe("Parameters for extracting clean academic and financial text from online PDF whitepapers");
+
+export type CleanPdfParams = z.infer<typeof CleanPdfSchema>;
+
+/**
+ * 3. Clean YouTube Transcript Schema
+ */
+export const CleanYoutubeSchema = z
+  .object({
+    videoUrl: z.string().describe("YouTube video URL or 11-character video ID"),
+    includeSummary: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("Whether to generate Gemini 3.8 Flash bullet-point executive summary"),
+  })
+  .strip()
+  .describe("Parameters for extracting timestamped subtitles and AI summaries from YouTube videos");
+
+export type CleanYoutubeParams = z.infer<typeof CleanYoutubeSchema>;
+
+/**
+ * 4. Oracle Grounding & EIP-712 Attestation Schema
+ */
+export const OracleGroundingSchema = z
+  .object({
+    query: z.string().min(3).describe("The factual proposition or topic to verify (e.g. 'Base TVL surpasses 4B' or 'CRMA compliance')"),
+    targetUrl: z
+      .string()
+      .url()
+      .optional()
+      .describe("Optional target webpage URL to ground the facts against"),
+    chainId: z
+      .number()
+      .int()
+      .optional()
+      .default(8453)
+      .describe("Target blockchain network ID for EIP-712 signature (Base Mainnet: 8453, Base Sepolia: 84532)"),
+  })
+  .strip()
+  .describe("Parameters for web ground-truth discovery with on-chain verifiable EIP-712 cryptographic attestation");
+
+export type OracleGroundingParams = z.infer<typeof OracleGroundingSchema>;
+
+/**
+ * 5. Manage x402 Agent Vault Schema
+ */
+export const ManageVaultSchema = z
+  .object({
+    action: z
+      .enum(["balance", "deposit_info", "pass_status"])
+      .describe("Action to perform: 'balance' (check prefunded USDC balance), 'deposit_info' (get deposit address & chain parameters), or 'pass_status' (check agent VIP pass)"),
+    agentAddress: z
+      .string()
+      .regex(/^0x[a-fA-F0-9]{40}$/, "Must be a valid EVM address (0x...)")
+      .optional()
+      .describe("The agent's EVM wallet address on Base Mainnet"),
+  })
+  .strip()
+  .describe("Parameters for managing gasless sub-millisecond x402 USDC micropayment session vaults");
+
+export type ManageVaultParams = z.infer<typeof ManageVaultSchema>;
+
+/**
+ * CleanWeb Universal Action Result Interfaces
+ */
+export interface CleanWebContentResult {
+  success: boolean;
+  url: string;
+  title: string;
+  cleanMarkdown: string;
+  tokenReductionRate: string;
+  sourceTokensEstimate: number;
+  compressedTokensEstimate: number;
+  latencyMs: number;
+}
+
+export interface CleanPdfResult {
+  success: boolean;
+  pdfUrl: string;
+  title: string;
+  pageCount: number;
+  wordCount: number;
+  text: string;
+  latencyMs: number;
+}
+
+export interface CleanYoutubeResult {
+  success: boolean;
+  videoId: string;
+  title: string;
+  channel: string;
+  summary?: string;
+  transcriptSample: string;
+  fullTranscriptLength: number;
+  latencyMs: number;
+}
+
+export interface OracleGroundingResult {
+  success: boolean;
+  query: string;
+  groundedFacts: string[];
+  summary: string;
+  verdict: "VERIFIED" | "CONTRADICTED" | "UNVERIFIED";
+  confidence: number;
+  attestation?: {
+    chainId: number;
+    signerAddress: string;
+    merkleRoot: string;
+    signature: string;
+    eip712Domain: Record<string, unknown>;
+  };
+  latencyMs: number;
+}
+
+export interface ManageVaultResult {
+  success: boolean;
+  action: string;
+  agentAddress?: string;
+  balanceUsdc?: number;
+  totalConsumedUsdc?: number;
+  depositAddress?: string;
+  supportedChains?: string[];
+  passTier?: string;
+  passActive?: boolean;
+}