Merge pull request #6 from superagents-lab/agent/add-plugin-sdk

Expose reusable Search1API SDK

Author: fatwang2

README.md

@@ -165,6 +165,27 @@ s1 update
 s1 update --force   # reinstall even if already on the latest version
 ```
 
+## SDK
+
+Plugin and integration packages can reuse the CLI's authentication, OAuth
+refresh, request handling, and typed Search1API methods instead of maintaining
+a second client:
+
+```ts
+import { search, crawl } from "search1api-cli/sdk";
+
+const results = await search("OpenCode plugins", {
+  maxResults: 5,
+  searchService: "github",
+});
+
+const page = await crawl("https://example.com");
+```
+
+The SDK uses `SEARCH1API_KEY`, the shared `s1 login` OAuth session, or the
+optional per-call `apiKey`. Every method also accepts an `AbortSignal` so host
+applications can cancel tool calls.
+
 ## Agent skill and plugins
 
 This repo includes an Agent Skill plus compatibility manifests for Claude Code,

package.json

@@ -1,8 +1,18 @@
 {
   "name": "search1api-cli",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "CLI tool for Search1API - web search, news, crawl, sitemap, and trending",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "import": "./dist/sdk.js"
+    }
+  },
   "bin": {
     "search1api": "./dist/index.js",
     "s1": "./dist/index.js"

src/api.ts

@@ -1,19 +1,34 @@
 import { fetchWithAuth } from "./auth.js";
 import { API_BASE } from "./config.js";
 
+export interface RequestOptions {
+  apiKey?: string;
+  signal?: AbortSignal;
+}
+
 export async function request<T>(
   path: string,
-  body: Record<string, unknown>
+  body: Record<string, unknown>,
+  options: RequestOptions = {}
 ): Promise<T> {
   const url = `${API_BASE}${path}`;
-
-  const res = await fetchWithAuth(url, {
+  const init: RequestInit = {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
     },
     body: JSON.stringify(body),
-  });
+    signal: options.signal,
+  };
+  const res = options.apiKey
+    ? await fetch(url, {
+        ...init,
+        headers: {
+          ...Object.fromEntries(new Headers(init.headers).entries()),
+          Authorization: `Bearer ${options.apiKey}`,
+        },
+      })
+    : await fetchWithAuth(url, init);
 
   if (!res.ok) {
     const text = await res.text();

src/commands/crawl.ts

@@ -1,22 +1,14 @@
 import { Command } from "commander";
-import { request } from "../api.js";
+import { crawl } from "../sdk.js";
 import { printCrawlResult, printJson } from "../output.js";
 
-interface CrawlResponse {
-  results: {
-    title: string;
-    link: string;
-    content: string;
-  };
-}
-
 export function registerCrawlCommand(program: Command): void {
   program
     .command("crawl <url>")
     .description("Extract content from a URL")
     .option("--json", "output raw JSON")
     .action(async (url: string, opts) => {
-      const data = await request<CrawlResponse>("/crawl", { url });
+      const data = await crawl(url);
 
       if (opts.json) {
         printJson(data);

src/commands/news.ts

@@ -1,18 +1,9 @@
 import { Command } from "commander";
-import { request } from "../api.js";
+import { news, type NewsOptions } from "../sdk.js";
 import { printSearchResults, printJson } from "../output.js";
 
 const NEWS_SERVICES = ["google", "bing", "duckduckgo", "yahoo", "hackernews"];
 
-interface NewsResponse {
-  results: Array<{
-    title: string;
-    link: string;
-    snippet: string;
-    content?: string;
-  }>;
-}
-
 export function registerNewsCommand(program: Command): void {
   program
     .command("news <query>")
@@ -25,17 +16,16 @@ export function registerNewsCommand(program: Command): void {
     .option("-t, --time <range>", "time range: day, month, year")
     .option("--json", "output raw JSON")
     .action(async (query: string, opts) => {
-      const body: Record<string, unknown> = {
-        query,
-        max_results: parseInt(opts.maxResults),
-        search_service: opts.service,
-        crawl_results: parseInt(opts.crawl),
+      const options: NewsOptions = {
+        maxResults: parseInt(opts.maxResults),
+        searchService: opts.service,
+        crawlResults: parseInt(opts.crawl),
       };
-      if (opts.include) body.include_sites = opts.include;
-      if (opts.exclude) body.exclude_sites = opts.exclude;
-      if (opts.time) body.time_range = opts.time;
+      if (opts.include) options.includeSites = opts.include;
+      if (opts.exclude) options.excludeSites = opts.exclude;
+      if (opts.time) options.timeRange = opts.time;
 
-      const data = await request<NewsResponse>("/news", body);
+      const data = await news(query, options);
 
       if (opts.json) {
         printJson(data);

src/commands/search.ts

@@ -1,21 +1,12 @@
 import { Command } from "commander";
-import { request } from "../api.js";
+import { search, type SearchOptions } from "../sdk.js";
 import { printSearchResults, printJson } from "../output.js";
 
 const SEARCH_SERVICES = [
   "google", "bing", "duckduckgo", "yahoo", "x", "reddit",
   "github", "youtube", "arxiv", "wechat", "bilibili", "imdb", "wikipedia",
 ];
 
-interface SearchResponse {
-  results: Array<{
-    title: string;
-    link: string;
-    snippet: string;
-    content?: string;
-  }>;
-}
-
 export function registerSearchCommand(program: Command): void {
   program
     .command("search <query>")
@@ -28,17 +19,16 @@ export function registerSearchCommand(program: Command): void {
     .option("-t, --time <range>", "time range: day, month, year")
     .option("--json", "output raw JSON")
     .action(async (query: string, opts) => {
-      const body: Record<string, unknown> = {
-        query,
-        max_results: parseInt(opts.maxResults),
-        search_service: opts.service,
-        crawl_results: parseInt(opts.crawl),
+      const options: SearchOptions = {
+        maxResults: parseInt(opts.maxResults),
+        searchService: opts.service,
+        crawlResults: parseInt(opts.crawl),
       };
-      if (opts.include) body.include_sites = opts.include;
-      if (opts.exclude) body.exclude_sites = opts.exclude;
-      if (opts.time) body.time_range = opts.time;
+      if (opts.include) options.includeSites = opts.include;
+      if (opts.exclude) options.excludeSites = opts.exclude;
+      if (opts.time) options.timeRange = opts.time;
 
-      const data = await request<SearchResponse>("/search", body);
+      const data = await search(query, options);
 
       if (opts.json) {
         printJson(data);

src/commands/sitemap.ts

@@ -1,18 +1,14 @@
 import { Command } from "commander";
-import { request } from "../api.js";
+import { sitemap } from "../sdk.js";
 import { printSitemapLinks, printJson } from "../output.js";
 
-interface SitemapResponse {
-  links: string[];
-}
-
 export function registerSitemapCommand(program: Command): void {
   program
     .command("sitemap <url>")
     .description("Get related links from a URL")
     .option("--json", "output raw JSON")
     .action(async (url: string, opts) => {
-      const data = await request<SitemapResponse>("/sitemap", { url });
+      const data = await sitemap(url);
 
       if (opts.json) {
         printJson(data);

src/commands/trending.ts

@@ -1,28 +1,20 @@
 import { Command } from "commander";
-import { request } from "../api.js";
+import { trending, type TrendingService } from "../sdk.js";
 import { printTrendingResults, printJson } from "../output.js";
 
 const TRENDING_SERVICES = ["github", "hackernews"];
 
-interface TrendingResponse {
-  results: Array<{
-    title: string;
-    url: string;
-    description?: string;
-  }>;
-}
-
 export function registerTrendingCommand(program: Command): void {
   program
     .command("trending <service>")
     .description(`Get trending topics (${TRENDING_SERVICES.join(", ")})`)
     .option("-n, --max-results <number>", "max results (1-50)", "10")
     .option("--json", "output raw JSON")
     .action(async (service: string, opts) => {
-      const data = await request<TrendingResponse>("/trending", {
-        search_service: service,
-        max_results: parseInt(opts.maxResults),
-      });
+      const data = await trending(
+        service as TrendingService,
+        { maxResults: parseInt(opts.maxResults) }
+      );
 
       if (opts.json) {
         printJson(data);