@lessly/sdk-app 83.4.0 → 84.0.0

package/dist/_types/gen/types.gen.d.ts

@@ -119974,25 +119974,106 @@ export interface UsersApikeysCreateInput {
     type: ("server" | "publishable");
 }
 export interface UsersApikeysCreateOutput {
+    /**
+     * Id of the key. Pass it to users_apikeys_revoke.
+     */
     id: string;
+    /**
+     * The full secret key, shown ONCE. Store it now — it is never returned again, and a lost key is replaced by minting a new one.
+     */
     key: string;
+    /**
+     * The label a human gave this key — which backend or environment holds it.
+     */
+    name: string;
+    /**
+     * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+     */
+    type: ("server" | "publishable");
+    /**
+     * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+     */
+    value: (string | null);
+    /**
+     * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+     */
+    prefix: string;
+    /**
+     * When the key was issued (ISO 8601).
+     */
+    createdAt: string;
+    /**
+     * When the key was revoked (ISO 8601). Null while it still works.
+     */
+    revokedAt: (string | null);
+}
+export interface UsersApikeysGetInput {
+    /**
+     * Id of the key to read — the `id` from users_apikeys_list.
+     */
+    id: string;
+}
+export interface UsersApikeysGetOutput {
+    /**
+     * Id of the key. Pass it to users_apikeys_revoke.
+     */
+    id: string;
+    /**
+     * The label a human gave this key — which backend or environment holds it.
+     */
     name: string;
+    /**
+     * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+     */
     type: ("server" | "publishable");
+    /**
+     * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+     */
     value: (string | null);
+    /**
+     * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+     */
     prefix: string;
+    /**
+     * When the key was issued (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the key was revoked (ISO 8601). Null while it still works.
+     */
     revokedAt: (string | null);
 }
 export interface UsersApikeysListInput {
 }
 export interface UsersApikeysListOutput {
     keys: {
+        /**
+         * Id of the key. Pass it to users_apikeys_revoke.
+         */
         id: string;
+        /**
+         * The label a human gave this key — which backend or environment holds it.
+         */
         name: string;
+        /**
+         * `server` for a secret backend key (usk_…), `publishable` for a browser-safe one (upk_…).
+         */
         type: ("server" | "publishable");
+        /**
+         * The full value of a publishable key, which is not a secret. Null for a server key — that value exists in exactly one response, ever.
+         */
         value: (string | null);
+        /**
+         * `usk_`/`upk_` plus six characters — enough to recognise a key, never to use one.
+         */
         prefix: string;
+        /**
+         * When the key was issued (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the key was revoked (ISO 8601). Null while it still works.
+         */
         revokedAt: (string | null);
     }[];
 }
@@ -120003,7 +120084,13 @@ export interface UsersApikeysRevokeInput {
     id: string;
 }
 export interface UsersApikeysRevokeOutput {
+    /**
+     * Id of the key that was revoked.
+     */
     id: string;
+    /**
+     * Always true — revocation is immediate and final.
+     */
     revoked: true;
 }
 export interface UsersAuditListInput {
@@ -120037,21 +120124,60 @@ export interface UsersAuditListInput {
     targetType?: string;
 }
 export interface UsersAuditListOutput {
+    /**
+     * The page of audit events, newest first.
+     */
     events: {
+        /**
+         * Id of this audit row.
+         */
         id: string;
+        /**
+         * IP the action came from. Null when it was not an HTTP action.
+         */
         ip: (string | null);
+        /**
+         * What happened, as a dotted name — `user.created`, `passkey.deleted`, `email_change.override_applied`.
+         */
         action: string;
+        /**
+         * Id of the actor. Null for a system action.
+         */
         actorId: (string | null);
+        /**
+         * Action-specific detail — the reason text, counts, whatever the action recorded.
+         */
         metadata: {
             [k: string]: unknown;
         };
+        /**
+         * Id of the row the action was about. Null when there was none.
+         */
         targetId: (string | null);
+        /**
+         * Who acted: `operator` (a human or agent on the management plane), `end_user`, or `system`.
+         */
         actorType: ("operator" | "system" | "end_user");
+        /**
+         * When the action happened (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * Product the audited action happened in.
+         */
         productId: string;
+        /**
+         * User agent the action came from. Null when none was sent.
+         */
         userAgent: (string | null);
+        /**
+         * What kind of row the action was about — `user` or `product`. Null when it was about nothing in particular.
+         */
         targetType: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
 export interface UsersConfigGetInput {
@@ -121027,12 +121153,33 @@ export interface UsersFactorsListInput {
     userId: string;
 }
 export interface UsersFactorsListOutput {
+    /**
+     * Every second factor this user has — types and status only, never material.
+     */
     factors: {
+        /**
+         * Kind of second factor: `totp` or `backup_codes`. No key material is ever returned.
+         */
         type: ("totp" | "backup_codes" | "webauthn");
+        /**
+         * Whether this factor is enrolled and usable, or still pending verification.
+         */
         status: ("unverified" | "verified");
+        /**
+         * When the factor was enrolled (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * `backup_codes` only: how many of the batch are still unspent. Null for any other factor type.
+         */
         remaining: (number | null);
+        /**
+         * When the factor was last used to sign in (ISO 8601). Null if it never was.
+         */
         lastUsedAt: (string | null);
+        /**
+         * When the user first proved the factor works (ISO 8601). Null while it is unverified.
+         */
         verifiedAt: (string | null);
     }[];
 }
@@ -121047,7 +121194,13 @@ export interface UsersFactorsResetInput {
     userId: string;
 }
 export interface UsersFactorsResetOutput {
+    /**
+     * Id of the scheduled reset. The same value arrives on `users/mfa.reset-settled`, which is what finishes this step.
+     */
     requestId: string;
+    /**
+     * When the removal happens, if nobody aborts it first (ISO 8601). The delay is this product's, not a fixed one.
+     */
     scheduledFor: string;
 }
 export interface UsersKeysListInput {
@@ -121328,6 +121481,50 @@ export interface UsersOpsSloGetOutput {
         signInFailureBaseline: (number | null);
     };
 }
+export interface UsersPasskeysGetInput {
+    /**
+     * The end user the credential belongs to.
+     */
+    userId: string;
+    /**
+     * Which credential to read — the `id` from `users_passkeys_list`.
+     */
+    passkeyId: string;
+}
+export interface UsersPasskeysGetOutput {
+    /**
+     * Id of the credential. Pass it to users_passkeys_revoke.
+     */
+    id: string;
+    /**
+     * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+     */
+    name: (string | null);
+    /**
+     * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+     */
+    aaguid: (string | null);
+    /**
+     * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+     */
+    backedUp: boolean;
+    /**
+     * When the credential was registered (ISO 8601).
+     */
+    createdAt: string;
+    /**
+     * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+     */
+    signCount: number;
+    /**
+     * When it last signed in (ISO 8601). Null when it never has.
+     */
+    lastUsedAt: (string | null);
+    /**
+     * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+     */
+    transports: string[];
+}
 export interface UsersPasskeysListInput {
     /**
      * The end user whose passkeys to list.
@@ -121335,14 +121532,41 @@ export interface UsersPasskeysListInput {
     userId: string;
 }
 export interface UsersPasskeysListOutput {
+    /**
+     * The credentials this user has registered, newest first. Empty when they have none.
+     */
     passkeys: {
+        /**
+         * Id of the credential. Pass it to users_passkeys_revoke.
+         */
         id: string;
+        /**
+         * The name the user gave this credential, so a person can tell their devices apart. Null when they never named it.
+         */
         name: (string | null);
+        /**
+         * The authenticator MODEL’s identifier, which says what kind of device this is, never which one. Null when the authenticator withheld it.
+         */
         aaguid: (string | null);
+        /**
+         * True when the platform syncs this credential, so it survives losing the device. False means it lives on that device alone.
+         */
         backedUp: boolean;
+        /**
+         * When the credential was registered (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * The authenticator’s own counter as of the last assertion. 0 when the authenticator does not count.
+         */
         signCount: number;
+        /**
+         * When it last signed in (ISO 8601). Null when it never has.
+         */
         lastUsedAt: (string | null);
+        /**
+         * How this authenticator can be reached. Empty when the browser reported nothing — the vocabulary is the platform’s and grows, so it is not an enum.
+         */
         transports: string[];
     }[];
 }
@@ -121365,9 +121589,18 @@ export interface UsersPasskeysRevokeOutput {
      * Present when the revoke was refused — today, only because it was the last way in.
      */
     error: ({
+        /**
+         * Why it was refused. Today only `passkey_last_way_in`.
+         */
         code: string;
+        /**
+         * The refusal in a sentence, safe to show a human.
+         */
         message: string;
     } | null);
+    /**
+     * `deleted` when the credential is gone, `failed` when the revoke was refused.
+     */
     status: ("deleted" | "failed");
 }
 export interface UsersSessionsGetInput {
@@ -121377,7 +121610,13 @@ export interface UsersSessionsGetInput {
     sessionId: string;
 }
 export interface UsersSessionsGetOutput {
+    /**
+     * Id of this session. Pass it to users_sessions_revoke.
+     */
     id: string;
+    /**
+     * IP the session was opened from. Null when it was not recorded.
+     */
     ip: (string | null);
     /**
      * `aal2` only if a verified second factor completed.
@@ -121387,18 +121626,45 @@ export interface UsersSessionsGetOutput {
      * The factors this session was established with.
      */
     amr: string[];
+    /**
+     * Whether the session is still usable, expired, or revoked.
+     */
     status: ("active" | "revoked");
+    /**
+     * The end user this session belongs to.
+     */
     userId: string;
+    /**
+     * When the session was opened (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the current token stops working unless refreshed (ISO 8601).
+     */
     expiresAt: string;
+    /**
+     * When the session was revoked (ISO 8601). Null while it is live.
+     */
     revokedAt: (string | null);
+    /**
+     * User agent the session was opened from. Null when none was sent.
+     */
     userAgent: (string | null);
+    /**
+     * Why the session ended, when it was revoked — e.g. `signout`, `ban`, `mfa_reset`. Null while it is live. The vocabulary is additive, so it is not an enum.
+     */
     revokedReason: (string | null);
     /**
      * The operator behind an impersonated session, or null for an ordinary one.
      */
     impersonatedBy: (string | null);
+    /**
+     * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+     */
     lastRefreshedAt: (string | null);
+    /**
+     * When the session ends no matter how often it refreshes (ISO 8601).
+     */
     absoluteExpiresAt: string;
 }
 export interface UsersSessionsImpersonateInput {
@@ -121434,16 +121700,49 @@ export interface UsersSessionsListInput {
     userId: string;
 }
 export interface UsersSessionsListOutput {
+    /**
+     * The sessions matching the filter, newest first.
+     */
     sessions: {
+        /**
+         * Id of this session. Pass it to users_sessions_revoke.
+         */
         id: string;
+        /**
+         * IP the session was opened from. Null when it was not recorded.
+         */
         ip: (string | null);
+        /**
+         * Whether the session is still usable, expired, or revoked.
+         */
         status: ("active" | "revoked");
+        /**
+         * The end user this session belongs to.
+         */
         userId: string;
+        /**
+         * When the session was opened (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the current token stops working unless refreshed (ISO 8601).
+         */
         expiresAt: string;
+        /**
+         * When the session was revoked (ISO 8601). Null while it is live.
+         */
         revokedAt: (string | null);
+        /**
+         * User agent the session was opened from. Null when none was sent.
+         */
         userAgent: (string | null);
+        /**
+         * When the session last refreshed its tokens (ISO 8601). Null if it never has.
+         */
         lastRefreshedAt: (string | null);
+        /**
+         * When the session ends no matter how often it refreshes (ISO 8601).
+         */
         absoluteExpiresAt: string;
     }[];
 }
@@ -121458,6 +121757,9 @@ export interface UsersSessionsRevokeInput {
     sessionId?: string;
 }
 export interface UsersSessionsRevokeOutput {
+    /**
+     * How many sessions were revoked. Zero when there was nothing live to revoke.
+     */
     revoked: number;
 }
 export interface UsersStatsGetInput {
@@ -121580,48 +121882,137 @@ export interface UsersUsersBanInput {
     userId: string;
 }
 export interface UsersUsersBanOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
-    requiresReset: boolean;
-    publicMetadata: UsersUsersBanOutputPublicMetadata;
-    unsafeMetadata: UsersUsersBanOutputPublicMetadata;
-    privateMetadata: UsersUsersBanOutputPublicMetadata;
-    emailChangeLockedUntil: (string | null);
-}
-export interface UsersUsersBanOutputPublicMetadata {
-    [k: string]: unknown;
-}
-export interface UsersUsersCreateInput {
     /**
-     * The user's display name.
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
      */
-    name?: string;
+    primaryEmail: (string | null);
     /**
-     * URL of the user's avatar image.
+     * Whether the user must set a new password at their next sign-in.
      */
-    imageUrl?: string;
+    requiresReset: boolean;
     /**
-     * Credential to store for this user. Supply hashes only; omit password to create no password identity.
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
+    emailChangeLockedUntil: (string | null);
+}
+export interface UsersUsersCreateInput {
+    /**
+     * The user's display name.
+     */
+    name?: string;
+    /**
+     * URL of the user's avatar image.
+     */
+    imageUrl?: string;
+    /**
+     * Credential to store for this user. Supply hashes only; omit password to create no password identity.
      */
     password?: {
         /**
@@ -121714,37 +122105,126 @@ export interface UsersUsersCreateInputPublicMetadata1 {
     [k: string]: unknown;
 }
 export interface UsersUsersCreateOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersCreateOutputPublicMetadata;
-    unsafeMetadata: UsersUsersCreateOutputPublicMetadata;
-    privateMetadata: UsersUsersCreateOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersCreateOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersDeleteInput {
     /**
      * The opaque user id returned by users_users_create or _list.
@@ -121752,37 +122232,126 @@ export interface UsersUsersDeleteInput {
     userId: string;
 }
 export interface UsersUsersDeleteOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersDeleteOutputPublicMetadata;
-    unsafeMetadata: UsersUsersDeleteOutputPublicMetadata;
-    privateMetadata: UsersUsersDeleteOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersDeleteOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersExportInput {
     /**
      * Rows per page, 1-500. Default 100.
@@ -121808,40 +122377,129 @@ export interface UsersUsersExportInput {
 export interface UsersUsersExportOutput {
     count: number;
     users: {
+        /**
+         * Id of this end user. Pass it to any users_users_* tool.
+         */
         id: string;
+        /**
+         * The user's display name. Null when nobody set one.
+         */
         name: (string | null);
+        /**
+         * When the user was banned (ISO 8601). Null while they are not banned.
+         */
         bannedAt: (string | null);
+        /**
+         * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+         */
         erasedAt: (string | null);
+        /**
+         * URL of the user's avatar. Null when there is none.
+         */
         imageUrl: (string | null);
+        /**
+         * Whether this is a test fixture — excluded from metering and from the default listing.
+         */
         testUser: boolean;
+        /**
+         * When the user was created (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the user was soft-deleted (ISO 8601). Null while the account is live.
+         */
         deletedAt: (string | null);
+        /**
+         * Product this user belongs to. Never an input — it comes from the calling identity.
+         */
         productId: string;
+        /**
+         * When the user was last changed (ISO 8601).
+         */
         updatedAt: string;
+        /**
+         * Whether this user is still on the waitlist and cannot sign in yet.
+         */
         waitlisted: boolean;
+        /**
+         * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+         */
         identifiers: {
+            /**
+             * Id of this identifier row.
+             */
             id: string;
+            /**
+             * What kind of identifier this is. Today always `email`.
+             */
             type: "email";
+            /**
+             * The address as the user typed it, for display.
+             */
             value: string;
+            /**
+             * Whether this is the identifier the user signs in with and is contacted at.
+             */
             isPrimary: boolean;
+            /**
+             * When this address was verified (ISO 8601). Null while it never was.
+             */
             verifiedAt: (string | null);
+            /**
+             * The address lowercased and NFC-normalised — what uniqueness is checked against.
+             */
             valueCanonical: string;
+            /**
+             * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+             */
             verificationStatus: ("unverified" | "verified" | "expired");
         }[];
+        /**
+         * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+         */
         lockedUntil: (string | null);
+        /**
+         * When the user last signed in (ISO 8601). Null if they never have.
+         */
         lastSignInAt: (string | null);
+        /**
+         * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+         */
+        primaryEmail: (string | null);
+        /**
+         * Whether the user must set a new password at their next sign-in.
+         */
         requiresReset: boolean;
-        publicMetadata: UsersUsersExportOutputPublicMetadata;
-        unsafeMetadata: UsersUsersExportOutputPublicMetadata;
-        privateMetadata: UsersUsersExportOutputPublicMetadata;
+        /**
+         * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+         */
+        publicMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata the end user may write themselves. Treat it as untrusted.
+         */
+        unsafeMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata for the management plane only. Never reaches the end user or a token.
+         */
+        privateMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Id of the primary identifier row. Null when there is no primary identifier.
+         */
+        primaryIdentifierId: (string | null);
+        /**
+         * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+         */
         emailChangeLockedUntil: (string | null);
     }[];
     exportedAt: string;
     nextCursor: (string | null);
 }
-export interface UsersUsersExportOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersGetInput {
     /**
      * The opaque user id returned by users_users_create or _list.
@@ -121849,37 +122507,126 @@ export interface UsersUsersGetInput {
     userId: string;
 }
 export interface UsersUsersGetOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersGetOutputPublicMetadata;
-    unsafeMetadata: UsersUsersGetOutputPublicMetadata;
-    privateMetadata: UsersUsersGetOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersGetOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersImportInput {
     /**
      * The users to import, at most 500 per call — batch client-side beyond that. Each row: identifiers (email), optional profile, optional password HASH, optional flags.
@@ -121890,15 +122637,42 @@ export interface UsersUsersImportInput {
     users: [unknown, ...(unknown)[]];
 }
 export interface UsersUsersImportOutput {
+    /**
+     * How many rows could not be imported at all.
+     */
     failed: number;
+    /**
+     * How many users were created.
+     */
     created: number;
+    /**
+     * One row per submitted row, in the order you sent them.
+     */
     results: {
+        /**
+         * Zero-based index of the row in the `users` array you sent.
+         */
         row: number;
+        /**
+         * Why it was skipped, or what went wrong. Null for a created row.
+         */
         reason: (string | null);
+        /**
+         * What happened to this row.
+         */
         status: ("created" | "skipped" | "failed");
+        /**
+         * The created user's id. Null for skipped and failed rows.
+         */
         userId: (string | null);
     }[];
+    /**
+     * How many rows were passed over — an address already in the directory, typically.
+     */
     skipped: number;
+    /**
+     * How many rows you submitted.
+     */
     requested: number;
 }
 export interface UsersUsersInviteInput {
@@ -121924,9 +122698,21 @@ export interface UsersUsersInviteInput {
     };
 }
 export interface UsersUsersInviteOutput {
+    /**
+     * False when the re-invite cooldown or the mail toolkit refused the send. The invite is still live.
+     */
     mailed: boolean;
+    /**
+     * The invited user, created immediately and listed straight away — they simply cannot sign in until they accept.
+     */
     userId: string;
+    /**
+     * False when this address had already been invited; the same user is returned.
+     */
     created: boolean;
+    /**
+     * When the invite link stops working (ISO 8601).
+     */
     expiresAt: string;
 }
 export interface UsersUsersListInput {
@@ -121960,40 +122746,135 @@ export interface UsersUsersListInput {
     includeWaitlisted?: boolean;
 }
 export interface UsersUsersListOutput {
+    /**
+     * The page of users, newest first.
+     */
     users: {
+        /**
+         * Id of this end user. Pass it to any users_users_* tool.
+         */
         id: string;
+        /**
+         * The user's display name. Null when nobody set one.
+         */
         name: (string | null);
+        /**
+         * When the user was banned (ISO 8601). Null while they are not banned.
+         */
         bannedAt: (string | null);
+        /**
+         * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+         */
         erasedAt: (string | null);
+        /**
+         * URL of the user's avatar. Null when there is none.
+         */
         imageUrl: (string | null);
+        /**
+         * Whether this is a test fixture — excluded from metering and from the default listing.
+         */
         testUser: boolean;
+        /**
+         * When the user was created (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the user was soft-deleted (ISO 8601). Null while the account is live.
+         */
         deletedAt: (string | null);
+        /**
+         * Product this user belongs to. Never an input — it comes from the calling identity.
+         */
         productId: string;
+        /**
+         * When the user was last changed (ISO 8601).
+         */
         updatedAt: string;
+        /**
+         * Whether this user is still on the waitlist and cannot sign in yet.
+         */
         waitlisted: boolean;
+        /**
+         * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+         */
         identifiers: {
+            /**
+             * Id of this identifier row.
+             */
             id: string;
+            /**
+             * What kind of identifier this is. Today always `email`.
+             */
             type: "email";
+            /**
+             * The address as the user typed it, for display.
+             */
             value: string;
+            /**
+             * Whether this is the identifier the user signs in with and is contacted at.
+             */
             isPrimary: boolean;
+            /**
+             * When this address was verified (ISO 8601). Null while it never was.
+             */
             verifiedAt: (string | null);
+            /**
+             * The address lowercased and NFC-normalised — what uniqueness is checked against.
+             */
             valueCanonical: string;
+            /**
+             * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+             */
             verificationStatus: ("unverified" | "verified" | "expired");
         }[];
+        /**
+         * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+         */
         lockedUntil: (string | null);
+        /**
+         * When the user last signed in (ISO 8601). Null if they never have.
+         */
         lastSignInAt: (string | null);
+        /**
+         * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+         */
+        primaryEmail: (string | null);
+        /**
+         * Whether the user must set a new password at their next sign-in.
+         */
         requiresReset: boolean;
-        publicMetadata: UsersUsersListOutputPublicMetadata;
-        unsafeMetadata: UsersUsersListOutputPublicMetadata;
-        privateMetadata: UsersUsersListOutputPublicMetadata;
+        /**
+         * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+         */
+        publicMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata the end user may write themselves. Treat it as untrusted.
+         */
+        unsafeMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Metadata for the management plane only. Never reaches the end user or a token.
+         */
+        privateMetadata: {
+            [k: string]: unknown;
+        };
+        /**
+         * Id of the primary identifier row. Null when there is no primary identifier.
+         */
+        primaryIdentifierId: (string | null);
+        /**
+         * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+         */
         emailChangeLockedUntil: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
-export interface UsersUsersListOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersSetPrimaryIdentifierInput {
     /**
      * The address to make primary. Must not already belong, verified, to another user of this product.
@@ -122009,7 +122890,13 @@ export interface UsersUsersSetPrimaryIdentifierInput {
     userId: string;
 }
 export interface UsersUsersSetPrimaryIdentifierOutput {
+    /**
+     * Id of the scheduled change. It appears in the audit rows and in the abort link mailed to the old address.
+     */
     requestId: string;
+    /**
+     * When the swap becomes applicable, if nobody aborts it first (ISO 8601). The delay is this product's `emailChange.overrideDelayHours`, 72 by default.
+     */
     scheduledFor: string;
 }
 export interface UsersUsersUnbanInput {
@@ -122019,37 +122906,126 @@ export interface UsersUsersUnbanInput {
     userId: string;
 }
 export interface UsersUsersUnbanOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersUnbanOutputPublicMetadata;
-    unsafeMetadata: UsersUsersUnbanOutputPublicMetadata;
-    privateMetadata: UsersUsersUnbanOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersUnbanOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersUsersUpdateInput {
     /**
      * The user's display name. Pass null to clear.
@@ -122097,37 +123073,126 @@ export interface UsersUsersUpdateInputPublicMetadata1 {
     [k: string]: unknown;
 }
 export interface UsersUsersUpdateOutput {
+    /**
+     * Id of this end user. Pass it to any users_users_* tool.
+     */
     id: string;
+    /**
+     * The user's display name. Null when nobody set one.
+     */
     name: (string | null);
+    /**
+     * When the user was banned (ISO 8601). Null while they are not banned.
+     */
     bannedAt: (string | null);
+    /**
+     * When this user's personal data was purged for good (ISO 8601). Null while it is intact.
+     */
     erasedAt: (string | null);
+    /**
+     * URL of the user's avatar. Null when there is none.
+     */
     imageUrl: (string | null);
+    /**
+     * Whether this is a test fixture — excluded from metering and from the default listing.
+     */
     testUser: boolean;
+    /**
+     * When the user was created (ISO 8601).
+     */
     createdAt: string;
+    /**
+     * When the user was soft-deleted (ISO 8601). Null while the account is live.
+     */
     deletedAt: (string | null);
+    /**
+     * Product this user belongs to. Never an input — it comes from the calling identity.
+     */
     productId: string;
+    /**
+     * When the user was last changed (ISO 8601).
+     */
     updatedAt: string;
+    /**
+     * Whether this user is still on the waitlist and cannot sign in yet.
+     */
     waitlisted: boolean;
+    /**
+     * Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
+     */
     identifiers: {
+        /**
+         * Id of this identifier row.
+         */
         id: string;
+        /**
+         * What kind of identifier this is. Today always `email`.
+         */
         type: "email";
+        /**
+         * The address as the user typed it, for display.
+         */
         value: string;
+        /**
+         * Whether this is the identifier the user signs in with and is contacted at.
+         */
         isPrimary: boolean;
+        /**
+         * When this address was verified (ISO 8601). Null while it never was.
+         */
         verifiedAt: (string | null);
+        /**
+         * The address lowercased and NFC-normalised — what uniqueness is checked against.
+         */
         valueCanonical: string;
+        /**
+         * `unverified`, `verified`, or `expired` when a verification link ran out before it was used.
+         */
         verificationStatus: ("unverified" | "verified" | "expired");
     }[];
+    /**
+     * When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
+     */
     lockedUntil: (string | null);
+    /**
+     * When the user last signed in (ISO 8601). Null if they never have.
+     */
     lastSignInAt: (string | null);
+    /**
+     * The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
+     */
+    primaryEmail: (string | null);
+    /**
+     * Whether the user must set a new password at their next sign-in.
+     */
     requiresReset: boolean;
-    publicMetadata: UsersUsersUpdateOutputPublicMetadata;
-    unsafeMetadata: UsersUsersUpdateOutputPublicMetadata;
-    privateMetadata: UsersUsersUpdateOutputPublicMetadata;
+    /**
+     * Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
+     */
+    publicMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata the end user may write themselves. Treat it as untrusted.
+     */
+    unsafeMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Metadata for the management plane only. Never reaches the end user or a token.
+     */
+    privateMetadata: {
+        [k: string]: unknown;
+    };
+    /**
+     * Id of the primary identifier row. Null when there is no primary identifier.
+     */
+    primaryIdentifierId: (string | null);
+    /**
+     * Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.
+     */
     emailChangeLockedUntil: (string | null);
 }
-export interface UsersUsersUpdateOutputPublicMetadata {
-    [k: string]: unknown;
-}
 export interface UsersWaitlistFunnelInput {
 }
 export interface UsersWaitlistFunnelOutput {
@@ -122138,6 +123203,62 @@ export interface UsersWaitlistFunnelOutput {
     registered: number;
     unconfirmed: number;
 }
+export interface UsersWaitlistGetInput {
+    /**
+     * The waitlisted user to read — the `userId` from `users_waitlist_list`.
+     */
+    userId: string;
+}
+export interface UsersWaitlistGetOutput {
+    /**
+     * Where in the funnel this entry is: `pending`, `invited`, `registered` or `withdrawn`.
+     */
+    status: ("pending" | "invited" | "registered" | "withdrawn");
+    /**
+     * The waitlisted user. Every users_users_* tool takes this id.
+     */
+    userId: string;
+    /**
+     * When the entry joined the waitlist (ISO 8601).
+     */
+    createdAt: string;
+    /**
+     * When the invite was sent (ISO 8601). Null while the entry is pending.
+     */
+    invitedAt: (string | null);
+    /**
+     * The email address that signed up.
+     */
+    identifier: string;
+    /**
+     * Where the signup came from — the campaign, referrer and landing page recorded at the time.
+     */
+    attribution: {
+        [k: string]: unknown;
+    };
+    /**
+     * When the address confirmed a double opt-in (ISO 8601). Null when it never did.
+     */
+    confirmedAt: (string | null);
+    /**
+     * When the address asked to be taken off the list (ISO 8601). Null when it did not.
+     */
+    withdrawnAt: (string | null);
+    /**
+     * What was recorded to show this address consented: when, from where, and under which wording.
+     */
+    consentProof: {
+        [k: string]: unknown;
+    };
+    /**
+     * When the invitee finished signing up (ISO 8601). Null until they do.
+     */
+    registeredAt: (string | null);
+    /**
+     * Id of the live invite token. Null while the entry has not been invited.
+     */
+    inviteTokenId: (string | null);
+}
 export interface UsersWaitlistImportInput {
     /**
      * The legacy signups to import, at most 500 per call — batch client-side beyond that.
@@ -122305,15 +123426,42 @@ export interface UsersWaitlistImportInput {
     ];
 }
 export interface UsersWaitlistImportOutput {
+    /**
+     * How many could not be imported at all.
+     */
     failed: number;
+    /**
+     * One row per submitted row, in the order you sent them.
+     */
     results: {
+        /**
+         * Zero-based index of the row in the array you sent.
+         */
         row: number;
+        /**
+         * Why it was skipped, or what went wrong. Null for an imported row.
+         */
         reason: (string | null);
+        /**
+         * What happened to this row.
+         */
         status: ("imported" | "skipped" | "failed");
+        /**
+         * The waitlisted user this row created. Null for skipped and failed rows.
+         */
         userId: (string | null);
     }[];
+    /**
+     * How many were already on the list or otherwise passed over.
+     */
     skipped: number;
+    /**
+     * How many became waitlist entries.
+     */
     imported: number;
+    /**
+     * How many rows you submitted.
+     */
     requested: number;
 }
 export interface UsersWaitlistInviteInput {
@@ -122326,12 +123474,30 @@ export interface UsersWaitlistInviteInput {
     userIds: [string, ...(string)[]];
 }
 export interface UsersWaitlistInviteOutput {
+    /**
+     * How many of the requested users were invited.
+     */
     invited: number;
+    /**
+     * One row per user you asked for, in the order you sent them.
+     */
     results: {
+        /**
+         * Why this user was skipped. Null for an invited row.
+         */
         reason: (("suppressed" | "not_found" | "already_registered") | null);
+        /**
+         * Whether this user was invited or passed over.
+         */
         status: ("invited" | "skipped");
+        /**
+         * The user this row is about.
+         */
         userId: string;
     }[];
+    /**
+     * How many were passed over — see each row's `reason`.
+     */
     skipped: number;
 }
 export interface UsersWaitlistListInput {
@@ -122353,23 +123519,62 @@ export interface UsersWaitlistListInput {
     confirmed?: boolean;
 }
 export interface UsersWaitlistListOutput {
+    /**
+     * The page of waitlist entries, newest first.
+     */
     entries: {
+        /**
+         * Where in the funnel this entry is: `pending`, `invited`, `registered` or `withdrawn`.
+         */
         status: ("pending" | "invited" | "registered" | "withdrawn");
+        /**
+         * The waitlisted user. Every users_users_* tool takes this id.
+         */
         userId: string;
+        /**
+         * When the entry joined the waitlist (ISO 8601).
+         */
         createdAt: string;
+        /**
+         * When the invite was sent (ISO 8601). Null while the entry is pending.
+         */
         invitedAt: (string | null);
+        /**
+         * The email address that signed up.
+         */
         identifier: string;
+        /**
+         * Where the signup came from — the campaign, referrer and landing page recorded at the time.
+         */
         attribution: {
             [k: string]: unknown;
         };
+        /**
+         * When the address confirmed a double opt-in (ISO 8601). Null when it never did.
+         */
         confirmedAt: (string | null);
+        /**
+         * When the address asked to be taken off the list (ISO 8601). Null when it did not.
+         */
         withdrawnAt: (string | null);
+        /**
+         * What was recorded to show this address consented: when, from where, and under which wording.
+         */
         consentProof: {
             [k: string]: unknown;
         };
+        /**
+         * When the invitee finished signing up (ISO 8601). Null until they do.
+         */
         registeredAt: (string | null);
+        /**
+         * Id of the live invite token. Null while the entry has not been invited.
+         */
         inviteTokenId: (string | null);
     }[];
+    /**
+     * Pass back as `cursor` to fetch the next page. Null when this page is the last.
+     */
     nextCursor: (string | null);
 }
 export interface UsersWebhooksCreateInput {