@typetorch/framework 0.5.7 → 0.6.1

package/README.md

@@ -360,6 +360,30 @@ TypeTorch.runDetached(() => store.StartSessionAsync(`Player_${userId}`)).then((p
   run at once per server (then it throws); one past 60 s is logged and flagged in Server > Status. Older kernels
   throw "needs kernel 0.3.8; use the DataHost job queue (Player data guide)": the other option, which works on every
   kernel. `features.runDetached` tells which one this server has.
+- **`notifications()`** (plans/29): native Roblox experience notifications through the TypeTorch backend (`backend.url`
+  / `backend.key`, the launch-token keys in `backend.notify` from `typetorch notify key rotate`; no kernel change).
+  The game says why a player should hear from it, the backend decides when and sends, the framework verifies the tap:
+
+  ```ts
+  const notify = TypeTorch.notifications();
+  // Server: intents (upsert by user + kind + key; offline players by UserId), batched and swap-safe.
+  notify.want(userIdOrPlayer, "gift_new", { key: letterId, until: expiresAt, params: { gift: "5 coins" }, data: `mail:${letterId}` });
+  notify.drop(userIdOrPlayer, "streak", "20034", "played"); // no key: every key of the kind
+  // The kinds the player switched off in your settings: REPLACES their set ([] = all on), at most 32 names. The backend
+  // skips those intents whoever issued them (pref_off) and keeps them, so switching a kind back on resumes it.
+  notify.setOff(player, ["daily", "quests"]);
+  trove.add(notify.onOpen((player, open) => openMail(player, open.data))); // open: { nid, kind, data, ageSeconds, first }
+  // Client: Roblox's opt-in prompt, once per session (show your own explainer first). Yields until it closes.
+  const result = TypeTorch.notifications().promptOptIn("streak_2"); // "shown" | "unavailable" | "error" | "busy" | "already"
+  ```
+
+  Kinds are declared in typetorch.json `notifications` and pushed with the CLI. Intents go to
+  `<backend.url>/v1/notify/intents` every `flushSeconds` (and at 200); presence (`online` on join and every 3 h, `offline` on leave)
+  rides along while `backend.notify` is set. A join with `tt1n.` launch data is verified on the server (HMAC, the
+  player's UserId, 14 days; the previous key for 14 days after a rotation): `onOpen` gets only verified data, also for
+  players who joined before the callback connected. Rows (`kind = notify`): `want`, `drop`, `optin_check`,
+  `optin_shown`, `optin_closed`, `open`, `open_bad`, `played` (src/analytics/SCHEMA.md); the join row gets
+  `from = "notification"`. Without backend settings (Studio) nothing is posted; rows are still written.
 - **Edit mode** (UI Labs stories, no kernel): `running` is false, identity has defaults, `persist` keeps a local table,
   events never fire, and the server-only reads throw.
 
@@ -520,7 +544,7 @@ const variant = analytics.experiment("onboarding", ["short", "long"]); // same a
   when the player is alone) intersected with the players there, not a web call per player.
 
 **Settings, framework 0.4.0 / kernel 0.4.0 (plans/21):** the record's `backend` = `{ url, key, analytics?: { flushSeconds,
-recordShare } }` (`typetorch backend setup`) is the whole sink: DuckDB at `<url>/v1/ingest` with the one key (Basin
+recordShare, joinLaunchPrefix, joinData } }` (`typetorch backend setup`) is the whole sink: DuckDB at `<url>/v1/ingest` with the one key (Basin
 identities to `<url>/v1/identity`). The old `analytics` value below is read while `backend` is missing, and stays the
 way to a Basin sink. The engine also tells the kernel each player's pid (`setAnalyticsId`: the kernel's error reports
 count affected players by pid, never by name) and counts its own DataStore and HTTP requests for the budget view (dev
@@ -543,6 +567,12 @@ there are no settings unless the game passes `new AnalyticsEngine({ settings })`
   Basin Pipelines Send permission, if the stream requires authentication). Without `recordings` nothing is recorded.
   The streams' schemas must match SCHEMA.md exactly: Basin drops rows that don't, silently.
 - `duckdb`: one `POST <events>` with `{"events":[...],"recordings":[...]}`, gzip, `Authorization: Bearer <token>`.
+- Join row settings (also in `backend.analytics`):
+
+  | Setting | Default | Meaning |
+  |---|---|---|
+  | `joinData` | `"full"` | `"full"`: the join row's summary props plus `jd`, a privacy-safe copy of the whole `GetJoinData()` (at most 1 KB: launch data up to 200 bytes, place / game ids, the join context as text, the TeleportData's size, type and keys but never its content, Members / referrer / followed user as pids or `"other"`, unknown fields by type; plans/30). `"summary"`: no `jd`. `"off"`: no `jd` and only the join props from before plans/29 (`from`, `ctx`, `tp`, `party`, age, prem, country, friends, ret). Anything else warns and means `"full"`. Games that put personal data in launch data should use `"summary"` |
+  | `joinLaunchPrefix` | `false` | `true`: the summary `launch` keeps the first 32 characters of the game's own launch data (`jd.LaunchData` follows `joinData`, not this) |
 - The token is write-only and never logged. Needs **Allow HTTP Requests** (Game Settings > Security). No key: the
   engine collects but keeps only the newest 1,000 rows until settings appear. Removing the key stops sending, live.
 
@@ -589,8 +619,10 @@ bun run build   # rbxtsc --type package -> out/
   vouch, live-copy rules), `test-messaging` (messaging and the server list), `test-settings` (`liveConfig` and the
   settings lines), `test-detached` (`runDetached`), `test-dev-access` (the dev-only tools rule and every gate through
   it), `test-remote-debug` (the remote debug ops and their limits), `test-net-inspect` (packet capture),
-  `test-explorer-core` (Dex), `test-toolbox-sanitize` (the Creator Store sanitizer) and `test-sha256` (the pairing-code
-  fingerprint). `node scripts/check-self-calls.mjs out` flags compiled functions that call themselves on their first
+  `test-explorer-core` (Dex), `test-toolbox-sanitize` (the Creator Store sanitizer), `test-sha256` (SHA-256 / HMAC in util and the
+  pairing-code fingerprint), `test-notifications` (the launch token with the contract's shared vector, intent checks,
+  the queue: batches of 200, rev order, a swap's handover), `test-notify-server` (the notifications server against
+  mocked services) and `test-analytics-join` (the join row's metadata; no other player's UserId). `node scripts/check-self-calls.mjs out` flags compiled functions that call themselves on their first
   lines (after `bun run build`).
 - **Package contents:** only `out/` (no `.tsbuildinfo`), `README.md` and `LICENSE`; check with `bun pm pack --dry-run`.
 - **Explorer class icons:** `assets/class-icons.png` (kept locally, not in the repo: it is Roblox's own texture) is

package/out/analytics/SCHEMA.md

@@ -15,7 +15,7 @@ Integers are written with every digit (never exponent notation).
 |---|---|---|
 | `v` | int32 | Row format version: `1` |
 | `t` | int64 | Unix ms on the game server's clock. Client events are corrected by the server (`server now - age - ping/2`) |
-| `kind` | string | `session`, `tech`, `zone`, `funnel`, `purchase`, `currency`, `state`, `experiment`, `custom`, `recording_meta`, `fleet` |
+| `kind` | string | `session`, `tech`, `zone`, `funnel`, `purchase`, `currency`, `state`, `experiment`, `custom`, `recording_meta`, `fleet`, `notify` |
 | `name` | string | Event name (1-64 chars), see below |
 | `pid` | string | Random player id (32 hex chars; `t` + 31 hex = temporary, the player-id store couldn't be read). `""` for server-only events. Never the UserId |
 | `sid` | string | Session id (32 hex), new per join, kept across hot swaps. `""` for server-only events |
@@ -57,8 +57,11 @@ First-ever-session detail, one row per packed chunk.
 
 | kind | name | props |
 |---|---|---|
-| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `share` (launch data), `follow` (followed someone); `ctx?` (GameJoinContext.JoinSource name); `tp?` (had teleport data); `party?` (players teleported along); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join). `t` is the join time |
+| session | `join` | `from`: `direct` (Home, search, sorts: Roblox doesn't say), `teleport` (same game), `teleport_game` (another game), `referral` (invite/referral link), `notification` (a TypeTorch notification's launch data verified), `share` (other launch data), `follow` (followed someone); join metadata (plans/29): `src_place?`, `src_game?` (SourcePlaceId / SourceGameId), `ref?` / `follow?` (the referrer / followed user as their pid when this game knows them, else `"other"`: never a UserId; players in the server are free, others cost one DataStore read each, at most 2 per join and only with read budget to spare), `party?` (players teleported along) + `party_pids?` (the pids of those this game knows, at most 10), `ctx?`, `ctx_item?`, `ctx_asset?`, `ctx_outfit?`, `ctx_asset_type?` (GameJoinContext JoinSource / ItemType / AssetId / OutfitId / AssetType), `launch?` (`notification` + `nid`, `nk` (kind); `tt_bad` + `launch_bad` (`format`, `sig`, `user`, `old`); or the game's own launch data: `launch_len`, plus its first 32 chars in `launch` only with the settings' `joinLaunchPrefix`), `tp?` + `tp_bytes?` (TeleportData present, its JSON size; never the content), `age_days` (exact account age), `locale?`, `verified?` (HasVerifiedBadge), `membership` (MembershipType name); `age` (account age: `<1d`, `1-7d`, `7-30d`, `30-90d`, `90-365d`, `1-3y`, `3y+`); `prem` (Premium); `country?` (ISO code); `friends` (how many of the player's friends are in the server: one friend-list lookup per join, at most 10 pages, `0` when it fails); `ret` (days since the last visit, `-1` first visit or unknown); `late?` (the engine started over 60 s after the join); `jd?` (plans/30, with the settings' `joinData` `"full"`, the default: the raw join data, below). With `joinData` `"off"` only `from`, `ctx`, `tp`, `party`, `age`, `prem`, `country`, `friends`, `ret`, `late` are written. `t` is the join time |
 | session | `device` (src client) | `dev?` (the device class, as the `dev` column; frameworks after 0.4.2, older ones leave it out), `input` (`kbm`, `touch`, `gamepad`, `vr`, `unknown`), `w`, `h` (viewport points), `touch`, `kb`, `mouse`, `pad`, `vr`. Once per session. The class (Roblox gives game scripts no OS): `vr` when VRService.VREnabled; `console` when GuiService:IsTenFootInterface(); touch without a keyboard: `tablet` when the viewport's short side is 600 points or more, else `phone` (the first hello waits up to 2 s for a real viewport); a keyboard or mouse: `desktop` (touch laptops, tablets with a keyboard); else `unknown` |
+| notify | `want`, `drop` | Notifications (plans/29), written by the game server: `k` (kind), `key?` (first 12 hex of SHA-256 of the intent's key; never the key), `at?`, `until?`, `offline` (want: the user isn't in this server; the row then has no pid), `why?` (drop) |
+| notify | `optin_check`, `optin_shown`, `optin_closed` | The client's opt-in prompt, checked and written by the server (at most 3 of each per session): `where`, `can` (check), `err?` (`timeout`, `swap` or the error's first 64 chars), `secs` (closed: how long it was up) |
+| notify | `open`, `open_bad`, `played` | A join from a notification: `open` (`nid`, `k`, `age` (secs since sent), `first`), `open_bad` (`why`: `format`, `sig`, `user`, `old`), `played` (`nid`, `k`, `secs`: the opened session's length, at its end). Backend rows of the same kind (`planned`, `sent`, ...) come from `src = "backend"` |
 | session | `leave` | `secs` (session length), `why`: `left`, `shutdown`, `gone` (left while no generation ran the engine), `swap60?` (left within 60 s of a hot swap) |
 | tech | `server` | Every `techEvery` s: `fps` (physics), `hb` (Heartbeat rate), `mem` (MB, 10s), `players`, `ping50?`, `ping90?` (ms), `q`, `qr` (queued events, recordings), `dropped`, `sent`, `fails`, `health?`, `errors?` (kernel 0.3.2 health) |
 | tech | `client` (src client) | Every `techEvery` s: `fps`, `mem` (MB, 10s), `ping?` (ms) |
@@ -159,9 +162,31 @@ repo's `bun run local` does it). Every new signed copy applies at once, so dials
 | `experiments` | none | Per experiment: `active: false` (everyone gets the first variant, not stamped), `weights` (per variant, in the game's order), `variant` (force one), `players` (`{ [UserId or pid]: variant }`, at most 200: forces one player's variant over everything else, stamped `forced`; each client's hello gets only its own entry). The CLI writes them: `typetorch experiment` |
 | `identity` | the settings' `fleet` url + `/v1/identity` | basin: where identity rows go (below); none and no `fleet` in the settings: not sent. duckdb: unused |
 | `identityToken` | the settings' `fleet` token | basin: the token for `identity`. Never logged |
+| `joinData` | `"full"` | `"full"`: the join row carries `jd` (below); `"summary"`: no `jd`; `"off"`: no `jd` and only the pre-plans/29 join props (no pid lookups). Anything else is an error line (warned) and means `"full"`. In `backend.analytics` (or the old `analytics` value) |
+| `joinLaunchPrefix` | false | true: the join row's `launch` keeps the first 32 characters of the game's own launch data (off: only `launch_len`). Set it in `backend.analytics` (or the old `analytics` value) |
 
 Unknown fields are ignored. Settings errors are warned once (never with the token).
 
+## The raw join data (`jd`, plans/30)
+
+The `session` / `join` row's `jd` prop mirrors `Player:GetJoinData()` field by field, privacy-safe, at most 1024 bytes of
+JSON (written by the framework's own encoder, so an empty table stays `{}` where the shape says object):
+
+| field | content |
+|---|---|
+| `keys` | The top-level keys Roblox returned, sorted (each cut to 32 characters) |
+| `LaunchData?`, `LaunchDataLen?` | The launch data cut to 200 bytes at a UTF-8 boundary, and its full byte length; present iff the key is |
+| `SourcePlaceId?`, `SourceGameId?` | Numbers, present iff the keys are |
+| `GameJoinContext?` | Present iff the key is: every field as text (EnumItems by name), `{}` when empty |
+| `TeleportData?` | `{ bytes?, type, keys? }`: its JSON size, type and top-level keys (at most 20, 32 characters each, sorted); never the content |
+| `Members?` | `{ count, pids? }`: each member's pid when this game knows them (players in the server, or one of the join's at most 2 budget-checked DataStore reads shared with the summary props), else `"other"`; the joining player by their own pid |
+| `ReferredByPlayerId?`, `FollowUserId?` | pid or `"other"`; absent for 0 |
+| `other?` | Any other top-level key: its type name only, never the value |
+| `trunc?` | `true` when cut to fit: TeleportData keys first (then the list), Members pids (then the list), LaunchData (shorter), GameJoinContext values (64 each), `other` |
+
+No other player's UserId is ever in `jd`. Example (Roblox dropped a notification's launch data):
+`{"keys":["GameJoinContext","LaunchData"],"LaunchData":"","LaunchDataLen":0,"GameJoinContext":{}}`.
+
 ## Transport
 
 - **basin:** `POST <events>` with a JSON array of event rows and `POST <recordings>` with a JSON array of recording

package/out/analytics/join.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The `session` / `join` row's join metadata (plans/29 "Native join metadata"): every field of `Player:GetJoinData()`
+ * and the player facts, as props. The engine reads the data (enum values as their names, the TeleportData's JSON size,
+ * other players' pids looked up beforehand) and this builds the props.
+ *
+ * Privacy: no other player's UserId ever lands in a prop. Referrer, followed user and party members become pids (the
+ * game's pseudonymous ids) when this game knows them, else "other" (ref / follow) or nothing (party_pids).
+ *
+ * Pure: no imports and no services, so it runs under Lune (scripts/test-analytics-join.luau).
+ */
+/** What the engine reads from GetJoinData (enums already turned into names). */
+export interface JoinDataLike {
+    SourcePlaceId?: number;
+    SourceGameId?: number;
+    ReferredByPlayerId?: number;
+    Members?: number[];
+    /** Whether TeleportData was present (its content never leaves the server). */
+    HasTeleportData?: boolean;
+    LaunchData?: string;
+    GameJoinContext?: {
+        JoinSource?: string;
+        ItemType?: string;
+        AssetId?: string;
+        OutfitId?: string;
+        AssetType?: string;
+    };
+}
+/** The joining player and this server. */
+export interface JoinFacts {
+    userId: number;
+    /** game.GameId (a teleport from another game is `teleport_game`). */
+    gameId: number;
+    followUserId: number;
+    /** Player.AccountAge (days). */
+    accountAge: number;
+    locale?: string;
+    verified?: boolean;
+    /** Enum.MembershipType name. */
+    membership?: string;
+    /** The TeleportData's JSON size in bytes (undefined: none or not encodable). */
+    tpBytes?: number;
+}
+/** The launch data's verdict (notifications/token.ts verifyToken): undefined when it isn't a TypeTorch token. */
+export type LaunchVerdict = {
+    ok: true;
+    nid: string;
+    kind: string;
+} | {
+    ok: false;
+    why: string;
+} | undefined;
+export interface JoinOptions {
+    /**
+     * Keep the first LAUNCH_KEEP chars of the game's own launch data in `launch` (the analytics settings'
+     * `joinLaunchPrefix`, default off: launch data can carry anything a link maker put there). `launch_len` is always kept.
+     */
+    launchPrefix?: boolean;
+    /**
+     * The analytics settings' `joinData` (plans/30). "off": only what the join row carried before plans/29 (`from`,
+     * `ctx`, `tp`, `party`; the engine adds age, prem, country, friends, ret). "full" / "summary": every summary prop.
+     */
+    mode?: JoinDataMode;
+}
+/** `joinData` (plans/30): "full" (default: the summary props + `jd`), "summary" (no `jd`), "off" (see JoinOptions.mode). */
+export type JoinDataMode = "full" | "summary" | "off";
+export declare const JOIN_DATA_MODES: ReadonlyArray<JoinDataMode>;
+/** Party pids kept at most. */
+export declare const PARTY_PIDS_MAX = 10;
+/** The game's own launch data: this many characters are kept. */
+export declare const LAUNCH_KEEP = 32;
+/** UserIds whose pids the row wants (referrer, followed user, party members), without the player and duplicates. */
+export declare function wantedUserIds(data: JoinDataLike | undefined, facts: JoinFacts): number[];
+/**
+ * The join props. `pidOf(userId)` answers a known pid (a player in this server, or one this game's records know) or
+ * undefined.
+ */
+export declare function joinProps(data: JoinDataLike | undefined, facts: JoinFacts, pidOf: (userId: number) => string | undefined, launch: LaunchVerdict, options?: JoinOptions): Record<string, unknown>;
+/** Bytes of the `jd` JSON at most (props hold 4 KB; the join row's other props stay well under the rest). */
+export declare const JD_MAX_BYTES = 1024;
+/** LaunchData bytes kept (Roblox's own limit for launch data). */
+export declare const JD_LAUNCH_MAX = 200;
+/** TeleportData: top-level keys listed at most, and characters per key. */
+export declare const JD_TP_KEYS_MAX = 20;
+export declare const JD_KEY_CHARS = 32;
+/** GameJoinContext values are cut to this when `jd` is over the cap. */
+export declare const JD_CONTEXT_CUT = 64;
+/** `text` cut to at most `max` bytes without splitting a UTF-8 sequence. */
+export declare function cutUtf8(text: string, max: number): string;
+interface JdTeleport {
+    bytes?: number;
+    type: string;
+    keys?: string[];
+}
+interface JdMembers {
+    count: number;
+    pids?: string[];
+}
+/** The `jd` value (see plans/30-join-data-raw.md for the shape). */
+export interface JoinDataJson {
+    keys: string[];
+    LaunchData?: string;
+    LaunchDataLen?: number;
+    SourcePlaceId?: number;
+    SourceGameId?: number;
+    GameJoinContext?: Record<string, string>;
+    TeleportData?: JdTeleport;
+    Members?: JdMembers;
+    ReferredByPlayerId?: string;
+    FollowUserId?: string;
+    other?: Record<string, string>;
+    trunc?: boolean;
+}
+/**
+ * `Player:GetJoinData()` field by field, privacy-safe (plans/30): the launch data (200 bytes), place / game ids, the
+ * join context as text, the TeleportData's size, type and top-level keys (never its content), Members / referrer /
+ * followed user as pids from `pidOf` (the same lookups as the summary props) else "other", and unknown keys by type
+ * only. At most JD_MAX_BYTES of JSON as `encodeJoinData` writes it (`encode`: HttpService.JSONEncode in game, only to
+ * size the TeleportData; `quote`: a string as JSON), cut in the plan's order with `trunc`. Not a table (GetJoinData
+ * failed): undefined.
+ */
+export declare function joinDataJson(raw: unknown, followUserId: number, pidOf: (userId: number) => string | undefined, encode: (value: unknown) => string, quote: (text: string) => string): JoinDataJson | undefined;
+/**
+ * `jd` as JSON text, field order fixed. Written here rather than by HttpService.JSONEncode, which turns an empty table
+ * into `[]`: the plan's `GameJoinContext: {}` (present but empty, the evidence case) stays an object, and lists stay
+ * lists.
+ */
+export declare function encodeJoinData(jd: JoinDataJson, quote: (text: string) => string): string;
+/**
+ * Cuts `jd` to JD_MAX_BYTES of JSON, in the plan's order: TeleportData.keys (then the field), Members.pids (then the
+ * field), LaunchData (shorter), GameJoinContext values (each to 64), `other` (entry by entry); `trunc: true` once cut.
+ * Still over (an absurd join context): only `keys` (shortened), the ids, LaunchDataLen and `trunc` stay.
+ */
+export declare function capJoinData(jd: JoinDataJson, quote: (text: string) => string): JoinDataJson;
+export {};