geo-new 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,101 @@
+import { type CredentialStore } from './credentials.js';
+import { type Api, type AuditSnapshot, type ClientKind, type Envelope, type Key, type KeyList } from './types.js';
+export declare const VERSION: string;
+export declare const DEFAULT_ORIGIN = "https://geo.new";
+export type ClientOptions = {
+    /** A `gnk_…` key. Without one the client mints and keeps a keyless session. */
+    apiKey?: string;
+    /** The Pages origin in production; `http://127.0.0.1:8787` against a local `dev:demo`. */
+    baseUrl?: string;
+    /** Injected in tests. */
+    fetch?: typeof fetch;
+    /** Where the keyless session and the last audit id live. Memory by default for the library. */
+    credentials?: CredentialStore;
+    /** Reported in the User-Agent so the server can count adoption by client kind. */
+    kind?: ClientKind;
+};
+export type WaitMode = 'none' | 'measured' | 'ai';
+export type WaitOptions = {
+    mode?: WaitMode;
+    timeoutSeconds?: number;
+    signal?: AbortSignal;
+    onSnapshot?: (snapshot: AuditSnapshot) => void;
+};
+export type WaitResult = {
+    snapshot: AuditSnapshot;
+    timedOut: boolean;
+};
+/**
+ * One HTTP client behind the CLI, the stdio MCP server and the library. It holds a session before any
+ * create and sends an `Idempotency-Key` on every create, so a retry after a timeout can never start a
+ * second audit as somebody new; it retries 5xx and network failures twice and never a 429; it treats a
+ * `session` in a response to a keyed request as a protocol error rather than persisting a downgrade;
+ * and it sends a key only to an https or loopback origin.
+ */
+export declare class GeoNewClient implements Api {
+    readonly origin: URL;
+    private readonly fetchImpl;
+    private readonly credentials;
+    private readonly kind;
+    private readonly explicitKey?;
+    constructor(options?: ClientOptions);
+    /** The key in force: the option or `GEO_NEW_API_KEY`, else the stored one; re-read on every call. */
+    get apiKey(): string | undefined;
+    get isDefaultOrigin(): boolean;
+    private authorization;
+    private request;
+    private failureOf;
+    /** Holds a keyless session before a create, so a retried create can bind to its idempotency record. */
+    ensureSession(signal?: AbortSignal): Promise<void>;
+    audit(url: string, options?: {
+        fresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Envelope>;
+    snapshot(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AuditSnapshot>;
+    markdown(id: string): Promise<{
+        text: string;
+        revision: number;
+        status: string;
+    }>;
+    fixPrompt(id: string): Promise<string>;
+    compare(id: string, baseline: string): Promise<unknown>;
+    usage(): Promise<{
+        principal: import("./openapi.js").components["schemas"]["Principal"] | null;
+        plan: "anonymous" | "free" | "builder";
+        allowance: import("./openapi.js").components["schemas"]["Allowance"];
+        global: {
+            five_minutes: {
+                limit: number;
+                used: number;
+            };
+            hour: {
+                limit: number;
+                used: number;
+            };
+        };
+    }>;
+    share(id: string): Promise<{
+        url: string;
+        expires_at: string;
+    }>;
+    revokeShare(id: string): Promise<{
+        revoked: boolean;
+    }>;
+    createKey(label?: string): Promise<Key>;
+    listKeys(): Promise<KeyList>;
+    revokeKey(prefix: string): Promise<{
+        revoked: boolean;
+    }>;
+    /** Polls until the report is measured (`writing` or terminal), terminal (`ai`), or the timeout. */
+    waitFor(id: string, options?: WaitOptions): Promise<WaitResult>;
+    /** The keyless session token, when the client holds one; the CLI prints it on request, never by default. */
+    get lastAuditId(): string | undefined;
+    remember(patch: Partial<{
+        key: string;
+        last_audit_id: string;
+    }>): void;
+    forget(): void;
+}
+export declare const createClient: (options?: ClientOptions) => GeoNewClient;

package/dist/credentials.d.ts

@@ -0,0 +1,41 @@
+export type Credentials = {
+    key?: string;
+    session?: {
+        token: string;
+        expires_at: string;
+    };
+    last_audit_id?: string;
+};
+export interface CredentialStore {
+    load(): Credentials;
+    save(next: Credentials): void;
+}
+/** `$XDG_CONFIG_HOME/geo-new/credentials.json`, `~/.config` when unset, `%APPDATA%\geo-new\` on Windows. */
+export declare function credentialsPath(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+/**
+ * A file the CLI and a running MCP server share. Reads are cached on the file's mtime, size and inode,
+ * so `geo-new key create` in another terminal reaches a running server on its next call without a
+ * restart; writes go to a temporary name and are renamed, so a reader never sees half a file; a file
+ * that fails to parse keeps the last good contents and warns once. A home directory that cannot be
+ * written means an in-memory session and one warning, never a failure.
+ */
+export declare class FileCredentials implements CredentialStore {
+    readonly path: string;
+    private readonly warn;
+    private cache;
+    private warned;
+    private memory;
+    constructor(path?: string, warn?: (message: string) => void);
+    private stamp;
+    load(): Credentials;
+    save(next: Credentials): void;
+    clear(): void;
+}
+export declare class MemoryCredentials implements CredentialStore {
+    private value;
+    constructor(value?: Credentials);
+    load(): Credentials;
+    save(next: Credentials): void;
+}
+/** A throwaway path for tests and for read-only homes. */
+export declare const scratchCredentialsPath: () => string;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createClient, GeoNewClient, VERSION, DEFAULT_ORIGIN } from './client.js';
+export type { ClientOptions, WaitMode, WaitOptions, WaitResult } from './client.js';
+export { FileCredentials, MemoryCredentials, credentialsPath } from './credentials.js';
+export type { Credentials, CredentialStore } from './credentials.js';
+export { ApiError, isMeasured, isTerminal } from './types.js';
+export type { Api, ApiFailure, ApiErrorBody, AuditSnapshot, ClientKind, Envelope, Key, KeyList, Share, Usage, } from './types.js';

package/dist/index.js

@@ -0,0 +1,341 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+
+// packages/geo-new/src/client.ts
+import { randomBytes } from "node:crypto";
+
+// packages/geo-new/src/credentials.ts
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync, chmodSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+function credentialsPath(env = process.env, platform = process.platform) {
+  const base = platform === "win32" ? env.APPDATA ?? join(homedir(), "AppData", "Roaming") : env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(base, "geo-new", "credentials.json");
+}
+var FileCredentials = class {
+  constructor(path = credentialsPath(), warn = (m) => process.stderr.write(`${m}
+`)) {
+    this.path = path;
+    this.warn = warn;
+  }
+  path;
+  warn;
+  cache = null;
+  warned = false;
+  memory = null;
+  stamp() {
+    try {
+      const s = statSync(this.path);
+      return `${s.mtimeMs}:${s.size}:${s.ino}`;
+    } catch {
+      return null;
+    }
+  }
+  load() {
+    if (this.memory) return this.memory;
+    const stamp = this.stamp();
+    if (stamp === null) return {};
+    if (this.cache && this.cache.stamp === stamp) return this.cache.value;
+    try {
+      const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+      if (!parsed || typeof parsed !== "object") throw new Error("not an object");
+      this.cache = { stamp, value: parsed };
+      this.warned = false;
+      return parsed;
+    } catch {
+      if (!this.warned) {
+        this.warn(`geo-new: could not read ${this.path}; keeping the last good credentials.`);
+        this.warned = true;
+      }
+      return this.cache?.value ?? {};
+    }
+  }
+  save(next) {
+    if (this.memory) {
+      this.memory = next;
+      return;
+    }
+    try {
+      mkdirSync(join(this.path, ".."), { recursive: true, mode: 448 });
+      const temporary = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+      writeFileSync(temporary, JSON.stringify(next, null, 2) + "\n", { mode: 384 });
+      try {
+        chmodSync(temporary, 384);
+      } catch {
+      }
+      renameSync(temporary, this.path);
+      this.cache = null;
+    } catch {
+      this.memory = next;
+      this.warn(`geo-new: ${this.path} is not writable; this session lives in memory only.`);
+    }
+  }
+  clear() {
+    try {
+      unlinkSync(this.path);
+    } catch {
+    }
+    this.cache = null;
+    this.memory = null;
+  }
+};
+var MemoryCredentials = class {
+  constructor(value = {}) {
+    this.value = value;
+  }
+  value;
+  load() {
+    return this.value;
+  }
+  save(next) {
+    this.value = next;
+  }
+};
+
+// packages/geo-new/src/types.ts
+var isMeasured = (status) => status === "writing" || status === "complete" || status === "partial" || status === "failed";
+var isTerminal = (status) => status === "complete" || status === "partial" || status === "failed";
+var ApiError = class extends Error {
+  constructor(failure2) {
+    super(failure2.message);
+    this.failure = failure2;
+    this.name = "ApiError";
+  }
+  failure;
+  get code() {
+    return this.failure.code;
+  }
+};
+
+// packages/geo-new/src/client.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+var DEFAULT_ORIGIN = "https://geo.new";
+var isLoopback = (url) => url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  const timer = setTimeout(resolve, ms);
+  signal?.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new Error("aborted"));
+    },
+    { once: true }
+  );
+});
+var failure = (code, message, status = 0, retryable = false) => new ApiError({ code, message, status, retryable });
+var GeoNewClient = class {
+  origin;
+  fetchImpl;
+  credentials;
+  kind;
+  explicitKey;
+  constructor(options = {}) {
+    this.origin = new URL(options.baseUrl ?? process.env.GEO_NEW_API_URL ?? DEFAULT_ORIGIN);
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.credentials = options.credentials ?? new MemoryCredentials();
+    this.kind = options.kind ?? "client";
+    this.explicitKey = options.apiKey ?? process.env.GEO_NEW_API_KEY;
+  }
+  /** The key in force: the option or `GEO_NEW_API_KEY`, else the stored one; re-read on every call. */
+  get apiKey() {
+    return this.explicitKey ?? this.credentials.load().key;
+  }
+  get isDefaultOrigin() {
+    return this.origin.origin === DEFAULT_ORIGIN;
+  }
+  authorization() {
+    const key = this.apiKey;
+    if (key) {
+      if (this.origin.protocol !== "https:" && !isLoopback(this.origin))
+        throw failure(
+          "INSECURE_ORIGIN",
+          `A key is sent only to an https or loopback origin, not ${this.origin.origin}.`
+        );
+      return `Bearer ${key}`;
+    }
+    const session = this.credentials.load().session;
+    if (session && Date.parse(session.expires_at) > Date.now()) return `Bearer ${session.token}`;
+    return void 0;
+  }
+  async request(method, path, options = {}) {
+    const headers = {
+      "User-Agent": `geo-new/${VERSION} (${this.kind})`,
+      Accept: options.accept ?? "application/json",
+      ...options.headers ?? {}
+    };
+    const authorization = this.authorization();
+    if (authorization) headers.Authorization = authorization;
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    const retries = options.retries ?? 2;
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.fetchImpl(new URL(path, this.origin), {
+          method,
+          headers,
+          body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+          signal: options.signal
+        });
+      } catch (error) {
+        if (options.signal?.aborted) throw error;
+        if (attempt < retries) {
+          attempt++;
+          await sleep(200 * 4 ** (attempt - 1), options.signal);
+          continue;
+        }
+        throw failure("NETWORK", describeNetworkError(error, this.origin), 0, true);
+      }
+      if (response.status >= 500 && attempt < retries) {
+        attempt++;
+        await sleep(200 * 4 ** (attempt - 1), options.signal);
+        continue;
+      }
+      if (!response.ok) throw await this.failureOf(response);
+      const data = options.text ? await response.text() : await response.json();
+      if (authorization?.startsWith("Bearer gnk_") && data && typeof data === "object" && "session" in data)
+        throw failure(
+          "PROTOCOL_ERROR",
+          "The server answered a keyed request with a session token: this server build does not accept keys.",
+          response.status
+        );
+      return { data, response };
+    }
+  }
+  async failureOf(response) {
+    const type = response.headers.get("Content-Type") ?? "";
+    if (/application\/json/i.test(type)) {
+      try {
+        const body = await response.json();
+        if (body?.error?.code) return new ApiError({ ...body.error, status: response.status });
+      } catch {
+      }
+    }
+    const kind = /text\/html/i.test(type) ? "an HTML error page" : `an empty or non-JSON ${response.status} response`;
+    return failure(
+      "UNEXPECTED_RESPONSE",
+      `The server returned ${kind}.`,
+      response.status,
+      response.status >= 500
+    );
+  }
+  /** Holds a keyless session before a create, so a retried create can bind to its idempotency record. */
+  async ensureSession(signal) {
+    if (this.apiKey) return;
+    const stored = this.credentials.load();
+    if (stored.session && Date.parse(stored.session.expires_at) > Date.now() + 6e4) return;
+    const { data } = await this.request(
+      "POST",
+      "/api/v1/session",
+      {
+        signal
+      }
+    );
+    if (!data.session) throw failure("NO_SESSION", "The server did not return a session token.");
+    this.credentials.save({
+      ...stored,
+      session: {
+        token: data.session,
+        expires_at: new Date(Date.now() + data.expires_in_seconds * 1e3).toISOString()
+      }
+    });
+  }
+  async audit(url, options = {}) {
+    await this.ensureSession(options.signal);
+    const { data } = await this.request("POST", "/api/v1/audits", {
+      body: { url, ...options.fresh ? { fresh: true } : {} },
+      headers: { "Idempotency-Key": randomBytes(16).toString("hex") },
+      signal: options.signal,
+      retries: 2
+    });
+    const stored = this.credentials.load();
+    this.credentials.save({ ...stored, last_audit_id: data.audit_id });
+    return data;
+  }
+  async snapshot(id, options = {}) {
+    return (await this.request("GET", `/api/v1/audits/${id}`, { signal: options.signal })).data;
+  }
+  async markdown(id) {
+    const { data, response } = await this.request("GET", `/api/v1/audits/${id}/report.md`, {
+      accept: "text/markdown",
+      text: true
+    });
+    return {
+      text: data,
+      revision: Number(response.headers.get("X-Audit-Revision") ?? 0),
+      status: response.headers.get("X-Audit-Status") ?? "unknown"
+    };
+  }
+  async fixPrompt(id) {
+    return (await this.request("GET", `/api/v1/audits/${id}/fix-prompt`, {
+      accept: "text/plain",
+      text: true
+    })).data;
+  }
+  async compare(id, baseline) {
+    return (await this.request("GET", `/api/v1/audits/${id}/compare/${baseline}`)).data;
+  }
+  async usage() {
+    return (await this.request("GET", "/api/v1/usage")).data;
+  }
+  async share(id) {
+    return (await this.request("POST", `/api/v1/audits/${id}/share`)).data;
+  }
+  async revokeShare(id) {
+    return (await this.request("DELETE", `/api/v1/audits/${id}/shares`)).data;
+  }
+  async createKey(label) {
+    await this.ensureSession();
+    return (await this.request("POST", "/api/v1/keys", { body: label ? { label } : {} })).data;
+  }
+  async listKeys() {
+    return (await this.request("GET", "/api/v1/keys")).data;
+  }
+  async revokeKey(prefix) {
+    return (await this.request("DELETE", `/api/v1/keys/${prefix.replace(/^gnk_/, "")}`)).data;
+  }
+  /** Polls until the report is measured (`writing` or terminal), terminal (`ai`), or the timeout. */
+  async waitFor(id, options = {}) {
+    const mode = options.mode ?? "measured", deadline = Date.now() + (options.timeoutSeconds ?? 90) * 1e3;
+    let snapshot = await this.snapshot(id, { signal: options.signal });
+    for (; ; ) {
+      options.onSnapshot?.(snapshot);
+      const done = mode === "none" || (mode === "measured" ? isMeasured(snapshot.status) : isTerminal(snapshot.status));
+      if (done) return { snapshot, timedOut: false };
+      if (Date.now() + 2e3 > deadline) return { snapshot, timedOut: true };
+      await sleep(2e3, options.signal);
+      snapshot = await this.snapshot(id, { signal: options.signal });
+    }
+  }
+  /** The keyless session token, when the client holds one; the CLI prints it on request, never by default. */
+  get lastAuditId() {
+    return this.credentials.load().last_audit_id;
+  }
+  remember(patch) {
+    const stored = this.credentials.load();
+    this.credentials.save({ ...stored, ...patch });
+  }
+  forget() {
+    this.credentials.save({});
+  }
+};
+function describeNetworkError(error, origin) {
+  const code = error?.cause?.code ?? error?.code ?? "";
+  const host = origin.host;
+  if (/ENOTFOUND|EAI_AGAIN/.test(code)) return `DNS could not resolve ${host}.`;
+  if (/ECONNREFUSED/.test(code)) return `${host} refused the connection.`;
+  if (/CERT|TLS|SSL/i.test(code) || /certificate/i.test(String(error))) return `TLS to ${host} failed.`;
+  return `Could not reach ${host}.`;
+}
+var createClient = (options = {}) => new GeoNewClient(options);
+export {
+  ApiError,
+  DEFAULT_ORIGIN,
+  FileCredentials,
+  GeoNewClient,
+  MemoryCredentials,
+  VERSION,
+  createClient,
+  credentialsPath,
+  isMeasured,
+  isTerminal
+};

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+import type { components } from './openapi.js';
+export type AuditSnapshot = components['schemas']['AuditSnapshot'];
+export type Envelope = components['schemas']['Admission'];
+export type Usage = components['schemas']['Usage'];
+export type Key = components['schemas']['Key'];
+export type KeyList = components['schemas']['KeyList'];
+export type Share = components['schemas']['Share'];
+export type ApiErrorBody = components['schemas']['ApiError'];
+export type ClientKind = 'cli' | 'mcp' | 'client';
+/** A non-terminal status whose measured rows are final. Scores are frozen once the model starts writing. */
+export declare const isMeasured: (status: string) => status is "writing" | "complete" | "partial" | "failed";
+export declare const isTerminal: (status: string) => status is "complete" | "partial" | "failed";
+/** What the server said when it refused. `status` 0 means the request never reached it. */
+export type ApiFailure = {
+    code: string;
+    message: string;
+    status: number;
+    retryable: boolean;
+    request_id?: string;
+    retry_after_seconds?: number;
+    field?: string;
+    help_path?: string;
+};
+export declare class ApiError extends Error {
+    failure: ApiFailure;
+    constructor(failure: ApiFailure);
+    get code(): string;
+}
+/**
+ * The seam between the tool surface and the transport that reaches the API. The stdio server uses the
+ * HTTP client; a hosted server can call the app in process without changing a tool.
+ */
+export interface Api {
+    audit(url: string, options?: {
+        fresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Envelope>;
+    snapshot(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AuditSnapshot>;
+    markdown(id: string): Promise<{
+        text: string;
+        revision: number;
+        status: string;
+    }>;
+    fixPrompt(id: string): Promise<string>;
+    compare(id: string, baseline: string): Promise<unknown>;
+    usage(): Promise<Usage>;
+    share(id: string): Promise<Share>;
+    revokeShare(id: string): Promise<{
+        revoked: boolean;
+    }>;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "geo-new",
+  "version": "0.1.0",
+  "description": "Audit one page for GEO, SEO and agent readiness from a terminal, a coding agent (MCP) or a script. Keyless by default; a key is optional.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "geo-new": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "geo",
+    "seo",
+    "audit",
+    "mcp",
+    "cli",
+    "ai-search",
+    "llms.txt"
+  ],
+  "homepage": "https://geo.new/agents",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aeelbeyoglu/geo-new.git",
+    "directory": "packages/geo-new"
+  },
+  "dependencies": {}
+}