A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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>;