@namingsignal/mcp 0.2.0

package/dist/core/namespaces.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkNamespaces = checkNamespaces;
+const normalize_1 = require("./normalize");
+const AUTOMATED = ["npm", "pypi", "apple_app_store", "github"];
+const MANUAL = ["google_play", "chrome_web_store", "x", "instagram", "linkedin", "youtube"];
+const defaultCache = new Map();
+const defaultInflight = new Map();
+class NamespaceTimeoutError extends Error {
+    constructor() {
+        super("Namespace request timed out.");
+        this.name = "NamespaceTimeoutError";
+    }
+}
+async function timedFetch(fetcher, url, timeoutMs, init = {}) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new NamespaceTimeoutError());
+            }, timeoutMs);
+        });
+        return await Promise.race([fetcher(url, { ...init, signal: controller.signal }), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function cancelResponseBody(response) {
+    if (!response.body)
+        return;
+    try {
+        await response.body.cancel();
+    }
+    catch {
+        // Status-only endpoints do not need their bodies; tolerate runtimes that
+        // expose a body stream which is already locked.
+    }
+}
+async function readBoundedJson(response, maxBytes) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await cancelResponseBody(response);
+        throw new Error("Namespace JSON response exceeded its byte limit.");
+    }
+    if (!response.body)
+        throw new Error("Namespace JSON response body was empty.");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel("Namespace JSON response exceeded its byte limit.").catch(() => undefined);
+                throw new Error("Namespace JSON response exceeded its byte limit.");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+function source(kind, name, label, status, provider, sourceUrl, checkedAt, detail, evidenceStatus, confidence, responseCode) {
+    return {
+        namespace: kind,
+        label,
+        status,
+        url: manualUrl(kind, name),
+        responseCode,
+        detail,
+        evidence: {
+            id: `namespace:${kind}:${(0, normalize_1.comparisonKey)(name)}`,
+            label: `${provider} exact-name check`,
+            provider,
+            sourceUrl,
+            checkedAt,
+            status: evidenceStatus,
+            confidence,
+            value: { namespace: kind, status, responseCode },
+            detail,
+        },
+    };
+}
+function manualUrl(kind, rawName) {
+    const slug = (0, normalize_1.toDomainLabel)(rawName);
+    const encoded = encodeURIComponent(rawName.trim());
+    switch (kind) {
+        case "npm":
+            return `https://www.npmjs.com/package/${encodeURIComponent(slug)}`;
+        case "pypi":
+            return `https://pypi.org/project/${encodeURIComponent(slug)}/`;
+        case "github":
+            return `https://github.com/${encodeURIComponent(slug.slice(0, 39))}`;
+        case "apple_app_store":
+            return `https://apps.apple.com/us/search?term=${encoded}`;
+        case "google_play":
+            return `https://play.google.com/store/search?q=${encoded}&c=apps`;
+        case "chrome_web_store":
+            return `https://chromewebstore.google.com/search/${encoded}`;
+        case "x":
+            return `https://x.com/${encodeURIComponent(slug.slice(0, 15))}`;
+        case "instagram":
+            return `https://www.instagram.com/${encodeURIComponent(slug.slice(0, 30))}/`;
+        case "linkedin":
+            return `https://www.linkedin.com/search/results/companies/?keywords=${encoded}`;
+        case "youtube":
+            return `https://www.youtube.com/results?search_query=${encoded}`;
+    }
+}
+function exactEndpoint(kind, rawName, country) {
+    const slug = (0, normalize_1.toDomainLabel)(rawName);
+    switch (kind) {
+        case "npm":
+            return `https://registry.npmjs.org/${encodeURIComponent(slug)}`;
+        case "pypi":
+            return `https://pypi.org/pypi/${encodeURIComponent(slug)}/json`;
+        case "github":
+            return `https://api.github.com/users/${encodeURIComponent(slug.slice(0, 39))}`;
+        case "apple_app_store":
+            return `https://itunes.apple.com/search?term=${encodeURIComponent(rawName.trim())}&entity=software&limit=50&country=${encodeURIComponent(country)}`;
+        default:
+            return manualUrl(kind, rawName);
+    }
+}
+function platformLabel(kind) {
+    return {
+        npm: "npm package",
+        pypi: "PyPI project",
+        github: "GitHub account",
+        apple_app_store: "Apple App Store",
+        google_play: "Google Play",
+        chrome_web_store: "Chrome Web Store",
+        x: "X handle",
+        instagram: "Instagram handle",
+        linkedin: "LinkedIn company",
+        youtube: "YouTube handle",
+    }[kind];
+}
+function providerLabel(kind) {
+    return {
+        npm: "npm Registry",
+        pypi: "PyPI JSON API",
+        github: "GitHub REST API",
+        apple_app_store: "Apple iTunes Search API",
+        google_play: "Google Play manual search",
+        chrome_web_store: "Chrome Web Store manual search",
+        x: "X manual verification",
+        instagram: "Instagram manual verification",
+        linkedin: "LinkedIn manual verification",
+        youtube: "YouTube manual verification",
+    }[kind];
+}
+function manualResult(kind, name, now) {
+    const checkedAt = now().toISOString();
+    const social = ["x", "instagram", "linkedin", "youtube"].includes(kind);
+    const detail = social
+        ? "No supported public API confirms handle availability. Automated or blocked page responses are not interpreted; verify manually."
+        : "The platform does not provide a suitable public catalog API for this exact check; use the manual search link.";
+    return source(kind, name, platformLabel(kind), social ? "unknown" : "manual", providerLabel(kind), manualUrl(kind, name), checkedAt, detail, "manual", "low");
+}
+async function automatedResult(kind, name, options) {
+    const fetcher = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!fetcher)
+        throw new Error("A Fetch-compatible function is required for namespace checks.");
+    const now = options.now ?? (() => new Date());
+    const timeoutMs = Math.max(50, options.timeoutMs ?? 4_000);
+    const country = (options.country ?? "us").toLowerCase();
+    const endpoint = exactEndpoint(kind, name, country);
+    const provider = providerLabel(kind);
+    const checkedAt = now().toISOString();
+    const headers = { accept: "application/json" };
+    if (kind === "github") {
+        headers["x-github-api-version"] = "2022-11-28";
+        headers["user-agent"] = "naming-signal/0.1";
+        if (options.githubToken)
+            headers.authorization = `Bearer ${options.githubToken}`;
+    }
+    const started = Date.now();
+    try {
+        const response = await timedFetch(fetcher, endpoint, timeoutMs, { headers });
+        const latencyMs = Date.now() - started;
+        options.usageLedger?.record({
+            kind: "namespace",
+            provider,
+            task: `namespace.${kind}`,
+            calls: 0,
+            requests: 1,
+            failures: response.status === 429 || response.status >= 500 ? 1 : 0,
+            latencyMs,
+        });
+        if (kind === "apple_app_store" && response.ok) {
+            let payload;
+            try {
+                payload = await readBoundedJson(response, 1_000_000);
+            }
+            catch {
+                return source(kind, name, platformLabel(kind), "unknown", provider, endpoint, checkedAt, "Apple returned an unreadable response; status remains unknown.", "unknown", "low", response.status);
+            }
+            const target = (0, normalize_1.comparisonKey)(name);
+            const exact = (payload.results ?? []).filter((item) => typeof item.trackName === "string" && (0, normalize_1.comparisonKey)(item.trackName) === target);
+            if (exact.length) {
+                return source(kind, name, platformLabel(kind), "conflict", provider, endpoint, checkedAt, `${exact.length} exact normalized title match${exact.length === 1 ? "" : "es"} found in the ${country.toUpperCase()} storefront.`, "confirmed", "high", response.status);
+            }
+            return source(kind, name, platformLabel(kind), "likely_available", provider, endpoint, checkedAt, `No exact normalized title match appeared in the first 50 ${country.toUpperCase()} storefront results; other storefronts and title rules remain unchecked.`, "inferred", "low", response.status);
+        }
+        await cancelResponseBody(response);
+        if (response.ok) {
+            return source(kind, name, platformLabel(kind), "taken", provider, endpoint, checkedAt, `Exact ${platformLabel(kind).toLowerCase()} lookup returned HTTP ${response.status}.`, "confirmed", "high", response.status);
+        }
+        if (response.status === 404) {
+            return source(kind, name, platformLabel(kind), "likely_available", provider, endpoint, checkedAt, `Exact lookup returned 404. The namespace appears unused, but reserved names and registration rules can still block it.`, "inferred", kind === "github" ? "medium" : "high", response.status);
+        }
+        return source(kind, name, platformLabel(kind), "unknown", provider, endpoint, checkedAt, response.status === 429
+            ? "The provider rate-limited this check; status remains unknown."
+            : `Provider returned ambiguous HTTP ${response.status}; status remains unknown.`, "unknown", "low", response.status);
+    }
+    catch (error) {
+        options.usageLedger?.record({
+            kind: "namespace",
+            provider,
+            task: `namespace.${kind}`,
+            calls: 0,
+            requests: 1,
+            failures: 1,
+            latencyMs: Date.now() - started,
+        });
+        return source(kind, name, platformLabel(kind), "unknown", provider, endpoint, checkedAt, error instanceof NamespaceTimeoutError || (error instanceof Error && error.name === "AbortError")
+            ? "Provider request timed out; status remains unknown."
+            : "Provider request failed; status remains unknown.", "unknown", "low");
+    }
+}
+async function checkOne(kind, name, options) {
+    const now = options.now ?? (() => new Date());
+    if (!AUTOMATED.includes(kind))
+        return manualResult(kind, name, now);
+    const cacheKey = `namespace:v1:${kind}:${(0, normalize_1.comparisonKey)(name)}:${options.country ?? "us"}`;
+    const local = !options.fetch ? defaultCache.get(cacheKey) : undefined;
+    if (local && local.expiresAt > now().getTime()) {
+        options.usageLedger?.record({ kind: "namespace", provider: "core-cache", task: `namespace.${kind}.cache`, calls: 0, requests: 0, cacheHits: 1 });
+        return { ...local.value, cached: true, evidence: { ...local.value.evidence } };
+    }
+    const external = await options.cache?.get(cacheKey);
+    if (external) {
+        options.usageLedger?.record({ kind: "namespace", provider: "core-cache", task: `namespace.${kind}.cache`, calls: 0, requests: 0, cacheHits: 1 });
+        return { ...external, cached: true, evidence: { ...external.evidence } };
+    }
+    const existing = !options.fetch ? defaultInflight.get(cacheKey) : undefined;
+    if (existing) {
+        const result = await existing;
+        return { ...result, evidence: { ...result.evidence } };
+    }
+    const operation = automatedResult(kind, name, options);
+    if (!options.fetch)
+        defaultInflight.set(cacheKey, operation);
+    try {
+        const result = await operation;
+        const ttl = result.status === "unknown" ? options.unknownCacheTtlMs ?? 15_000 : options.cacheTtlMs ?? 5 * 60_000;
+        if (ttl > 0) {
+            if (!options.fetch)
+                defaultCache.set(cacheKey, { value: result, expiresAt: now().getTime() + ttl });
+            await options.cache?.set(cacheKey, result, ttl);
+        }
+        return { ...result, evidence: { ...result.evidence } };
+    }
+    finally {
+        if (!options.fetch)
+            defaultInflight.delete(cacheKey);
+    }
+}
+/** Check exact public namespaces. Unsupported/social platforms remain manual or unknown, never "free". */
+async function checkNamespaces(name, options = {}) {
+    if (typeof name !== "string" || !(0, normalize_1.toDomainLabel)(name))
+        throw new TypeError("A non-empty name is required.");
+    let kinds = options.include ? [...new Set(options.include)] : [...AUTOMATED];
+    if (options.includeManual)
+        kinds = [...new Set([...kinds, ...MANUAL])];
+    return Promise.all(kinds.map((kind) => checkOne(kind, name, options)));
+}

package/dist/core/normalize.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeName = normalizeName;
+exports.toDomainLabel = toDomainLabel;
+exports.normalizeDomain = normalizeDomain;
+exports.comparisonKey = comparisonKey;
+const TRADEMARK_MARKS = /[\u00ae\u2122\u2120]/gu;
+const DASHES = /[\u2010-\u2015\u2212]/gu;
+const COMBINING_MARKS = /\p{M}+/gu;
+const NON_NAME_CHARACTERS = /[^a-z0-9]+/g;
+/**
+ * Produce a comparison-safe form while keeping meaningful word boundaries.
+ * This is intentionally not a display-name formatter or a domain lookup.
+ */
+function normalizeName(input) {
+    if (typeof input !== "string")
+        return "";
+    return input
+        .replace(TRADEMARK_MARKS, "")
+        .normalize("NFKD")
+        .replace(COMBINING_MARKS, "")
+        .replace(DASHES, "-")
+        .replace(/&/g, " and ")
+        .toLowerCase()
+        .replace(NON_NAME_CHARACTERS, " ")
+        .trim()
+        .replace(/\s+/g, " ");
+}
+function toDomainLabel(input) {
+    return normalizeName(input)
+        .replace(/\band\b/g, "and")
+        .replace(/\s+/g, "")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63);
+}
+/** Normalize and validate a fully-qualified domain, or build one from a name and TLD. */
+function normalizeDomain(input, tld) {
+    if (typeof input !== "string" || !input.trim()) {
+        throw new TypeError("A domain or name is required.");
+    }
+    let hostname;
+    if (tld !== undefined) {
+        const label = toDomainLabel(input);
+        const normalizedTld = String(tld).trim().toLowerCase().replace(/^\.+/, "").replace(/\.+$/, "");
+        if (!label || !normalizedTld)
+            throw new TypeError("The name and TLD must contain valid DNS characters.");
+        hostname = `${label}.${normalizedTld}`;
+    }
+    else {
+        const raw = input.trim();
+        try {
+            const parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`);
+            hostname = parsed.hostname;
+        }
+        catch {
+            throw new TypeError(`Invalid fully-qualified domain: ${input}`);
+        }
+    }
+    hostname = hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+    if (hostname.length > 253 || !hostname.includes(".")) {
+        throw new TypeError(`Invalid fully-qualified domain: ${input}`);
+    }
+    const labels = hostname.split(".");
+    if (labels.some((label) => label.length < 1 ||
+        label.length > 63 ||
+        !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(label))) {
+        throw new TypeError(`Invalid fully-qualified domain: ${input}`);
+    }
+    return hostname;
+}
+function comparisonKey(input) {
+    return normalizeName(input).replace(/\s+/g, "");
+}