Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp

docs: document visiting a community before joining

Hampus55629b36de81
diff --git a/fluxer_docs/src/content/docs/admin-api/discovery.mdx b/fluxer_docs/src/content/docs/admin-api/discovery.mdx
index a34867b52..5b7c9aa20 100644
--- a/fluxer_docs/src/content/docs/admin-api/discovery.mdx
+++ b/fluxer_docs/src/content/docs/admin-api/discovery.mdx
@@ -6,7 +6,7 @@ description: Discovery application review, listing reads, category moves, and re
import RouteHeader from '@/components/RouteHeader.astro';
-Admin discovery is the review side of the public guild directory. An Admin decides the application a guild manager submits, reads and edits the approved listing, moves it between categories, and removes the guild from the directory. A guild has at most one application, and the public [Discovery](/http-api/discovery/) resource drives the same lifecycle from the guild's side.
+Admin discovery is the review side of the public guild directory. An Admin decides the application a guild manager submits, reads and edits the approved listing, moves it between categories, and removes the guild from the directory. A guild has at most one application, and the public [Discovery](/http-api/discovery/) resource drives the same lifecycle from the guild's side. People see this feature as "Explore" in the Fluxer apps. The API calls it discovery.
Every operation except [Remove discovery listing](#remove-discovery-listing) requires `discovery:review`, which covers the reads, [Review discovery application](#review-discovery-application), [Move discovery listings to a category](#move-discovery-listings-to-a-category), and [Update discovery listing](#update-discovery-listing). [Remove discovery listing](#remove-discovery-listing) requires `discovery:remove` instead. Neither implies the other.
@@ -181,8 +181,6 @@ Approves or rejects a pending application and returns the updated [discovery app
### JSON body
-`status` is the decision, and the constraint on `reason` depends on which one it is.
-
| Field | Type | Description |
| --- | --- | --- |
| status<sup>1</sup> | approved \| rejected | Decision to apply |
@@ -363,8 +361,6 @@ Updates the stored listing of one guild and returns the updated [discovery appli
### JSON body
-Every member is optional. An omitted member preserves the stored value, and an empty object is accepted and changes nothing.
-
| Field | Type | Description |
| --- | --- | --- |
| description?<sup>1</sup> | string | Listing description of 10 through 300 characters |
@@ -415,8 +411,6 @@ Removes an approved listing from discovery, strips the guild's discoverable feat
### JSON body
-The body is required even though this is a DELETE, so a request without one fails body validation.
-
| Field | Type | Description |
| --- | --- | --- |
| reason | string | Reason stored on the application as `removal_reason`, 1 through 500 characters |
diff --git a/fluxer_docs/src/content/docs/gateway/commands.md b/fluxer_docs/src/content/docs/gateway/commands.md
index 41a01448f..c1b9a37a1 100644
--- a/fluxer_docs/src/content/docs/gateway/commands.md
+++ b/fluxer_docs/src/content/docs/gateway/commands.md
@@ -127,8 +127,9 @@ A token the backend rejects closes with `4004` and reason `Invalid token`. A non
| --- | --- | --- |
| 1 &lt;&lt; 1 | DEBOUNCE_MESSAGE_REACTIONS | Merge runs of reaction additions into [Message Reaction Add Many](/gateway/events/#message-reaction-add-many) |
| 1 &lt;&lt; 2 | [CHANNEL_THREADS](/gateway/threads/#session-flag) | The client can parse thread, forum, and media channels |
+| 1 &lt;&lt; 3 | GUILD_VISITS | The session receives the guilds the account is [visiting](/http-api/guilds/#visiting-guilds) |
-Bit `0` and every bit above `2` are undefined. An undefined bit is accepted and ignored without closing the connection.
+Bit `0` and every bit above `3` are undefined. An undefined bit is accepted and ignored without closing the connection.
`DEBOUNCE_MESSAGE_REACTIONS` applies to a reaction in a direct message or group direct message. A reaction in a guild channel is never merged and arrives as its own [Message Reaction Add](/gateway/events/#message-reaction-add).
@@ -429,8 +430,6 @@ Opcode `14` sets the per-guild subscriptions that decide member list, typing, sy
}
```
-`subscriptions` is an object whose keys are canonical decimal Snowflake strings. A key that does not parse, a value that is not an object, and a guild the session is not connected to are all skipped without affecting the rest of the command. The command never closes the connection.
-
### Guild subscription object
#### Structure
@@ -442,11 +441,14 @@ Opcode `14` sets the per-guild subscriptions that decide member list, typing, sy
| typing? | boolean | Whether the guild delivers [Typing Start](/gateway/events/#typing-start), overriding the active flag |
| member_list_channels?<sup>2</sup> | map[snowflake, array[array[integer]]] | The member list windows to subscribe to, keyed by channel ID |
| members? | array[snowflake] | The explicit member IDs to subscribe to, at most 1,000 |
+| focused_channel_id?<sup>3</sup> | ?snowflake | The channel or public thread a visiting session has open |
<sup>1</sup> Both are Booleans when present. Any other value stops Fluxer from applying the remaining options for that guild and every guild it has not yet processed, without a close and without a result
<sup>2</sup> Subscriptions may be combined over a 100 ms window. Ranges sent during that window are merged for the same channel, and an empty range list clears its pending ranges
+<sup>3</sup> Read only for a guild the session is visiting, where it is the only option applied. A channel the visitor cannot read, or null, clears the focus. Messages and reactions reach a visiting session only for its focused channel
+
Fluxer applies each option only when its key is present, in the order `active`, `sync`, `member_list_channels`, `members`, `typing`. The [thread options](/gateway/threads/#lazy-request-thread-options) `threads` and `thread_member_lists` follow `typing`.
Marking a guild active changes how much traffic it produces, and [Event filtering](/gateway/event-filtering/) specifies the difference. A transition from passive to active, and a transition from active to passive, both imply a sync even when `sync` is absent. Every sync request, implied or explicit, is dropped when the guild is already marked synced for that session. Going passive clears that mark, so the next sync request produces a fresh Guild Sync. Going passive also clears the [`threads`](/gateway/threads/#lazy-request-thread-options) subscription.
diff --git a/fluxer_docs/src/content/docs/gateway/event-filtering.md b/fluxer_docs/src/content/docs/gateway/event-filtering.md
index 5bd108ba4..1212632f9 100644
--- a/fluxer_docs/src/content/docs/gateway/event-filtering.md
+++ b/fluxer_docs/src/content/docs/gateway/event-filtering.md
@@ -70,10 +70,6 @@ Such a session receives exactly this set:
- [Channel Create](/gateway/events/#channel-create), [Channel Update](/gateway/events/#channel-update), [Channel Update Bulk](/gateway/events/#channel-update-bulk), and [Channel Delete](/gateway/events/#channel-delete)
- [Guild Audit Log Entry Create](/gateway/events/#guild-audit-log-entry-create)
- [Passive Updates](/gateway/events/#passive-updates)
-- [Message Create](/gateway/events/#message-create) when the message mentions the session's user or that user wrote it
-- [Message Update](/gateway/events/#message-update) when the message has a mention that overrides the passive filter for [Message Create](/gateway/events/#message-create)
-- [Guild Member Update](/gateway/events/#guild-member-update) and [Guild Member Remove](/gateway/events/#guild-member-remove) when the subject is the session's own user
-- The thread events [Gateway threads](/gateway/threads/#dispatch-events) states for a passive session
Every other Dispatch the guild produces is suppressed:
@@ -108,6 +104,18 @@ A message, reaction, typing, or pin event in a thread follows the rules on this
[Guild Member List Update](/gateway/events/#guild-member-list-update) has its own subscription. A session receives it only for a channel it named in `member_list_channels`, and only while it can view that channel and holds `VIEW_CHANNEL_MEMBERS` on it. One session holds at most one member list subscription per guild. [Thread Member List Update](/gateway/threads/#thread-member-list-update) has a separate subscription, as [Lazy Request thread options](/gateway/threads/#lazy-request-thread-options) describes.
+## Visited guilds
+
+A session [visiting](/http-api/guilds/#visiting-guilds) a guild receives only these events for it, and every other event is withheld, including any event added later:
+
+- [Guild Update](/gateway/events/#guild-update), and the role, emoji, and sticker events.
+- [Channel Create](/gateway/events/#channel-create), [Channel Update](/gateway/events/#channel-update), [Channel Update Bulk](/gateway/events/#channel-update-bulk), and [Channel Delete](/gateway/events/#channel-delete) for channels a visitor can read, with only the @everyone permission overwrite. A channel a visitor can no longer read arrives as Channel Delete, and one that becomes readable arrives as Channel Create.
+- [Channel Pins Update](/gateway/events/#channel-pins-update) for channels a visitor can read.
+- Message and reaction events for the channel the session has focused with `focused_channel_id` in [Lazy Request](/gateway/commands/#lazy-request). Reaction events have no `user_id` and no `member`.
+- Thread Create, Thread Update, and Thread Delete for public threads in channels a visitor can read.
+
+Visitors never appear in member lists, presences, typing, voice states, or member counts, and members receive nothing when a visitor connects or leaves. Member list ranges, [Request Guild Members](/gateway/commands/#request-guild-members), acknowledgements, and typing are ignored for a visited guild.
+
## Presence subscriptions
[Presence Update](/gateway/events/#presence-update) skips gates 1 through 3 and is subject only to gate 4. A guild dispatches it only to a session that named the subject in the `members` array of a [Lazy Request](/gateway/commands/#lazy-request), that can view at least one channel the subject can view, and that does not belong to the subject.
@@ -131,12 +139,6 @@ Identify accepts `ignored_events`, an array of up to 256 Dispatch event names. F
}
```
-[Message Create](/gateway/events/#message-create) is the one exception. Fluxer delivers it even when `MESSAGE_CREATE` is ignored, if the message names the session's user in `mentions`, sets `mention_here`, or sets `mention_everyone`. A role mention does not defeat the list.
-
-A suppressed Dispatch consumes no sequence number, so a client MUST NOT expect a gap in the sequence where the list dropped one.
-
-The list is fixed for the lifetime of the session. Changing it requires a new Identify.
-
## The shard filter
A session that identified with a `shard` pair whose `shard_id` is not 0 drops every Dispatch that does not name a guild. A Dispatch names a guild through a non-empty `guild_id`, or through a non-empty `id` on a [Guild Create](/gateway/events/#guild-create), [Guild Update](/gateway/events/#guild-update), [Guild Delete](/gateway/events/#guild-delete), or [Guild Sync](/gateway/events/#guild-sync) payload. [Rate Limited](/gateway/events/#rate-limited), [Guild Counts Update](/gateway/events/#guild-counts-update), and [Channel Member Counts Update](/gateway/events/#channel-member-counts-update) answer a command the session sent, and each passes the gate whatever its payload holds.
diff --git a/fluxer_docs/src/content/docs/gateway/events.md b/fluxer_docs/src/content/docs/gateway/events.md
index ed83623ba..2b1740fa0 100644
--- a/fluxer_docs/src/content/docs/gateway/events.md
+++ b/fluxer_docs/src/content/docs/gateway/events.md
@@ -228,8 +228,6 @@ The first entry always has `session_id: "all"` and the account's combined status
| last_used_at | ?ISO8601 timestamp | When the credential was last used |
| rp_id | string | The domain the passkey was created for, as in the [WebAuthn credential object](/http-api/users/mfa/#webauthn-credential-object) |
-[Replaced passkeys](/http-api/users/mfa/#replaced-passkeys) never appear in this list.
-
#### RTC region object
| Field | Type | Description |
@@ -402,6 +400,8 @@ A guild became available to the session. The payload is a [guild ready object](#
Every session receives Guild Create when a guild becomes available after Ready, for example after joining one or after an unavailable guild recovers. A bot session also receives one for each available guild in the burst that follows Ready.
+A guild the account is [visiting](/http-api/guilds/#visiting-guilds) arrives with `visiting: true`, `joined_at: null`, and empty `members`, `presences`, and `voice_states`. Its `channels` hold only the channels a visitor can read, each with only the @everyone overwrite. Ready lists visited guilds the same way for a session with the `GUILD_VISITS` [session flag](/gateway/commands/#session-flags). A later Guild Create without `visiting` for a visited guild means the account joined it, and a client replaces the guild in place without clearing its messages.
+
A bot session's Guild Create has `unavailable: false` unless it is the first Guild Create for a guild the bot joined during the session and [Ready](#ready) did not list. That Dispatch has no `unavailable` field, even when a [Guild Delete](#guild-delete) with `unavailable: true` for the guild came before it. A user session never receives the field on Guild Create.
### <span id="guild-sync"></span>GUILD_SYNC
@@ -429,7 +429,7 @@ A guild left the session's visibility, or became unavailable.
<sup>1</sup> Present only when the guild itself is deleted. The payload has `id` alone when the account leaves a guild or is removed from one, and `id` with `unavailable` in the unavailable form
-Without `unavailable`, the account is no longer a member, and a client deletes everything it stores for that guild. With `unavailable: true`, the guild is temporarily unreachable. A client keeps the guild as an unavailable entry until a later [Guild Create](#guild-create) sends its full state again.
+Without `unavailable`, the account is no longer a member or no longer visiting, and a client deletes everything it stores for that guild. With `unavailable: true`, the guild is temporarily unreachable. A client keeps the guild as an unavailable entry until a later [Guild Create](#guild-create) sends its full state again.
### <span id="guild-role-create"></span>GUILD_ROLE_CREATE
@@ -476,8 +476,6 @@ A guild's emojis changed.
| guild_id | snowflake | Guild the emojis belong to |
| emojis | array[[guild emoji](/http-api/guild-emojis/#guild-emoji-object) object] | Every emoji in the guild |
-A client that stores the guild's emojis replaces them with this array. Fluxer does not send per-emoji create, update, or delete events.
-
### <span id="guild-stickers-update"></span>GUILD_STICKERS_UPDATE
A guild's stickers changed.
@@ -487,8 +485,6 @@ A guild's stickers changed.
| guild_id | snowflake | Guild the stickers belong to |
| stickers | array[[guild sticker](/http-api/guild-stickers/#guild-sticker-object) object] | Every sticker in the guild |
-A client that stores the guild's stickers replaces them with this array. Fluxer does not send per-sticker create, update, or delete events.
-
### <span id="channel-create"></span>CHANNEL_CREATE
A channel became visible to the session, whether newly created or newly permitted. The payload is the complete [channel object](/http-api/channels/#channel-object), with `guild_id` present for a guild channel.
@@ -644,8 +640,6 @@ A group whose count is `0` is omitted. The `offline` group is also omitted once
| range | array[integer] | Inclusive `[start, end]` range this operation replaces |
| items | array[[member list item object](#member-list-item-object)] | Replacement items for the range |
-`SYNC` is the only operation Fluxer sends. A client MUST ignore an operation whose `op` it does not recognise or whose range fails the bounds in [Lazy Request](/gateway/commands/#lazy-request).
-
#### Member list item object
Each item has exactly one of the fields.
@@ -1111,8 +1105,6 @@ Another connection of a [peer-to-peer](#peer-to-peer-voice) voice channel or cal
}
```
-Fluxer authorises every signal against the current voice states, so `from` always names a connection with `p2p: true` in `channel_id`. A client discards a signal whose `from` it no longer has in its roster.
-
### <span id="entrance-sound-play"></span>ENTRANCE_SOUND_PLAY
A participant asked for their entrance sound to play in a voice channel they are already connected to.
@@ -1128,8 +1120,6 @@ A participant asked for their entrance sound to play in a voice channel they are
| duration_ms | integer | Sound duration in milliseconds |
| content_type | string | MIME type of the sound file |
-Recipients are every other account with a voice state in that channel, one Dispatch each and at most one per account. The requesting account never receives its own sound.
-
### <span id="call-create"></span>CALL_CREATE
A private channel call began, or became visible in the session's initial state.
diff --git a/fluxer_docs/src/content/docs/http-api/discovery.mdx b/fluxer_docs/src/content/docs/http-api/discovery.mdx
index 7ebce459b..37cd63785 100644
--- a/fluxer_docs/src/content/docs/http-api/discovery.mdx
+++ b/fluxer_docs/src/content/docs/http-api/discovery.mdx
@@ -6,7 +6,7 @@ description: Guild discovery listings, the application lifecycle, and joining an
import RouteHeader from '@/components/RouteHeader.astro';
-Discovery is the public directory of guilds any account can browse and join. A guild manager applies to have a guild listed, and an operator reviews that application through the [Admin Discovery API](/admin-api/discovery/).
+Discovery is the public directory of guilds any account can browse and join. A guild manager applies to have a guild listed, and an operator reviews that application through the [Admin Discovery API](/admin-api/discovery/). People see this feature as "Explore" in the Fluxer apps. The API calls it discovery.
[Preview discovery channel](#preview-discovery-channel) and [Join discovery guild](#join-discovery-guild) are user-only and reject a bot token with 403 `ACCESS_DENIED`. Every other route accepts a user session token or a bot token. Besides that rejection, a bearer credential is the only credential that produces `ACCESS_DENIED` on any route here. Where a response table below pairs a revoked account with `ACCESS_DENIED`, a session, bot, or bearer token that no longer resolves to an account returns 401 `UNAUTHORIZED` instead.
@@ -38,6 +38,7 @@ One public guild listing.
| online_count<sup>2</sup> | integer | The current online member count of the guild |
| features | array[string] | The [guild features](/http-api/guilds/#guild-features) the guild has |
| verification_level<sup>4</sup> | integer | The effective [verification level](/http-api/guilds/#verification-levels) of the guild |
+| visits_enabled?<sup>5</sup> | boolean | Whether the caller can [visit](/http-api/guilds/#visiting-guilds) the guild before joining |
<sup>1</sup> These fields describe the approved application. An unspecified category is reported as `0`
@@ -47,6 +48,8 @@ One public guild listing.
<sup>4</sup> A listed guild is reported at least at level `1`, so a guild that stores level `0` is reported as `1` while it remains discoverable
+<sup>5</sup> Present only for a caller with the `guild_visits` assignment. True when the guild holds `VISITS_ENABLED` and invites are not disabled
+
:::note[Listing updates can take time]
Changes to a guild's name, icon, banner, features or verification level can take up to 15 minutes to appear.
:::
@@ -233,8 +236,6 @@ The guild and channel behind a channel or message link, as [Preview discovery ch
## Discovery categories
-The release fixes the set, so an operator cannot add, rename, or remove a category.
-
| Value | Name | Display name |
| --- | --- | --- |
| 0 | GAMING | Gaming |
@@ -247,10 +248,6 @@ The release fixes the set, so an operator cannot add, rename, or remove a catego
| 7 | MOVIES_AND_TV | Movies & TV |
| 8 | OTHER | Other |
-Every category value on the wire is one of these integers. A value outside 0 through 8 fails body or query validation with the validation code `INVALID_FORMAT`, so [Apply for discovery](#apply-for-discovery) and [Edit discovery application](#edit-discovery-application) reject it before the listing is stored.
-
-The display names above are the strings [List discovery categories](#list-discovery-categories) returns. They are not localised, so the same ID has the same name for every account.
-
## Discovery application statuses
| Value | Description |
@@ -410,6 +407,39 @@ None. The route reads stored records only and emits no Gateway Dispatch.
60 requests per 10 seconds for each authenticated user, on the `discovery:channel_preview` bucket, which is not partitioned by guild or channel.
+## Visit discovery guild
+
+<RouteHeader method="POST" path="/v1/discovery/guilds/{guild_id}/visit" />
+
+Starts a [visit](/http-api/guilds/#visiting-guilds) to an approved discovery guild and returns the [guild visit start object](/http-api/guilds/#guild-visit-start-object). It works like [Visit invite guild](/http-api/invites/#visit-invite-guild) without an invite. A caller who is already a member receives `member: true` and no visit.
+
+### Limitations
+
+- User-only, so a bot token is rejected with 403 `ACCESS_DENIED`.
+- Needs the `guild_visits` [experiment assignment](/http-api/experiments/#guild-visits-assignment-object), otherwise the route returns 404 `UNKNOWN_GUILD`.
+
+### Path parameters
+
+| Field | Type | Description |
+| --- | --- | --- |
+| guild_id | snowflake | The ID of the approved guild to visit |
+
+### Response
+
+| Status | Body | Condition |
+| --- | --- | --- |
+| 200 | [guild visit start](/http-api/guilds/#guild-visit-start-object) object | Visit started, was already open, or the caller is a member |
+| 400 | [error response](/http-api/#error-response) | Discovery is disabled for the instance and the request returns `DISCOVERY_DISABLED` |
+| 403 | [error response](/http-api/#error-response) | The guild does not accept visitors and the request returns `GUILD_VISITS_DISABLED` |
+| 403 | [error response](/http-api/#error-response) | The guild is for adults and the caller may not see adult content, returning `GUILD_VISIT_AGE_RESTRICTED` |
+| 403 | [error response](/http-api/#error-response) | Invites are disabled for the guild and the request returns `INVITES_DISABLED` |
+| 403 | [error response](/http-api/#error-response) | The caller is banned from the guild and the request returns `USER_BANNED_FROM_GUILD` or `USER_IP_BANNED_FROM_GUILD` |
+| 404 | [error response](/http-api/#error-response) | The guild has no approved listing, is unavailable, or visits are off for the caller, returning `UNKNOWN_GUILD` |
+
+### Rate limit
+
+10 requests per 60 seconds for each authenticated user, on the `guild:visit:start` bucket. Each address can also start 30 visits per 60 seconds.
+
## Join discovery guild
<RouteHeader method="POST" path="/v1/discovery/guilds/{guild_id}/join" />
@@ -530,8 +560,6 @@ Updates the stored listing of a guild and returns the updated [discovery applica
### JSON body
-Every field is optional, and an omitted field preserves the stored value.
-
| Field | Type | Description |
| --- | --- | --- |
| description?<sup>1</sup> | string | The listing description (10-300 characters) |
diff --git a/fluxer_docs/src/content/docs/http-api/experiments.mdx b/fluxer_docs/src/content/docs/http-api/experiments.mdx
index cc30f0cf7..c01f5b1f4 100644
--- a/fluxer_docs/src/content/docs/http-api/experiments.mdx
+++ b/fluxer_docs/src/content/docs/http-api/experiments.mdx
@@ -6,14 +6,12 @@ description: The experiment assignments envelope, the revalidation and polling c
import RouteHeader from '@/components/RouteHeader.astro';
-An experiment is an instance-wide rollout. For each account, Fluxer works out whether the account is in the rollout and which settings the account receives. The single route on this page resolves every experiment the server defines and returns them in one envelope, together with the polling cadence they share. This server defines `domain_migration`, `plutonium_page`, `channel_threads`, and `voice_p2p`. Only `domain_migration` and `voice_p2p` are configured by an operator. `plutonium_page` and `channel_threads` are on for every account.
+An experiment is an instance-wide rollout. For each account, Fluxer works out whether the account is in the rollout and which settings the account receives. The single route on this page resolves every experiment the server defines and returns them in one envelope, together with the polling cadence they share. This server defines `plutonium_page`, `channel_threads`, `voice_p2p`, and `guild_visits`. Only `voice_p2p` and `guild_visits` are configured by an operator. `plutonium_page` and `channel_threads` are on for every account.
Every assignment is advice. A client that ignores one behaves as it does with the rollout off, and no route and no Gateway event reports what a client actually ran.
## Experiment assignments object
-One resolution of every defined experiment against one account. Every field is present on every response.
-
### Structure
| Field | Type | Description |
@@ -26,37 +24,17 @@ Every account on the instance receives the same `poll_interval_seconds` and `pol
## Assignment map object
-One entry per experiment. The envelope reports this object even when it is empty.
-
### Structure
| Field | Type | Description |
| --- | --- | --- |
-| domain_migration? | [domain migration assignment](#domain-migration-assignment-object) object | The caller's web domain migration assignment |
| plutonium_page? | [Plutonium page assignment](#plutonium-page-assignment-object) object | The caller's Plutonium page assignment |
| channel_threads? | [channel threads assignment](#channel-threads-assignment-object) object | The caller's channel threads assignment |
| voice_p2p? | [peer-to-peer voice assignment](#peer-to-peer-voice-assignment-object) object | The caller's peer-to-peer voice assignment |
-
-Ignore unknown experiments and treat a missing experiment as off.
-
-## Domain migration assignment object
-
-One resolution of the instance web domain migration rollout against one account. This server version writes the key on every response.
-
-### Structure
-
-| Field | Type | Description |
-| --- | --- | --- |
-| enabled | boolean | Whether the caller's web client moves to the new web origin |
-
-A caller is drawn by the operator's account or guild allowlist, by having premium when the operator includes premium users, or by the sampled share of the account population. When the operator lists rollout countries, the sampled share only draws a caller whose request comes from a listed country. `enabled` is false in every other case, the rollout being off included.
-
-Only the official web client acts on this assignment, and only on its legacy origins. Every other client ignores it. The logged-out share and the instance-wide switch are published in the [instance discovery document](/http-api/instance/#domain-migration-object) instead, because a client that holds no credential cannot read this route.
+| guild_visits? | [guild visits assignment](#guild-visits-assignment-object) object | The caller's guild visits assignment |
## Plutonium page assignment object
-The Plutonium page state for one account. This server version writes the key on every response, always with `enabled` true.
-
### Structure
| Field | Type | Description |
@@ -80,9 +58,17 @@ The channel threads state for one account. This server version writes the key on
The key stays for clients that still read it. Threads, forum channels, and media channels need the [`channel_threads` client capability](/http-api/threads/#client-capability).
-## Peer-to-peer voice assignment object
+## Guild visits assignment object
+
+Whether the caller may look around a community before joining it. This server version writes the key on every response.
-One resolution of the instance peer-to-peer voice rollout against one account. This server version writes the key on every response.
+### Structure
+
+| Field | Type | Description |
+| --- | --- | --- |
+| enabled | boolean | Whether the caller is in the [guild visits rollout](/admin-api/instance/#guild-visits-configuration-object) |
+
+## Peer-to-peer voice assignment object
### Structure
diff --git a/fluxer_docs/src/content/docs/http-api/guilds.mdx b/fluxer_docs/src/content/docs/http-api/guilds.mdx
index 224d6ba5f..6065954b8 100644
--- a/fluxer_docs/src/content/docs/http-api/guilds.mdx
+++ b/fluxer_docs/src/content/docs/http-api/guilds.mdx
@@ -18,8 +18,6 @@ Submitted names and other text must pass the instance's content policy. Blocked
## Guild object
-A guild object contains the guild's configuration. The operation that returns it decides which embedded collections and caller-specific fields it has.
-
### Structure
| Field | Type | Description |
@@ -65,6 +63,7 @@ A guild object contains the guild's configuration. The operation that returns it
| approximate_member_count?<sup>15</sup> | integer | Approximate member count |
| approximate_presence_count?<sup>15</sup> | integer | Approximate online presence count |
| threads_active?<sup>16</sup> | boolean | Whether the caller can use threads, forum channels, and media channels in the guild, always `true` when present |
+| visiting?<sup>17</sup> | boolean | Present and `true` when the caller is [visiting](#visiting-guilds) the guild without being a member |
<sup>1</sup> An animated icon hash has the `a_` prefix, and that prefix is removed from the returned value while the guild lacks `ANIMATED_ICON`
@@ -98,6 +97,8 @@ A guild object contains the guild's configuration. The operation that returns it
<sup>16</sup> Only [List current user guilds](#list-current-user-guilds) populates this field, and only for a bot or a user session that declares the [`channel_threads` client capability](/http-api/threads/#client-capability)
+<sup>17</sup> Only [Get guild](#get-guild) populates this field, for a caller with a visit. That response has no `permissions`, and `channels` holds the channels a visitor can read with only the @everyone overwrite kept
+
A caller other than a bot or a user session that declares `channel_threads` receives `permissions` and each role `permissions` with the [thread permission bits](/http-api/threads/#thread-permissions) removed. The `permission_overwrites` of `channels` keep the thread bits.
:::note[An absent field means the operation omitted it]
@@ -155,6 +156,7 @@ A partial guild object is the smaller shape that appears inside invite payloads.
| embed_splash_width<sup>3</sup> | ?integer | Embedded invite splash width in pixels |
| embed_splash_height<sup>3</sup> | ?integer | Embedded invite splash height in pixels |
| features<sup>5</sup> | array[string] | [Guild features](#guild-features) |
+| visits_enabled?<sup>6</sup> | boolean | Whether the caller can [visit](#visiting-guilds) the guild from this invite |
<sup>1</sup> An animated icon hash has the `a_` prefix, and that prefix is removed from the returned value while the guild lacks `ANIMATED_ICON`
@@ -166,6 +168,8 @@ A partial guild object is the smaller shape that appears inside invite payloads.
<sup>5</sup> The set has each feature at most once, and `vanity_url_code` is never part of this representation
+<sup>6</sup> Present only on [Get invite](/http-api/invites/#get-invite) for a caller with the `guild_visits` assignment. True when the guild holds `VISITS_ENABLED` and invites are not disabled
+
### Example
```json
@@ -391,8 +395,6 @@ A guild explicit content filter level is the guild-wide filter a moderator selec
| 0 | SAFE | Guild is not age restricted |
| 3 | AGE_RESTRICTED | Guild is age restricted |
-The registry has no other value. Fluxer derives the level from the guild's `nsfw` field and never writes it directly.
-
## Guild content warning levels
The guild is the last position in the resolution chain described by [channel content warning levels](/http-api/channels/#content-warning-levels).
@@ -408,8 +410,6 @@ The guild is the last position in the resolution chain described by [channel con
| --- | --- | --- |
| 1 &lt;&lt; 0 | SUPPRESS_JOIN_NOTIFICATIONS | Suppress member join system messages |
-Every bit outside this registry is discarded when the field is written.
-
## Disabled guild operations
A set bit disables the named behaviour across the guild. Only the [Admin API](/admin-api/guilds/) writes the bitfield.
@@ -426,12 +426,8 @@ A set bit disables the named behaviour across the guild. Only the [Admin API](/a
## Guild features
-Each value in the guild's `features` array is a capability or availability flag.
-
| Value | Description |
| --- | --- |
-| ANIMATED_ICON | Guild can use an animated icon |
-| ANNOUNCEMENT_CHANNELS_DISABLED<sup>8</sup> | Publishing from and following the guild's announcement channels is disabled |
| ANIMATED_BANNER | Guild can use an animated banner |
| AUDIO_BITRATE_128_KBPS<sup>6</sup> | Voice channel bitrate ceiling is raised to 128000 |
| AUDIO_BITRATE_256_KBPS<sup>6</sup> | Voice channel bitrate ceiling is raised to 256000 |
@@ -458,12 +454,6 @@ Each value in the guild's `features` array is a capability or availability flag.
| VERIFIED | Guild has verified status |
| VIP_VOICE | Guild can use voice regions that are restricted to VIP guilds |
| VOICE_E2EE | Guild voice channels support end-to-end encryption |
-| UNAVAILABLE_FOR_EVERYONE<sup>4</sup> | Guild is unavailable to every account |
-| UNAVAILABLE_FOR_EVERYONE_BUT_STAFF<sup>4</sup> | Guild is unavailable to every account without the instance staff flag |
-| UNAVAILABLE_HIDDEN | While the guild is unavailable, the Gateway sends its unavailable guild entry with `unavailable_hidden: true` |
-| VISIONARY | Guild has visionary status |
-| LARGE_GUILD_OVERRIDE<sup>2</sup> | Guild is marked as a large guild |
-| VERY_LARGE_GUILD<sup>5</sup> | Guild member capacity is raised |
<sup>1</sup> The feature is added or removed through [Modify guild](#modify-guild), as part of the complete array. Send every feature without this marker back to `features` exactly as the guild holds it
@@ -485,6 +475,53 @@ Each value in the guild's `features` array is a capability or availability flag.
Cloning requires `CLONE_EMOJI_ENABLED` or `CLONE_STICKER_ENABLED`. A member with `MANAGE_GUILD` can enable them through [Modify guild](#modify-guild). The deprecated `CLONE_EMOJI_DISABLED` and `CLONE_STICKER_DISABLED` features have no effect.
:::
+## Visiting guilds
+
+A visit lets someone read a guild before joining it. The visitor reads the channels the @everyone role can see, and cannot post, react, type, join voice, or see the member list. Members see no member add, presence, or count change. Visits need the `guild_visits` [experiment assignment](/http-api/experiments/#guild-visits-assignment-object). Without it every route here behaves as if the guild or invite did not exist, and no session receives a visited guild. A session receives its visited guilds only when it identifies with the `GUILD_VISITS` [session flag](/gateway/commands/#session-flags).
+
+A guild accepts visitors while it holds `VISITS_ENABLED`. New guilds get it at creation, an approved [discovery](/http-api/discovery/) listing turns it back on, and a member with `MANAGE_GUILD` can turn it off through [Modify guild](#modify-guild). A visit starts from an invite ([Visit invite guild](/http-api/invites/#visit-invite-guild)), from a discovery listing ([Visit discovery guild](/http-api/discovery/#visit-discovery-guild)), or from the instance community after sign up. The instance community does not need `VISITS_ENABLED`.
+
+What a visitor can read:
+
+- The visitor's permissions in a channel are the @everyone role permissions without `ADMINISTRATOR`, with only the @everyone channel overwrite applied, limited to `VIEW_CHANNEL` and `READ_MESSAGE_HISTORY`. Role and member overwrites are ignored.
+- Adult channels are hidden from a visitor who may not see adult content, and an adult guild cannot be visited by them at all.
+- Private threads are never visible. Public threads follow their parent channel.
+- An account without a confirmed email reads only the last `guild_visit_history_days_unverified` days of history, 30 by default.
+- Channel search accepts content, `has`, and date filters. Filtering by author or mention returns 400 `SEARCH_FILTER_NEEDS_MEMBERSHIP`.
+- Every channel object a visitor receives has only the @everyone permission overwrite.
+
+A person can visit at most `max_guild_visits` guilds at once, 10 by default and half that without a confirmed email. Starting another visit ends the one opened longest ago. A visit ends after 14 days without being opened, when the invite that started it is deleted or expires, when the person is banned, when the guild drops `VISITS_ENABLED`, and when the person joins. Each ending sends [Guild Delete](/gateway/events/#guild-delete) to every session of that person, except a join, which sends a member [Guild Create](/gateway/events/#guild-create) in place.
+
+Visiting does not use up a limited invite. Joining from the visit uses one, so a visitor cannot join once every use is taken.
+
+### Guild visit object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| guild_id | snowflake | The ID of the guild being visited |
+| source | integer | [Guild visit source](#guild-visit-sources) |
+| started_at | ISO8601 timestamp | When the visit started |
+| opened_at<sup>1</sup> | ISO8601 timestamp | When the visit was last opened |
+
+<sup>1</sup> Updated at most once a day
+
+### Guild visit sources
+
+| Value | Name | Description |
+| --- | --- | --- |
+| 1 | INVITE | The visit started from an invite |
+| 2 | VANITY_URL | The visit started from a custom invite URL |
+| 3 | DISCOVERY | The visit started from a discovery listing |
+| 4 | OPERATOR | The visit started from the instance community after sign up |
+
+### Guild visit start object
+
+| Field | Type | Description |
+| --- | --- | --- |
+| guild_id | snowflake | The ID of the guild |
+| member | boolean | Whether the caller is already a member, in which case no visit starts |
+| visit | ?[guild visit](#guild-visit-object) object | The visit, or null when `member` is true |
+
## Custom invite URL object
A custom invite URL object reports the guild's current custom invite code and how many times the invite behind it has been used. [Get guild custom invite URL](#get-guild-custom-invite-url) returns it.
@@ -526,10 +563,12 @@ These fields prove [sudo mode](/http-api/users/mfa/#sudo-mode) when an operation
| Field | Type | Description |
| --- | --- | --- |
| password?<sup>1</sup> | string | Current account password |
-| mfa_method?<sup>2</sup> | string | MFA method, either `totp` or `webauthn` |
+| mfa_method?<sup>2</sup> | string | MFA method, one of `totp`, `webauthn` or `email_code` |
| mfa_code? | string | Authenticator code or unconsumed backup code when the method is `totp` (1-32 characters) |
| webauthn_response? | [WebAuthn assertion](/http-api/authentication/#webauthn-assertion) object | Assertion when the method is `webauthn` |
| webauthn_challenge? | string | Challenge bound to the WebAuthn assertion |
+| email_code_ticket? | string | The ticket from [send a sudo email code](/http-api/users/mfa/#send-a-sudo-email-code) (1-128 characters) |
+| email_code? | string | The 6-digit code from that email |
<sup>1</sup> The password is accepted only while the account holds neither a TOTP secret nor a registered WebAuthn credential, and it returns the field code `INVALID_PASSWORD` when it does not match
@@ -689,8 +728,6 @@ Changing `mfa_level` to a different value also requires the guild owner, an owne
### JSON body
-Every field is optional. An omitted field preserves its current value, and a field explicitly set to null clears it where the type allows null.
-
| Field | Type | Description |
| --- | --- | --- |
| name?<sup>1</sup> | string | Guild name (1-100 characters) |
@@ -714,10 +751,12 @@ Every field is optional. An omitted field preserves its current value, and a fie
| features?<sup>14</sup> | array[string] | Complete desired [guild feature](#guild-features) set (max 100 entries) |
| message_history_cutoff?<sup>15</sup> | ?ISO8601 timestamp | Earliest history visible without [READ_MESSAGE_HISTORY](/http-api/permissions/), or null to deny historical access |
| password? | string | [Sudo verification](#sudo-verification-fields) password |
-| mfa_method? | string | [Sudo verification](#sudo-verification-fields) method, either `totp` or `webauthn` |
+| mfa_method? | string | [Sudo verification](#sudo-verification-fields) method, one of `totp`, `webauthn` or `email_code` |
| mfa_code? | string | [Sudo verification](#sudo-verification-fields) authenticator code |
| webauthn_response? | [WebAuthn assertion](/http-api/authentication/#webauthn-assertion) object | [Sudo verification](#sudo-verification-fields) assertion |
| webauthn_challenge? | string | Challenge bound to the WebAuthn assertion |
+| email_code_ticket? | string | The ticket from [send a sudo email code](/http-api/users/mfa/#send-a-sudo-email-code) (1-128 characters) |
+| email_code? | string | The 6-digit code from that email |
<sup>1</sup> Normalised and trimmed before its length is measured. A blocked name returns 403 `CONTENT_BLOCKED`
diff --git a/fluxer_docs/src/content/docs/http-api/invites.mdx b/fluxer_docs/src/content/docs/http-api/invites.mdx
index 92222de9c..5fde0873a 100644
--- a/fluxer_docs/src/content/docs/http-api/invites.mdx
+++ b/fluxer_docs/src/content/docs/http-api/invites.mdx
@@ -12,8 +12,6 @@ An invite is a code that admits an account into a guild or a group direct messag
## Invite object
-An invite object describes one code and the target it admits into. The `type` selects the representation.
-
### Structure
| Field | Type | Description |
@@ -127,14 +125,6 @@ A partial recipient has only the username.
| --- | --- | --- |
| username | string | The username of the recipient |
-### Example
-
-```json
-{
- "username": "example"
-}
-```
-
## Custom invite URLs
[Modify guild custom invite URL](/http-api/guilds/#modify-guild-custom-invite-url) creates or replaces a custom invite code. It has type `0`, null `inviter` and `expires_at`, and `max_uses` and `max_age` of `0`. Its channel is the first guild text channel in channel order that the default role can view.
@@ -242,6 +232,44 @@ No admission path records a guild audit entry.
10 requests per 10 seconds for each authenticated user, on the `invite:accept` bucket, which is not partitioned by invite code.
+## Visit invite guild
+
+<RouteHeader method="POST" path="/v1/invites/{invite_code}/visit" />
+
+Starts a [visit](/http-api/guilds/#visiting-guilds) to the guild of an invite and returns the [guild visit start object](/http-api/guilds/#guild-visit-start-object). The caller reads the guild without joining it. A caller who is already a member receives `member: true` and no visit. Opening the same visit again returns it unchanged.
+
+Visiting does not use up a limited invite. Joining later from the visit uses one. Deleting the invite, or its expiry, ends every visit it started. The caller's sessions with the `GUILD_VISITS` [session flag](/gateway/commands/#session-flags) receive [Guild Create](/gateway/events/#guild-create) with `visiting: true`.
+
+### Limitations
+
+- User-only, so a bot token is rejected with 403 `ACCESS_DENIED`.
+- Needs the `guild_visits` [experiment assignment](/http-api/experiments/#guild-visits-assignment-object), otherwise the route returns 404 `UNKNOWN_INVITE`.
+
+### Path parameters
+
+| Field | Type | Description |
+| --- | --- | --- |
+| invite_code | string | The invite code (1 through 256 characters) |
+
+### Response
+
+| Status | Body | Condition |
+| --- | --- | --- |
+| 200 | [guild visit start](/http-api/guilds/#guild-visit-start-object) object | Visit started, was already open, or the caller is a member |
+| 403 | [error response](/http-api/#error-response) | The guild does not accept visitors and the request returns `GUILD_VISITS_DISABLED` |
+| 403 | [error response](/http-api/#error-response) | The guild is for adults and the caller may not see adult content, returning `GUILD_VISIT_AGE_RESTRICTED` |
+| 403 | [error response](/http-api/#error-response) | Invites are disabled for the guild and the request returns `INVITES_DISABLED` |
+| 403 | [error response](/http-api/#error-response) | The caller is banned from the guild and the request returns `USER_BANNED_FROM_GUILD` or `USER_IP_BANNED_FROM_GUILD` |
+| 403 | [error response](/http-api/#error-response) | The account is [limited](/http-api/users/#account-limitation) and the request returns `ACCOUNT_LIMITED` |
+| 403 | [error response](/http-api/#error-response) | The caller has not given a date of birth and the request returns `DATE_OF_BIRTH_REQUIRED` |
+| 403 | [error response](/http-api/#error-response) | The caller is below the minimum age and the request returns `ACCOUNT_BELOW_MINIMUM_AGE` |
+| 404 | [error response](/http-api/#error-response) | The code resolves to no guild invite, the invite is used up, or visits are off for the caller, returning `UNKNOWN_INVITE` |
+| 404 | [error response](/http-api/#error-response) | The guild is unavailable and the request returns `UNKNOWN_GUILD` |
+
+### Rate limit
+
+10 requests per 60 seconds for each authenticated user, on the `guild:visit:start` bucket. Each address can also start 30 visits per 60 seconds.
+
## Delete invite
<RouteHeader method="DELETE" path="/v1/invites/{invite_code}" bot auditReason mfa />
@@ -318,8 +346,6 @@ A channel that belongs to a guild creates a guild invite. Any other channel the
### JSON body
-Every field is optional and nullable, and an omitted or null value takes the stated default.
-
| Field | Type | Description |
| --- | --- | --- |
| max_uses?<sup>1</sup> | ?integer | The maximum number of admissions (0-100, default 0, where 0 is unlimited) |