Migrate OrganizationService to StateProvider (#7895)

libs/common/src/admin-console/abstractions/organization/organization.service.abstraction.ts

@@ -2,6 +2,7 @@ import { map, Observable } from "rxjs";
 
 import { I18nService } from "../../../platform/abstractions/i18n.service";
 import { Utils } from "../../../platform/misc/utils";
+import { UserId } from "../../../types/guid";
 import { OrganizationData } from "../../models/data/organization.data";
 import { Organization } from "../../models/domain/organization";
 
@@ -86,34 +87,67 @@ export function canAccessImport(i18nService: I18nService) {
 
 /**
  * Returns `true` if a user is a member of an organization (rather than only being a ProviderUser)
- * @deprecated Use organizationService.memberOrganizations$ instead
+ * @deprecated Use organizationService.organizations$ with a filter instead
  */
 export function isMember(org: Organization): boolean {
   return org.isMember;
 }
 
+/**
+ * Publishes an observable stream of organizations. This service is meant to
+ * be used widely across Bitwarden as the primary way of fetching organizations.
+ * Risky operations like updates are isolated to the
+ * internal extension `InternalOrganizationServiceAbstraction`.
+ */
 export abstract class OrganizationService {
+  /**
+   * Publishes state for all organizations under the active user.
+   * @returns An observable list of organizations
+   */
   organizations$: Observable<Organization[]>;
 
-  /**
-   * Organizations that the user is a member of (excludes organizations that they only have access to via a provider)
-   */
+  // @todo Clean these up. Continuing to expand them is not recommended.
+  // @see https://bitwarden.atlassian.net/browse/AC-2252
   memberOrganizations$: Observable<Organization[]>;
-
-  get$: (id: string) => Observable<Organization | undefined>;
-  get: (id: string) => Organization;
-  getByIdentifier: (identifier: string) => Organization;
-  getAll: (userId?: string) => Promise<Organization[]>;
   /**
-   * @deprecated For the CLI only
-   * @param id id of the organization
+   * @deprecated This is currently only used in the CLI, and should not be
+   * used in any new calls. Use get$ instead for the time being, and we'll be
+   * removing this method soon. See Jira for details:
+   * https://bitwarden.atlassian.net/browse/AC-2252.
    */
   getFromState: (id: string) => Promise<Organization>;
   canManageSponsorships: () => Promise<boolean>;
-  hasOrganizations: () => boolean;
+  hasOrganizations: () => Promise<boolean>;
+  get$: (id: string) => Observable<Organization | undefined>;
+  get: (id: string) => Promise<Organization>;
+  getAll: (userId?: string) => Promise<Organization[]>;
+  //
 }
 
+/**
+ * Big scary buttons that **update** organization state. These should only be
+ * called from within admin-console scoped code. Extends the base
+ * `OrganizationService` for easy access to `get` calls.
+ * @internal
+ */
 export abstract class InternalOrganizationServiceAbstraction extends OrganizationService {
-  replace: (organizations: { [id: string]: OrganizationData }) => Promise<void>;
-  upsert: (OrganizationData: OrganizationData | OrganizationData[]) => Promise<void>;
+  /**
+   * Replaces state for the provided organization, or creates it if not found.
+   * @param organization The organization state being saved.
+   * @param userId The userId to replace state for. Defaults to the active
+   * user.
+   */
+  upsert: (OrganizationData: OrganizationData) => Promise<void>;
+
+  /**
+   * Replaces state for the entire registered organization list for the active user.
+   * You probably don't want this unless you're calling from a full sync
+   * operation or a logout. See `upsert` for creating & updating a single
+   * organization in the state.
+   * @param organizations A complete list of all organization state for the active
+   * user.
+   * @param userId The userId to replace state for. Defaults to the active
+   * user.
+   */
+  replace: (organizations: { [id: string]: OrganizationData }, userId?: UserId) => Promise<void>;
 }