@surfaceapi/surface 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +44 -9
  2. package/package.json +4 -9
package/README.md CHANGED
@@ -1,26 +1,61 @@
1
- # Surface: check a short link before you open it
1
+ # Surface
2
2
 
3
- [![links checked | Surface](https://nova-otter-delta-cloud.grok.me/badge/surface.svg)](https://nova-otter-delta-cloud.grok.me)
3
+ Surface checks a short link before your agent opens it. The answer is fetch or skip. It never returns the page. A hop or a 1×1 pixel counts the same way, with no install. Free for the first million requests a month. https://nova-otter-delta-cloud.grok.me
4
4
 
5
- [Surface](https://nova-otter-delta-cloud.grok.me) follows the hops on t.co, bit.ly, lnkd.in and youtu.be links (or any https URL) and says **fetch** or **skip**. It never returns the page, so it's one quick round trip.
5
+ Surface by Canada Site Ops. Ontario, Canada.
6
6
 
7
- Free for the first 1,000,000 requests every month, no card needed. After that: Preflight $0.25, Hop $0.40, Pixel $0.15, Inspect $0.20 per 1,000 requests (USD). Production plan with your own key and meter: $50 CAD/month ([billing](https://nova-otter-delta-cloud.grok.me/billing)).
7
+ ## Get a free API key in about 10 seconds
8
8
 
9
- [Get started](https://nova-otter-delta-cloud.grok.me/start) · [Docs](https://nova-otter-delta-cloud.grok.me/docs) · Free API key in 10 seconds: `curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys`
9
+ No email, no card. Then set it on every call as `Authorization: Bearer <key>` or `X-Surface-Key: <key>`.
10
+
11
+ ```bash
12
+ curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
13
+ # returns {"key","created_at","free_monthly":1000000,"usage_url"}
14
+ export SURFACE_API_KEY=... # paste the key value
15
+ ```
16
+
17
+ A key gets its own million free requests a month. Anonymous calls still work on a shared demo limit.
10
18
 
11
19
  ## One install for Cursor or Claude (MCP)
12
- Paste this into your MCP settings. The agent then calls `preflight_url` before it opens a short link.
20
+
21
+ Tool: `preflight_url`. Mint a key first, then paste this into your MCP settings:
22
+
13
23
  ```json
14
- { "mcpServers": { "surface": { "type": "http", "url": "https://nova-otter-delta-cloud.grok.me/mcp" } } }
24
+ {
25
+ "mcpServers": {
26
+ "surface": {
27
+ "type": "http",
28
+ "url": "https://nova-otter-delta-cloud.grok.me/mcp",
29
+ "headers": {
30
+ "Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
31
+ }
32
+ }
33
+ }
34
+ }
15
35
  ```
16
36
 
17
37
  ## JavaScript
38
+
18
39
  `npm install @surfaceapi/surface`
40
+
19
41
  ```js
20
42
  const { Surface } = require('@surfaceapi/surface');
21
- const { key } = await new Surface().createKey(); // free key
43
+ const { key } = await new Surface().createKey(); // free key in ~10 seconds
22
44
  const s = new Surface({ apiKey: key });
23
45
  console.log(await s.preflight('https://youtu.be/jNQXAC9IVRw')); // next: fetch or skip
24
- console.log(await s.inspect()); // bot, browser, or script
46
+ console.log(await s.inspect());
25
47
  ```
48
+
49
+ Or set `SURFACE_API_KEY` after the curl above.
50
+
26
51
  Python: `pip install surfaceapi`
52
+
53
+ ## Also listed
54
+
55
+ - Official MCP Registry: `me.grok.nova-otter-delta-cloud/surface`
56
+ - https://www.curatedmcp.com/marketplace/surface
57
+ - https://www.npmjs.com/package/@surfaceapi/surface
58
+ - https://pypi.org/project/surfaceapi/
59
+ - https://huggingface.co/spaces/surfaceapi/surface-preflight
60
+
61
+ MCP at `/mcp` (tool `preflight_url`). CLI and GitHub Action are coming soon.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@surfaceapi/surface",
3
- "version": "0.1.1",
4
- "description": "Check a short link before your agent opens it. Surface client: unwrap t.co/bit.ly/lnkd.in/youtu.be and get fetch or skip. 1M requests/month free.",
3
+ "version": "0.1.3",
4
+ "description": "Surface checks a short link before your agent opens it. The answer is fetch or skip. It never returns the page. Free for the first million requests a month.",
5
5
  "main": "index.js",
6
6
  "files": [
7
7
  "index.js",
@@ -22,10 +22,5 @@
22
22
  ],
23
23
  "author": "Surface / Canada Site Ops <canada.site.ops@gmail.com>",
24
24
  "license": "MIT",
25
- "homepage": "https://nova-otter-delta-cloud.grok.me",
26
- "repository": {
27
- "type": "git",
28
- "url": "git+https://github.com/Surface-ops/surface.git",
29
- "directory": "clients/js"
30
- }
31
- }
25
+ "homepage": "https://nova-otter-delta-cloud.grok.me"
26
+ }