@streamoid/settings 0.4.7 → 0.6.1

package/dist/index.d.mts

@@ -233,21 +233,46 @@ interface SettingsWorkspaceAdapter {
     /** Toggle this workspace's `orgVisibility` within its parent org. */
     setOrgVisibility?: (visibility: "private" | "shared") => Promise<void>;
 }
+/**
+ * An organization membership role.
+ *
+ * `guest` is an outsider who accepted an invite to a single workspace inside
+ * the organization. They hold a membership row — so they show up in these
+ * responses — but inherit nothing from the org: no implicit access to its
+ * shared workspaces, and every org-level write is refused by the backend.
+ *
+ * Gate write affordances on `=== "admin"`, never on `!== "member"`: a role this
+ * union does not yet name must read as least-privileged, not as an editor.
+ *
+ * Deliberately NOT applied to `autoJoinRole` or to workspace/team roles — a
+ * domain claim that auto-joins its own company as guests is a contradiction,
+ * and a workspace role of "guest" is not a value the backend accepts.
+ */
+type SettingsOrganizationRole = "admin" | "member" | "guest";
 interface SettingsOrganizationListItem {
     _id: string;
     name: string;
     imageUrl?: string;
-    role?: "admin" | "member";
+    role?: SettingsOrganizationRole;
 }
 interface SettingsOrganizationCurrent {
     id: string;
     name?: string;
     imageUrl?: string;
-    role?: "admin" | "member" | string;
+    role?: SettingsOrganizationRole | string;
+    /**
+     * Whether the viewer may invite into this organization.
+     *
+     * Orthogonal to `role`, not implied by it: a guest row can carry it too, so
+     * gate on `role !== "guest" && (role === "admin" || inviteAccess)`. The
+     * shorter `role === "admin" || inviteAccess` is the escalation the backend
+     * explicitly refuses.
+     */
+    inviteAccess?: boolean;
 }
 interface OrganizationMember {
     _id: string;
-    role: "admin" | "member";
+    role: SettingsOrganizationRole;
     inviteAccess: boolean;
     /** Populated user. Rows whose user document was deleted come back from the
      *  API with a null `user` — OrganizationContent drops those on fetch, so
@@ -357,9 +382,21 @@ interface SettingsOrganizationAdapter {
         role: "admin" | "member";
         inviteAccess?: boolean;
     }) => Promise<void>;
-    /** Optional: gates write affordances inside the Organization tab. */
+    /** Optional: gates write affordances inside the Organization tab. Can report
+     *  "guest", so callers must gate on `=== "admin"` rather than `!== "member"`. */
     getHighestRole?: () => Promise<{
-        role: "admin" | "member";
+        role: SettingsOrganizationRole;
+        /**
+         * The viewer's own email domain, and whether it can be claimed at all.
+         *
+         * A self-serve domain claim can only ever be the claimer's OWN domain —
+         * there is no DNS verification, so the backend refuses any other — which
+         * makes one boolean about one known domain the entire answer. Server
+         * computed on purpose: the disposable-domain lists it consults are
+         * provisioned at runtime, so no bundled list could agree with it.
+         */
+        emailDomain?: string | null;
+        canClaimEmailDomain?: boolean;
     }>;
     fetchWorkspaces: () => Promise<OrganizationWorkspaceItem[]>;
     fetchJoinRequests: () => Promise<OrganizationJoinRequest[]>;
@@ -675,7 +712,18 @@ interface SettingsApiAdapter {
     /** Send an invitation to `email` with the given permissions. */
     inviteMember: (input: {
         email: string;
-    } & MemberPermissionsPayload) => Promise<void>;
+    } & MemberPermissionsPayload & {
+        /**
+         * Standing in the workspace's ORGANIZATION, independent of `role`,
+         * which is the role inside the workspace. Omit for "no preference" —
+         * the backend then derives it from the invitee's email domain, which
+         * is what it has always done.
+         *
+         * Deliberately not on MemberPermissionsPayload: that type is shared
+         * with `updateMemberRole`, and org membership is not editable there.
+         */
+        organizationRole?: "member" | "guest";
+    }) => Promise<void>;
     /**
      * Canonical name for role updates. CXO's underlying service is named
      * `changeUserRole(workspaceId, payload)`; the adapter wraps that. Both
@@ -755,6 +803,18 @@ interface SettingsNavigationAdapter {
     getCheckoutReturnUrl?: (kind: "success" | "cancel") => string;
     /** Imperative navigate to another settings tab. */
     navigateToTab: (tab: SettingsTab) => void;
+    /**
+     * Go back to whatever the user was doing before they opened settings.
+     *
+     * Distinct from `close`: closing is "leave settings" and lands wherever the
+     * host decides settings' parent is; back is "the screen I came from", which
+     * only the history knows. Omit it and the shell calls
+     * `window.history.back()`, which is right in every host today — settings is
+     * a route, and the browser already knows where the user was. Supply it when
+     * your router keeps its own stack, or pass `onBack={null}` on
+     * `<SettingsContent>` to render no back control at all.
+     */
+    back?: () => void;
     /**
      * Leave settings entirely. Supplying this makes the shell render a close (×)
      * button and dismiss on Escape. Hosts that would rather pass a callback
@@ -880,8 +940,19 @@ interface SettingsContentProps {
      * no close affordance is rendered — that is the pre-0.3.8 behaviour.
      */
     onClose?: () => void;
+    /**
+     * Go back to the screen the user came from, rendered as a `← Back` control
+     * above the breadcrumb.
+     *
+     * Defaults to `adapters.navigation.back`, and to `window.history.back()`
+     * when neither is supplied — settings is a route in every host, so the
+     * browser already knows where the user was, and requiring a prop would mean
+     * the control appeared in whichever app remembered to pass one. Pass `null`
+     * to render no back control.
+     */
+    onBack?: (() => void) | null;
 }
-declare function SettingsContent({ adapters, activeTab, onClose, hiddenApps, }: SettingsContentProps): react.JSX.Element;
+declare function SettingsContent({ adapters, activeTab, onClose, onBack, hiddenApps, }: SettingsContentProps): react.JSX.Element;
 
 interface WorkspaceData {
     id: string;
@@ -1135,7 +1206,36 @@ interface OrganizationInviteModalProps {
     mode: ModalMode$1;
     /** Update mode: the target member's email (read-only display). */
     userEmail?: string;
+    /** admin/member only — the toggle below cannot express any other role, so
+     *  pass `lockRole` for a target whose role is outside that pair. */
     initialRole?: "admin" | "member";
+    /**
+     * Show the target's role read-only and disable Save, leaving Remove as the
+     * only action.
+     *
+     * For an organization guest: the toggle offers Admin and Member and nothing
+     * else, so opening it on a guest preselected "Member" and quietly promoted
+     * them the moment Save was pressed — even by an admin who came only to flip
+     * `inviteAccess`, which is itself the thing a guest must never hold. Removing
+     * a guest happens through this same modal, so refusing to open it was not an
+     * option.
+     */
+    lockRole?: boolean;
+    /**
+     * Whether the viewer's own email domain can be claimed at all. Defaults to
+     * true, preserving today's behaviour for any host that does not pass it.
+     *
+     * A domain claim can only ever be the claimer's OWN domain — there is no DNS
+     * verification, so the backend refuses any other — and a public provider
+     * like gmail.com can never be claimed by anybody. Offering the tab in that
+     * case advertises the one mechanism that would solve bulk onboarding and
+     * then fails after submit, which is worse than not offering it.
+     */
+    canClaimDomain?: boolean;
+    /** The viewer's own email domain: the only one they could ever claim. */
+    claimableDomain?: string | null;
+    /** Label for the read-only role shown when `lockRole` is set. */
+    lockedRoleLabel?: string;
     initialInviteAccess?: boolean;
     /** Lets a pending-invite row reopen this modal to resend without edits. */
     allowSubmitWithoutChanges?: boolean;
@@ -1156,7 +1256,7 @@ interface OrganizationInviteModalProps {
     }) => void;
     onRemove?: () => void;
 }
-declare function OrganizationInviteModal({ open, mode, userEmail, initialRole, initialInviteAccess, allowSubmitWithoutChanges, canRemove, onClose, onInviteEmail, onInviteDomain, onUpdate, onRemove, }: OrganizationInviteModalProps): react.JSX.Element | null;
+declare function OrganizationInviteModal({ open, mode, userEmail, initialRole, lockRole, canClaimDomain, claimableDomain, lockedRoleLabel, initialInviteAccess, allowSubmitWithoutChanges, canRemove, onClose, onInviteEmail, onInviteDomain, onUpdate, onRemove, }: OrganizationInviteModalProps): react.JSX.Element | null;
 
 interface ConfirmLeaveModalProps {
     open: boolean;
@@ -1191,6 +1291,12 @@ interface StoreOption {
     _id: string;
     name?: string;
 }
+/**
+ * Standing in the workspace's parent organization, as distinct from `role`,
+ * which is the role inside the workspace itself. The two are independent: an
+ * external collaborator is routinely a workspace admin and an org guest.
+ */
+type OrganizationStanding = "colleague" | "guest";
 interface InviteUpdateModalProps {
     open: boolean;
     mode: ModalMode;
@@ -1233,10 +1339,32 @@ interface InviteUpdateModalProps {
     onRemove?: () => void;
     /** Controls whether the Remove user button is enabled. Defaults to true. */
     canRemove?: boolean;
-    /** Called only in invite mode; receives (permissions, email) */
-    onInvite?: (permissions: UserPermissions, email: string) => void;
+    /**
+     * Offer the invitee an explicit standing in the workspace's parent
+     * organization.
+     *
+     * Omit it and nothing renders and nothing is submitted — the backend keeps
+     * deriving the standing from the invitee's email domain, which is today's
+     * behaviour. Pass it only when the workspace HAS an organization and the
+     * inviter may grant membership in it; showing the choice to someone who
+     * cannot grant it produces an invite the backend quietly downgrades.
+     */
+    showOrganizationStanding?: boolean;
+    /** Name of the parent organization, for the option copy. */
+    organizationName?: string;
+    /**
+     * Hide the Guest option. For an invitee whose email domain the organization
+     * already claims, guest is not expressible: the backend takes the higher of
+     * the requested and domain-derived roles, so choosing it would appear to
+     * work and change nothing.
+     */
+    allowGuestStanding?: boolean;
+    /** Defaults to "guest" — the least-privileged of the two. */
+    initialOrganizationStanding?: OrganizationStanding;
+    /** Called only in invite mode; receives (permissions, email, standing) */
+    onInvite?: (permissions: UserPermissions, email: string, organizationStanding?: OrganizationStanding) => void;
 }
-declare function InviteUpdateModal({ open, mode, userEmail, stores, hiddenApps, allowSubmitWithoutChanges, initialPermissions, onClose, onSave, onRemove, canRemove, onInvite, }: InviteUpdateModalProps): react.JSX.Element | null;
+declare function InviteUpdateModal({ open, mode, userEmail, stores, hiddenApps, allowSubmitWithoutChanges, initialPermissions, onClose, onSave, onRemove, canRemove, showOrganizationStanding, organizationName, allowGuestStanding, initialOrganizationStanding, onInvite, }: InviteUpdateModalProps): react.JSX.Element | null;
 
 interface ExportDateModalProps {
     title: string;

package/dist/index.d.ts

@@ -233,21 +233,46 @@ interface SettingsWorkspaceAdapter {
     /** Toggle this workspace's `orgVisibility` within its parent org. */
     setOrgVisibility?: (visibility: "private" | "shared") => Promise<void>;
 }
+/**
+ * An organization membership role.
+ *
+ * `guest` is an outsider who accepted an invite to a single workspace inside
+ * the organization. They hold a membership row — so they show up in these
+ * responses — but inherit nothing from the org: no implicit access to its
+ * shared workspaces, and every org-level write is refused by the backend.
+ *
+ * Gate write affordances on `=== "admin"`, never on `!== "member"`: a role this
+ * union does not yet name must read as least-privileged, not as an editor.
+ *
+ * Deliberately NOT applied to `autoJoinRole` or to workspace/team roles — a
+ * domain claim that auto-joins its own company as guests is a contradiction,
+ * and a workspace role of "guest" is not a value the backend accepts.
+ */
+type SettingsOrganizationRole = "admin" | "member" | "guest";
 interface SettingsOrganizationListItem {
     _id: string;
     name: string;
     imageUrl?: string;
-    role?: "admin" | "member";
+    role?: SettingsOrganizationRole;
 }
 interface SettingsOrganizationCurrent {
     id: string;
     name?: string;
     imageUrl?: string;
-    role?: "admin" | "member" | string;
+    role?: SettingsOrganizationRole | string;
+    /**
+     * Whether the viewer may invite into this organization.
+     *
+     * Orthogonal to `role`, not implied by it: a guest row can carry it too, so
+     * gate on `role !== "guest" && (role === "admin" || inviteAccess)`. The
+     * shorter `role === "admin" || inviteAccess` is the escalation the backend
+     * explicitly refuses.
+     */
+    inviteAccess?: boolean;
 }
 interface OrganizationMember {
     _id: string;
-    role: "admin" | "member";
+    role: SettingsOrganizationRole;
     inviteAccess: boolean;
     /** Populated user. Rows whose user document was deleted come back from the
      *  API with a null `user` — OrganizationContent drops those on fetch, so
@@ -357,9 +382,21 @@ interface SettingsOrganizationAdapter {
         role: "admin" | "member";
         inviteAccess?: boolean;
     }) => Promise<void>;
-    /** Optional: gates write affordances inside the Organization tab. */
+    /** Optional: gates write affordances inside the Organization tab. Can report
+     *  "guest", so callers must gate on `=== "admin"` rather than `!== "member"`. */
     getHighestRole?: () => Promise<{
-        role: "admin" | "member";
+        role: SettingsOrganizationRole;
+        /**
+         * The viewer's own email domain, and whether it can be claimed at all.
+         *
+         * A self-serve domain claim can only ever be the claimer's OWN domain —
+         * there is no DNS verification, so the backend refuses any other — which
+         * makes one boolean about one known domain the entire answer. Server
+         * computed on purpose: the disposable-domain lists it consults are
+         * provisioned at runtime, so no bundled list could agree with it.
+         */
+        emailDomain?: string | null;
+        canClaimEmailDomain?: boolean;
     }>;
     fetchWorkspaces: () => Promise<OrganizationWorkspaceItem[]>;
     fetchJoinRequests: () => Promise<OrganizationJoinRequest[]>;
@@ -675,7 +712,18 @@ interface SettingsApiAdapter {
     /** Send an invitation to `email` with the given permissions. */
     inviteMember: (input: {
         email: string;
-    } & MemberPermissionsPayload) => Promise<void>;
+    } & MemberPermissionsPayload & {
+        /**
+         * Standing in the workspace's ORGANIZATION, independent of `role`,
+         * which is the role inside the workspace. Omit for "no preference" —
+         * the backend then derives it from the invitee's email domain, which
+         * is what it has always done.
+         *
+         * Deliberately not on MemberPermissionsPayload: that type is shared
+         * with `updateMemberRole`, and org membership is not editable there.
+         */
+        organizationRole?: "member" | "guest";
+    }) => Promise<void>;
     /**
      * Canonical name for role updates. CXO's underlying service is named
      * `changeUserRole(workspaceId, payload)`; the adapter wraps that. Both
@@ -755,6 +803,18 @@ interface SettingsNavigationAdapter {
     getCheckoutReturnUrl?: (kind: "success" | "cancel") => string;
     /** Imperative navigate to another settings tab. */
     navigateToTab: (tab: SettingsTab) => void;
+    /**
+     * Go back to whatever the user was doing before they opened settings.
+     *
+     * Distinct from `close`: closing is "leave settings" and lands wherever the
+     * host decides settings' parent is; back is "the screen I came from", which
+     * only the history knows. Omit it and the shell calls
+     * `window.history.back()`, which is right in every host today — settings is
+     * a route, and the browser already knows where the user was. Supply it when
+     * your router keeps its own stack, or pass `onBack={null}` on
+     * `<SettingsContent>` to render no back control at all.
+     */
+    back?: () => void;
     /**
      * Leave settings entirely. Supplying this makes the shell render a close (×)
      * button and dismiss on Escape. Hosts that would rather pass a callback
@@ -880,8 +940,19 @@ interface SettingsContentProps {
      * no close affordance is rendered — that is the pre-0.3.8 behaviour.
      */
     onClose?: () => void;
+    /**
+     * Go back to the screen the user came from, rendered as a `← Back` control
+     * above the breadcrumb.
+     *
+     * Defaults to `adapters.navigation.back`, and to `window.history.back()`
+     * when neither is supplied — settings is a route in every host, so the
+     * browser already knows where the user was, and requiring a prop would mean
+     * the control appeared in whichever app remembered to pass one. Pass `null`
+     * to render no back control.
+     */
+    onBack?: (() => void) | null;
 }
-declare function SettingsContent({ adapters, activeTab, onClose, hiddenApps, }: SettingsContentProps): react.JSX.Element;
+declare function SettingsContent({ adapters, activeTab, onClose, onBack, hiddenApps, }: SettingsContentProps): react.JSX.Element;
 
 interface WorkspaceData {
     id: string;
@@ -1135,7 +1206,36 @@ interface OrganizationInviteModalProps {
     mode: ModalMode$1;
     /** Update mode: the target member's email (read-only display). */
     userEmail?: string;
+    /** admin/member only — the toggle below cannot express any other role, so
+     *  pass `lockRole` for a target whose role is outside that pair. */
     initialRole?: "admin" | "member";
+    /**
+     * Show the target's role read-only and disable Save, leaving Remove as the
+     * only action.
+     *
+     * For an organization guest: the toggle offers Admin and Member and nothing
+     * else, so opening it on a guest preselected "Member" and quietly promoted
+     * them the moment Save was pressed — even by an admin who came only to flip
+     * `inviteAccess`, which is itself the thing a guest must never hold. Removing
+     * a guest happens through this same modal, so refusing to open it was not an
+     * option.
+     */
+    lockRole?: boolean;
+    /**
+     * Whether the viewer's own email domain can be claimed at all. Defaults to
+     * true, preserving today's behaviour for any host that does not pass it.
+     *
+     * A domain claim can only ever be the claimer's OWN domain — there is no DNS
+     * verification, so the backend refuses any other — and a public provider
+     * like gmail.com can never be claimed by anybody. Offering the tab in that
+     * case advertises the one mechanism that would solve bulk onboarding and
+     * then fails after submit, which is worse than not offering it.
+     */
+    canClaimDomain?: boolean;
+    /** The viewer's own email domain: the only one they could ever claim. */
+    claimableDomain?: string | null;
+    /** Label for the read-only role shown when `lockRole` is set. */
+    lockedRoleLabel?: string;
     initialInviteAccess?: boolean;
     /** Lets a pending-invite row reopen this modal to resend without edits. */
     allowSubmitWithoutChanges?: boolean;
@@ -1156,7 +1256,7 @@ interface OrganizationInviteModalProps {
     }) => void;
     onRemove?: () => void;
 }
-declare function OrganizationInviteModal({ open, mode, userEmail, initialRole, initialInviteAccess, allowSubmitWithoutChanges, canRemove, onClose, onInviteEmail, onInviteDomain, onUpdate, onRemove, }: OrganizationInviteModalProps): react.JSX.Element | null;
+declare function OrganizationInviteModal({ open, mode, userEmail, initialRole, lockRole, canClaimDomain, claimableDomain, lockedRoleLabel, initialInviteAccess, allowSubmitWithoutChanges, canRemove, onClose, onInviteEmail, onInviteDomain, onUpdate, onRemove, }: OrganizationInviteModalProps): react.JSX.Element | null;
 
 interface ConfirmLeaveModalProps {
     open: boolean;
@@ -1191,6 +1291,12 @@ interface StoreOption {
     _id: string;
     name?: string;
 }
+/**
+ * Standing in the workspace's parent organization, as distinct from `role`,
+ * which is the role inside the workspace itself. The two are independent: an
+ * external collaborator is routinely a workspace admin and an org guest.
+ */
+type OrganizationStanding = "colleague" | "guest";
 interface InviteUpdateModalProps {
     open: boolean;
     mode: ModalMode;
@@ -1233,10 +1339,32 @@ interface InviteUpdateModalProps {
     onRemove?: () => void;
     /** Controls whether the Remove user button is enabled. Defaults to true. */
     canRemove?: boolean;
-    /** Called only in invite mode; receives (permissions, email) */
-    onInvite?: (permissions: UserPermissions, email: string) => void;
+    /**
+     * Offer the invitee an explicit standing in the workspace's parent
+     * organization.
+     *
+     * Omit it and nothing renders and nothing is submitted — the backend keeps
+     * deriving the standing from the invitee's email domain, which is today's
+     * behaviour. Pass it only when the workspace HAS an organization and the
+     * inviter may grant membership in it; showing the choice to someone who
+     * cannot grant it produces an invite the backend quietly downgrades.
+     */
+    showOrganizationStanding?: boolean;
+    /** Name of the parent organization, for the option copy. */
+    organizationName?: string;
+    /**
+     * Hide the Guest option. For an invitee whose email domain the organization
+     * already claims, guest is not expressible: the backend takes the higher of
+     * the requested and domain-derived roles, so choosing it would appear to
+     * work and change nothing.
+     */
+    allowGuestStanding?: boolean;
+    /** Defaults to "guest" — the least-privileged of the two. */
+    initialOrganizationStanding?: OrganizationStanding;
+    /** Called only in invite mode; receives (permissions, email, standing) */
+    onInvite?: (permissions: UserPermissions, email: string, organizationStanding?: OrganizationStanding) => void;
 }
-declare function InviteUpdateModal({ open, mode, userEmail, stores, hiddenApps, allowSubmitWithoutChanges, initialPermissions, onClose, onSave, onRemove, canRemove, onInvite, }: InviteUpdateModalProps): react.JSX.Element | null;
+declare function InviteUpdateModal({ open, mode, userEmail, stores, hiddenApps, allowSubmitWithoutChanges, initialPermissions, onClose, onSave, onRemove, canRemove, showOrganizationStanding, organizationName, allowGuestStanding, initialOrganizationStanding, onInvite, }: InviteUpdateModalProps): react.JSX.Element | null;
 
 interface ExportDateModalProps {
     title: string;