Skip to content

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

TypeScript fluxerfluxerapp

feat(schema): add community visit schemas and visit errors

Hampusbbc5b2116266
diff --git a/packages/errors/src/domains/guild/GuildVisitAgeRestrictedError.ts b/packages/errors/src/domains/guild/GuildVisitAgeRestrictedError.ts
new file mode 100644
index 000000000..ff7bed895
--- /dev/null
+++ b/packages/errors/src/domains/guild/GuildVisitAgeRestrictedError.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {ForbiddenError} from '@fluxer/errors/src/domains/core/ForbiddenError';
+
+export class GuildVisitAgeRestrictedError extends ForbiddenError {
+ constructor() {
+ super({code: APIErrorCodes.GUILD_VISIT_AGE_RESTRICTED});
+ }
+}
diff --git a/packages/errors/src/domains/guild/GuildVisitNotFoundError.ts b/packages/errors/src/domains/guild/GuildVisitNotFoundError.ts
new file mode 100644
index 000000000..33ed3bf76
--- /dev/null
+++ b/packages/errors/src/domains/guild/GuildVisitNotFoundError.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {NotFoundError} from '@fluxer/errors/src/domains/core/NotFoundError';
+
+export class GuildVisitNotFoundError extends NotFoundError {
+ constructor() {
+ super({code: APIErrorCodes.GUILD_VISIT_NOT_FOUND});
+ }
+}
diff --git a/packages/errors/src/domains/guild/GuildVisitsDisabledError.ts b/packages/errors/src/domains/guild/GuildVisitsDisabledError.ts
new file mode 100644
index 000000000..b7500a4cc
--- /dev/null
+++ b/packages/errors/src/domains/guild/GuildVisitsDisabledError.ts
@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {ForbiddenError} from '@fluxer/errors/src/domains/core/ForbiddenError';
+
+export class GuildVisitsDisabledError extends ForbiddenError {
+ constructor() {
+ super({code: APIErrorCodes.GUILD_VISITS_DISABLED});
+ }
+}
diff --git a/packages/schema/src/domains/admin/GuildVisitsSchemas.ts b/packages/schema/src/domains/admin/GuildVisitsSchemas.ts
new file mode 100644
index 000000000..84ffd2bad
--- /dev/null
+++ b/packages/schema/src/domains/admin/GuildVisitsSchemas.ts
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {EXPERIMENT_BUCKET_RESOLUTION, experimentBucket} from '@fluxer/schema/src/domains/experiment/ExperimentBucket';
+import {z} from 'zod';
+
+const GUILD_VISITS_MAX_TARGETED_IDS = 1000;
+const DEFAULT_GUILD_VISITS_USER_SALT = 'guild-visits-user-v1';
+
+const GuildVisitsUserIdsSchema = z.array(z.string().regex(/^\d{1,20}$/u)).max(GUILD_VISITS_MAX_TARGETED_IDS);
+
+const guildVisitsConfigFields = {
+ enabled: z.boolean().describe('Kill switch for visiting communities without joining'),
+ user_basis_points: z
+ .number()
+ .int()
+ .min(0)
+ .max(EXPERIMENT_BUCKET_RESOLUTION)
+ .describe('Share of people assigned, in basis points'),
+ user_salt: z
+ .string()
+ .trim()
+ .min(1)
+ .max(64)
+ .regex(/^[\x20-\x7e]+$/u)
+ .describe('Salt for the assignment bucket'),
+ included_user_ids: GuildVisitsUserIdsSchema.describe('People always assigned'),
+ excluded_user_ids: GuildVisitsUserIdsSchema.describe('People never assigned, checked before the included list'),
+};
+
+export const GuildVisitsConfigSchema = z.object({
+ enabled: guildVisitsConfigFields.enabled.default(false),
+ user_basis_points: guildVisitsConfigFields.user_basis_points.default(0),
+ user_salt: guildVisitsConfigFields.user_salt.default(DEFAULT_GUILD_VISITS_USER_SALT),
+ included_user_ids: guildVisitsConfigFields.included_user_ids.default([]),
+ excluded_user_ids: guildVisitsConfigFields.excluded_user_ids.default([]),
+});
+
+export type GuildVisitsConfig = z.infer<typeof GuildVisitsConfigSchema>;
+
+export const GuildVisitsConfigResponse = GuildVisitsConfigSchema;
+
+export const GuildVisitsConfigUpdateRequest = z.object(guildVisitsConfigFields).partial();
+
+export type GuildVisitsConfigUpdateRequest = z.infer<typeof GuildVisitsConfigUpdateRequest>;
+
+export const GuildVisitsAssignmentResponse = z.object({
+ enabled: z.boolean().describe('Whether this person may visit communities without joining'),
+});
+
+export type GuildVisitsAssignmentResponse = z.infer<typeof GuildVisitsAssignmentResponse>;
+
+export function guildVisitsUserActive(config: GuildVisitsConfig, userId: string): boolean {
+ if (!config.enabled) return false;
+ if (config.excluded_user_ids.includes(userId)) return false;
+ if (config.included_user_ids.includes(userId)) return true;
+ return config.user_basis_points > 0 && experimentBucket(userId, config.user_salt) < config.user_basis_points;
+}
diff --git a/packages/schema/src/domains/experiment/ExperimentSchemas.ts b/packages/schema/src/domains/experiment/ExperimentSchemas.ts
index 5266f6a62..f6d94a946 100644
--- a/packages/schema/src/domains/experiment/ExperimentSchemas.ts
+++ b/packages/schema/src/domains/experiment/ExperimentSchemas.ts
@@ -5,6 +5,7 @@ import {
DomainMigrationAssignmentResponse,
INERT_DOMAIN_MIGRATION_ASSIGNMENT,
} from '@fluxer/schema/src/domains/admin/DomainMigrationSchemas';
+import {GuildVisitsAssignmentResponse} from '@fluxer/schema/src/domains/admin/GuildVisitsSchemas';
import {PlutoniumPageAssignmentResponse} from '@fluxer/schema/src/domains/admin/PlutoniumPageSchemas';
import {INERT_VOICE_P2P_ASSIGNMENT, VoiceP2pAssignmentResponse} from '@fluxer/schema/src/domains/admin/VoiceP2pSchemas';
import {z} from 'zod';
@@ -33,8 +34,6 @@ export const ExperimentDeliveryConfigSchema = z.object({
export type ExperimentDeliveryConfig = z.infer<typeof ExperimentDeliveryConfigSchema>;
-export const DEFAULT_EXPERIMENT_DELIVERY_CONFIG: ExperimentDeliveryConfig = ExperimentDeliveryConfigSchema.parse({});
-
export const ExperimentDeliveryConfigUpdateRequest = z.object(experimentDeliveryFields).partial();
export type ExperimentDeliveryConfigUpdateRequest = z.infer<typeof ExperimentDeliveryConfigUpdateRequest>;
@@ -48,6 +47,7 @@ const ExperimentAssignmentsSchema = z.object({
channel_threads: ChannelThreadsAssignmentResponse.optional(),
plutonium_page: PlutoniumPageAssignmentResponse.optional(),
voice_p2p: VoiceP2pAssignmentResponse.optional(),
+ guild_visits: GuildVisitsAssignmentResponse.optional(),
});
export const ExperimentAssignmentsResponse = z.object({
diff --git a/packages/schema/src/domains/guild/GuildDiscoverySchemas.ts b/packages/schema/src/domains/guild/GuildDiscoverySchemas.ts
index fabfeec19..00bc77d20 100644
--- a/packages/schema/src/domains/guild/GuildDiscoverySchemas.ts
+++ b/packages/schema/src/domains/guild/GuildDiscoverySchemas.ts
@@ -14,6 +14,7 @@ import {
} from '@fluxer/constants/src/DiscoveryConstants';
import {NSFWLevelSchema} from '@fluxer/schema/src/primitives/GuildValidators';
import {SnowflakeStringType, SnowflakeType, withOpenApiType} from '@fluxer/schema/src/primitives/SchemaPrimitives';
+import {withSchemaMetadata} from '@fluxer/schema/src/SchemaMetadata';
import {z} from 'zod';
const DISCOVERY_CATEGORY_MAX = Math.max(...Object.values(DiscoveryCategories));
@@ -83,6 +84,14 @@ const DiscoveryGuildResponse = z.object({
online_count: z.number().describe('Approximate online member count'),
features: z.array(z.string()).describe('Guild feature flags'),
verification_level: z.number().describe('Verification level'),
+ visits_enabled: withSchemaMetadata(
+ z
+ .boolean()
+ .describe(
+ 'Whether opening this listing starts a visit instead of a join for the requesting user. Omitted for a caller outside the guild visits experiment',
+ ),
+ {experiment: 'guild_visits'},
+ ).optional(),
});
const DiscoveryCategoryCountResponse = z.object({
diff --git a/packages/schema/src/domains/guild/GuildResponseSchemas.ts b/packages/schema/src/domains/guild/GuildResponseSchemas.ts
index fedd4a3a0..c95dffddf 100644
--- a/packages/schema/src/domains/guild/GuildResponseSchemas.ts
+++ b/packages/schema/src/domains/guild/GuildResponseSchemas.ts
@@ -114,6 +114,11 @@ export const GuildFeatureSchema = withOpenApiType(
'ANNOUNCEMENT_CHANNELS_DISABLED',
'Guild cannot publish announcement messages or gain new followers',
],
+ [
+ GuildFeatures.VISITS_ENABLED,
+ 'VISITS_ENABLED',
+ 'People with an invite or a discovery listing can read channels that @everyone can see without joining',
+ ],
],
'A guild feature flag',
),
@@ -208,6 +213,10 @@ export const GuildResponse = z.object({
),
{experiment: 'channel_threads'},
).optional(),
+ visiting: withSchemaMetadata(
+ z.literal(true).describe('Present and true when the requesting user is visiting the guild without being a member'),
+ {experiment: 'guild_visits'},
+ ).optional(),
});
export type GuildResponse = z.infer<typeof GuildResponse>;
@@ -227,6 +236,15 @@ export const GuildPartialResponse = GuildResponse.pick({
embed_splash_width: true,
embed_splash_height: true,
features: true,
+}).extend({
+ visits_enabled: withSchemaMetadata(
+ z
+ .boolean()
+ .describe(
+ 'Whether opening this invite starts a visit instead of a join for the requesting user. Omitted for a caller outside the guild visits experiment',
+ ),
+ {experiment: 'guild_visits'},
+ ).optional(),
});
export type GuildPartialResponse = z.infer<typeof GuildPartialResponse>;
@@ -272,6 +290,7 @@ export interface Guild {
readonly message_history_cutoff?: string | null;
readonly joined_at?: string;
readonly unavailable?: boolean;
+ readonly visiting?: boolean;
readonly unavailable_hidden?: boolean;
readonly member_count?: number;
readonly online_count?: number;
diff --git a/packages/schema/src/domains/guild/GuildVisitSchemas.ts b/packages/schema/src/domains/guild/GuildVisitSchemas.ts
new file mode 100644
index 000000000..798e2d5db
--- /dev/null
+++ b/packages/schema/src/domains/guild/GuildVisitSchemas.ts
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {GuildVisitSources} from '@fluxer/constants/src/GuildVisitConstants';
+import {SnowflakeStringType} from '@fluxer/schema/src/primitives/SchemaPrimitives';
+import {z} from 'zod';
+
+export const GuildVisitSourceSchema = z
+ .union([
+ z.literal(GuildVisitSources.INVITE),
+ z.literal(GuildVisitSources.VANITY_URL),
+ z.literal(GuildVisitSources.DISCOVERY),
+ z.literal(GuildVisitSources.OPERATOR),
+ ])
+ .describe('How the visit started: 1 invite, 2 custom invite URL, 3 discovery, 4 the instance community');
+
+export const GuildVisitResponse = z.object({
+ guild_id: SnowflakeStringType.describe('ID of the guild being visited'),
+ source: GuildVisitSourceSchema,
+ started_at: z.iso.datetime().describe('When the visit started'),
+ opened_at: z.iso.datetime().describe('When the visit was last opened, updated at most once a day'),
+});
+
+export type GuildVisitResponse = z.infer<typeof GuildVisitResponse>;
+
+export const GuildVisitListResponse = z.array(GuildVisitResponse).describe('Guilds the current user is visiting');
+
+export type GuildVisitListResponse = z.infer<typeof GuildVisitListResponse>;
+
+export const GuildVisitStartResponse = z.object({
+ guild_id: SnowflakeStringType.describe('ID of the guild'),
+ member: z.boolean().describe('True when the current user is already a member, in which case no visit starts'),
+ visit: GuildVisitResponse.nullable().describe('The visit, or null when the current user is already a member'),
+});
+
+export type GuildVisitStartResponse = z.infer<typeof GuildVisitStartResponse>;
diff --git a/packages/schema/src/domains/invite/InviteSchemas.ts b/packages/schema/src/domains/invite/InviteSchemas.ts
index e991b7eec..1cc3fc76f 100644
--- a/packages/schema/src/domains/invite/InviteSchemas.ts
+++ b/packages/schema/src/domains/invite/InviteSchemas.ts
@@ -102,7 +102,7 @@ interface InviteBase {
export interface GuildInvite extends InviteBase {
readonly type: typeof InviteTypes.GUILD;
- readonly guild: Guild;
+ readonly guild: Guild & {readonly visits_enabled?: boolean};
readonly channel: Channel;
readonly member_count: number;
readonly presence_count: number;
diff --git a/packages/schema/src/domains/rpc/RpcSchemas.ts b/packages/schema/src/domains/rpc/RpcSchemas.ts
index 48bde58b8..ef1a992ac 100644
--- a/packages/schema/src/domains/rpc/RpcSchemas.ts
+++ b/packages/schema/src/domains/rpc/RpcSchemas.ts
@@ -6,6 +6,7 @@ import {
VOICE_P2P_MAX_PARTICIPANTS,
} from '@fluxer/constants/src/LimitConstants';
import {FORUM_UNREAD_COUNT_CAP, FORUM_UNREADS_MAX_THREADS} from '@fluxer/constants/src/ThreadConstants';
+import {AccountTierSchema} from '@fluxer/schema/src/domains/account/AccountTierSchemas';
import {ChannelThreadsConfigResponse} from '@fluxer/schema/src/domains/admin/ChannelThreadsSchemas';
import {GatewayRolloutConfigResponse} from '@fluxer/schema/src/domains/admin/GatewayRolloutSchemas';
import {LegacyPushServiceDeliveryWire} from '@fluxer/schema/src/domains/admin/PushRelaySchemas';
@@ -77,6 +78,7 @@ export const RpcRequest = z.discriminatedUnion('type', [
latitude: createStringType(1, 32).optional().describe('Client latitude for region selection'),
longitude: createStringType(1, 32).optional().describe('Client longitude for region selection'),
thread_channels_capable: z.boolean().optional().describe('Whether the session can handle thread channels'),
+ guild_visits_capable: z.boolean().optional().describe('Whether the session can visit guilds without joining'),
}),
z.object({
type: z.literal('guild_collection').describe('Request type for fetching a single guild collection chunk'),
@@ -355,6 +357,17 @@ export const RpcResponseSessionData = z.object({
.array(WebAuthnCredentialResponse)
.describe('Registered WebAuthn credentials (passkeys) for the authenticated user'),
version: z.number().int().describe('Session data version for cache invalidation'),
+ visit_guild_ids: z
+ .array(SnowflakeStringType)
+ .optional()
+ .describe('Guilds the user is visiting, only for sessions that can visit guilds'),
+ operator_visit_guild_ids: z
+ .array(SnowflakeStringType)
+ .optional()
+ .describe('Subset of visit_guild_ids opened by the instance operator entry, which ignore the guild visit setting'),
+ adult_content_allowed: z.boolean().optional().describe('Whether the user may see adult channels while visiting'),
+ account_tier: AccountTierSchema.optional().describe('Account tier of the user'),
+ ip_key: z.string().nullish().describe('Address key of the identifying connection, used to evict visitors on IP bans'),
});
export type RpcResponseSessionData = z.infer<typeof RpcResponseSessionData>;