@surfaceapi/surface 0.1.3 → 0.1.4

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 (3) hide show
  1. package/README.md +4 -4
  2. package/index.js +36 -5
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -14,7 +14,7 @@ curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
14
14
  export SURFACE_API_KEY=... # paste the key value
15
15
  ```
16
16
 
17
- A key gets its own million free requests a month. Anonymous calls still work on a shared demo limit.
17
+ A key gets its own million free requests a month. The client reads `SURFACE_KEY` or `SURFACE_API_KEY` automatically. Anonymous calls still work on a shared demo limit; without a key the client prints a one-line hint.
18
18
 
19
19
  ## One install for Cursor or Claude (MCP)
20
20
 
@@ -40,13 +40,13 @@ Tool: `preflight_url`. Mint a key first, then paste this into your MCP settings:
40
40
 
41
41
  ```js
42
42
  const { Surface } = require('@surfaceapi/surface');
43
- const { key } = await new Surface().createKey(); // free key in ~10 seconds
44
- const s = new Surface({ apiKey: key });
43
+ const s = new Surface(); // or new Surface() after export SURFACE_API_KEY=...
44
+ await s.createKey(); // free key in ~10 seconds; stored on this client
45
45
  console.log(await s.preflight('https://youtu.be/jNQXAC9IVRw')); // next: fetch or skip
46
46
  console.log(await s.inspect());
47
47
  ```
48
48
 
49
- Or set `SURFACE_API_KEY` after the curl above.
49
+ Or set `SURFACE_API_KEY` (or `SURFACE_KEY`) in the environment — the client sends it on every call.
50
50
 
51
51
  Python: `pip install surfaceapi`
52
52
 
package/index.js CHANGED
@@ -1,11 +1,38 @@
1
1
  'use strict';
2
2
  const DEFAULT_BASE = 'https://nova-otter-delta-cloud.grok.me';
3
+ const HINT = 'Surface: no API key set; this call shares the demo meter. Get a free key in about 10 seconds: curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys then set SURFACE_API_KEY or pass apiKey.';
4
+ let hinted = false;
5
+
6
+ function envKey() {
7
+ try {
8
+ if (typeof process !== 'undefined' && process.env) {
9
+ return process.env.SURFACE_KEY || process.env.SURFACE_API_KEY || '';
10
+ }
11
+ } catch (_) {}
12
+ return '';
13
+ }
14
+
15
+ function warnNoKey() {
16
+ if (hinted) return;
17
+ hinted = true;
18
+ try {
19
+ if (typeof process !== 'undefined' && process.stderr && typeof process.stderr.write === 'function') {
20
+ process.stderr.write(HINT + '\n');
21
+ return;
22
+ }
23
+ } catch (_) {}
24
+ try { console.warn(HINT); } catch (_) {}
25
+ }
26
+
3
27
  class Surface {
4
28
  constructor({ apiKey, baseUrl = DEFAULT_BASE, headers = {} } = {}) {
5
- this.apiKey = apiKey; this.baseUrl = baseUrl.replace(/\/$/, ''); this.headers = headers;
29
+ this.apiKey = apiKey || envKey() || undefined;
30
+ this.baseUrl = baseUrl.replace(/\/$/, '');
31
+ this.headers = headers;
6
32
  }
7
- async _req(method, path, body) {
8
- const h = { 'user-agent': 'surfaceapi-js/0.1.0', ...this.headers };
33
+ async _req(method, path, body, { silent = false } = {}) {
34
+ if (!this.apiKey && !silent) warnNoKey();
35
+ const h = { 'user-agent': 'surfaceapi-js/0.1.4', ...this.headers };
9
36
  if (this.apiKey) h.authorization = 'Bearer ' + this.apiKey;
10
37
  if (body) h['content-type'] = 'application/json';
11
38
  const r = await fetch(this.baseUrl + path, { method, headers: h, body: body ? JSON.stringify(body) : undefined, redirect: 'manual' });
@@ -13,8 +40,12 @@ class Surface {
13
40
  if (r.status >= 400) { const e = new Error('Surface ' + r.status); e.status = r.status; e.data = data; throw e; }
14
41
  return { status: r.status, location: r.headers.get('location'), data };
15
42
  }
16
- /** Get a free API key (first 1M requests/month free). */
17
- async createKey(opts = {}) { return (await this._req('POST', '/v1/keys', opts)).data; }
43
+ /** Get a free API key (first 1M requests/month free). The key is stored on this client for later calls. */
44
+ async createKey(opts = {}) {
45
+ const data = (await this._req('POST', '/v1/keys', opts, { silent: true })).data;
46
+ if (data && typeof data.key === 'string' && data.key) this.apiKey = data.key;
47
+ return data;
48
+ }
18
49
  /** Preflight a URL: reachability, status, redirects, headers. */
19
50
  async preflight(url) { return (await this._req('POST', '/v1/preflight', { url })).data; }
20
51
  /** Inspect the calling request as Surface sees it. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@surfaceapi/surface",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
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": [