Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,10 @@ player, and production-minded.
count. Do not add a fourth: the rules in a group's first post and the
admins' note when maply may not pin go into the post itself, and so does
the month's season champion, in the look back of the month's last day.
The welcome when maply is added answers the admin, as `/start` does, and
is not one of the three. A group added after its reveal gets a warm-up on
the archive's newest day and its result an hour later, the only scheduled
message of that day (`docs/design.md` → "Groups").
- Posts write the reveal with the chat's zone, "20:00 (Kyiv)". A chat's zone is
stored the first time maply needs it (`FixZone`), so a later change of
language cannot move a reveal. A DM's stored this way is marked automatic
Expand Down Expand Up @@ -99,10 +103,11 @@ player, and production-minded.
- Free play (`internal/free`, `/play`, `/party/<code>`; the archive and a
challenge are screens inside `/play`) is outside the day:
its own `free_*` tables, no place in the world, no stats shared with the
day, and no bot message in groups. Its rules are in `docs/design.md` →
"Free play". Records and friends need an account: a Telegram person (the
Mini App, or the site with an account that has Telegram, which plays as
the person and writes nothing to `core`) or an account with Google alone,
day, and no bot message in groups but a new group's warm-up result. Its
rules are in `docs/design.md` → "Free play". Records and friends need an
account: a Telegram person (the Mini App, or the site with an account
that has Telegram, which plays as the person and writes nothing to
`core`) or an account with Google alone,
which plays as its own site player. A guest plays alone, without records.
Its leaderboards (`/api/top`) count only games on a timer and never an
attempt at a challenge, one row a person or an account with their best:
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ See [`docs/versioning.md`](docs/versioning.md) for what the numbers mean and
result says, before the evening, whether you have answered and how long
until the result, and after it your score and place in the world. The
keyboard follows a language change; groups never get it.
- A group hears from maply the moment it is added: what maply is, when the
place and the answer come in the group's zone, and what comes next. A
group added after its 20:00 gets a warm-up on the newest day of the
archive, with its own result an hour later, so it has something to play
that evening. The warm-up counts nowhere: not in the day's tables, the
world, profiles, streaks or ratings. When maply may not pin in a
supergroup, the welcome asks the admins once, with a button that requests
just that right. `/start` in a group offers the warm-up while it runs.
For the operator: migration 031 adds the `warmup` tables and job kind.

## v0.0.1-alpha.20 - 2026-11-10

Expand Down
2 changes: 1 addition & 1 deletion cmd/maply-dev/fakebot.go
Original file line number Diff line number Diff line change
Expand Up @@ -1047,7 +1047,7 @@ func (f *fakeTelegram) run(ctx context.Context, e *Env) (func(), error) {
tgc := telegram.New(client)
tgc.Upload = &telegram.Uploader{Base: base, Token: BotToken}
avatars := &avatar.Service{Store: e.Store, TG: tgc, Log: log, Now: e.Clock.Now}
opts := bot.Options{Username: botUsername, Version: "dev", AppURL: appURL, Zones: e.Zones, Now: e.Clock.Now}
opts := bot.Options{Payloads: e.Signer, Username: botUsername, Version: "dev", AppURL: appURL, Zones: e.Zones, Now: e.Clock.Now}
sched := &schedule.Scheduler{
Store: e.Store, TG: tgc, Weather: standWeather{}, Payloads: e.Signer, Zones: e.Zones,
Countries: e.Countries, ImagesDir: e.ImagesDir, Username: botUsername, AppURL: appURL,
Expand Down
3 changes: 2 additions & 1 deletion cmd/maply/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,9 @@ func run(log *slog.Logger) error {
log.Info("animated posts on", "ffmpeg", path)
}
}
signer := auth.NewSigner(cfg.TelegramBotToken)
opts := bot.Options{
Payloads: signer,
Username: me.Username,
Version: version,
AppURL: cfg.AppURL,
Expand All @@ -130,7 +132,6 @@ func run(log *slog.Logger) error {
// The players' photos for the pins and tables of the results.
avatars := &avatar.Service{Store: store, TG: tgc, Log: log}

signer := auth.NewSigner(cfg.TelegramBotToken)
// Without a renderer the result goes out with the place's photo and the
// Mini App shares through t.me/share, as before the card existed.
var cards *card.Service
Expand Down
11 changes: 8 additions & 3 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,15 +189,20 @@ In a DM the intrigue arrives only if the person has not answered yet. The "Chat

## Groups

- **First day.** Right after being added, the bot runs a warm-up round on yesterday's place with the answer the same evening, so the group does not wait until tomorrow morning.
- **Permissions.** The game works without the right to pin messages. The bot tells the admins once that it is more fun with a pin.
- **First day.** The moment maply is added, the group gets one welcome: the group's home panel (Settings, Help, Close) with what maply is, when the place comes and when the answer does, "07:00" and "20:00 (Kyiv)" in the group's own post time and zone, and what comes next, which depends on where the group's day stands (decided in #57 on 16 November 2026):
- before the morning post: the first place comes at the post time today;
- between the post and the reveal: today's real round, whose post the scheduler sends within seconds of the welcome. A real round beats a warm-up, and two places at once would only confuse;
- after the reveal: a **warm-up**, since the group would otherwise wait until tomorrow morning. It plays the archive's newest day, normally yesterday's place: over in every zone, kept, and a panorama, as the free game's archive has it. Its button opens the Mini App with `startapp=w<payload>`, signed for the group and the day (version 3 of the payload), and membership is asked of Telegram as for a day's post. Each player's game is their own day from the archive (`free_archive`), so the warm-up counts in no day's table, no world, no profile, no streak and no rating, and someone who answered that day or had its place cannot take it, as in the archive. `warmup_game` only says which of those games came from the group. It takes answers for an hour (`schedule.WarmupFor`); then the `warmup` job sends its result: the place, the group's table and when the real game starts. Nobody played, no result. A group gets one warm-up ever; added back, it gets a welcome without one. The day's game for that date has no post and no result there.

The welcome answers an admin adding maply, as a `/start` panel does, and is none of the day's three messages; the warm-up's result is the only scheduled message of a day the group has no round of. `/start` in a group shows the warm-up's button while it takes answers.
- **Permissions.** The game works without the right to pin messages. The bot tells the admins once that it is more fun with a pin: in the welcome, when maply joins a supergroup without being its admin, with a button `t.me/<bot>?startgroup=pin&admin=pin_messages` that asks Telegram for that one right; otherwise in the first post that could not be pinned. In a basic group every member may pin unless the admins said otherwise, so the welcome does not ask there.
- **`/rival`.** Links two chats into a duel: a shared season score and the "Rival" intrigue.
- **Seasons.** A calendar month. At the end the chat gets a champion of the month, and the ranking resets.
- **Settings** through buttons in `/start`, as in quoto: morning post time, intrigue on/off, streak mentions on/off.

## Free play

Next to the day's game, which keeps every rule above, there is free play: alone or with up to eight friends, as many places as one likes, with no place in the world and no stats shared with the day. It is called "Free play" and opens at `/play`: from the menu, from the DM's `/start` panel and from a friend's invitation. It looks as the day's game does, the same header, panorama, globe, caption and bottom strip, and after an answer the same plates on a phone and the same side panel on a computer; only what is counted differs: the place of the game ("Place 2/5") where the day has its number, the place's clock where the day has its countdown, and the points. The menu's cards open the settings on a mode, `/play?mode=classic|blitz|streak|clock|archive`, and `/play?with=friends` opens a lobby; Blitz is the classic on 30 s. The bot writes nothing about it in groups, so the three messages a day stay three.
Next to the day's game, which keeps every rule above, there is free play: alone or with up to eight friends, as many places as one likes, with no place in the world and no stats shared with the day. It is called "Free play" and opens at `/play`: from the menu, from the DM's `/start` panel and from a friend's invitation. It looks as the day's game does, the same header, panorama, globe, caption and bottom strip, and after an answer the same plates on a phone and the same side panel on a computer; only what is counted differs: the place of the game ("Place 2/5") where the day has its number, the place's clock where the day has its countdown, and the points. The menu's cards open the settings on a mode, `/play?mode=classic|blitz|streak|clock|archive`, and `/play?with=friends` opens a lobby; Blitz is the classic on 30 s. The bot writes nothing about it in groups, so the three messages a day stay three; a group's warm-up on its first evening (see "Groups") is the one day of the archive a group hears about.

Back goes one step up: from a place or the final to the mode's settings, from a day of the archive to the archive, from a game of a challenge to its table. The mode's settings, the archive and the lobby are pages of the top, as the days and the leaderboards are: on a phone's browser Back leads to the menu, on a computer they have no Back, the header is the way, and in Telegram Telegram's Back is the only one on every screen. Escape does what Back does. Between `/play` and `/party/<code>` the free game keeps one entry of the browser's history, so the menu is the step before any of its pages.

Expand Down
2 changes: 1 addition & 1 deletion docs/mvp-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ maply calls them through `Client.Call` right away. Typed methods will be added t

- `/start` in a group:
- settings with buttons, as in voicy and branchy;
- a warm-up on yesterday's place with the answer the same evening;
- a welcome the moment maply is added, and a warm-up on the archive's newest day with its result an hour later when the group joins after its reveal (decided in #57, see `docs/design.md` → "Groups");
- one message to the admins if the bot has no right to pin.
- 07:00 in the chat's time zone, or at the time the group chose:
- a post with the photo and a button;
Expand Down
2 changes: 2 additions & 0 deletions internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ type Store interface {
AdoptDMZone(context.Context, int64, string) (bool, error)
FixZone(context.Context, int64, string) error
ChatActive(context.Context, int64) (bool, error)
WarmupOf(ctx context.Context, chatID int64) (db.Warmup, bool, error)
JoinWarmup(ctx context.Context, chatID, game int64) error
DaysPage(context.Context, db.DaysQuery) (db.DaysPage, error)
RoundNo(context.Context, int) (db.Round, bool, error)
ClosedDay(context.Context, round.Date, round.Date) (db.ClosedDay, error)
Expand Down
5 changes: 4 additions & 1 deletion internal/api/free.go
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,9 @@ type freeViewer struct {
// site is a browser rather than the Mini App: its invitations are the
// site's own links.
site bool
// start is the Mini App's start_param, which Telegram signs with the rest
// of initData; empty on the site.
start string
}

// keeps is whether the viewer keeps records and may play with friends. An
Expand Down Expand Up @@ -126,7 +129,7 @@ func (s *Server) freeViewer(w http.ResponseWriter, r *http.Request, lim *limiter
if err != nil {
return freeViewer{}, err
}
return freeViewer{who: free.Who{UserID: data.User.ID}, user: data.User, lang: i18n.Resolve(lang)}, nil
return freeViewer{who: free.Who{UserID: data.User.ID}, user: data.User, lang: i18n.Resolve(lang), start: data.StartParam}, nil
}
if write && !ownJSON(r) {
return freeViewer{}, apiError{http.StatusUnsupportedMediaType, "json_only"}
Expand Down
56 changes: 56 additions & 0 deletions internal/api/free_more.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ package api
// keep records, a Telegram person or an account, as a party is.

import (
"context"
"crypto/rand"
"encoding/base64"
"net/http"
"strings"

"github.com/FreshLabDev/maply/internal/free"
"github.com/FreshLabDev/maply/internal/i18n"
Expand Down Expand Up @@ -37,11 +39,21 @@ func (s *Server) archiveTake(w http.ResponseWriter, r *http.Request) {
}
var b struct {
N int `json:"n"`
// Warmup takes the day of the group's warm-up the app was opened
// on, in place of n.
Warmup bool `json:"warmup"`
}
if err := readBody(w, r, &b); err != nil {
s.freeFail(w, r, err)
return
}
var chatID int64
if b.Warmup {
if chatID, b.N, err = s.warmup(r.Context(), v); err != nil {
s.freeFail(w, r, err)
return
}
}
if err := s.met(r.Context(), v); err != nil {
s.freeFail(w, r, err)
return
Expand All @@ -51,9 +63,53 @@ func (s *Server) archiveTake(w http.ResponseWriter, r *http.Request) {
s.freeFail(w, r, err)
return
}
if chatID != 0 {
if err := s.Store.JoinWarmup(r.Context(), chatID, g.ID); err != nil {
s.freeFail(w, r, err)
return
}
}
writeJSON(w, http.StatusOK, g)
}

// errWarmupOver is a warm-up whose result has gone out, or whose time has.
var errWarmupOver = apiError{http.StatusGone, "warmup_over"}

// warmup is the group and the day of the warm-up the Mini App was opened on
// from a group's welcome: "w" and a payload signed for both, read from
// initData. As with the day's post, the payload only says where the link
// came from, so membership is asked of Telegram. A warm-up is a day of the
// archive, closed in every zone, played as any day of the archive is: the
// group only gets to see who of it played.
func (s *Server) warmup(ctx context.Context, v freeViewer) (int64, int, error) {
raw, ok := strings.CutPrefix(v.start, "w")
if !ok || v.who.UserID == 0 {
return 0, 0, errBadRequest
}
p, err := s.Payloads.VerifyWarmup(raw)
if err != nil {
return 0, 0, errUnauthorized
}
wu, ok, err := s.Store.WarmupOf(ctx, p.ChatID)
if err != nil {
return 0, 0, err
}
if !ok || wu.Day.String() != p.Date.String() {
return 0, 0, free.ErrNotFound
}
if !wu.Open(s.Now()) {
return 0, 0, errWarmupOver
}
member, err := s.Members.IsMember(ctx, p.Date, p.ChatID, v.who.UserID)
if err != nil {
return 0, 0, err
}
if !member {
return 0, 0, errNotMember
}
return p.ChatID, wu.DayNo, nil
}

func (s *Server) challengeMake(w http.ResponseWriter, r *http.Request) {
v, err := s.freeViewer(w, r, s.makeLimit, true)
if err != nil {
Expand Down
Loading
Loading