@meertrack/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meertrack
+
+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, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,313 @@
+# `@meertrack/mcp`
+
+[![MCP protocol 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-5e5edd)](https://modelcontextprotocol.io/specification/2025-11-25)
+[![8 tools · 3 prompts](https://img.shields.io/badge/tools-8%20%C2%B7%20prompts%203-10b981)](#the-8-tools)
+[![npm](https://img.shields.io/npm/v/@meertrack/mcp.svg)](https://www.npmjs.com/package/@meertrack/mcp)
+[![CI](https://github.com/meertrack/meertrack-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/meertrack/meertrack-mcp/actions/workflows/ci.yml)
+
+Model Context Protocol server for [Meertrack](https://meertrack.com). Ask your
+agent "what did my competitors ship this week?" from Claude, Cursor, Claude
+Code, VS Code, Windsurf, Cline, ChatGPT, or anywhere that speaks MCP.
+
+Wraps the [Meertrack v1 REST API](https://api.meertrack.com/v1) as **8
+read-only tools** and **3 prompt workflows**. No backend changes, same
+`mt_live_` keys, same rate limits.
+
+---
+
+## Pick your transport
+
+| | Local (stdio) | Remote (Streamable HTTP) |
+| --- | --- | --- |
+| **Setup time** | 30 seconds (paste a JSON block) | 10 seconds (paste a URL) |
+| **Best for** | Individual Pro customers; all Claude Desktop plans; any IDE on your laptop | Team/Enterprise custom connectors; Claude.ai web; remote-capable IDEs |
+| **Runs where** | Your machine (`npx -y @meertrack/mcp`) | Meertrack's Fly.io fleet (`https://mcp.meertrack.com/mcp`) |
+| **Auth** | `MEERTRACK_API_KEY` env var | `Authorization: Bearer mt_live_…` header |
+| **Plan gating** | Works on Claude Pro, Team, Enterprise | Claude Desktop "Add custom connector" is **Team/Enterprise only** |
+
+**If you're on Claude Pro, use the local (stdio) path.** The "Add custom
+connector" button in the Claude Desktop settings is gated to Team/Enterprise,
+and pasting `https://mcp.meertrack.com/mcp` there won't do anything on a Pro
+plan.
+
+## Get an API key
+
+Mint a production key at **Settings → API Keys** in the Meertrack app. Keys
+start with `mt_live_`. Only production keys work; there is no `mt_test_`
+flavour.
+
+> **Rate limits.** Each API key shares a **60 requests/minute** budget enforced
+> upstream. If you run the MCP from multiple clients at once (Claude Desktop +
+> Cursor + a background agent) they all draw from the same bucket. Mint a
+> separate key per workstation or per agent to isolate budgets. The tool-error
+> message on 429 includes both a human-readable reset time and the raw
+> `X-RateLimit-Reset` epoch so the agent can back off automatically.
+
+---
+
+## Local install: recommended default
+
+All local-mode clients use the same shape: `npx -y @meertrack/mcp` with
+`MEERTRACK_API_KEY` in the environment. What differs is the config file and
+the surrounding JSON key.
+
+Drop-in copies of every config file below live in [`examples/`](examples/).
+
+### Claude Desktop (all plans)
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "meertrack": {
+      "command": "npx",
+      "args": ["-y", "@meertrack/mcp"],
+      "env": {
+        "MEERTRACK_API_KEY": "mt_live_..."
+      }
+    }
+  }
+}
+```
+
+> **Gotcha**: Claude Desktop only re-reads this file on launch. Fully quit
+> (⌘Q on macOS) and reopen. Reloading the window is not enough.
+
+### Cursor
+
+Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "meertrack": {
+      "command": "npx",
+      "args": ["-y", "@meertrack/mcp"],
+      "env": {
+        "MEERTRACK_API_KEY": "mt_live_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add meertrack npx -y @meertrack/mcp \
+  --env MEERTRACK_API_KEY=mt_live_...
+```
+
+### VS Code (GitHub Copilot MCP)
+
+Edit `.vscode/mcp.json` (per-workspace) or the user settings equivalent:
+
+```json
+{
+  "servers": {
+    "meertrack": {
+      "command": "npx",
+      "args": ["-y", "@meertrack/mcp"],
+      "env": {
+        "MEERTRACK_API_KEY": "mt_live_..."
+      }
+    }
+  }
+}
+```
+
+> **Gotcha**: VS Code uses `servers`, not `mcpServers`. The Copilot MCP picker
+> won't find your server if you use the Claude Desktop key.
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "meertrack": {
+      "command": "npx",
+      "args": ["-y", "@meertrack/mcp"],
+      "env": {
+        "MEERTRACK_API_KEY": "mt_live_..."
+      }
+    }
+  }
+}
+```
+
+> **Gotcha**: Windsurf's remote-connector shape uses `serverUrl`, not `url`.
+> For the stdio config above, the shape is identical to Claude Desktop.
+
+### Cline (VS Code extension)
+
+Cline's settings panel → "MCP Servers" → paste:
+
+```json
+{
+  "mcpServers": {
+    "meertrack": {
+      "command": "npx",
+      "args": ["-y", "@meertrack/mcp"],
+      "env": {
+        "MEERTRACK_API_KEY": "mt_live_..."
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+---
+
+## Remote install: Team/Enterprise + claude.ai web
+
+All remote clients point at the same URL:
+
+```
+https://mcp.meertrack.com/mcp
+```
+
+...with `Authorization: Bearer mt_live_…`. One shared hosted server. Nothing
+to install locally.
+
+### Claude Desktop (Team / Enterprise only: "Add custom connector")
+
+Settings → Connectors → **Add custom connector** → paste the URL above and
+your bearer token when prompted. The "Add custom connector" button is not
+visible on Pro; use the stdio path above instead.
+
+### Claude.ai web (Connectors)
+
+Same as above in the web app's Connectors panel.
+
+### Cursor (remote MCP)
+
+```json
+{
+  "mcpServers": {
+    "meertrack": {
+      "url": "https://mcp.meertrack.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mt_live_..."
+      }
+    }
+  }
+}
+```
+
+### ChatGPT MCP connectors
+
+Paste the URL and bearer in the ChatGPT "Add MCP" dialog. Note: ChatGPT's
+bearer support is minimal today; full OAuth parity is tracked as Phase 11.
+
+### n8n / Zapier / …any Streamable HTTP client
+
+- Endpoint: `https://mcp.meertrack.com/mcp`
+- Method: `POST`
+- Headers: `Authorization: Bearer mt_live_…`, `Accept: application/json, text/event-stream`, `MCP-Protocol-Version: 2025-11-25`
+
+---
+
+## The 8 tools
+
+All read-only, all snake_case. Collection returns use the `list_` prefix;
+single-item returns use `get_`. Every list response includes
+`pagination.next_cursor` and `pagination.has_more`, and agents must pass
+`next_cursor` back as `cursor` to fetch the next page.
+
+| Domain | Tool | Wraps | Notes |
+| --- | --- | --- | --- |
+| Identity | [`whoami`](src/tools/whoami.ts) | `GET /me` | Confirms workspace + subscription + rate-limit snapshot. Call first. |
+| Competitors | [`list_competitors`](src/tools/list_competitors.ts) | `GET /competitors` | Defaults to `expand=full` so agents don't round-trip for socials/pages. |
+| Competitors | [`get_competitor`](src/tools/get_competitor.ts) | `GET /competitors/{id}` | 11 tracked sections (blog, pricing, jobs, …) with per-section caps. |
+| Activity | [`list_activities`](src/tools/list_activities.ts) | `GET /activity` | Core "what shipped" feed. Default `limit=50` to stay under tool-result size limits. |
+| Activity | [`get_activity_item`](src/tools/get_activity_item.ts) | `GET /activity/{row_uuid}` | Drill-in for a specific row's full payload. |
+| Digests | [`list_digests`](src/tools/list_digests.ts) | `GET /digests` | Cursor-paginated weekly digests. No `total` field (unlike activity). |
+| Digests | [`list_latest_digests`](src/tools/list_latest_digests.ts) | `GET /digests/latest` | No params; one-shot "what happened this week". |
+| Digests | [`get_digest`](src/tools/get_digest.ts) | `GET /digests/{id}` | Full summary + themes for one competitor × period. |
+
+Full input / output / error-code documentation is on the tool descriptions
+themselves, and the MCP client displays them inline.
+
+## The 3 prompts
+
+Slash commands in Claude Desktop / Cursor / Claude Code / any prompt-capable
+MCP client. Each one chains tool calls into a complete workflow.
+
+| Prompt | Args | Chains |
+| --- | --- | --- |
+| [`/weekly_recap`](src/prompts/weekly_recap.ts) | none | `list_latest_digests` → per-competitor summary + highlights |
+| [`/competitor_deep_dive`](src/prompts/competitor_deep_dive.ts) | `competitor_name` | `list_competitors` → `get_competitor` → `list_activities` (last 30d) |
+| [`/whats_new`](src/prompts/whats_new.ts) | `days?` (default 7) | `list_activities` from `now - N days`, grouped by competitor |
+
+### Example invocations
+
+- `/weekly_recap`
+- `/competitor_deep_dive competitor_name="Acme"`
+- `/whats_new days="14"`
+
+See [`examples/prompts.md`](examples/prompts.md) for a dozen copy-paste user
+prompts grouped by use case (weekly check-in, feature spec research, pricing
+comparison, board-deck prep).
+
+---
+
+## Troubleshooting
+
+When the upstream API returns an error, the MCP tool response surfaces the
+upstream `code` in the error text. Map them:
+
+| Upstream `code` | What it means | Fix |
+| --- | --- | --- |
+| `unauthorized` | Key is invalid, revoked, or expired | Mint a new key at Settings → API Keys and update the config |
+| `competitor_inactive` | Competitor is archived in this workspace | Reactivate the competitor in the dashboard |
+| `forbidden_competitor` | The `id` you passed isn't in this workspace | Call `list_competitors` first to discover valid ids |
+| `rate_limited` | 60 req/min cap hit | Wait until the reset timestamp in the error message, or mint a second key for the other client |
+| `not_found` | No such row in this workspace | The id is either wrong or belongs to a different workspace |
+| `invalid_parameter` / `invalid_cursor` | Bad input | Check the error message; cursors expire, so re-list from the start |
+
+**Other common snags**
+
+- Claude Desktop didn't pick up your config → **quit and relaunch the app**,
+  not just close the window. Config is read at launch.
+- `command not found: npx` → install Node ≥ 20. The MCP pins `engines.node`.
+- Remote URL returns 401 with `WWW-Authenticate: Bearer` → your bearer is
+  missing, malformed, or doesn't start with `mt_live_`.
+- You see 401s that clear up when you refresh the key → the bearer is fine;
+  this is a spec-conformant "please authenticate" from the MCP. Send the
+  `Authorization` header.
+- Running both stdio and remote with the **same key** → you're sharing a
+  60/min budget across both. Mint separate keys per client.
+
+---
+
+## Semantic versioning
+
+MCP tool schemas are part of the public API contract; agents cache them. So:
+
+- **MAJOR**: a tool is removed, or an existing tool's input/output schema
+  breaks (required arg added, field renamed, enum value removed).
+- **MINOR**: a new tool, a new optional argument, or a new prompt.
+- **PATCH**: bug fixes, description improvements, internal refactors with no
+  schema impact.
+
+See [CHANGELOG.md](CHANGELOG.md) for the release history.
+
+## Security & privacy
+
+- [SECURITY.md](SECURITY.md): disclosure policy (`security@meertrack.com`),
+  in-scope surface.
+- [docs/PRIVACY.md](docs/PRIVACY.md): the MCP layer is stateless; bearers are
+  forwarded per-request and nothing is persisted.
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): request flow diagram.
+- [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md): what gets logged, and how
+  bearer tokens are redacted.
+
+## License
+
+MIT.

package/dist/auth.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bearer resolution for both transports.
+ *
+ * - `stdio`: key comes from `MEERTRACK_API_KEY` once at process start.
+ * - `http` : key comes from the `Authorization` header per request, with a
+ *            `?api_key=` query-string fallback for clients that can't set
+ *            custom headers (some Claude Desktop builds, claude.ai web).
+ *
+ * In both modes we validate the `mt_live_` prefix locally before the first
+ * upstream call — fail fast with a useful message instead of round-tripping
+ * an upstream 401 for an obviously malformed key.
+ */
+export declare const API_KEY_PREFIX = "mt_live_";
+/** True iff `value` begins with `mt_live_`. Does not assert length/charset. */
+export declare function hasApiKeyPrefix(value: string): boolean;
+/** Strict format check: prefix + non-empty base64url body. */
+export declare function isWellFormedApiKey(value: string): boolean;
+export declare class MissingApiKeyError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidApiKeyError extends Error {
+    constructor(message: string);
+}
+/**
+ * stdio: resolve the bearer from the environment exactly once at startup.
+ * Throws a descriptive error that the entrypoint can surface on stderr and
+ * exit with. Never logs the key itself.
+ */
+export declare function resolveEnvApiKey(env?: NodeJS.ProcessEnv): string;
+/**
+ * HTTP mode: resolution outcome per request. Successful cases carry the
+ * forwardable bearer; failures carry everything the transport needs to emit
+ * a spec-conformant 401 (WWW-Authenticate header value included).
+ */
+export type HttpAuthResolution = {
+    ok: true;
+    apiKey: string;
+    source: "header" | "query";
+} | {
+    ok: false;
+    status: 401;
+    code: "unauthorized";
+    message: string;
+    wwwAuthenticate: string;
+};
+export interface HttpAuthContext {
+    /** Case-insensitive header lookup — works for `Headers`, plain objects, and Hono's helpers. */
+    header: (name: string) => string | null | undefined;
+    /** Parsed search params for the inbound URL. */
+    searchParams: URLSearchParams;
+    /** Public URL of the `/.well-known/oauth-protected-resource` document. */
+    protectedResourceMetadataUrl: string;
+}
+/**
+ * Extract a bearer from an incoming HTTP request. Header wins over query when
+ * both are set. If absent or malformed, return an `ok: false` resolution
+ * carrying a fully-formed `WWW-Authenticate` header value — the transport
+ * emits the 401 without touching the upstream API.
+ */
+export declare function extractHttpBearer(ctx: HttpAuthContext): HttpAuthResolution;
+/** Extract a bearer token from an `Authorization` header value, or `null` if absent/malformed. */
+export declare function parseBearerHeader(value: string): string | null;
+/**
+ * MCP 2025-11-25 §Authorization / RFC 9728: 401 responses on the HTTP transport
+ * MUST advertise where the client can find Protected Resource Metadata. Clients
+ * use this to discover how to authenticate (static bearer today; OAuth in a
+ * future version).
+ */
+export declare function buildWwwAuthenticateHeader(protectedResourceMetadataUrl: string): string;
+/**
+ * Redact every `mt_live_…` token in `value`. Apply to any string before
+ * writing it to logs or error messages. Also redacts `Bearer mt_live_…`.
+ */
+export declare function redactApiKeys(value: string): string;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,cAAc,aAAa,CAAC;AAKzC,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAcR;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,GACxD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,GAAG,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD,gDAAgD;IAChD,YAAY,EAAE,eAAe,CAAC;IAC9B,0EAA0E;IAC1E,4BAA4B,EAAE,MAAM,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,kBAAkB,CAgC1E;AAED,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,4BAA4B,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/auth.js

@@ -0,0 +1,109 @@
+/**
+ * Bearer resolution for both transports.
+ *
+ * - `stdio`: key comes from `MEERTRACK_API_KEY` once at process start.
+ * - `http` : key comes from the `Authorization` header per request, with a
+ *            `?api_key=` query-string fallback for clients that can't set
+ *            custom headers (some Claude Desktop builds, claude.ai web).
+ *
+ * In both modes we validate the `mt_live_` prefix locally before the first
+ * upstream call — fail fast with a useful message instead of round-tripping
+ * an upstream 401 for an obviously malformed key.
+ */
+export const API_KEY_PREFIX = "mt_live_";
+/** Full pattern: `mt_live_` followed by base64url characters. */
+const API_KEY_PATTERN = /^mt_live_[A-Za-z0-9_-]+$/;
+/** True iff `value` begins with `mt_live_`. Does not assert length/charset. */
+export function hasApiKeyPrefix(value) {
+    return value.startsWith(API_KEY_PREFIX);
+}
+/** Strict format check: prefix + non-empty base64url body. */
+export function isWellFormedApiKey(value) {
+    return API_KEY_PATTERN.test(value);
+}
+export class MissingApiKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MissingApiKeyError";
+    }
+}
+export class InvalidApiKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidApiKeyError";
+    }
+}
+/**
+ * stdio: resolve the bearer from the environment exactly once at startup.
+ * Throws a descriptive error that the entrypoint can surface on stderr and
+ * exit with. Never logs the key itself.
+ */
+export function resolveEnvApiKey(env = process.env) {
+    const raw = env["MEERTRACK_API_KEY"];
+    if (!raw || raw.trim().length === 0) {
+        throw new MissingApiKeyError("MEERTRACK_API_KEY is not set. Mint a key at Settings → API Keys in the Meertrack app and export it before running the MCP server.");
+    }
+    const trimmed = raw.trim();
+    if (!hasApiKeyPrefix(trimmed)) {
+        throw new InvalidApiKeyError("MEERTRACK_API_KEY does not start with `mt_live_`. Only production keys (`mt_live_…`) are supported.");
+    }
+    return trimmed;
+}
+/**
+ * Extract a bearer from an incoming HTTP request. Header wins over query when
+ * both are set. If absent or malformed, return an `ok: false` resolution
+ * carrying a fully-formed `WWW-Authenticate` header value — the transport
+ * emits the 401 without touching the upstream API.
+ */
+export function extractHttpBearer(ctx) {
+    const headerValue = ctx.header("authorization") ?? ctx.header("Authorization");
+    const fromHeader = headerValue ? parseBearerHeader(headerValue) : null;
+    const fromQuery = ctx.searchParams.get("api_key");
+    const candidate = fromHeader ?? (fromQuery ? fromQuery.trim() : null);
+    const source = fromHeader ? "header" : "query";
+    const wwwAuthenticate = buildWwwAuthenticateHeader(ctx.protectedResourceMetadataUrl);
+    if (!candidate) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: "Missing API key. Send `Authorization: Bearer mt_live_…` (preferred) or `?api_key=mt_live_…` as a query-string fallback.",
+            wwwAuthenticate,
+        };
+    }
+    if (!hasApiKeyPrefix(candidate)) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: "API key does not start with `mt_live_`. Only production keys are supported — mint one at Settings → API Keys.",
+            wwwAuthenticate,
+        };
+    }
+    return { ok: true, apiKey: candidate, source };
+}
+/** Extract a bearer token from an `Authorization` header value, or `null` if absent/malformed. */
+export function parseBearerHeader(value) {
+    const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+    if (!match)
+        return null;
+    const token = match[1]?.trim() ?? "";
+    return token.length > 0 ? token : null;
+}
+/**
+ * MCP 2025-11-25 §Authorization / RFC 9728: 401 responses on the HTTP transport
+ * MUST advertise where the client can find Protected Resource Metadata. Clients
+ * use this to discover how to authenticate (static bearer today; OAuth in a
+ * future version).
+ */
+export function buildWwwAuthenticateHeader(protectedResourceMetadataUrl) {
+    return `Bearer realm="meertrack", resource_metadata="${protectedResourceMetadataUrl}"`;
+}
+/**
+ * Redact every `mt_live_…` token in `value`. Apply to any string before
+ * writing it to logs or error messages. Also redacts `Bearer mt_live_…`.
+ */
+export function redactApiKeys(value) {
+    return value.replace(/mt_live_[A-Za-z0-9_-]+/g, "mt_live_***");
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,84 @@
+import type { ActivityDetailResponse, ActivityListResponse, ChangeType, CompetitorDetailListResponse, CompetitorListResponse, CompetitorOverviewResponse, DigestLatestResponse, DigestListResponse, DigestResponse, MeResponse, SectionSlug } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.meertrack.com/v1";
+/** Resolve the upstream base URL, honoring `MEERTRACK_API_BASE_URL` for staging/local. */
+export declare function resolveBaseUrl(override?: string): string;
+export interface MeertrackClientOptions {
+    baseUrl?: string;
+    apiKey: string;
+    /** Test/DI seam — defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Optional override for the User-Agent suffix (tests). */
+    userAgent?: string;
+    /**
+     * Fired after every upstream response (success or failure) with the parsed
+     * `X-Request-Id` header. Used by the HTTP transport to fold the upstream
+     * trace ID into the per-request structured log line so a Fly log entry can
+     * be cross-referenced against Meertrack backend logs.
+     */
+    onUpstreamResponse?: (info: {
+        status: number;
+        requestId: string | null;
+    }) => void;
+}
+/**
+ * Typed error thrown for every non-2xx upstream response. `code` reflects the
+ * upstream error envelope's `error.code` when present, else a generic fallback
+ * (`http_<status>`, `transport_error`, `invalid_response`).
+ */
+export declare class MeertrackApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly rateLimitReset?: number;
+    constructor(params: {
+        status: number;
+        code: string;
+        message: string;
+        rateLimitReset?: number;
+    });
+}
+export interface ListActivityParams {
+    competitor_ids?: string[];
+    sections?: SectionSlug[];
+    change_types?: ChangeType[];
+    from?: string;
+    to?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface ListCompetitorsParams {
+    active?: boolean;
+    ids?: string[];
+    expand?: "full";
+}
+export interface ListDigestsParams {
+    competitor_id?: string[];
+    from?: string;
+    to?: string;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * Thin typed wrapper over `api.meertrack.com/v1`. Each method is a 1:1 shadow
+ * of its endpoint. No retry/backoff in v1 — a 429 throws with the reset
+ * epoch and the caller (the MCP tool layer) decides what to tell the agent.
+ */
+export declare class MeertrackClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly onUpstreamResponse?;
+    constructor(opts: MeertrackClientOptions);
+    me(): Promise<MeResponse>;
+    listCompetitors(params?: ListCompetitorsParams): Promise<CompetitorListResponse | CompetitorDetailListResponse>;
+    getCompetitor(id: string): Promise<CompetitorOverviewResponse>;
+    listActivity(params?: ListActivityParams): Promise<ActivityListResponse>;
+    getActivityItem(rowUuid: string): Promise<ActivityDetailResponse>;
+    listDigests(params?: ListDigestsParams): Promise<DigestListResponse>;
+    listLatestDigests(): Promise<DigestLatestResponse>;
+    getDigest(id: string): Promise<DigestResponse>;
+    private request;
+}
+/** Parse an upstream non-2xx into a `MeertrackApiError`. Exported for tests. */
+export declare function toApiError(response: Response): Promise<MeertrackApiError>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}