ghost-api-cli 0.2.0__py3-none-any.whl

ghost_api/generator/templates/client.ts.j2

@@ -0,0 +1,339 @@
+/**
+ * {{ spec.class_name }}: a typed TypeScript client for {{ spec.domain }}.
+ *
+ * Generated by Ghost API {{ version }} on {{ generated_on }} from the site's own traffic.
+ * Made for Node 18+ (servers, scripts, serverless functions). The types describe responses
+ * seen while exploring; they are not checked at runtime.
+ *
+ * In a web page: browsers don't let code set the User-Agent header, so this client doesn't
+ * try there (the site can't tell the calls come from it), and the browser only lets the page
+ * read the replies if the site allows cross-origin requests (CORS), which internal APIs
+ * rarely do. Call the client from your own server and have the page call that instead.
+ *
+ * This is an unofficial client for a website's internal API. It can change without
+ * notice, and the site's terms of service still apply. Re-run `ghost-api run` to refresh.
+ */
+{% for m in spec.models %}
+
+{% if m.doc %}
+/** {{ m.doc | doc }} */
+{% endif %}
+export interface {{ m.name }} {
+{% for f in m.fields %}
+  {{ f | ts_prop }}{% if f.optional %}?{% endif %}: {{ f.type | ts_type }};
+{% endfor %}
+  /** Fields not seen while exploring. */
+  [extra: string]: unknown;
+}
+{% endfor %}
+
+/** An API call failed. `status` is the HTTP status (0 for network errors). */
+export class {{ spec.error_class }} extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, message: string, body?: unknown) {
+    super(status ? `HTTP ${status}: ${message}` : message);
+    this.name = new.target.name;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/** 401 or 403: a credential is missing, wrong or expired. */
+export class {{ spec.error_classes.auth }} extends {{ spec.error_class }} {}
+/** 404: no such resource (or the site moved this endpoint). */
+export class {{ spec.error_classes.not_found }} extends {{ spec.error_class }} {}
+/** 429 after all retries: slow down (see `maxRequestsPerSecond`). */
+export class {{ spec.error_classes.rate_limit }} extends {{ spec.error_class }} {}
+/** 5xx after all retries: the site has a problem. */
+export class {{ spec.error_classes.server }} extends {{ spec.error_class }} {}
+
+function errorFor(status: number, message: string, body?: unknown): {{ spec.error_class }} {
+  if (status === 401 || status === 403) return new {{ spec.error_classes.auth }}(status, message, body);
+  if (status === 404) return new {{ spec.error_classes.not_found }}(status, message, body);
+  if (status === 429) return new {{ spec.error_classes.rate_limit }}(status, message, body);
+  if (status >= 500) return new {{ spec.error_classes.server }}(status, message, body);
+  return new {{ spec.error_class }}(status, message, body);
+}
+
+export interface {{ spec.class_name }}Options {
+  baseUrl?: string;
+{% for c in spec.credentials %}
+  /** Defaults to the {{ c.env }} environment variable (Node). */
+  {{ c.arg | camel }}?: string;
+{% endfor %}
+  maxRequestsPerSecond?: number;
+  maxRetries?: number;
+  fetch?: typeof fetch;
+}
+
+const USER_AGENT = {{ user_agent | json }};
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+// Guards some sites put before JSON so other sites can't read it (Google: ")]}'").
+const JSON_GUARDS = [")]}'", "while(1);", "for(;;);"];
+const CREDENTIAL_ENV: Record<string, string> = {
+{% for c in spec.credentials %}
+  {{ c.arg | camel | json }}: {{ c.env | json }},
+{% endfor %}
+};
+
+/** True in a web page (and web workers), where the User-Agent header can't be set. */
+function inBrowser(): boolean {
+  const g = globalThis as { document?: unknown; importScripts?: unknown };
+  return g.document !== undefined || typeof g.importScripts === "function";
+}
+
+function readEnv(name: string): string | undefined {
+  const proc = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process;
+  return proc?.env?.[name];
+}
+
+function parseJson(text: string): unknown {
+  let body = text.trimStart();
+  const guard = JSON_GUARDS.find((g) => body.startsWith(g));
+  if (guard) body = body.slice(guard.length).replace(/^,/, "").trimStart();
+  return JSON.parse(body);
+}
+
+/** GraphQL variables without the ones left out. */
+function compact(values: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(values).filter(([, v]) => v !== undefined && v !== null));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class {{ spec.class_name }} {
+  static readonly BASE_URL = {{ spec.base_url | json }};
+
+  readonly baseUrl: string;
+  private readonly credentials: Record<string, string | undefined>;
+  private readonly interval: number;
+  private readonly maxRetries: number;
+  private readonly fetchImpl: typeof fetch;
+  private lastRequest = 0;
+
+  constructor(options: {{ spec.class_name }}Options = {}) {
+    this.baseUrl = (options.baseUrl ?? {{ spec.class_name }}.BASE_URL).replace(/\/+$/, "");
+    this.credentials = {
+{% for c in spec.credentials %}
+      {{ c.arg | camel | json }}: options.{{ c.arg | camel }} ?? readEnv({{ c.env | json }}),
+{% endfor %}
+    };
+    const rate = options.maxRequestsPerSecond ?? 1;
+    this.interval = rate > 0 ? 1000 / rate : 0;
+    this.maxRetries = options.maxRetries ?? 3;
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+{% for m in spec.methods %}
+
+  /**
+   * {{ m.summary | doc }}
+   *
+   * `{{ m.http_method }} {{ (m.host and 'https://' ~ m.host) or spec.base_url }}{{ m.path }}`
+   */
+  async {{ m.name | camel }}(
+{% for p in m.required %}
+    {{ p.name | camel }}: {{ p.type | ts_type }},
+{% endfor %}
+{% if m.optional %}
+    opts: {
+{% for p in m.optional %}
+      {{ p.name | camel }}?: {{ p.type | ts_type }}{% if not p.required and (p.default is none or p.default == "None") %} | null{% endif %};
+{% endfor %}
+    } = {},
+{% endif %}
+  ): Promise<{{ m.response_type | ts_type }}> {
+    const data = await this.request(
+      "{{ m.http_method }}",
+      {% if m.host %}"https://{{ m.host }}"{% else %}this.baseUrl{% endif %} + {{ m | path_expr }},
+      {
+{% for p in m.by_location('query') %}
+        {{ p.wire | json }}: {{ p | value }},
+{% endfor %}
+{% for c in m | creds(spec, 'query') %}
+        {{ c.wire | json }}: this.credential({{ c.arg | camel | json }}),
+{% endfor %}
+      },
+      {
+{% for name, value in m.headers.items() %}
+        {{ name | json }}: {{ value | json }},
+{% endfor %}
+{% for c in m | creds(spec, 'header') %}
+        {{ c.wire | json }}: this.credential({{ c.arg | camel | json }}),
+{% endfor %}
+      },
+{% if m.graphql %}
+      {
+{% for key, value in m.graphql.items() %}
+        {{ key | json }}: {{ value | json }},
+{% endfor %}
+        variables: compact({
+{% for p in m.by_location('variable') %}
+          {{ p.wire | json }}: {{ p | value }},
+{% endfor %}
+        }),
+      },
+{% elif m.by_location('body') %}
+      {
+{% for p in m.by_location('body') %}
+        {{ p.wire | json }}: {{ p | value }},
+{% endfor %}
+      },
+{% endif %}
+    );
+    return data as {{ m.response_type | ts_type }};
+  }
+{% if m.page_param %}
+{% set pp = m.page_param %}
+
+  /**
+   * Yield each page of `{{ m.name | camel }}()` until the results run out.
+   * Pages by {{ m.pagination.style }} using `{{ pp.wire }}`. Set `maxPages` to stop early.
+   */
+  async *iter{{ (m.name | camel)[:1] | upper }}{{ (m.name | camel)[1:] }}(
+{% for p in m.required %}
+    {{ p.name | camel }}: {{ p.type | ts_type }},
+{% endfor %}
+    opts: {
+{% for p in m.optional if p.name != pp.name %}
+      {{ p.name | camel }}?: {{ p.type | ts_type }}{% if p.default is none or p.default == "None" %} | null{% endif %};
+{% endfor %}
+      start?: {{ pp.type | ts_type }};
+      maxPages?: number;
+    } = {},
+  ): AsyncGenerator<{{ m.response_type | ts_type }}> {
+    const { start, maxPages, ...rest } = opts;
+    let position: unknown = start ?? {{ pp.default | js }};
+    let previous = "";
+    for (let pages = 0; maxPages === undefined || pages < maxPages; pages++) {
+      const page = await this.{{ m.name | camel }}(
+{% for p in m.required %}
+        {{ p.name | camel }},
+{% endfor %}
+        { ...rest, {{ pp.name | camel }}: position as {{ pp.type | ts_type }} },
+      );
+      const items = findItems(page);
+      const fingerprint = JSON.stringify(items);
+      if (!items || items.length === 0 || fingerprint === previous) return;
+      yield page;
+      if (hasMore(page) === false) return;
+      previous = fingerprint;
+{% if m.pagination.style == "cursor" %}
+      position = nextCursor(page);
+      if (position === undefined) return;
+{% elif m.pagination.style == "offset" %}
+      position = Number(position ?? 0) + items.length;
+{% else %}
+      position = Number(position ?? 0) + 1;
+{% endif %}
+    }
+  }
+{% endif %}
+{% endfor %}
+
+  // --- plumbing ---
+
+  private credential(name: string): string {
+    const value = this.credentials[name];
+    if (!value) {
+      const env = CREDENTIAL_ENV[name] ?? "";
+      throw new {{ spec.error_classes.auth }}(0, `Missing credential: pass ${name} or set ${env}`);
+    }
+    return value;
+  }
+
+  private async request(
+    method: string,
+    url: string,
+    query: Record<string, unknown>,
+    headers: Record<string, string>,
+    body?: Record<string, unknown>,
+  ): Promise<unknown> {
+    const target = new URL(url);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) target.searchParams.set(key, String(value));
+    }
+    const init: RequestInit = {
+      method,
+      headers: {
+        ...(inBrowser() ? {} : { "User-Agent": USER_AGENT }),
+        Accept: "application/json",
+        ...headers,
+      },
+    };
+    if (body !== undefined) {
+      const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined && v !== null));
+      init.body = JSON.stringify(clean);
+      init.headers = { ...init.headers, "Content-Type": "application/json" };
+    }
+    for (let attempt = 0; ; attempt++) {
+      const wait = this.lastRequest + this.interval - Date.now();
+      if (wait > 0) await sleep(wait);
+      this.lastRequest = Date.now();
+      let response: Response;
+      try {
+        response = await this.fetchImpl(target, init);
+      } catch (error) {
+        if (attempt >= this.maxRetries) {
+          throw new {{ spec.error_class }}(0, `network error: ${String(error)}`);
+        }
+        await sleep(1000 * 2 ** attempt);
+        continue;
+      }
+      if (RETRY_STATUSES.has(response.status) && attempt < this.maxRetries) {
+        const retryAfter = Number(response.headers.get("retry-after"));
+        await sleep(Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter * 1000 : 1000 * 2 ** attempt);
+        continue;
+      }
+      const text = await response.text();
+      let data: unknown;
+      try {
+        data = parseJson(text);
+      } catch {
+        if (!response.ok) throw errorFor(response.status, response.statusText, text.slice(0, 500));
+        throw new {{ spec.error_class }}(response.status, "response is not JSON", text.slice(0, 500));
+      }
+      if (!response.ok) throw errorFor(response.status, response.statusText, data);
+      return data;
+    }
+  }
+}
+
+function findItems(data: unknown, depth = 0): unknown[] | undefined {
+  if (Array.isArray(data)) return data;
+  if (data === null || typeof data !== "object" || depth > 2) return undefined;
+  let best: unknown[] | undefined;
+  for (const value of Object.values(data)) {
+    const found = Array.isArray(value) ? value : findItems(value, depth + 1);
+    if (found && (!best || found.length > best.length)) best = found;
+  }
+  return best;
+}
+
+function hasMore(data: unknown): boolean | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const record = data as Record<string, unknown>;
+  for (const key of ["has_next", "hasNext", "has_more", "hasMore"]) {
+    if (typeof record[key] === "boolean") return record[key] as boolean;
+  }
+  return undefined;
+}
+
+function nextCursor(data: unknown): string | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const record = data as Record<string, unknown>;
+  const places = [record, ...["meta", "pagination", "paging", "pageInfo", "links"]
+    .map((k) => record[k])
+    .filter((v): v is Record<string, unknown> => v !== null && typeof v === "object")];
+  for (const place of places) {
+    for (const key of ["next_cursor", "nextCursor", "cursor", "next", "after", "endCursor",
+      "next_page_token", "nextPageToken"]) {
+      const value = place[key];
+      if ((typeof value === "string" && value) || typeof value === "number") return String(value);
+    }
+  }
+  return undefined;
+}

ghost_api/generator/templates/models.py.j2

@@ -0,0 +1,45 @@
+"""Data models for {{ spec.domain }}, inferred from real responses.
+
+Generated by Ghost API {{ version }} on {{ generated_on }}. Fields that were missing or
+null in some responses are optional. Unknown extra fields are kept, so a new field in
+the API does not break parsing.
+"""
+
+from __future__ import annotations
+
+{% if uses_any %}
+from typing import Any
+
+{% endif %}
+from pydantic import BaseModel, ConfigDict{% if uses_field %}, Field{% endif %}
+
+
+__all__ = [
+{% for m in spec.models %}
+    {{ m.name | pyrepr }},
+{% endfor %}
+]
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+{% for m in spec.models %}
+
+
+class {{ m.name }}(_Model):
+{% if m.doc %}
+    """{{ m.doc | doc }}"""
+{% endif %}
+{% for f in m.fields %}
+{% if f.alias %}
+    {{ f.name }}: {{ f.type }} = Field({% if f.optional %}None, {% endif %}alias={{ f.alias | pyrepr }})
+{% elif f.optional %}
+    {{ f.name }}: {{ f.type }} = None
+{% else %}
+    {{ f.name }}: {{ f.type }}
+{% endif %}
+{% endfor %}
+{% if not m.fields and not m.doc %}
+    pass
+{% endif %}
+{% endfor %}

ghost_api/generator/templates/package_readme.md.j2

@@ -0,0 +1,111 @@
+# {{ dist }}
+
+An **unofficial**, typed {{ "Python" if lang == "python" else "TypeScript" }} client for
+[{{ spec.domain }}]({{ spec.base_url }}), generated by
+[Ghost API](https://github.com/Danielraj5605/Ghost-api) {{ version }} from the site's own
+traffic. It is not made or supported by {{ spec.domain }}: the API can change without notice,
+and the site's terms of service apply. Regenerate it with `ghost-api refresh {{ spec.domain }}`.
+
+## Install
+
+{% if lang == "python" %}
+```bash
+pip install path/to/package/python        # or vendor src/{{ module }}/ into your project
+```
+
+Needs Python 3.10+, `httpx` and `pydantic` (installed with it).
+{% else %}
+```bash
+npm install path/to/package/typescript     # builds dist/ on install
+```
+
+Made for Node 18+ (servers, scripts, serverless functions). In a web page, browsers block
+reading another site's replies unless it allows CORS, and don't let code set the
+User-Agent: call this client from your own server instead.
+{% endif %}
+
+## Use it
+
+{% if lang == "python" %}
+```python
+from {{ module }} import {{ spec.class_name }}
+
+with {{ spec.class_name }}() as api:
+{% if methods %}
+    result = api.{{ methods[0].method.name }}({{ methods[0].py_args }})
+{% endif %}
+```
+
+The same methods with asyncio:
+
+```python
+from {{ module }} import {{ spec.async_class }}
+
+async with {{ spec.async_class }}() as api:
+{% if methods %}
+    result = await api.{{ methods[0].method.name }}({{ methods[0].py_args }})
+{% endif %}
+```
+{% else %}
+```ts
+import { {{ spec.class_name }} } from "{{ dist }}";
+
+const api = new {{ spec.class_name }}();
+{% if methods %}
+const result = await api.{{ methods[0].ts_name }}({{ methods[0].ts_args }});
+{% endif %}
+```
+{% endif %}
+{% if spec.credentials %}
+
+### Credentials
+
+| Argument | Environment variable |
+|---|---|
+{% for c in spec.credentials %}
+| `{{ c.arg if lang == "python" else (c.arg | camel) }}` | `{{ c.env }}` |
+{% endfor %}
+
+Pass them to the constructor, or set the environment variables.
+{% endif %}
+
+## Methods
+
+| Method | Calls | Returns | What it does |
+|---|---|---|---|
+{% for item in methods %}
+{% set m = item.method %}
+| `{{ m.name if lang == "python" else item.ts_name }}` | `{{ m.http_method }} {{ m.path }}` | `{{ m.response_type }}` | {{ m.summary | replace("|", "/") | replace("\n", " ") }}{% if m.page_param %} Pages with `{{ ("iter_" ~ m.name) if lang == "python" else item.ts_iter }}()`.{% endif %} |
+{% endfor %}
+
+## The same calls with curl
+
+Values are examples seen while exploring the site.
+
+{% for item in methods %}
+**{{ item.method.name }}**
+
+```bash
+{{ item.curl }}
+```
+
+{% endfor %}
+## Errors
+
+Every failure is a `{{ spec.error_class }}` with `.status` (0 for network errors) and
+`.body`. Catch one kind with its subclass:
+
+| Error | When |
+|---|---|
+| `{{ spec.error_classes.auth }}` | 401 / 403, or a missing credential |
+| `{{ spec.error_classes.not_found }}` | 404 |
+| `{{ spec.error_classes.rate_limit }}` | 429 after the retries |
+| `{{ spec.error_classes.server }}` | 5xx after the retries |
+
+## Manners
+
+The client sends at most one request per second by default
+(`{{ "max_requests_per_second" if lang == "python" else "maxRequestsPerSecond" }}`), retries
+429 and 5xx with backoff (`{{ "max_retries" if lang == "python" else "maxRetries" }}`), and
+identifies itself with a User-Agent naming Ghost API. Keep it that way: it's someone else's
+server.

ghost_api/generator/templates/pyproject.toml.j2

@@ -0,0 +1,22 @@
+# Generated by Ghost API. Install with:  pip install .   (or publish it to your own index)
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{{ dist }}"
+version = "{{ version }}"
+description = "Unofficial typed client for {{ spec.domain }} (generated by Ghost API)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27", "pydantic>=2.7"]
+classifiers = ["Typing :: Typed", "Private :: Do Not Upload"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+{{ module }} = ["py.typed"]

ghost_api/generator/templates/test_client.py.j2

@@ -0,0 +1,105 @@
+"""Tests for {{ spec.class_name }} (generated by Ghost API {{ version }}).
+
+By default they replay replies recorded from {{ spec.domain }} (cassettes.json): offline,
+fast and the same every time, so they fit CI. With GHOST_API_LIVE=1 they call the real API,
+slowly (1 request per second), with values seen while exploring; a failure then usually
+means the site changed its API: `ghost-api diff --live` says what changed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from {{ module }} import {{ spec.class_name }}  # noqa: E402
+
+CASSETTES = Path(__file__).parent / "cassettes.json"
+LIVE = os.environ.get("GHOST_API_LIVE") == "1" or not CASSETTES.exists()
+REPLIES: list[dict[str, Any]] = (
+    [] if LIVE else json.loads(CASSETTES.read_text(encoding="utf-8"))["replies"]
+)
+
+
+def _replay(request: httpx.Request) -> httpx.Response:
+    """The recorded reply closest to this request: same path first, then query values."""
+    query = dict(request.url.params)
+    operation = None
+    if request.content:
+        try:
+            body = json.loads(request.content)
+            operation = body.get("operationName") if isinstance(body, dict) else None
+        except ValueError:
+            pass
+    found = [
+        r for r in REPLIES
+        if r["method"] == request.method
+        and re.fullmatch(r["path_regex"], request.url.path)
+        and (operation is None or r.get("operation") in (None, operation))
+    ]  # fmt: skip
+    if not found:
+        message = f"no recorded reply for {request.method} {request.url.path}"
+        return httpx.Response(404, json={"error": message})
+
+    def score(reply: dict[str, Any]) -> tuple[bool, int, int]:
+        same = sum(1 for k, v in reply["query"].items() if query.get(k) == v)
+        return reply["path"] == request.url.path, same, -abs(len(reply["query"]) - len(query))
+
+    best = max(found, key=score)
+    return httpx.Response(
+        best["status"], text=best["body"], headers={"content-type": best["content_type"]}
+    )
+
+
+@pytest.fixture(scope="module")
+def api() -> Iterator[{{ spec.class_name }}]:
+    if LIVE:
+        with {{ spec.class_name }}() as client:
+            yield client
+        return
+    offline = httpx.Client(transport=httpx.MockTransport(_replay))
+    with {{ spec.class_name }}(
+{% for c in spec.credentials %}
+        {{ c.arg }}="offline-placeholder",
+{% endfor %}
+        http_client=offline,
+        max_requests_per_second=0,
+    ) as client:
+        yield client
+{% for m in spec.methods if m.testable %}
+
+
+def test_{{ m.name }}(api: {{ spec.class_name }}) -> None:
+{% for c in m | creds(spec, 'any') %}
+    if LIVE and not os.environ.get({{ c.env | pyrepr }}):
+        pytest.skip("set {{ c.env }} to run this test against the live API")
+{% endfor %}
+    result = api.{{ m.name }}({% for p in m.required %}{{ p.name }}={{ p.example }}{% if not loop.last %}, {% endif %}{% endfor %})
+    assert result is not None
+{% if m.page_param %}
+
+
+def test_iter_{{ m.name }}(api: {{ spec.class_name }}) -> None:
+{% for c in m | creds(spec, 'any') %}
+    if LIVE and not os.environ.get({{ c.env | pyrepr }}):
+        pytest.skip("set {{ c.env }} to run this test against the live API")
+{% endfor %}
+    pages = list(api.iter_{{ m.name }}({% for p in m.required %}{{ p.name }}={{ p.example }}, {% endfor %}max_pages=2))
+    assert len(pages) >= 1
+{% endif %}
+{% endfor %}
+{% for m in spec.methods if not m.testable %}
+
+
+@pytest.mark.skip(reason="no example values were captured for its required arguments")
+def test_{{ m.name }}() -> None: ...
+{% endfor %}