diff --git a/.github/workflows/generate-references.yml b/.github/workflows/generate-references.yml new file mode 100644 index 00000000..f59f75fb --- /dev/null +++ b/.github/workflows/generate-references.yml @@ -0,0 +1,64 @@ +name: Generate references + +# Regenerates references/ by hand, for when the release's best-effort reference step fails +# or the pages need a refresh. Same shape as posthog-js's generate-references.yml. +on: + workflow_dispatch: + +permissions: {} + +jobs: + generate-references: + name: Generate SDK reference + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Get GitHub App token + id: releaser + uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 + with: + client-id: ${{ secrets.GH_APP_POSTHOG_FLUTTER_RELEASER_APP_ID }} + private-key: ${{ secrets.GH_APP_POSTHOG_FLUTTER_RELEASER_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + token: ${{ steps.releaser.outputs.token }} + + - name: Check out sdk-specs + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: PostHog/sdk-specs + path: .sdk-specs + persist-credentials: false + + - name: Set up Flutter + uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30 + with: + channel: 'stable' + + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.13' + + - name: Generate references + id: changes + run: | + python3 -m pip install --quiet -r scripts/requirements.txt + python3 scripts/generate_markdown_reference.py --sdk-specs .sdk-specs + git add references + git diff --cached --quiet || echo "changed=true" >> "$GITHUB_OUTPUT" + + - name: Commit generated references + if: steps.changes.outputs.changed == 'true' + uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22 + with: + commit_message: "docs: update the SDK reference [skip ci]" + repo: ${{ github.repository }} + branch: main + file_pattern: references/ + env: + GITHUB_TOKEN: ${{ steps.releaser.outputs.token }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b8a6720b..17b6e2a9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -160,6 +160,55 @@ jobs: git tag -a "$NEW_VERSION" -m "$NEW_VERSION" git push origin "$NEW_VERSION" + # The reference headings come from the sdk-specs capabilities. + - name: Check out sdk-specs + # Best-effort: a failure never blocks the release. Run generate-references.yml to retry. + continue-on-error: true + if: steps.commit-version-bump.outputs.commit-hash != '' + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: PostHog/sdk-specs + path: .sdk-specs + persist-credentials: false + + # The generator runs `flutter pub get` and `dart doc`. Same pinned action as ci.yml. + - uses: axi92/flutter-action@36d2c2625bac6ea011cd7808d2a01bd8a7e5c766 # feature/pin-action-sha @ 2026-04-30 + if: steps.commit-version-bump.outputs.commit-hash != '' + with: + channel: 'stable' + + # Ubuntu's system Python refuses a plain pip install (externally managed). + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + if: steps.commit-version-bump.outputs.commit-hash != '' + with: + python-version: '3.13' + + - name: Generate references + id: reference + # Best-effort: a failure never blocks the release. Run generate-references.yml to retry. + continue-on-error: true + if: steps.commit-version-bump.outputs.commit-hash != '' + run: | + python3 -m pip install --quiet -r scripts/requirements.txt + python3 scripts/generate_markdown_reference.py --sdk-specs .sdk-specs + # Stage the pages, so a new page shows in git status as a file, not as an untracked folder. + git add references + + - name: Warn if the SDK reference didn't regenerate + if: steps.reference.outcome == 'failure' + run: echo "::warning::The SDK reference didn't regenerate. Run generate-references.yml to retry." + + - name: Commit generated references + if: steps.commit-version-bump.outputs.commit-hash != '' + uses: planetscale/ghcommit-action@a6b150b81dca5dd027baa898604418eec9e11465 # v0.2.22 + with: + commit_message: 'Update generated references' + repo: ${{ github.repository }} + branch: main + file_pattern: references/ + env: + GITHUB_TOKEN: ${{ steps.releaser.outputs.token }} + - name: Send failure event to PostHog if: ${{ failure() }} continue-on-error: true diff --git a/docs/capabilities.json b/docs/capabilities.json new file mode 100644 index 00000000..a2139df7 --- /dev/null +++ b/docs/capabilities.json @@ -0,0 +1,53 @@ +{ + "Posthog.addExceptionStep": "exception-steps", + "Posthog.alias": "alias", + "Posthog.capture": "capture", + "Posthog.captureException": "capture-exception", + "Posthog.captureLog": "logs", + "Posthog.captureRunZonedGuardedError": "capture-exception", + "Posthog.close": "shutdown", + "Posthog.debug": "debug", + "Posthog.flush": "flush", + "Posthog.getAllFeatureFlags": "get-feature-flags", + "Posthog.getDistinctId": "get-distinct-id", + "Posthog.getFeatureFlag": "get-feature-flag", + "Posthog.getFeatureFlagPayload": "get-feature-flag-payload", + "Posthog.getFeatureFlagResult": "get-feature-flag-result", + "Posthog.getSessionId": "get-session-id", + "Posthog.group": "group", + "Posthog.identify": "identify", + "Posthog.isFeatureEnabled": "is-feature-enabled", + "Posthog.isOptOut": "is-opt-out", + "Posthog.isSessionReplayActive": "is-session-replay-active", + "Posthog.logger": "logs", + "Posthog.optIn": "opt-in", + "Posthog.register": "register", + "Posthog.reloadFeatureFlags": "reload-feature-flags", + "Posthog.reset": "reset", + "Posthog.resetGroupPropertiesForFlags": "reset-group-properties-for-flags", + "Posthog.resetPersonPropertiesForFlags": "reset-person-properties-for-flags", + "Posthog.screen": "screen", + "Posthog.setGroupPropertiesForFlags": "set-group-properties-for-flags", + "Posthog.setPersonProperties": "set-person-properties", + "Posthog.setPersonPropertiesForFlags": "set-person-properties-for-flags", + "Posthog.setup": "setup", + "Posthog.startSessionRecording": "start-session-recording", + "Posthog.stopSessionRecording": "stop-session-recording", + "Posthog.unregister": "unregister", + "next": { + "Posthog.captureAi": "capture-ai", + "Posthog.onFeatureFlags": "on-feature-flags" + }, + "utils": [ + "Posthog.Posthog.new", + "Posthog.captureFeatureInteraction", + "Posthog.captureFeatureView", + "Posthog.capturePushNotificationOpened", + "Posthog.disable", + "Posthog.enable", + "Posthog.optOut", + "Posthog.registerPushNotificationToken", + "Posthog.setAppLanguage", + "Posthog.unregisterPushNotificationToken" + ] +} diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..611b164f --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,44 @@ +# Getting started + +The Flutter SDK runs in iOS, Android, macOS, and web apps. + +To send your first event, add `posthog_flutter`, then call `setup` once before `runApp` with your project token and host from your [project settings](https://app.posthog.com/project/settings). + +Use `capture` for your own events, and call `flush` and `close` before the app exits. + +Install the package: + +```bash +flutter pub add posthog_flutter +``` + +Initialize the SDK once, before `runApp`, with your project token and host: + +```dart +import 'package:flutter/widgets.dart'; +import 'package:posthog_flutter/posthog_flutter.dart'; + +Future main() async { + WidgetsFlutterBinding.ensureInitialized(); + + final config = PostHogConfig(''); + config.host = 'https://us.i.posthog.com'; + await Posthog().setup(config); + + runApp(const MyApp()); +} +``` + +Capture an event and identify the user: + +```dart +await Posthog().capture(eventName: 'user_signed_up', properties: {'plan': 'free'}); +await Posthog().identify(userId: 'user_123', userProperties: {'email': 'a@example.com'}); +``` + +Flush queued events and shut the SDK down before the app exits: + +```dart +await Posthog().flush(); +await Posthog().close(); +``` diff --git a/posthog_flutter/lib/src/replay/mask/posthog_platform_view.dart b/posthog_flutter/lib/src/replay/mask/posthog_platform_view.dart index 947e43c5..90f654f6 100644 --- a/posthog_flutter/lib/src/replay/mask/posthog_platform_view.dart +++ b/posthog_flutter/lib/src/replay/mask/posthog_platform_view.dart @@ -40,9 +40,15 @@ enum PostHogPlatformViewPrivacy { /// This widget has no runtime state — it is a pure marker. The compositor reads /// [privacy] from the element tree during each capture frame. class PostHogPlatformView extends StatelessWidget { + /// The platform view subtree this policy applies to. final Widget child; + + /// How the platform views in [child] are handled in session replay. + /// + /// Defaults to [PostHogPlatformViewPrivacy.mask]. final PostHogPlatformViewPrivacy privacy; + /// Creates a session replay policy marker around [child]. const PostHogPlatformView({ super.key, required this.child, diff --git a/scripts/generate_markdown_reference.py b/scripts/generate_markdown_reference.py new file mode 100644 index 00000000..6a129aa9 --- /dev/null +++ b/scripts/generate_markdown_reference.py @@ -0,0 +1,203 @@ +"""Generate the SDK reference Markdown from the doc comments with `dart doc`. + +`dart doc` (part of the Dart SDK) writes one HTML page per symbol and an index.json that lists every +symbol with its kind and enclosing type. BeautifulSoup reads each page's signature and description, +and markdownify turns the description into Markdown. Our code only groups Posthog members by the +sdk-specs capability docs/capabilities.json gives them, in the PostHog/sdk-specs README's order, and +writes front matter. Members it lists under `utils` go to SDK utils. + + pip install -r scripts/requirements.txt + python3 scripts/generate_markdown_reference.py --sdk-specs DIR [--major 6] +""" + +import argparse +import json +import subprocess +import tempfile +from pathlib import Path + +from bs4 import BeautifulSoup +from markdownify import markdownify + +ROOT = Path(__file__).resolve().parents[1] +PKG = ROOT / "posthog_flutter" +LIBRARY = "posthog_flutter" +FIRST = ["setup", "capture", "identify"] +# Public client classes get their own H2; every other public type goes in Types. +CLIENTS = "PostHogLogger PosthogObserver PostHogWidget PostHogMaskWidget PostHogUnmaskWidget PostHogPlatformView PostHogIsolateExtension".split() +# dartdoc's index.json kinds. +CONSTRUCTOR, CLASS, ENUM, EXTENSION, FUNCTION, METHOD, PROPERTY, TYPEDEF = 2, 3, 5, 6, 8, 10, 16, 21 +KEYWORD = {CLASS: "class", ENUM: "enum", EXTENSION: "extension"} +# Members every Dart object has, which say nothing about the SDK. +OBJECT = {"hashCode", "toString", "noSuchMethod", "runtimeType", "operator =="} +MDX = str.maketrans({"{": "{", "}": "}"}) # MDX 1 reads braces as JSX + + +class Docs: + def __init__(self, out: Path): + self.out = out + self.index = json.loads((out / "index.json").read_text()) + + def page(self, symbol: dict): + html = (self.out / symbol["href"].split("#")[0]).read_text() + return BeautifulSoup(html, "html.parser").select_one("#dartdoc-main-content") + + def members(self, symbol: dict) -> list[dict]: + """What a type declares itself: constructors, properties and methods, without overrides.""" + return [ + s for s in self.index + if s.get("enclosedBy", {}).get("href") == symbol["href"] and s["kind"] in (CONSTRUCTOR, PROPERTY, METHOD) + and not s.get("overriddenDepth") and s["name"] not in OBJECT + ] + + def entry(self, symbol: dict, label: str, level: int) -> str: + page = self.page(symbol) + sig = page.select_one("section.multi-line-signature") + for feature in sig.select(".features") if sig else []: # "final", "getter/setter pair" + feature.decompose() + code = tidy(" ".join(sig.get_text().split())) if sig else f"{KEYWORD.get(symbol['kind'], '')} {symbol['name']}".strip() + parts = [f"{'#' * level} `{label}`", f"```dart\n{code}\n```"] + parts += [markdown(page.select_one(s)) for s in ("section.desc", "section#values") if page.select_one(s)] + return "\n\n".join(p for p in parts if p) + + +def tidy(signature: str) -> str: + """Drops the spaces dartdoc's line breaks leave just inside brackets and before a closing one.""" + for a, b in (("( ", "("), (" )", ")"), ("{ ", "{"), (", }", "}"), (", )", ")"), ("[ ", "["), (", ]", "]")): + signature = signature.replace(a, b) + return signature + + +def markdown(node) -> str: + """A dartdoc section as Markdown. Links become plain text.""" + for dl in node.select("dl"): # enum values and properties become `name: description` lists + items = [(dt.select_one(".name") or dt).get_text().strip() for dt in dl.select("dt")] + docs = [(dd.p or dd).decode_contents() for dd in dl.select("dd")] + dl.replace_with(BeautifulSoup("", "html.parser")) + for h in node.find_all(["h2", "h3"]): + h.name = "h5" + for text in node.find_all(string=True): # braces in prose only; code keeps them + if not text.find_parent(["code", "pre"]): + text.replace_with(str(text).translate(MDX)) + md = markdownify(str(node), strip=["a"], heading_style="ATX", bullets="-", code_language="dart") + return md.strip().replace("
", "
") + + +def capabilities(checkout: str) -> dict[str, str]: + """Each sdk-specs capability's slug and title in sentence case, in the README's order.""" + acronyms = {"id": "ID", "ai": "AI", "http": "HTTP", "mcp": "MCP"} + titles = {} + for line in (Path(checkout) / "README.md").read_text().split("\n"): + cells = line.split("|") + if len(cells) > 2 and "openspec/specs/" in cells[2]: + slug = cells[2].split("openspec/specs/")[1].split("/")[0] + titles[slug] = " ".join(acronyms.get(w.lower(), w.lower()) for w in cells[1].split()) + order = [*FIRST, *(s for s in titles if s not in FIRST)] + return {s: titles[s][0].upper() + titles[s][1:] for s in order if s in titles} + + +def reference(docs: Docs, caps: dict[str, str], current: bool) -> list[str]: + top = sorted( + (s for s in docs.index if s.get("enclosedBy", {}).get("name") == LIBRARY and s["kind"] in (CLASS, ENUM, EXTENSION, TYPEDEF, FUNCTION)), + key=lambda s: s["name"], + ) + sdk = next(s for s in top if s["name"] == "Posthog") + mapped = json.loads((ROOT / "docs/capabilities.json").read_text()) + listed, upcoming = set(mapped.pop("utils")), mapped.pop("next", {}) + members = {f"Posthog.{m['name']}": m for m in docs.members(sdk)} + for name in mapped if current else []: # the next major may remove methods + if name not in members: + raise SystemExit(f"docs/capabilities.json: {name} is not a Posthog member") + mapped |= upcoming + tagged: dict[str, list[str]] = {} + utils = [] + for name, m in members.items(): + found = mapped.get(name) + if found and found not in caps: + raise SystemExit(f"docs/capabilities.json: {name} has unknown capability {found}") + if not found and name not in listed: + raise SystemExit(f"docs/capabilities.json: map {name} to a capability or list it in utils") + (tagged.setdefault(found, []) if found else utils).append(docs.entry(m, name, 3)) + out = [] + for slug, title in caps.items(): + if slug in tagged: + out += [f"## {title}", *tagged[slug]] + out += ["## SDK utils", *utils] + for name in sorted(CLIENTS): + client = next(s for s in top if s["name"] == name) + out += [f"## {name}", docs.entry(client, name, 3)] + out += [docs.entry(m, label(name, m), 4) for m in docs.members(client)] + out.append("## Types") + for t in top: + if t["name"] not in CLIENTS and t is not sdk: + out.append(docs.entry(t, t["name"], 3)) + out += [docs.entry(m, label(t["name"], m), 4) for m in docs.members(t)] + return out + + +def label(owner: str, member: dict) -> str: + """`Type.member`, or `Type()` and `Type.named` for constructors, which dartdoc names `Type.new`.""" + if member["kind"] == CONSTRUCTOR: + return f"{owner}()" if member["name"].endswith(".new") else member["name"] + return f"{owner}.{member['name']}" + + +def anchor(heading: str) -> str: + """The github-slugger slug the docs site gives a heading.""" + return "".join(c for c in heading.lower() if c.isalnum() or c in "-_ ").replace(" ", "-") + + +def front_matter(title: str, sections: list[str]) -> str: + """The docs site's front matter. Its ToC lists the page's H2 sections only.""" + toc = [] + for heading in [s[3:] for s in sections if s.startswith("## ")]: + toc.append(f' - value: "{heading}"\n url: {anchor(heading)}\n depth: 0') + head = [f'title: "{title}"', "sidebar: Docs", "showTitle: true"] + head += ["contentMaxWidthClass: max-w-full", "platformLogo: flutter", "tableOfContents:", *toc] + return "\n".join(["---", *head, "---"]) + + +def nest(markdown: str) -> str: + """Moves each heading down one level and drops the H1. Code stays as written.""" + out, fence = [], False + for line in markdown.strip().split("\n"): + fence ^= line.strip().startswith("```") + if fence or not line.startswith("#"): + out.append(line) + elif not line.startswith("# "): + out.append("#" + line) + return "\n".join(out) + + +def write(name: str, sections: list[str]) -> None: + (ROOT / "references" / name).write_text("\n\n".join(sections) + "\n") + print(f"wrote references/{name}") + + +def main() -> None: + args = argparse.ArgumentParser(description="Generate the SDK reference Markdown.") + args.add_argument("--sdk-specs", required=True, help="PostHog/sdk-specs checkout") + args.add_argument("--major", type=int, help="target major, defaults to the declared one") + opts = args.parse_args() + version = next(l for l in (PKG / "pubspec.yaml").read_text().split("\n") if l.startswith("version:")) + declared = int(version.split(":")[1].strip().split(".")[0]) + major = opts.major or declared + with tempfile.TemporaryDirectory() as tmp: + subprocess.run(["flutter", "pub", "get"], cwd=PKG, check=True, stdout=subprocess.DEVNULL) + subprocess.run(["dart", "doc", "--output", tmp], cwd=PKG, check=True, stdout=subprocess.DEVNULL) + docs = Docs(Path(tmp)) + body = ["## Getting started", nest((ROOT / "docs/getting-started.md").read_text())] + body += reference(docs, capabilities(opts.sdk_specs), declared >= major) + (ROOT / "references").mkdir(exist_ok=True) + title = f"PostHog Flutter SDK {major}.x" + ("" if declared >= major else " (experimental)") + write(f"posthog-flutter-{major}.md", [front_matter(title, body), *body]) + if declared >= major: + write("posthog-flutter-reference.md", [front_matter("PostHog Flutter SDK", body), *body]) + # The migration guide lives next to the package, as posthog_flutter/MIGRATION.md. + if guides := [g for g in [PKG / "MIGRATION.md"] if g.exists()]: + head = "---\ntitle: PostHog Flutter SDK migration guides\nsidebar: Docs\nshowTitle: true\n---" + write("posthog-flutter-migration.md", [head, *(g.read_text().strip() for g in guides)]) + + +if __name__ == "__main__": + main() diff --git a/scripts/requirements.txt b/scripts/requirements.txt new file mode 100644 index 00000000..49a49188 --- /dev/null +++ b/scripts/requirements.txt @@ -0,0 +1,2 @@ +beautifulsoup4==4.15.0 +markdownify==1.2.3