@affset/mcp 0.1.0 → 0.2.0

package/.env.example

@@ -12,6 +12,11 @@ AFFSET_NAMESPACE=your-namespace
 # Optional. Per-request HTTP timeout in milliseconds (1000–300000; default 30000).
 # AFFSET_REQUEST_TIMEOUT_MS=30000
 
+# Optional. Origin the API-reference documentation resources are fetched from
+# (origin only, no path). Defaults to the affset marketing site; override to
+# point at a staging docs host. Fetched anonymously — no API key is sent here.
+# AFFSET_DOCS_URL=https://affset.com
+
 # Optional. Set to true to register only read-only tools (no create/update/delete/
 # cut) — recommended for stats/reporting sessions, especially with an MCP client
 # that auto-approves tool calls. See README Security section. Default false.

package/README.md

@@ -9,32 +9,34 @@ It's a thin wrapper over the existing affset tenant API (`Bearer` token +
 
 ## Tools
 
-| Tool                    | What it does                                                                                                                                                                                                                                                    |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `whoami`                | Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only.                                                                                                     |
-| `get_stats`             | Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, …). Returns clicks, conversions, CR, payout, media cost and ROI as a table. Sub columns use the tenant's sub labels when configured.                                               |
-| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                              |
-| `list_zones`            | List traffic-source zones (status / name filter, pagination).                                                                                                                                                                                                   |
-| `list_team`             | List team members (email, role, manager). **Never returns API tokens.**                                                                                                                                                                                         |
-| `create_campaign`       | Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, **paused**, global payout rule, ready tracking link with `source_click_id={clickid}` + sub placeholders. **Dry-run by default**; `confirm: true` to apply. |
-| `set_campaign_status`   | **Run** or **pause** a campaign (`action: "run" \| "pause"`). **Dry-run by default**; `confirm: true` to apply. Running can hit the plan's active-campaign limit.                                                                                               |
-| `update_campaign`       | Partial update (name, offer URL, status, rate, budgets, dates, …). **Dry-run by default**; `confirm: true` to apply. Prefer `set_campaign_status` for run/pause.                                                                                                |
-| `create_zone`           | Create a traffic-source zone (name + optional postback/site/traffic-back URLs). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                      |
-| `update_zone`           | Partial update (name, status, URLs). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL.                                                                                                                                              |
-| `get_zone_url`          | The `/serve` URL to paste into a network's campaign settings — rotates across the zone's **active** campaigns. Prefilled sub convention, optional `cost` macro. Warns when no active campaigns are visible.                                                     |
-| `get_tracking_link`     | The `/track/click` link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Re-derives what `create_campaign` echoed on create.                                                                            |
-| `cut_zones`             | Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                |
-| `list_payout_rules`     | List a campaign's global + per-zone payout rules and its `payout_goal_type`.                                                                                                                                                                                    |
-| `set_payout_rule`       | Upsert a global or zone-specific payout. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                      |
-| `delete_payout_rule`    | Delete a global or zone-specific payout rule. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                 |
-| `set_payout_goal`       | Set or clear `payout_goal_type` (goal-based conversions). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                     |
-| `list_targeting_types`  | Catalog of targeting rule types, flagging the seeded ones `/serve` never evaluates.                                                                                                                                                                             |
-| `list_targeting_rules`  | List a campaign's targeting rules, flagging any that have no effect.                                                                                                                                                                                            |
-| `set_targeting_rule`    | Upsert one targeting rule (safe merge), normalised to what `/serve` matches. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                  |
-| `remove_targeting_rule` | Remove one targeting rule by id or type+method. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                               |
-| `list_sub_labels`       | List tenant display names for sub1–sub5.                                                                                                                                                                                                                        |
-| `set_sub_labels`        | Set or clear sub labels (partial; `null` clears). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                             |
-| `list_conversions`      | List conversion audit records (payout, spend, pixel type, payload, postback). Optional client-side filters on the current page.                                                                                                                                 |
+| Tool                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `whoami`                | Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only.                                                                                                                                                                                                                                                                      |
+| `get_stats`             | Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, advertiser, publisher, …), optionally narrowed with `advertiser_email`/`publisher_email` filters (one user, any group_by). Returns clicks, conversions, CR, payout, media cost and ROI as a table. Sub columns use the tenant's sub labels when configured. Per-user groupings and filters are owner/manager plus the matching side's manager role. |
+| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                                                                                                                                                                                               |
+| `get_campaign`          | One campaign's full record — every field (untruncated offer URL, exact schedule, budgets/pacing, silent flag, payout goal type) plus its targeting rules and payout rules, in one call.                                                                                                                                                                                                                                          |
+| `list_zones`            | List traffic-source zones (status / name filter, pagination).                                                                                                                                                                                                                                                                                                                                                                    |
+| `list_team`             | List team members (email, role, manager). **Never returns API tokens.**                                                                                                                                                                                                                                                                                                                                                          |
+| `create_team_member`    | Invite a team member (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). A scoped manager key can only create its own managed role, self-assigned. Returns the new API key **once** — `list_team` never shows it again. **Dry-run by default**; `confirm: true` to apply.                                                                                                                            |
+| `create_campaign`       | Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, **paused**, global payout rule, ready tracking link with `source_click_id={clickid}` + sub placeholders. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                  |
+| `set_campaign_status`   | **Run** or **pause** a campaign (`action: "run" \| "pause"`). **Dry-run by default**; `confirm: true` to apply. Running can hit the plan's active-campaign limit.                                                                                                                                                                                                                                                                |
+| `update_campaign`       | Partial update (name, offer URL, status, rate, budgets, dates, …). **Dry-run by default**; `confirm: true` to apply. Prefer `set_campaign_status` for run/pause.                                                                                                                                                                                                                                                                 |
+| `create_zone`           | Create a traffic-source zone (name + optional postback/site/traffic-back URLs). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                       |
+| `update_zone`           | Partial update (name, status, URLs). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL.                                                                                                                                                                                                                                                                                                               |
+| `get_zone_url`          | The `/serve` URL to paste into a network's campaign settings — rotates across the zone's **active** campaigns. Prefilled sub convention, optional `cost` macro. Warns when no active campaigns are visible.                                                                                                                                                                                                                      |
+| `get_tracking_link`     | The `/track/click` link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Re-derives what `create_campaign` echoed on create.                                                                                                                                                                                                                                             |
+| `cut_zones`             | Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                 |
+| `list_payout_rules`     | List a campaign's global + per-zone payout rules and its `payout_goal_type`.                                                                                                                                                                                                                                                                                                                                                     |
+| `set_payout_rule`       | Upsert a global or zone-specific payout. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                       |
+| `delete_payout_rule`    | Delete a global or zone-specific payout rule. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                  |
+| `set_payout_goal`       | Set or clear `payout_goal_type` (goal-based conversions). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                      |
+| `list_targeting_types`  | Catalog of targeting rule types, flagging the seeded ones `/serve` never evaluates.                                                                                                                                                                                                                                                                                                                                              |
+| `list_targeting_rules`  | List a campaign's targeting rules, flagging any that have no effect.                                                                                                                                                                                                                                                                                                                                                             |
+| `set_targeting_rule`    | Upsert one targeting rule (safe merge), normalised to what `/serve` matches. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                   |
+| `remove_targeting_rule` | Remove one targeting rule by id or type+method. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                |
+| `list_sub_labels`       | List tenant display names for sub1–sub5.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `set_sub_labels`        | Set or clear sub labels (partial; `null` clears). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                              |
+| `list_conversions`      | List conversion audit records (payout, spend, pixel type, payload, postback). Optional client-side filters on the current page.                                                                                                                                                                                                                                                                                                  |
 
 ### Which URL do I give the network?
 
@@ -63,22 +65,46 @@ URL. Both URL types also require an active zone. Geo whitelist is enforced in `/
 only — the direct tracking link is **not** geo-gated, but it still requires an active,
 currently serviceable campaign.
 
+## Documentation resources
+
+Beyond the tools, the server exposes the affset **API reference** as MCP
+[resources](https://modelcontextprotocol.io/docs/concepts/resources), so an
+assistant can answer "how does conversion tracking work?" or "what does `/serve`
+accept?" from the docs themselves — not just from the tool schemas.
+
+| Resource URI                       | Type               | Content                                                      |
+| ---------------------------------- | ------------------ | ------------------------------------------------------------ |
+| `affset://docs/api-reference`      | `text/markdown`    | The full API reference — endpoints, auth, roles, examples.   |
+| `affset://docs/api-reference.json` | `application/json` | The same reference as structured data, for programmatic use. |
+
+They're the exact content published at [affset.com/docs](https://affset.com/docs),
+generated from one source, and **fetched at read time** from `AFFSET_DOCS_URL`
+(`{origin}/api-reference.md` and `{origin}/api-reference.json`) — so they always
+reflect the currently published docs, not a copy pinned to this package. The
+fetch sends **no credentials** (the docs are public and live on a different
+origin than the tenant API). HTML SPA fallbacks, redirects, invalid JSON, and
+oversized bodies are rejected. Both resources are always available, including
+under `AFFSET_READ_ONLY`.
+
 ## Configuration
 
 All config comes from environment variables (never hard-coded):
 
-| Variable                    | Description                                                                                                                                                                                                                                                                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AFFSET_BASE_URL`           | Origin of the affset API, e.g. `https://api.affset.com` (no path/query/credentials). Must be `https` unless the host is `localhost`/`127.0.0.1`/`::1` — plain http would send the API key in cleartext.                                                                                             |
-| `AFFSET_API_KEY`            | Tenant API key. Its namespace must match `AFFSET_NAMESPACE`.                                                                                                                                                                                                                                        |
-| `AFFSET_NAMESPACE`          | Tenant namespace (lowercase letters, numbers, hyphens; 3–63 chars — same rules as signup).                                                                                                                                                                                                          |
-| `AFFSET_READ_ONLY`          | Optional, default `false`. Set to `true`/`1` to register only the read-only tools (`whoami`, `get_stats`, every `list_*`, `get_zone_url`, `get_tracking_link`) — every create/update/delete/cut tool is unavailable, not just gated behind confirm. See [Security](#security) for why this matters. |
-| `AFFSET_REQUEST_TIMEOUT_MS` | Optional, default `30000`. Per-request HTTP timeout in milliseconds (`1000`–`300000`).                                                                                                                                                                                                              |
+| Variable                    | Description                                                                                                                                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AFFSET_BASE_URL`           | Origin of the affset API, e.g. `https://api.affset.com` (no path/query/credentials). Must be `https` unless the host is `localhost`/`127.0.0.1`/`::1` — plain http would send the API key in cleartext.                                                                                                             |
+| `AFFSET_API_KEY`            | Tenant API key. Its namespace must match `AFFSET_NAMESPACE`.                                                                                                                                                                                                                                                        |
+| `AFFSET_NAMESPACE`          | Tenant namespace (lowercase letters, numbers, hyphens; 3–63 chars — same rules as signup).                                                                                                                                                                                                                          |
+| `AFFSET_READ_ONLY`          | Optional, default `false`. Set to `true`/`1` to register only the read-only tools (`whoami`, `get_stats`, `get_campaign`, every `list_*`, `get_zone_url`, `get_tracking_link`) — every create/update/delete/cut tool is unavailable, not just gated behind confirm. See [Security](#security) for why this matters. |
+| `AFFSET_REQUEST_TIMEOUT_MS` | Optional, default `30000`. Per-request HTTP timeout in milliseconds (`1000`–`300000`).                                                                                                                                                                                                                              |
+| `AFFSET_DOCS_URL`           | Optional, default `https://affset.com`. Origin the API-reference [documentation resources](#documentation-resources) are fetched from (origin only, no path). Fetched anonymously — no API key is sent here.                                                                                                        |
 
 See [`.env.example`](.env.example).
 
 ## Install
 
+Requires Node.js 22.13 or newer.
+
 ### From npm (recommended)
 
 No clone, no build — your MCP client runs it with `npx`. For **Claude Desktop**
@@ -110,9 +136,44 @@ claude mcp add affset \
   -- npx -y @affset/mcp
 ```
 
+Same env flags with `-- npx -y github:affset/mcp` if you install from GitHub
+instead of the npm registry (see below).
+
 Add `-e AFFSET_READ_ONLY=true` for a stats/reporting-only instance (see
 [Security](#security)).
 
+### From GitHub directly (no npm publish required)
+
+`npx` can install straight from the git repo instead of the npm registry —
+useful if you'd rather not publish, or just want to track `main` without a
+release step:
+
+```json
+{
+  "mcpServers": {
+    "affset": {
+      "command": "npx",
+      "args": ["-y", "github:affset/mcp"],
+      "env": {
+        "AFFSET_BASE_URL": "https://api.affset.com",
+        "AFFSET_API_KEY": "sk_live_...",
+        "AFFSET_NAMESPACE": "your-namespace"
+      }
+    }
+  }
+}
+```
+
+A push to `main` makes that commit available to this unpinned install path — no
+npm publish is required. On resolution, npm fetches the repository and runs the
+`prepare` script to build `dist/` before starting the binary. npm may reuse its
+cache on later starts; an already running MCP process is not updated until it is
+restarted and `npx` resolves the dependency again.
+
+For reproducible deployments, pin a reviewed ref instead of floating on `main`:
+`github:affset/mcp#<commit-sha>` or `github:affset/mcp#<tag>`. Restart the MCP
+process deliberately when you want it to resolve and run a newer revision.
+
 ### From source
 
 ```bash
@@ -128,12 +189,20 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
 
 > **list paused campaigns** → `list_campaigns(status: "paused")`
 >
+> **show me everything about campaign 42** → `get_campaign(campaign_id: 42)`
+>
 > **show zones** → `list_zones()`
 >
 > **who's on the team?** → `list_team()`
 >
+> **add sarah@offer.com as a publisher** → `create_team_member(email: "sarah@offer.com", role: "publisher")` (dry-run) → confirm
+>
 > **stats for today by sub1** → `get_stats(group_by: "sub1")`
 >
+> **stats by advertiser** → `get_stats(group_by: "advertiser_email")`
+>
+> **stats for one publisher, grouped by zone** → `get_stats(group_by: "zone_id", publisher_email: "publisher@example.com")`
+>
 > **create a RichAds zone with postback** → `create_zone(name: "RichAds", postback_url: "https://…/{source_click_id}")` (dry-run) → confirm
 >
 > **create a campaign for offer X, advertiser buyer@example.com, geo BR, payout $2**
@@ -173,7 +242,12 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
 ## Notes & limits
 
 - **`get_stats` groups by one dimension per call.** Drill-down is a sequence of
-  calls, each narrowing with `campaign_ids` / `zone_ids` / `sub1..sub5` filters.
+  calls, each narrowing with `campaign_ids` / `zone_ids` / `sub1..sub5` /
+  `conversion_type` / `advertiser_email` / `publisher_email` filters. The two email
+  filters select one user's campaigns or zones without changing `group_by`; access
+  is limited to owner/manager or the corresponding scoped manager role. Filtering
+  by `conversion_type` returns conversion rows only (impressions, clicks and media
+  cost are zero).
 - **`spend` means `media_cost`** (your traffic cost). ROI / spend thresholds need
   cost data imported for the slice.
 - List endpoints have **no server-side name search** — `name_contains` filters the
@@ -206,7 +280,11 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
   has no campaign/zone/date filters; optional filters apply to the current page only.
   Rows do not include campaign_id/zone_id. Publisher-side roles do not see `spend` and
   advertiser-side roles do not see `payout`, so `zero_payout` needs a role that can.
-- Out of scope: deleting campaigns/zones/conversions, billing, creative management, invite flows.
+- **`create_team_member`** creates the API key directly (like the dashboard's "Add Team
+  Member") — it does not send an invite email. Hand the returned key to the person
+  yourself. Revoking/removing a team member is not yet a tool; use the dashboard's
+  Team page.
+- Out of scope: deleting campaigns/zones/conversions, billing, creative management.
 - **Tenant signup is deliberately not a tool.** `POST /api/public/create-instance`
   is Origin-gated and fails closed, which is what keeps signup browser-only; a
   server-side caller would have to spoof an allowlisted Origin to get past it. The
@@ -215,6 +293,44 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
   startup — so it could not use a tenant it just created. Sign up in the dashboard,
   then point a server instance at the new namespace.
 
+## Using as a library
+
+Since 0.2.0 the package doubles as a runtime-agnostic library: everything the
+stdio server registers (tools, docs resources, read-only stripping) is exposed
+as one helper that runs on any fetch-capable runtime — Node ≥22.13 or Cloudflare
+Workers. The hosted affset MCP gateway (`mcp.affset.com`, in progress) consumes
+exactly this surface, so the remote roster can never drift from stdio.
+
+```ts
+import { registerAffsetTools, type Config } from "@affset/mcp/core";
+
+const config: Config = {
+  baseUrl: "https://api.affset.com",
+  docsBaseUrl: "https://affset.com",
+  apiKey: perRequestKey, // e.g. an OAuth grant's backing credential
+  namespace: tenantNamespace,
+  requestTimeoutMs: 30_000,
+  readOnly: scope === "read", // never registers tools without readOnlyHint: true
+};
+
+registerAffsetTools(server, config); // server: your own McpServer instance
+```
+
+`registerAffsetTools` accepts your `McpServer` structurally, so your own
+`@modelcontextprotocol/sdk` install works — no need to match this package's
+copy. Env-var loading (`AFFSET_*`) is deliberately not part of the library
+surface; it belongs to the stdio entrypoint only. A third, optional
+`{ onToolCall }` argument reports only tool name, duration, and success/error
+status for transport-owned audit logging; arguments and output are never
+included.
+
+The library validates and normalizes `config` before registering anything.
+Remote API origins must use HTTPS (plain HTTP is accepted only on loopback),
+origins cannot contain credentials or paths, and invalid namespaces, timeouts,
+API keys, or non-boolean read-only settings fail closed at startup. The public
+declarations do not require Node ambient types, so the same import type-checks
+in Workers and other web-standard runtimes.
+
 ## Development
 
 ```bash
@@ -231,12 +347,17 @@ npm run dev          # watch mode
 
 - No secrets in the repo; credentials come from the environment at runtime.
 - `AFFSET_BASE_URL` must be `https` unless the host is loopback — no cleartext API key.
+- Tenant API responses are streamed under a 5 MB hard limit; larger bodies are
+  cancelled before parsing or reaching model context.
 - stdout is the JSON-RPC channel — all logs go to stderr.
 - `list_team` redacts API tokens.
 - All mutations (including creates) follow **show → confirm → apply**.
 - Create a **dedicated, least-privilege API key** for the MCP rather than reusing an
-  owner key, and give it an expiry — affset's RBAC roles (owner/manager/publisher/
-  advertiser) apply to MCP tool calls exactly as they do to the dashboard.
+  owner key, and give it an expiry — affset's RBAC roles (owner / manager /
+  publisher / advertiser / advertiser_manager / publisher_manager) apply to MCP
+  tool calls exactly as they do to the dashboard.
+- Pin GitHub installs to a reviewed commit or tag in long-lived environments. A
+  floating `main` spec can run newer repository code the next time `npx` resolves it.
 
 ### Prompt injection via conversion/click data
 

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import { type Config } from "./runtimeConfig.js";
+/** Thrown when the affset API returns a non-2xx response. */
+export declare class AffsetApiError extends Error {
+    readonly status: number;
+    /** Parsed JSON body when present (e.g. plan-limit details). */
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, 
+    /** Parsed JSON body when present (e.g. plan-limit details). */
+    body?: unknown | undefined);
+}
+type Query = Record<string, string | number | undefined>;
+/**
+ * Thin typed HTTP client over the affset tenant API. Injects the Bearer token
+ * and `X-Namespace` header on every request and normalises error handling.
+ */
+export declare class AffsetClient {
+    private readonly config;
+    constructor(config: Config);
+    /** Resolved once per process; the tenant timezone changes about never. */
+    private tenantTimezone?;
+    /**
+     * The tenant's timezone (IANA name). Date ranges must be resolved in it, not
+     * in the host machine's zone, so that a requested window lines up with the
+     * date buckets `/api/stats?group_by=date` returns.
+     *
+     * Falls back to UTC if the setting cannot be read — a stats query with a
+     * slightly-off window beats failing the whole call.
+     */
+    getTenantTimezone(): Promise<string>;
+    /**
+     * Tenant timezone for a write whose meaning depends on local midnight. Unlike
+     * stats reads, silently falling back to UTC here could change a schedule, so
+     * callers get the underlying API error and must stop the mutation.
+     */
+    getRequiredTenantTimezone(): Promise<string>;
+    private readTenantTimezone;
+    get<T>(path: string, query?: Query): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string, query?: Query): Promise<T>;
+    private request;
+}
+export {};

package/dist/client.js

@@ -1,3 +1,5 @@
+import { readResponseText, ResponseTooLargeError } from "./lib/readBody.js";
+import { normalizeRuntimeConfig } from "./runtimeConfig.js";
 /** Thrown when the affset API returns a non-2xx response. */
 export class AffsetApiError extends Error {
     status;
@@ -11,6 +13,8 @@ export class AffsetApiError extends Error {
         this.name = "AffsetApiError";
     }
 }
+/** Bound upstream memory use before JSON parsing or rendering into model context. */
+const MAX_API_RESPONSE_BYTES = 5_000_000;
 /**
  * Thin typed HTTP client over the affset tenant API. Injects the Bearer token
  * and `X-Namespace` header on every request and normalises error handling.
@@ -18,7 +22,7 @@ export class AffsetApiError extends Error {
 export class AffsetClient {
     config;
     constructor(config) {
-        this.config = config;
+        this.config = normalizeRuntimeConfig(config);
     }
     /** Resolved once per process; the tenant timezone changes about never. */
     tenantTimezone;
@@ -100,7 +104,16 @@ export class AffsetClient {
             }
             throw new AffsetApiError(0, `Network error calling ${method} ${path}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const text = await res.text();
+        let text;
+        try {
+            text = await readResponseText(res, MAX_API_RESPONSE_BYTES);
+        }
+        catch (err) {
+            if (err instanceof ResponseTooLargeError) {
+                throw new AffsetApiError(res.ok ? 0 : res.status, `Response too large calling ${method} ${path}: ${err.message}.`);
+            }
+            throw err;
+        }
         let data = null;
         if (text) {
             try {

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from "./runtimeConfig.js";
+export type { Config } from "./runtimeConfig.js";
+/**
+ * Read and validate config from the environment. Throws with an actionable
+ * message listing every missing variable — surfaced to the user at startup.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -1,31 +1,9 @@
+import { MAX_REQUEST_TIMEOUT_MS, MIN_REQUEST_TIMEOUT_MS, parseOriginUrl, validateApiKey, validateNamespace, } from "./runtimeConfig.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
-const MAX_TIMEOUT_MS = 300_000;
+/** Where the docs feeds live when AFFSET_DOCS_URL is not set. */
+const DEFAULT_DOCS_URL = "https://affset.com";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 const FALSY = new Set(["0", "false", "no", "off"]);
-/**
- * Same rules as lite-adserver signup: lowercase alnum + hyphens, 3–63 chars,
- * no leading/trailing hyphen, no consecutive hyphens. Keeps whoami's
- * `https://{namespace}.affset.com` URL from embedding attacker-chosen junk if
- * someone pastes a weird AFFSET_NAMESPACE into their MCP client config.
- */
-const NAMESPACE_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-/** Loopback hosts allowed to stay on plain http — everything else must be https. */
-function isLoopbackHost(hostname) {
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "::1" ||
-        hostname.endsWith(".localhost"));
-}
-function namespaceError(namespace) {
-    if (namespace.length < 3 || namespace.length > 63) {
-        return "AFFSET_NAMESPACE must be 3–63 characters.";
-    }
-    if (!NAMESPACE_RE.test(namespace) || namespace.includes("--")) {
-        return ("AFFSET_NAMESPACE must be lowercase letters, numbers, and hyphens only " +
-            "(no leading/trailing or consecutive hyphens).");
-    }
-    return null;
-}
 /**
  * Read and validate config from the environment. Throws with an actionable
  * message listing every missing variable — surfaced to the user at startup.
@@ -45,38 +23,20 @@ export function loadConfig(env = process.env) {
         throw new Error(`Missing required environment variable(s): ${missing.join(", ")}. ` +
             `See .env.example for the expected values.`);
     }
-    const nsErr = namespaceError(namespace);
-    if (nsErr)
-        throw new Error(nsErr);
-    const normalized = baseUrl.replace(/\/+$/, "");
-    let parsed;
-    try {
-        parsed = new URL(normalized);
-    }
-    catch {
-        throw new Error(`AFFSET_BASE_URL is not a valid URL: ${baseUrl}`);
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new Error(`AFFSET_BASE_URL must be http(s), got ${parsed.protocol}`);
-    }
-    if (parsed.username || parsed.password) {
-        throw new Error("AFFSET_BASE_URL must not contain embedded credentials.");
-    }
-    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash) {
-        throw new Error("AFFSET_BASE_URL must be an origin only (scheme, host, and optional port; no path, query, or fragment).");
-    }
-    // Plain http sends the Bearer API key in cleartext. Only loopback (local dev /
-    // wrangler dev) is exempt — anything else must be https.
-    if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-        throw new Error(`AFFSET_BASE_URL must be https for a non-local host (got http://${parsed.hostname}) — ` +
-            `plain http would send the API key in cleartext.`);
-    }
+    validateNamespace(namespace, "AFFSET_NAMESPACE");
+    const parsedApiKey = validateApiKey(apiKey, "AFFSET_API_KEY");
+    // Plain http on AFFSET_BASE_URL sends the Bearer API key in cleartext; the
+    // helper refuses it for non-loopback hosts.
+    const parsed = parseOriginUrl(baseUrl, "AFFSET_BASE_URL", true);
+    // Optional — the docs feeds are public, so this only sets where to fetch them.
+    const docsRaw = env.AFFSET_DOCS_URL?.trim();
+    const docsBaseUrl = parseOriginUrl(docsRaw || DEFAULT_DOCS_URL, "AFFSET_DOCS_URL").origin;
     const timeoutRaw = env.AFFSET_REQUEST_TIMEOUT_MS?.trim();
     let requestTimeoutMs = DEFAULT_TIMEOUT_MS;
     if (timeoutRaw) {
         const n = Number(timeoutRaw);
-        if (!Number.isSafeInteger(n) || n < 1000 || n > MAX_TIMEOUT_MS) {
-            throw new Error(`AFFSET_REQUEST_TIMEOUT_MS must be an integer between 1000 and ${MAX_TIMEOUT_MS}.`);
+        if (!Number.isSafeInteger(n) || n < MIN_REQUEST_TIMEOUT_MS || n > MAX_REQUEST_TIMEOUT_MS) {
+            throw new Error(`AFFSET_REQUEST_TIMEOUT_MS must be an integer between ${MIN_REQUEST_TIMEOUT_MS} and ${MAX_REQUEST_TIMEOUT_MS}.`);
         }
         requestTimeoutMs = n;
     }
@@ -91,7 +51,8 @@ export function loadConfig(env = process.env) {
     }
     return {
         baseUrl: parsed.origin,
-        apiKey: apiKey,
+        docsBaseUrl,
+        apiKey: parsedApiKey,
         namespace: namespace,
         requestTimeoutMs,
         readOnly,

package/dist/core.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime-agnostic library surface of @affset/mcp (REMOTE-MCP-PRD.md §5.6).
+ *
+ * Everything exported here runs on any fetch-capable runtime (Node ≥22.13,
+ * Cloudflare Workers) — no `process.env`, no `node:` imports. The stdio
+ * entrypoint (`dist/index.js`, the `affset-mcp` bin) layers env-var loading on
+ * top of this; the remote MCP gateway imports this surface directly and
+ * supplies per-grant credentials instead.
+ *
+ * `loadConfig` (env-var parsing) is deliberately NOT exported: it is the
+ * stdio entrypoint's concern, and its signature drags Node types into
+ * consumers.
+ */
+export { registerAffsetTools, type AffsetToolServer, type RegisterAffsetToolsOptions, type ToolCallEvent, } from "./registerTools.js";
+export type { Config } from "./runtimeConfig.js";
+export { AffsetClient, AffsetApiError } from "./client.js";
+export { DOCS_FEEDS, fetchDocsFeed, DocsFetchError, type DocsFeed } from "./docs.js";
+export { VERSION } from "./version.js";

package/dist/core.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime-agnostic library surface of @affset/mcp (REMOTE-MCP-PRD.md §5.6).
+ *
+ * Everything exported here runs on any fetch-capable runtime (Node ≥22.13,
+ * Cloudflare Workers) — no `process.env`, no `node:` imports. The stdio
+ * entrypoint (`dist/index.js`, the `affset-mcp` bin) layers env-var loading on
+ * top of this; the remote MCP gateway imports this surface directly and
+ * supplies per-grant credentials instead.
+ *
+ * `loadConfig` (env-var parsing) is deliberately NOT exported: it is the
+ * stdio entrypoint's concern, and its signature drags Node types into
+ * consumers.
+ */
+export { registerAffsetTools, } from "./registerTools.js";
+export { AffsetClient, AffsetApiError } from "./client.js";
+export { DOCS_FEEDS, fetchDocsFeed, DocsFetchError } from "./docs.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=core.js.map

package/dist/docs.d.ts

@@ -0,0 +1,39 @@
+import { type Config } from "./runtimeConfig.js";
+/**
+ * Fetches the affset documentation feeds that back the MCP documentation
+ * resources. These are static files published by the marketing site
+ * (see lite-adserver-home/scripts/generate-docs.mjs), generated from the same
+ * source as the /docs page, so the resource content never drifts from the docs.
+ *
+ * Fetched at read time — the resource is always the currently published docs,
+ * not a snapshot pinned to this package version. Unlike the tenant API client,
+ * this sends NO credentials: the docs are public, and the docs origin
+ * (AFFSET_DOCS_URL) is deliberately not the API host that holds the API key.
+ */
+/** One published feed: the URI path segment and how it's served. */
+export interface DocsFeed {
+    /** Trailing path on the docs origin, e.g. "api-reference.md". */
+    file: string;
+    mimeType: string;
+}
+export declare const DOCS_FEEDS: {
+    readonly markdown: {
+        readonly file: "api-reference.md";
+        readonly mimeType: "text/markdown";
+    };
+    readonly json: {
+        readonly file: "api-reference.json";
+        readonly mimeType: "application/json";
+    };
+};
+/** Thrown when a docs feed can't be fetched or looks wrong. */
+export declare class DocsFetchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Fetch one docs feed and return its text. Throws {@link DocsFetchError} with an
+ * actionable message on any network error, non-2xx status, HTML SPA fallback,
+ * invalid body, or oversized response — the MCP layer surfaces that to the
+ * caller as the resource read failure.
+ */
+export declare function fetchDocsFeed(config: Config, feed: DocsFeed): Promise<string>;