optbrew 0.0.0-stage → 0.1.1

package/skills/optbrew/modules/seranking-seo/skills/seo-api/references/auth-and-keys.md

@@ -0,0 +1,182 @@
+# Auth & Keys
+
+The full picture of how to authenticate against SE Ranking's APIs and the MCP server. Used by the `seo-api` skill to answer "how do I auth", "where does the key come from", "what's the OAuth flow", and "how do I run this headlessly in CI".
+
+## Key types — single source of truth
+
+As of 2026, **one API key authenticates everything**. The legacy split into separate Data and Project keys is gone. The same UUID-format key works against:
+
+- All `DATA_*` MCP tools and the underlying `/v1/backlinks/*`, `/v1/domain/*`, `/v1/keywords/*`, `/v1/serp/*`, `/v1/audit/*`, `/v1/ai-search/*`, `/v1/account/*` REST endpoints.
+- All `PROJECT_*` MCP tools and the underlying `/v1/projects/*`, `/v1/projects/{id}/keywords/*`, `/v1/projects/{id}/audits/*`, `/v1/projects/{id}/backlinks/*`, `/v1/projects/{id}/airt/*`, `/v1/account/*` REST endpoints.
+
+Get keys at: <https://online.seranking.com/admin.api.dashboard.html>.
+
+You can mint multiple keys per account — useful for splitting rate-limit budgets across environments (dev, staging, prod) or workloads (research vs. recurring jobs).
+
+### Required plan
+
+- **Data API access** ships with: any plan that has API credits — Business / Enterprise plans (100K credits/month included), API add-on (1M+), or standalone API plan (1M+).
+- **Project API access** requires: Business or Enterprise plan. The Project API consumes plan limits ("Sites", "Keywords", "Audit Pages", "AIRT Prompts") rather than credits.
+
+If the user is on Essential or Pro, Project API tools will return `403 Subscription required`. Surface the upgrade link: <https://seranking.com/subscription.html>.
+
+## REST API auth
+
+### Recommended — Authorization header
+
+```bash
+curl -X GET 'https://api.seranking.com/v1/account/subscription' \
+  -H 'Authorization: Token YOUR_API_KEY'
+```
+
+Token scheme prefix is **`Token`**, not `Bearer`.
+
+### Fallback — query parameter
+
+```bash
+curl -X GET 'https://api.seranking.com/v1/account/subscription?apikey=YOUR_API_KEY'
+```
+
+Avoid the query param in production — it leaks the key into access logs, browser history, and HTTP referrers. Header is always preferred.
+
+### Liveness check
+
+The cheapest way to confirm a key is valid (0 credits):
+
+```bash
+curl -X GET 'https://api.seranking.com/v1/account/subscription' \
+  -H 'Authorization: Token YOUR_API_KEY'
+```
+
+`200 OK` with a `subscription_info` payload = key is alive. `401 Unauthorized` = key is invalid or revoked.
+
+## MCP server auth
+
+The MCP server at `https://api.seranking.com/mcp` is the recommended interface for any agentic workflow. It supports two auth modes, **pick one per client**:
+
+### Mode 1 — OAuth 2.1 (interactive, recommended for IDEs and desktop)
+
+Opens a browser on first connect, stores the token locally, reuses across sessions. Right for Claude Desktop, Claude Code on a workstation, Cursor, Codex IDE.
+
+```bash
+claude mcp add --transport http se-ranking https://api.seranking.com/mcp
+```
+
+First tool call triggers the browser sign-in. Subsequent calls reuse the refresh token (30-day sliding window, configurable via `MCP_REFRESH_TOKEN_TTL` server-side).
+
+### Mode 2 — API key header (non-interactive, recommended for CI / headless)
+
+Pass the key directly. Server skips OAuth entirely.
+
+```bash
+claude mcp add --transport http se-ranking https://api.seranking.com/mcp \
+  --header "X-Api-Key: $SERANKING_API_KEY"
+```
+
+The header `X-Data-Api-Key` is still accepted as an alias for `X-Api-Key` (backwards compat with older self-hosted installs).
+
+### Precedence when both are present
+
+If a request arrives with both header auth and an `Authorization: Bearer …` token from a previous OAuth session, **headers win**. This lets you override a stale Bearer token without reconfiguring the client.
+
+### Discovery endpoints (auto-resolved by spec-compliant clients)
+
+| Endpoint | Purpose |
+|---|---|
+| `/.well-known/oauth-authorization-server` | RFC 8414 authorization server metadata |
+| `/.well-known/oauth-protected-resource` | RFC 9728 protected-resource metadata |
+| `/.well-known/openid-configuration` | OIDC compatibility for clients that probe OIDC first |
+| `/register` | RFC 7591 dynamic client registration (no manual `client_id` provisioning) |
+
+## Per-client configuration cheat-sheet
+
+### Claude Code
+
+```bash
+claude mcp add --transport http se-ranking https://api.seranking.com/mcp
+# Then /mcp to complete OAuth.
+```
+
+### Claude Desktop / claude.ai
+
+`Customize` → `Connectors` → `+` → `Add custom connector`. Name: `SE Ranking`. URL: `https://api.seranking.com/mcp`.
+
+### Codex (CLI + IDE)
+
+```bash
+codex mcp add se-ranking --url https://api.seranking.com/mcp
+```
+
+First-time Codex users: enable the rmcp feature in `~/.codex/config.toml`:
+
+```toml
+[features]
+experimental_use_rmcp_client = true
+```
+
+### Cursor
+
+`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "se-ranking": {
+      "url": "https://api.seranking.com/mcp"
+    }
+  }
+}
+```
+
+### VS Code
+
+`Cmd+P` → `MCP: Add Server` → `Command (stdio)`:
+
+```bash
+npx -y mcp-remote https://api.seranking.com/mcp
+```
+
+### Windsurf / Zed / Gemini CLI / others
+
+All use the same `npx -y mcp-remote https://api.seranking.com/mcp` pattern via their respective MCP config files (`~/.codeium/windsurf/mcp_config.json`, `~/.config/zed/settings.json`, `~/.gemini/settings.json`).
+
+## Sub-accounts on a shared workspace
+
+If the user is a sub-account on a master SE Ranking workspace, the "Sign in with SE Ranking" OAuth path won't enumerate any tools — **API access lives with the master account**. Workaround until sub-account API keys ship:
+
+1. Get the API key from the workspace administrator (from the API Dashboard on the master account).
+2. In the MCP connection dialog, choose **Enter API key manually** (or use Mode 2 via `X-Api-Key` header) instead of OAuth.
+3. Paste the master key.
+
+## Key rotation
+
+Rotate keys when:
+
+- A key leaks (committed to git, posted in a Slack channel, ended up in a screenshot).
+- An employee with access leaves.
+- A workload moves between environments and you want clean rate-limit accounting.
+
+Rotation:
+
+1. Generate a new key at the API Dashboard.
+2. Roll the new key into production (env var, secret manager).
+3. Revoke the old key.
+4. **Note:** keys are validated and cached server-side. After revoking, allow up to 60 seconds for the cache to invalidate before assuming the old key is fully dead.
+
+## Common 401 / 403 patterns
+
+| HTTP | `error.message` | What it means | Fix |
+|---|---|---|---|
+| 401 | `Unauthorized` | Key missing, malformed, or revoked. | Re-check `Authorization` header format. Token scheme is `Token`, not `Bearer`. |
+| 401 | `API key provided via X-Api-Key failed validation.` | Format check passed (UUID-shaped) but liveness probe to `/v1/account/info` failed. | Key is revoked or typo'd. |
+| 403 | `Insufficient funds` | Data API balance too low for the requested cost. | Top up at the API Dashboard, or downsize the request. |
+| 403 | `Subscription required` | Project API call from a non-Business/Enterprise plan. | Upgrade plan, or stick to Data API only. |
+| 403 | `Limit reached` | Project API plan limit ("Sites", "Keywords", "Audit Pages", "AIRT Prompts") exceeded. | Upgrade plan, or release unused resources via the corresponding `PROJECT_delete*` tool. |
+
+## Storing keys safely
+
+- **Never commit keys to git.** Even in private repos. Use `.env` (gitignored) + a secret manager (1Password, Doppler, AWS Secrets Manager, Vault).
+- **Don't pass keys in URL query parameters.** They leak into access logs.
+- **For client-side code:** API keys must never reach the browser. Proxy through your own backend.
+- **For CI:** use the platform's secret store (GitHub Actions secrets, GitLab CI variables, etc.).
+- **For Docker:** pass via `--env-file`, never bake into the image layer.

package/skills/optbrew/modules/seranking-seo/skills/seo-api/references/integration-patterns.md

@@ -0,0 +1,283 @@
+# Integration Patterns
+
+Five canonical recipes the `seo-api` skill draws from. Each one is ready to paste — the skill adapts variable names, target domains, and credentials but doesn't need to re-derive the shape.
+
+## Pattern 1 — Rank tracker setup (Project API)
+
+**Goal:** stand up a new project, add a search engine, add 50 keywords, run the first position check.
+
+**Surfaces used:** Project API.
+**Plan cost:** 1 Site + 50 Keywords from the user's subscription.
+**Credits:** 0 (Project API).
+
+### MCP-tool-call sequence
+
+```text
+1. PROJECT_listProjects             // confirm the project doesn't already exist
+2. PROJECT_createProject            // domain="acme.com", name="ACME Rank Tracker"
+3. PROJECT_addSearchEngine          // project_id=<from #2>, country_code="us"
+4. PROJECT_addKeywords              // project_id=<from #2>, keywords=[...50 strings]
+5. PROJECT_runPositionCheck         // project_id=<from #2>
+6. PROJECT_getPositionHistory       // project_id=<from #2>  (poll until ready)
+```
+
+### Python equivalent
+
+```python
+import os, time, requests
+
+API_KEY = os.environ["SERANKING_API_KEY"]
+HEADERS = {"Authorization": f"Token {API_KEY}", "Content-Type": "application/json"}
+BASE = "https://api.seranking.com/v1"
+
+DOMAIN = "acme.com"
+NAME = "ACME Rank Tracker"
+COUNTRY = "us"
+KEYWORDS = ["seo software", "rank tracker", ...]  # 50 total
+
+project = requests.post(f"{BASE}/projects", json={"domain": DOMAIN, "name": NAME}, headers=HEADERS).json()
+project_id = project["id"]
+
+requests.post(f"{BASE}/projects/{project_id}/search-engines", json={"country_code": COUNTRY}, headers=HEADERS)
+
+requests.post(
+    f"{BASE}/projects/{project_id}/keywords",
+    json={"keywords": KEYWORDS},
+    headers=HEADERS,
+)
+
+requests.post(f"{BASE}/projects/{project_id}/positions/check", headers=HEADERS)
+
+# Position checks are async — poll
+for _ in range(20):
+    r = requests.get(f"{BASE}/projects/{project_id}/positions/history", headers=HEADERS)
+    if r.json().get("ready"):
+        positions = r.json()
+        break
+    time.sleep(15)
+```
+
+### When to use
+
+User says: "set up rank tracking for X", "create a new project for client Y", "I want to monitor positions for these keywords".
+
+### Variants
+
+- **Local rank tracking.** Add a region: call `PROJECT_getAvailableRegions` first, then pass `region_name` (verbatim from the response, no abbreviations) to `PROJECT_addSearchEngine`.
+- **Multiple search engines.** Loop `PROJECT_addSearchEngine` per `country_code`. Each one is independent — rank checks run in parallel.
+- **Tagged keyword groups.** After `PROJECT_addKeywords`, use `PROJECT_createKeywordGroup` + `PROJECT_moveKeywordsToGroup` to organise.
+
+## Pattern 2 — Bulk backlink export to BigQuery / S3 (Data API)
+
+**Goal:** pull every backlink for a list of 250 domains and ship the rows to BigQuery for analysis.
+
+**Surfaces used:** Data API only.
+**Credits:** ~75,000 (25,000 for 250 summaries + 50,000 for one full domain export; multi-domain exports scale linearly).
+**Plan cost:** 0.
+
+### Sequence
+
+```text
+1. DATA_getCreditBalance                    // confirm budget
+2. for each domain:
+     DATA_getBacklinksSummary               // 100 credits / domain
+3. DATA_exportBacklinksData                 // 1 credit per backlink record returned (per domain)
+4. DATA_getBacklinksExportStatus            // 0 credits / call; poll
+5. (when ready) fetch the result URL        // 0 credits
+```
+
+### Python skeleton
+
+```python
+import requests, time, json
+from google.cloud import bigquery
+
+DOMAINS = [...]  # 250 entries
+
+bq = bigquery.Client()
+table = bq.dataset("seo").table("backlinks")
+
+for domain in DOMAINS:
+    summary = client.get("/backlinks/summary", params={"target": domain}).json()
+    bq.insert_rows_json(table, [summary])
+
+    task = client.post("/backlinks/export", json={"target": domain}).json()
+    task_id = task["task_id"]
+
+    while True:
+        status = client.get(f"/backlinks/export/status", params={"task_id": task_id}).json()
+        if status["status"] == "done":
+            rows = requests.get(status["result_url"]).json()
+            bq.insert_rows_json(table, rows)
+            break
+        time.sleep(15)
+```
+
+(See `references/rate-limits-and-credits.md` for the `client` wrapper — it handles 429 + 403 + throttling.)
+
+### When to use
+
+User says: "export all backlinks for X", "ship backlinks to {warehouse}", "I need a daily/weekly backlink delta job".
+
+### Variants
+
+- **Incremental (delta) export.** Use `DATA_listNewLostBacklinks` instead of full export — much cheaper for daily jobs.
+- **Filter at request time.** Pass `min_authority`, `dofollow_only`, `anchor_contains` to reduce both data volume and credit cost.
+- **For ref domains instead of links.** Same shape with `DATA_getBacklinksRefDomains` → `DATA_listNewLostReferringDomains`.
+
+## Pattern 3 — Audit pipeline (Project API + Data API hybrid)
+
+**Goal:** stand up an ongoing audit for a project, then pull the latest report into a Slack alert.
+
+**Surfaces used:** both.
+**Credits:** 0 (audit lives on Project API).
+**Plan cost:** Audit Pages quota (depends on crawl scope).
+
+### Sequence
+
+```text
+1. PROJECT_listProjects                    // resolve project_id
+2. PROJECT_getAuditSettings                // confirm current crawl scope
+3. PROJECT_updateAuditSettings             // optional — tune scope
+4. PROJECT_createAudit                     // kicks off crawl
+5. PROJECT_getAuditStatus                  // poll until "completed"
+6. PROJECT_getAuditReport                  // top-level summary
+7. PROJECT_getIssuesByUrl                  // per-URL issue list
+8. (optional) DATA_getDomainAuthority      // contextual signal for severity ranking
+9. Slack webhook                            // emit alert
+```
+
+### Slack-alert TS skeleton
+
+```typescript
+const project = (await client.get(`/projects/list`)).find(p => p.domain === DOMAIN);
+
+await client.post(`/projects/${project.id}/audits/create`);
+
+let status = "pending";
+while (status !== "completed") {
+  await sleep(60_000);
+  status = (await client.get(`/projects/${project.id}/audits/status`)).status;
+}
+
+const report = await client.get(`/projects/${project.id}/audits/report`);
+const critical = report.issues.filter(i => i.severity === "critical");
+
+if (critical.length > 0) {
+  await fetch(SLACK_WEBHOOK, {
+    method: "POST",
+    body: JSON.stringify({
+      text: `⚠️ ${critical.length} critical SEO issues on ${DOMAIN}:\n${critical.map(i => `- ${i.title}`).join("\n")}`,
+    }),
+  });
+}
+```
+
+### When to use
+
+User says: "set up site auditing for X", "alert me when audit issues appear", "build an audit pipeline".
+
+### Variants
+
+- **One-off audit (no project).** Use `DATA_createStandardAudit` / `DATA_createAdvancedAudit` instead — fits when there's no Project API access or no need for ongoing tracking.
+- **Compare against last week.** Hold the previous `audit_id`; diff `PROJECT_getAuditReport` summaries to detect new/resolved issues.
+
+## Pattern 4 — AIRT visibility tracker (Project API)
+
+**Goal:** track how often a brand appears in answers across ChatGPT / Gemini / Perplexity for a curated prompt set.
+
+**Surfaces used:** Project API (with optional `DATA_getAiSearch*` for cross-domain comparison).
+**Credits:** 0 (AIRT is plan-billed).
+**Plan cost:** N AIRT Prompts from subscription.
+
+### Sequence
+
+```text
+1. PROJECT_listProjects                  // resolve project_id
+2. PROJECT_listLlmEngines                // confirm engines available
+3. (optional) PROJECT_createLlmEngine    // if a custom engine is needed
+4. PROJECT_createPromptGroup             // group the prompts logically
+5. PROJECT_addPrompts                    // attach 20–50 prompts
+6. PROJECT_getLlmStatus                  // poll — answers refresh on a schedule
+7. PROJECT_getPromptAnswer (per prompt)   // current top-N answers
+8. PROJECT_getPromptsRankings             // brand mention positions across the group
+```
+
+### When to use
+
+User says: "track brand mentions in LLMs", "AIRT setup", "AI Result Tracker prompts for X", "build LLM visibility dashboard".
+
+### Variants
+
+- **Cross-domain competitive view.** Pair with `DATA_getAiSearchLeaderboard` + `DATA_getAiSearchOverview` for a benchmark against domains you don't own.
+- **Per-engine breakdown.** Call `PROJECT_getLlmStatistics` filtered by engine_id for an engine-by-engine heatmap.
+
+## Pattern 5 — Keyword research bulk job (Data API)
+
+**Goal:** for a list of seed keywords, expand each into related / similar / longtail / question keywords, write the merged result to a CSV.
+
+**Surfaces used:** Data API only.
+**Credits:** ~1–5 per keyword expanded (varies by tool).
+**Plan cost:** 0.
+
+### Sequence
+
+```text
+for each seed:
+  DATA_getRelatedKeywords
+  DATA_getSimilarKeywords
+  DATA_getLongTailKeywords
+  DATA_getKeywordQuestions
+merge + dedupe
+write to CSV
+```
+
+### Python skeleton
+
+```python
+import csv, itertools
+
+SEEDS = [...]  # e.g., 20 seed keywords
+COUNTRY = "us"
+
+rows = []
+for seed in SEEDS:
+    rel = client.get("/keywords/related", params={"keyword": seed, "source": COUNTRY}).json()
+    sim = client.get("/keywords/similar", params={"keyword": seed, "source": COUNTRY}).json()
+    long = client.get("/keywords/longtail", params={"keyword": seed, "source": COUNTRY}).json()
+    qst = client.get("/keywords/questions", params={"keyword": seed, "source": COUNTRY}).json()
+
+    for kw in itertools.chain(rel, sim, long, qst):
+        rows.append({**kw, "source_seed": seed})
+
+# Dedupe by keyword
+unique = {row["keyword"]: row for row in rows}.values()
+
+with open("keywords.csv", "w", newline="") as f:
+    writer = csv.DictWriter(f, fieldnames=["keyword", "volume", "kd", "intent", "source_seed"])
+    writer.writeheader()
+    writer.writerows(unique)
+```
+
+### When to use
+
+User says: "expand these seeds", "bulk keyword research", "build a keyword list for X", "I have 20 seeds, give me 2000 keywords".
+
+### Variants
+
+- **By intent.** Filter on `intent` in the response: keep only `informational` + `commercial` for content briefs.
+- **By KD ceiling.** Filter `kd <= 30` for new domains to skip the impossible-to-rank keywords.
+- **Cluster after expansion.** Pipe the merged CSV into `seo-keyword-cluster` for pillar-and-spoke structure.
+
+## Composing patterns
+
+Real integrations chain these. Common compositions:
+
+| Goal | Patterns chained |
+|---|---|
+| "Weekly client SEO report" | Pattern 1 (one-time setup) → Pattern 3 (recurring audit) + `PROJECT_getPositionHistory` + Pattern 2 trim (delta backlinks) |
+| "Find the highest-value new content opportunities" | Pattern 5 → `seo-keyword-cluster` → `seo-content-brief` |
+| "AI Search competitive intelligence" | Pattern 4 → `seo-ai-search-share-of-voice` |
+| "Outreach prospecting" | Pattern 2 (variant: ref domains) → competitor diff → outreach CSV |
+
+When the user's goal spans more than one pattern, the `seo-api` skill writes them all as numbered sections inside `RECIPE.md` and emits separate `code/` files per language for the combined flow.