Document generated plugin user names

docs/PLUGIN_AUTHOR_GUIDE.md

@@ -834,11 +834,12 @@ return { status: 302, headers: { Location: returnTo } };
 
 `users.register` finds or creates an authenticated Owncast user for an external
 identity. The host scopes `authId` to your slug, so pass the provider's raw
-stable ID. `profileUrl` must be empty or an absolute HTTP(S) URL. Set `handle`
-to the verified provider label and set `public` true only after the viewer opts
-into public display. `grantSession` and `endSession` are meaningful only inside
-`onHttpRequest`, where the host attaches or clears the cookie after the handler
-returns.
+stable ID. `displayName` is optional. Omit it or pass `null` to generate a
+display name. `profileUrl` must be empty or an absolute HTTP(S) URL. Set
+`handle` to the verified provider label and set `public` true only after the
+viewer opts into public display. `grantSession` and `endSession` are meaningful
+only inside `onHttpRequest`, where the host attaches or clears the cookie after
+the handler returns.
 
 ### Re-validating sessions: `onAuthCheck`
 

docs/WIRE_PROTOCOL.md

@@ -291,6 +291,9 @@ authentication gate uses this before granting a session.
   as the unmodified provider-specific ID. The host rejects administrative or
   otherwise disallowed scopes.
 
+  `displayName` is optional and nullable. When omitted or `null`, the host generates
+  the user's display name.
+
 ### `auth.gate`
 
 Only one `auth.gate` plugin can be enabled at a time. These calls are meaningful
@@ -745,7 +748,7 @@ type CommandEvent = {
 
 type UserRegisterRequest = {
   authId: string;
-  displayName?: string;
+  displayName?: string | null;
   scopes?: string[];
   profileUrl?: string;
   handle?: string;

sdks/js/index.d.ts

@@ -212,8 +212,8 @@ export const Permissions: {
 export interface UserRegisterRequest {
   /** Stable external identity within this plugin's provider namespace. */
   authId: string;
-  /** Optional display name to seed on the user. */
-  displayName?: string;
+  /** Optional display name to seed on the user. Omit or pass `null` to generate one. */
+  displayName?: string | null;
   /** Optional scopes to grant the user (e.g. `["MODERATOR"]`). */
   scopes?: string[];
   /** Verified public profile URL. The host accepts only absolute HTTP(S) URLs. */

sdks/python/owncast_plugin/__init__.py

@@ -655,10 +655,11 @@ def register(
     ):
         """Find or create an authenticated user for an external identity.
 
-        auth_id is the stable, provider-scoped ID. profile_url and handle
-        describe a verified external profile. Set public=True only when the
-        viewer agreed to show that identity publicly. Returns an object with
-        .user_id. Raises on host error. Requires 'users.register'.
+        auth_id is the stable, provider-scoped ID. Omit display_name to have
+        Owncast generate one. profile_url and handle describe a verified
+        external profile. Set public=True only when the viewer agreed to show
+        that identity publicly. Returns an object with .user_id. Raises on host
+        error. Requires 'users.register'.
         """
         req = {"authId": str(auth_id)}
         if display_name is not None: