@surfaceapi/ai-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Canada Site Ops
+
+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.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @surfaceapi/ai-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Surface is the link-safety layer between an AI agent and the open web.** Before your agent opens a link someone pasted, Surface checks it: it unwraps short links (t.co, bit.ly, lnkd.in, youtu.be), follows the redirects, and answers **fetch** or **skip**, along with where the link really goes. It never downloads the page for you, so it's fast and cheap.
+
+This package gives Vercel AI SDK agents that check as one ready-made tool: `surface_preflight`.
+
+```bash
+npm install @surfaceapi/ai-sdk ai zod
+```
+
+```js
+import { generateText } from "ai";
+import { surface_preflight } from "@surfaceapi/ai-sdk";
+
+const { text } = await generateText({
+  model,
+  tools: { surface_preflight },
+  prompt: "Summarize https://bit.ly/... if it's safe to open",
+});
+```
+
+The tool returns:
+
+```json
+{"next": "fetch", "fetch": true, "url": "https://youtu.be/jNQXAC9IVRw",
+ "final_url": "https://www.youtube.com/watch?v=jNQXAC9IVRw&feature=youtu.be",
+ "final_host": "youtube.com", "status": 200, "redirects": 1, "shortener": true,
+ "reason": "unwrapped youtu.be → youtube.com · alive, worth a fetch"}
+```
+
+## Free to start
+
+The first 1M requests a month are free. It works with no key at all (shared demo limit), or grab your own free key in one call, with no email and no card:
+
+```bash
+curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
+export SURFACE_API_KEY=...
+```
+
+After the free tier: $0.25 USD per 1,000 preflights.
+
+## Prefer MCP?
+
+Point any MCP client at `https://nova-otter-delta-cloud.grok.me/mcp` (tool `preflight_url`).
+
+- Website: https://otter-sand-wolf-spring.grok.me
+- Docs: https://nova-otter-delta-cloud.grok.me/docs
+- LLM reference: https://nova-otter-delta-cloud.grok.me/llms.txt
+
+Made by Canada Site Ops. MIT licensed.

package/index.d.ts

@@ -0,0 +1,8 @@
+export interface PreflightOptions { apiKey?: string; baseUrl?: string; headers?: Record<string, string>; timeoutMs?: number; }
+export interface PreflightResult { next: "fetch" | "skip"; fetch: boolean; url: string; final_url?: string; final_host?: string; status?: number; redirects?: number; shortener?: boolean; reason?: string; error?: string; }
+export declare const DEFAULT_BASE_URL: string;
+export declare const TOOL_DESCRIPTION: string;
+export declare function preflight(url: string, opts?: PreflightOptions): Promise<PreflightResult>;
+export declare function surfacePreflightTool(opts?: PreflightOptions): any;
+export declare const surface_preflight: any;
+export default surface_preflight;

package/index.js

@@ -0,0 +1,51 @@
+// Surface for the Vercel AI SDK: the link-safety layer between an AI agent and the open web.
+import { tool } from "ai";
+import { z } from "zod";
+
+export const DEFAULT_BASE_URL = "https://nova-otter-delta-cloud.grok.me";
+export const TOOL_DESCRIPTION =
+  "Check a link before you open it. Surface unwraps short links (t.co, bit.ly, lnkd.in, youtu.be), " +
+  "follows redirects, and tells you whether the destination is worth fetching ('fetch') or should be " +
+  "skipped ('skip'), plus where the link really goes. It never returns the page itself.";
+
+const env = (k) => (typeof process !== "undefined" && process.env ? process.env[k] : undefined);
+
+export async function preflight(url, { apiKey, baseUrl, headers, timeoutMs = 15000 } = {}) {
+  const base = (baseUrl || env("SURFACE_BASE_URL") || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const key = apiKey || env("SURFACE_API_KEY");
+  const res = await fetch(base + "/v1/preflight", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json",
+      "user-agent": "@surfaceapi/ai-sdk/0.1.0",
+      ...(key ? { authorization: "Bearer " + key } : {}),
+      ...(headers || {}),
+    },
+    body: JSON.stringify({ url }),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error("Surface preflight HTTP " + res.status);
+  const d = await res.json();
+  const next = d.next || d.verdict;
+  return {
+    next, fetch: next === "fetch", url: d.url || url, final_url: d.final_url, final_host: d.final_host,
+    status: d.status, redirects: d.redirects, shortener: d.shortener, reason: d.reason,
+  };
+}
+
+export function surfacePreflightTool(opts = {}) {
+  return tool({
+    description: TOOL_DESCRIPTION,
+    parameters: z.object({ url: z.string().describe("The link to check before fetching it") }),
+    inputSchema: z.object({ url: z.string().describe("The link to check before fetching it") }),
+    execute: async ({ url }) => {
+      try { return await preflight(url, opts); }
+      catch (e) { return { next: "skip", fetch: false, url, error: String(e && e.message || e) }; }
+    },
+  });
+}
+
+/** Ready-made tool. Use as: tools: { surface_preflight } */
+export const surface_preflight = surfacePreflightTool();
+export default surface_preflight;

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@surfaceapi/ai-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Surface for the Vercel AI SDK: the link-safety layer between an AI agent and the open web. One tool, surfacePreflight, that tells your agent whether a link is worth fetching.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },
+  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
+  "keywords": ["ai", "ai-sdk", "vercel", "ai-agents", "tools", "link-safety", "url", "preflight", "mcp", "surface"],
+  "author": "Canada Site Ops <canada.site.ops@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://otter-sand-wolf-spring.grok.me",
+  "peerDependencies": { "ai": ">=4.0.0", "zod": ">=3.22.0" },
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" }
+}