mirror of
https://github.com/tiennm99/miti99bot.git
synced 2026-09-12 04:20:49 +00:00
tiennm99
4e805f0a7f
Nine commands mirroring the names @Stickers uses: /newpack, /mypack, /addsticker, /delsticker, /editsticker, /ordersticker, /setpackicon, /renamepack and /delpack, plus a confirm callback for the destructive one. Sources are replied stickers, photos or image documents; photos are downloaded, resampled to 512px and re-uploaded. One pack per user, keyed by owner id. Creating a pack is the only operation here that makes a durable, publicly linkable object on a user's behalf, so it is built around proving ownership rather than assuming it: - A name is claimed globally and create-only before Telegram is called. A pending record alone proves only that a caller *asked* for a name, which is exactly what someone naming a victim's public slug also does. - Adopting an existing set additionally requires that the claim predates this invocation. The claim lives in our store and the pack lives at Telegram, so a wiped store would otherwise make every pack adoptable. - Names are released only on positive evidence that no pack stands behind them, never on a generic failure, so a transient error cannot hand a live name to the next caller. - Ownership refusals are byte-identical across failure modes, so they cannot be used to probe which sets exist. Error classification is positive-only throughout: "the set is gone" and "nothing was created" are each proven from a specific Telegram response, never inferred from an error. Post-action commits run on a context detached from the request so a shutdown mid-handler cannot lose the record of something Telegram already did. Enabled explicitly via MODULES rather than by default.
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
# Command Parameter Conventions
|
|
|
|
## Overview
|
|
|
|
Every Telegram command declares optional `Parameters` metadata. The bot reuses
|
|
that string in `/help` and Telegram's native command menu, so it must be short,
|
|
consistent, and understandable on a phone.
|
|
|
|
Treat `Parameters` as display syntax, not as a validation schema. Handlers
|
|
remain responsible for parsing and validation.
|
|
|
|
## Syntax
|
|
|
|
| Meaning | Format | Example |
|
|
|---|---|---|
|
|
| Required value | `<name>` | `<ticker>` |
|
|
| Required comma-separated values | `<name,...>` | `<option,...>` |
|
|
| Required remaining text | `<name...>` | `<title...>` |
|
|
| Optional value | `[name]` | `[date]` |
|
|
| Optional remaining text | `[name...]` | `[target...]` |
|
|
| Alternatives in an optional group | `[literal | literal <name>]` | `[users | user <username>]` |
|
|
|
|
Use only constructs required by the command. Do not introduce a formal schema
|
|
language or extra punctuation without a user-facing need.
|
|
|
|
## Naming
|
|
|
|
- Use lowercase `snake_case`.
|
|
- Prefer one descriptive noun: `<ticker>`, `<quantity>`, `<champion>`.
|
|
- Include units or currencies when they prevent ambiguity: `<vnd_amount>`,
|
|
`<usd_to_spend>`.
|
|
- Do not add primitive types such as `<quantity:number>` or `<date:string>`.
|
|
- Keep literal subcommands bare: `users`, `user`, `cmd`.
|
|
- Put spaces around `|` in alternatives.
|
|
- Do not repeat format prose inside a placeholder.
|
|
- Show punctuation that users must type exactly when omitting it would be
|
|
error-prone. `<ratio(owned:new)>` and `<option,...>` are approved compact
|
|
shapes.
|
|
|
|
## Examples
|
|
|
|
```text
|
|
/stock_buy <quantity> <ticker>
|
|
/renamepack <title...>
|
|
/lol [date]
|
|
/trongtruonghop [target...]
|
|
/stats [users | user <username> | cmd <command_name>]
|
|
/stock_share_dividend <ratio(owned:new)> <ticker>
|
|
/random <option,...>
|
|
```
|
|
|
|
## Change Checklist
|
|
|
|
When adding or changing a command:
|
|
|
|
1. Make `Parameters` match the handler's accepted argument order.
|
|
2. Keep the parameter string single-line and concise enough for Telegram's
|
|
command-description limit.
|
|
3. Update handler usage and error text to use the same syntax.
|
|
4. Update registration, handler, `/help`, and native-menu tests.
|
|
5. Update README or feature documentation when behavior is user-visible.
|
|
6. Follow the stats migration rules in `AGENTS.md` when a command name changes
|
|
or a command is deleted.
|
|
|
|
## References
|
|
|
|
- [POSIX.1-2024 utility conventions](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html)
|
|
- [GNU command-line interface standards](https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html)
|
|
- [Microsoft command-line syntax key](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/command-line-syntax-key)
|
|
- [Python argparse documentation](https://docs.python.org/3/library/argparse.html)
|
|
- [docopt usage-pattern grammar](https://github.com/docopt/docopt/blob/master/README.rst)
|