clientCommands/docs/sdk-notes.md

exteraGram plugin SDK — condensed notes

Gathered from https://plugins.exteragram.app/docs, the SDK type stubs (stubs.zip from exteraSquad/plugins-pysdk-builds), the official exteragram-utils PyPI package (exteragram_utils/dev_client.py), and the app's gradle.properties. Not exhaustive — see the full docs site for anything not covered here.

Plugin identity and metadata

Read statically via AST from top-level constant assignments in the plugin's single .py file — the app never executes the file just to read metadata. Docs: https://plugins.exteragram.app/docs/metadata.

Constant	Required	Notes
__id__	yes	2–32 chars, starts with a letter, only A-Za-z0-9_-
__name__	yes	display name
__description__	no
__author__	no
__version__	no
__icon__	no	e.g. "exteraPlugins/1"
__app_version__	no	e.g. ">=12.5.1"; legacy alias __min_version__
__sdk_version__	no	e.g. ">=1.4.4.3"
__requirements__	no	list of pip package specs the host installs before loading

BasePlugin lifecycle and hooks

https://plugins.exteragram.app/docs/base-plugin

• on_plugin_load(self) — called once when the plugin is enabled/loaded. Hooks must be registered here (e.g. self.add_on_send_message_hook()); registering later has no effect.
• on_plugin_unload(self) — called on disable/removal; release resources here.
• create_settings(self) — returns a list of ui.settings rows rendered in the plugin's settings screen.
• Hooks: on_send_message_hook(self, account, params), pre_request_hook(self, ...), post_request_hook(self, ...), on_update_hook(s)(self, ...), on_app_event(self, ...). Each returns a HookResult.
• HookResult(strategy=HookStrategy.MODIFY, params=params) applies the mutated params back to the host; HookStrategy.DEFAULT (a bare HookResult()) passes through unchanged; HookStrategy.CANCEL drops the action; HookStrategy.MODIFY_FINAL applies changes and short-circuits any later hooks.
• Settings persistence: self.get_setting(key, default) / self.set_setting(key, value).

ui.settings row types

https://plugins.exteragram.app/docs/ui-settings

Header, Input, Switch, Text, Selector, Divider — plain kwargs-holding row descriptors consumed by the host's settings renderer; construct and return them from create_settings.

Logging

https://plugins.exteragram.app/docs/logging

android_utils.log(...) writes to logcat. Chaquopy additionally redirects sys.stdout/sys.stderr to the logcat tags python.stdout / python.stderr — useful when a dependency logs with plain print().

Background work

https://plugins.exteragram.app/docs/client-utils

client_utils.run_on_queue(...) schedules work off the UI thread; use it for anything that shouldn't block message handling.

Reflection / private API access

https://plugins.exteragram.app/docs/hook-utils

hook_utils.find_class(...) and related helpers locate app classes and private fields for plugins that need to reach beyond the public SDK surface.

UI helpers

• ui.alert.AlertDialogBuilder — native alert dialogs. https://plugins.exteragram.app/docs/ui-alert
• ui.bulletin — transient bottom bulletins/toasts. https://plugins.exteragram.app/docs/ui-bulletin
• intents.IntentsManager — Android intent integration, exteraGram 12.6.4+ only. https://plugins.exteragram.app/docs/intents

On-device dev server protocol

https://plugins.exteragram.app/docs/dev-server

TCP 127.0.0.1:42690, reachable from a PC via adb forward tcp:42690 tcp:42690. Wire format is consecutive UTF-8 JSON objects with no length framing — parse with json.JSONDecoder().raw_decode over an accumulating buffer, never assume one JSON object per recv(). Requests: {"@": <command>, "#": <id>, ...}; responses echo "#".

Commands used by this repo's tools/devclient.py: ping, get_plugins, enable_plugin, disable_plugin, reload_plugin, remove_plugin (field plugin_id), write_plugin (plugin_id, content — installs or updates), start_debugger/stop_debugger (host, port, platform ∈ vscode|pycharm). The official exteragram-utils client (PyPI) uses integer request ids from 1, a 30 s response timeout, a 1.0 s socket timeout, a write_plugin → sleep 0.3 s → reload_plugin deploy sequence, and adb forward (not reverse) for both the dev-server port and the debugger port. elyx_* commands exist for the Elyx engine and are out of scope here.

Runtime

Chaquopy 16 / Python 3.11. Anything shipped in a bundle must be 3.11-compatible.

Why not Elyx/ElyxBuilder

The official structured plugin format (Elyx/ElyxBuilder) is a real alternative to a single .plugin file, but it:

• requires the separate Elyx engine to be installed and enabled on the device;
• ships archives, not the .plugin files the base plugin engine understands;
• needs a manual first install before live reload works.

This repo's bundler instead compiles a normal multi-file src/ project down to the one .plugin file the base engine already knows how to load, so the dev-server write/reload loop works from the first deploy with no extra on-device engine.

Gotchas found on exteraGram 12.10.6 (client_commands)

• Class checks. hook_utils.find_class returns a Chaquopy class wrapper without isInstance. Use jutil.java_class(name), which gives the real java.lang.Class.
• Plugin-made modules. A module a plugin puts into sys.modules doesn't reliably survive that plugin's reload. State that must outlive a reload (the library registry) hangs off builtins instead.
• Suggestion list. MentionsAdapter.notifyDataSetChanged diffs rows by their item (the command string). Rows whose label stays the same aren't rebound, so call notifyItemRangeChanged too. The adapter's : emoji search is async and replaces the rows, so replace the search (skip the method) instead of patching its result.
• Recycled cells. A cell restyled by an earlier load of the plugin keeps that style. Remember the original in the view's tag, not in plugin memory.
• Ephemeral messages. A tap opens their menu; a long press does nothing. Deleting one goes through MessagesController.deleteEphemeralMessage, which also asks Telegram to delete it.