prow-authority 3.6.3

package/src/v1/controllers/organizations/public-organization-controller.ts

@@ -0,0 +1,1796 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+import { Resource } from "@beseif-solutions/prow-authority-for-services";
+import { Date2, Formats } from "@beseif-solutions/utility-functions/dist/utils/date-utils";
+import { Requester } from "@beseif-solutions/utility-functions/dist/utils/http-utils";
+import { Where } from "@beseif-solutions/utility-functions/dist/utils/sql-utils";
+import { DeepPartial } from "@beseif-solutions/utility-functions/dist/utils/typing-utils";
+import { Schema, Validator } from "@beseif-solutions/utility-functions/dist/utils/validation-utils";
+import _ from "lodash";
+import Stripe from "stripe";
+import APIError, { StatusCodes } from "../../../helpers/api-error";
+import authority, { BillingChanged, LicenseDowngraded, LicenseDowngradeScheduled, LicenseLimitNames, LicenseUpgraded, MemberRemoved, NotificationEventNames, OrganizationAdded, OrganizationRemoved, PowerUpAdded, PowerUpRemoved, ResourceModelName } from "../../../helpers/authority";
+import nconf from "../../../helpers/config";
+import holded, { Holded } from "../../../helpers/holded";
+import stripe from "../../../helpers/stripe";
+import { informationResponseSchema } from "../../schemas/admin/service-schemas";
+import { activateLicenseSchema, activatePowerUpSchema, addPaymentMethodSchema, createOrganizationSchema, licenseParamsSchema, updateOrganizationSchema, updatePaymentMethodSchema } from "../../schemas/organizations/public-organization-schemas";
+import { changeOwnershipSchema, inviteUserSchema, updateUserAccessSchema, updateUserOrganizationSchema } from "../../schemas/users/public-user-schemas";
+import { BillingCycle } from "../../types/admin/billing-cycle-types";
+import { Invoice } from "../../types/admin/invoice-types";
+import { License, LicenseType, Prices } from "../../types/admin/license-types";
+import { OrganizationLicense } from "../../types/admin/organization-license-types";
+import { Organization, OrganizationStatus, ServiceInformation } from "../../types/admin/organization-types";
+import { PaymentMethod, PaymentMethodType } from "../../types/admin/payment-method-types";
+import { UserOrganization, UserOrganizationRole } from "../../types/admin/user-organization-types";
+import { User, UserStatus } from "../../types/admin/user-types";
+import { Environment } from "../../types/auth/organization-token-types";
+import { ActivateLicense, ActivatePowerUp, AddPaymentMethod, InviteUser, LicenseParams, PublicInvoice, PublicOrganization, PublicOrganizationLicense, PublicOrganizationUser, PublicPaymentMethod, UpdatePaymentMethod, UpdateUserAccess, UpdateUserOrganization } from "../../types/organizations/public-organization-types";
+import { PublicService, PublicServiceInformation } from "../../types/services/public-service-types";
+import { Quota, QuotaParams, ServiceEnvironment } from "../../types/services/service-types";
+import billingCycleController from "../admin/billing-cycle-controller";
+import invoiceController from "../admin/invoice-controller";
+import licenseController from "../admin/license-controller";
+import licenseLimitController from "../admin/license-limit-controller";
+import notificationController from "../admin/notification-controller";
+import organizationController from "../admin/organization-controller";
+import organizationLicenseController from "../admin/organization-license-controller";
+import organizationLicenseLimitController from "../admin/organization-license-limit-controller";
+import paymentMethodController from "../admin/payment-method-controller";
+import adminServiceController from "../admin/service-controller";
+import userController from "../admin/user-controller";
+import userOrganizationController from "../admin/user-organization-controller";
+import billingController from "../billing/billing-controller";
+import publicServiceController from "../services/public-service-controller";
+import serviceController from "../services/service-controller";
+import publicUserController from "../users/public-user-controller";
+
+const { getCountry } = require(`country-list-spanish`);
+const { getName } = require(`country-list`);
+
+type Create = Omit<PublicOrganization, `uuid` | `status` | `created_date` | `modified_date`>;
+type Update = DeepPartial<Omit<PublicOrganization, `uuid` | `status` | `created_date` | `modified_date`>>;
+
+class PublicOrganizationCtrl {
+
+  // authority endpoint: organization resources
+  public readonly authority = async (organizationUUID: string): Promise<Resource<ResourceModelName>[]> => {
+    try {
+      const organization = (await organizationController.list({ uuid: organizationUUID }))[0];
+      if (!organization) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `Organization ${organizationUUID} not found.`,
+        });
+      }
+
+      const [seats] = await Promise.all([
+        userOrganizationController.list({ organization: organization.id }),
+      ]);
+
+      const response: Resource<ResourceModelName>[] = [
+        {
+          type: `owner`,
+          model: `organization.seat`,
+          count: seats.length,
+        },
+      ];
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly getInformation = async (env: Environment): Promise<PublicServiceInformation[]> => {
+    try {
+      const services = await adminServiceController.list({ enabled: true });
+
+      const response: PublicServiceInformation[] = _.compact(await Promise.all(services.map(async (service) => {
+        try {
+          let information: any[] = [];
+          if (service.internal.host && service.internal.organization?.information) {
+            information = await Requester.get(`${service.internal.organization?.information}/${env.organization.uuid}`, {
+              baseURL: service.internal.host,
+              headers: {
+                "x-service-uuid": service.uuid,
+                "x-service-token": service.token,
+              },
+            });
+            Validator.validate(informationResponseSchema, information);
+          }
+
+          return {
+            service: (await publicServiceController.parseServices([service]))[0],
+            information: information,
+          };
+        } catch (e) { return null; }
+      })));
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  private readonly deleteInformation = async (env: Environment): Promise<void> => {
+    try {
+      const services = await adminServiceController.list({ enabled: true });
+
+      await Promise.all(services.map(async (service) => {
+        try {
+          if (service.internal.host && service.internal.organization?.deleted) {
+            await Requester.delete(`${service.internal.organization.deleted}/${env.organization.uuid}`, {
+              baseURL: service.internal.host,
+              headers: {
+                "x-service-uuid": service.uuid,
+                "x-service-token": service.token,
+              },
+            });
+          }
+        } catch (e) {
+          // TODO: what to do when error?
+        }
+      }));
+    } catch (e) { throw e; }
+  };
+
+  public readonly create = async (user: User, data: Create): Promise<PublicOrganization> => {
+    let organization: Organization;
+    try {
+      Validator.validate(createOrganizationSchema, data);
+
+      // create organization
+      organization = (await organizationController.add({
+        ...data,
+        status: OrganizationStatus.Active,
+        internal: {
+          services: {},
+        },
+      }, { timestamp: true }))[0];
+
+      // get base license
+      const service = (await adminServiceController.list({ uuid: authority.configuration.uuid }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not find service.`,
+        });
+      }
+
+      const base = (await licenseController.list({
+        service: service.id,
+        type: LicenseType.Base,
+        enabled: true,
+      }))[0];
+      if (!base) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not find base license.`,
+        });
+      }
+
+      // assign base license
+      await this.configureLicense(organization, base, {
+        billing: `lifetime`, // set lifetime until billing is configured
+        start_date: Date2.current(),
+        internal: {},
+      });
+
+      // add organization owner
+      await userOrganizationController.add({
+        organization: organization.id,
+        user: user.id,
+        role: UserOrganizationRole.Owner,
+        invited_by: null,
+        invite: null,
+        enabled: true,
+        metadata: {},
+      });
+
+      // update quota usage
+      await authority.register(organization.uuid, {
+        name: LicenseLimitNames.Seats,
+        count: +1,
+      });
+
+      await authority.notify<OrganizationAdded>(organization.uuid, {
+        event: NotificationEventNames.OrganizationAdded,
+        data: {
+          cta: {
+            dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:DASHBOARD`),
+            preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+          },
+          organization: organization,
+        },
+      });
+
+      return (await publicOrganizationController.parse(null, [organization]))[0];
+    } catch (e) {
+      if (organization) { await organizationController.delete(organization.id); }
+      throw e;
+    }
+  };
+
+  public readonly get = async (env: Environment): Promise<PublicOrganization> => {
+    try {
+      const organization = (await organizationController.get(env.organization.id, { timestamp: true }))[0];
+      const [response] = await this.parse(env, [organization]);
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly update = async (env: Environment, data: Update): Promise<PublicOrganization> => {
+    try {
+      Validator.validate(updateOrganizationSchema, data);
+      const updated = (await organizationController.update(env.organization.id, data, { timestamp: true }))[0];
+
+      if (!_.isEqual(env.organization.billing, updated.billing) && updated.billing?.document) {
+        // update customer
+        await Promise.all([
+          this.configureStripeCustomer(updated),
+          this.configureHoldedContact(updated),
+        ]);
+      }
+
+      const [response] = await this.parse(env, [updated]);
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly delete = async (env: Environment, force: boolean): Promise<void> => {
+    try {
+      const ownService = (await adminServiceController.list({ uuid: authority.configuration.uuid }))[0];
+      if (!ownService) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not find base service.`,
+        });
+      }
+
+      const activeLicenses = await organizationLicenseController.list({
+        organization: env.organization.id,
+        enabled: true,
+        service: { is: ownService.id, inverse: true },
+      });
+
+      if (activeLicenses.filter((l) => l.end_date === null && l.type === LicenseType.Base).length > 0 && !force) {
+        throw new APIError({
+          code: StatusCodes.CONFLICT,
+          detail: `Organization has active licenses.`,
+        });
+      }
+
+      await authority.notify<OrganizationRemoved>(env.organization.uuid, {
+        event: NotificationEventNames.OrganizationRemoved,
+        data: {
+          cta: {
+            dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_DASHBOARD`),
+            preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+          },
+          organization: env.organization,
+        },
+      });
+
+      const deleteDate = Date2.current().format(Formats.ISO);
+
+      // end all organization licenses
+      await organizationLicenseController.update(env.license.id, { end_date: deleteDate });
+      for (const license of activeLicenses) {
+        await organizationLicenseController.update(license.id, { end_date: deleteDate });
+      }
+
+      // TODO: last payment?
+
+      // remove accesses
+      const accesses = await userOrganizationController.list({ organization: env.organization.id });
+      for (const access of accesses) { await userOrganizationController.delete(access.id); }
+
+      // mark organization as deleted
+      await organizationController.update(env.organization.id, {
+        status: `deleted` as any,
+        internal: { deleted_date: deleteDate },
+      }, { deletion: true });
+
+      // TODO: schedule the deletion of the organization
+      // await this.deleteInformation(env);
+    } catch (e) {
+      console.log(e);
+      throw e;
+    }
+  };
+
+  public readonly getServiceLicenses = async (env: Environment, serviceUUID: string, params: LicenseParams = {}): Promise<PublicOrganizationLicense[]> => {
+    try {
+      Validator.validate(licenseParamsSchema, params);
+
+      return this.getLicenses(env, serviceUUID, {
+        type: LicenseType.Base,
+        ...params.enabled ? { enabled: params.enabled === `true` } : {},
+      });
+    } catch (e) { throw e; }
+  };
+
+  public readonly activateServiceLicense = async (env: Environment, serviceUUID: string, data: ActivateLicense): Promise<PublicOrganizationLicense[]> => {
+    let organizationLicense: OrganizationLicense;
+    try {
+      Validator.validate(activateLicenseSchema, data);
+
+      const context = await this.licenseActivationContext(env, serviceUUID, { ...data, type: LicenseType.Base });
+
+      const isBillable = await billingController.isBillable(env.organization);
+      if ((context.cycle.trial && data.renew && !isBillable)
+        || (!context.cycle.trial && !isBillable)) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Organization must configure billing and payment before doing this action.`,
+        });
+      }
+
+      let startDate: Date2;
+      let endDate: Date2;
+
+      const now = Date2.current();
+
+      if (context.enabled) {
+        // determine immediate or end of cycle change
+        const key: keyof Prices = context.enabled.billing === `monthly` ? `monthly_price` : `annual_price`;
+        const immediateChange =
+          // upgrade (and not scheduled)
+          ((context.license[key] >= context.enabled[key]) && !data.scheduled)
+          // trial period license change
+          || (context.cycle.trial);
+
+        if (context.future) {
+          // override previously selected future license
+          await organizationLicenseController.delete(context.future.id);
+        }
+
+        if (!context.enabled.end_date || immediateChange) {
+          context.enabled = (await organizationLicenseController.update(context.enabled.id, {
+            end_date: immediateChange ? now.format(Formats.ISO) : context.cycle.end_date,
+          }))[0];
+        }
+
+        // start future license when the enabled license ends
+        startDate = new Date2(context.enabled.end_date, Formats.ISO);
+      } else {
+        // start license now
+        startDate = now;
+      }
+
+      if (context.enabled && context.cycle.trial) {
+        // end trial when license change
+        context.cycle = await this.internal_endTrial(env, context.cycle, now);
+      }
+
+      if (!data.renew) { endDate = new Date2(context.cycle.end_date, Formats.ISO); }
+
+      const liveNotification = startDate.isEqual(now);
+
+      organizationLicense = await this.configureLicense(env.organization, context.license, {
+        billing: data.billing,
+        start_date: startDate,
+        end_date: endDate,
+        metadata: data.metadata,
+        // flag notification for later if not live
+        internal: liveNotification ? {} : { notified: false },
+      });
+
+      // notify license activation on live
+      if (liveNotification) {
+        if (context.setup && context.service.internal.host && context.service.internal.organization?.created) {
+          // setup organization on service
+          setImmediate(async () => {
+            try {
+              await Requester.post(`${context.service.internal.organization?.created}`,
+                (await this.parse(env, [env.organization]))[0],
+                {
+                  baseURL: context.service.internal.host,
+                  headers: {
+                    "x-service-uuid": context.service.uuid,
+                    "x-service-token": context.service.token,
+                  },
+                });
+            } catch {  /* TODO: what to do if the organization setup fails on service? */ }
+          });
+        } else if (context.service.internal.host && context.service.internal.organization?.modified) {
+          // update organization setup on service
+          setImmediate(async () => {
+            try {
+              await Requester.patch(`${context.service.internal.organization?.modified}/${env.organization.uuid}`,
+                null,
+                {
+                  baseURL: context.service.internal.host,
+                  headers: {
+                    "x-service-uuid": context.service.uuid,
+                    "x-service-token": context.service.token,
+                  },
+                });
+            } catch { /* TODO: what to do if the organization setup fails on service? */ }
+          });
+        }
+
+        // notify license upgrade or downgrade when changing from one license to another
+        if (context.enabled) {
+          setImmediate(async () => {
+            try {
+              const key: keyof Prices = context.enabled.billing === `monthly` ? `monthly_price` : `annual_price`;
+              const downgrade = context.license[key] < context.enabled[key];
+
+              if (downgrade) {
+                await authority.notify<LicenseDowngraded>(env.organization.uuid, {
+                  event: NotificationEventNames.LicenseDowngraded,
+                  data: {
+                    cta: {
+                      dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_DASHBOARD`),
+                      preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+                    },
+                    organization: env.organization,
+                  },
+                });
+              } else {
+                await authority.notify<LicenseUpgraded>(env.organization.uuid, {
+                  event: NotificationEventNames.LicenseUpgraded,
+                  data: {
+                    cta: {
+                      dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_DASHBOARD`),
+                      preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+                    },
+                    organization: env.organization,
+                  },
+                });
+              }
+            } catch { }
+          });
+        }
+      } else if (context.enabled) {
+        // scheduled change at end of current cycle: notify only on downgrade
+        setImmediate(async () => {
+          try {
+            const key = context.enabled.billing === `monthly` ? `monthly_price` : `annual_price`;
+            const downgrade = context.license[key] < context.enabled[key];
+
+            if (downgrade) {
+              await authority.notify<LicenseDowngradeScheduled>(env.organization.uuid, {
+                event: NotificationEventNames.LicenseDowngradeScheduled,
+                data: {
+                  organization: env.organization,
+                  scheduled_date: startDate.format(Formats.ReadableFormat),
+                  cta: {
+                    subscription: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_USAGE`),
+                    preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+                  },
+                },
+              });
+            }
+          } catch { }
+        });
+      }
+
+      setImmediate(async () => {
+        try {
+          // generate invoice once license is activated
+          await billingController.generateLicensesInvoice(env.organization);
+        } catch { }
+      });
+
+      return await this.getServiceLicenses(env, serviceUUID);
+    } catch (e) {
+      if (organizationLicense) { await organizationLicenseController.delete(organizationLicense.id); }
+      throw e;
+    }
+  };
+
+  public readonly renewServiceLicense = async (env: Environment, serviceUUID: string, licenseUUID: string): Promise<PublicOrganizationLicense> => {
+    try {
+      if (!await billingController.isBillable(env.organization)) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Organization must configure billing and payment before doing this action.`,
+        });
+      }
+
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      let license = (await organizationLicenseController.list({
+        uuid: licenseUUID,
+        organization: env.organization.id,
+        service: service.id,
+        type: LicenseType.Base,
+        enabled: true,
+      }))[0];
+      if (!license) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `No license ${licenseUUID} found.`,
+        });
+      }
+
+      if (license.end_date) {
+        license = (await organizationLicenseController.update(license.id, { end_date: null }))[0];
+      }
+
+      return (await this.parseLicenses(env.organization, [license]))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly cancelServiceLicense = async (env: Environment, serviceUUID: string, licenseUUID: string): Promise<PublicOrganizationLicense | void> => {
+    try {
+      return await this.cancelLicense(env, serviceUUID, licenseUUID, LicenseType.Base);
+    } catch (e) { throw e; }
+  };
+
+  public readonly activateServicePowerUp = async (env: Environment, serviceUUID: string, data: ActivatePowerUp): Promise<PublicOrganizationLicense[]> => {
+    let organizationLicense: OrganizationLicense;
+    try {
+      Validator.validate(activatePowerUpSchema, data);
+
+      const context = await this.licenseActivationContext(env, serviceUUID, { ...data, type: LicenseType.Variant });
+
+      if (context.cycle.trial) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Cannot activate power-up during trial period.`,
+        });
+      }
+
+      if (!await billingController.isBillable(env.organization)) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Organization must configure billing and payment before doing this action.`,
+        });
+      }
+
+      let endDate: Date2;
+      if (!data.renew) { endDate = new Date2(context.cycle.end_date, Formats.ISO); }
+
+      organizationLicense = await this.configureLicense(env.organization, context.license, {
+        billing: data.billing,
+        start_date: Date2.current(),
+        end_date: endDate,
+        metadata: data.metadata,
+        internal: {},
+      });
+
+      setImmediate(async () => {
+        try {
+          await authority.notify<PowerUpAdded>(env.organization.uuid, {
+            event: NotificationEventNames.PowerUpAdded,
+            data: {
+              cta: {
+                dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_DASHBOARD`),
+                preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+              },
+              organization: env.organization,
+            },
+          });
+        } catch { }
+      });
+
+      setImmediate(async () => {
+        try {
+          // generate invoice once license is activated
+          await billingController.generateLicensesInvoice(env.organization);
+        } catch { }
+      });
+
+      return await this.getLicenses(env, serviceUUID, { id: organizationLicense.id });
+    } catch (e) {
+      if (organizationLicense) { await organizationLicenseController.delete(organizationLicense.id); }
+      throw e;
+    }
+  };
+
+  public readonly getServicePowerUps = async (env: Environment, serviceUUID: string, params: LicenseParams = {}): Promise<PublicOrganizationLicense[]> => {
+    try {
+      Validator.validate(licenseParamsSchema, params);
+
+      return this.getLicenses(env, serviceUUID, {
+        type: LicenseType.Variant,
+        ...params.enabled ? { enabled: params.enabled === `true` } : {},
+      });
+    } catch (e) { throw e; }
+  };
+
+  public readonly cancelServicePowerUp = async (env: Environment, serviceUUID: string, licenseUUID: string): Promise<PublicOrganizationLicense | void> => {
+    try {
+      return await this.cancelLicense(env, serviceUUID, licenseUUID, LicenseType.Variant);
+    } catch (e) { throw e; }
+  };
+
+  public readonly endTrial = async (env: Environment): Promise<void> => {
+    try {
+      const { cycle, now } = await billingController.cycleContext(env.organization);
+      if (!cycle.trial) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No active trial.`,
+        });
+      }
+
+      if (!await billingController.isBillable(env.organization)) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Organization must configure billing and payment before ending trial.`,
+        });
+      }
+
+      await this.internal_endTrial(env, cycle, now);
+
+      setImmediate(async () => {
+        try {
+          // generate invoice once trial ends
+          await billingController.generateLicensesInvoice(env.organization);
+        } catch { }
+      });
+    } catch (e) { throw e; }
+  };
+
+  private readonly internal_endTrial = async (env: Environment, cycle: BillingCycle, now: Date2): Promise<BillingCycle> => {
+    try {
+      // end trial cycle and suppress trial_ended notification: trial ended by upgrade, not by expiration
+      await billingCycleController.update(cycle.id, {
+        end_date: now.format(Formats.ISO),
+        internal: { trial_ended_sent: true },
+      });
+
+      // start a new one
+      const { cycle: newCycle } = await billingController.cycleContext(env.organization, now.format(Formats.ISO));
+      return newCycle;
+    } catch (e) { throw e; }
+  };
+
+  public readonly getServices = async (env: Environment): Promise<(PublicService & { blocked: boolean })[]> => {
+    try {
+      const enabledLicenses = await organizationLicenseController.list({
+        organization: env.organization.id,
+        enabled: true,
+      });
+
+      const services = await adminServiceController.list({ id: { in: _.uniq(enabledLicenses.map((el) => el.service)) }, enabled: true });
+      return (await publicServiceController.parseServices(services))
+        .map((ps) => {
+          const information: ServiceInformation = _.get(env.organization.internal, `services.${ps.uuid}`);
+          return {
+            ...ps,
+            blocked: information?.blocked || false,
+          };
+        });
+    } catch (e) { throw e; }
+  };
+
+  public readonly getServiceQuota = async (env: Environment, serviceUUID: string, params: QuotaParams): Promise<Quota[]> => {
+    try {
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      const enabledLicenses = await organizationLicenseController.list({
+        organization: env.organization.id,
+        service: service.id,
+        enabled: true,
+      });
+
+      if (enabledLicenses.length === 0) { return []; }
+
+      return await serviceController.getQuota({
+        organization: env.organization,
+        service: service,
+        licenses: enabledLicenses,
+      }, params);
+    } catch (e) { throw e; }
+  };
+
+  public readonly checkServiceQuota = async (env: Environment, serviceUUID: string): Promise<Quota[]> => {
+    try {
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      const enabledLicenses = await organizationLicenseController.list({
+        organization: env.organization.id,
+        service: service.id,
+        enabled: true,
+      });
+
+      if (enabledLicenses.length === 0) { return []; }
+
+      const sEnv: ServiceEnvironment = {
+        organization: env.organization,
+        service: service,
+        licenses: enabledLicenses,
+      };
+
+      await serviceController.checkQuota(sEnv);
+
+      return await serviceController.getQuota(sEnv, {});
+    } catch (e) { throw e; }
+  };
+
+  public readonly updateOverconsume = async (env: Environment, serviceUUID: string, body: { limit: string, overconsume: boolean }): Promise<PublicOrganizationLicense[]> => {
+    try {
+      Validator.validate(Schema.object({
+        limit: Schema.requiredString(),
+        overconsume: Schema.requiredBool(),
+      }), body);
+
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      const enabledLicenses = await organizationLicenseController.list({
+        organization: env.organization.id,
+        service: service.id,
+        enabled: true,
+      });
+
+      const limits = (await organizationLicenseLimitController.list({
+        organization: env.organization.id,
+        license: { in: enabledLicenses.map((l) => l.id) },
+        name: body.limit,
+      })).filter((ll) => ll.overconsume_annual_price_per_unit !== null || ll.overconsume_monthly_price_per_unit !== null);
+
+      if (limits.length === 0) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Limit ${body.limit} can't be configured to overconsume.`,
+        });
+      } else if (limits.length > 1) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Unexpected error: multiple limits found. Please contact support.`,
+        });
+      }
+
+      const limit = limits[0];
+      await organizationLicenseLimitController.update(limit.id, {
+        overconsume: body.overconsume,
+      });
+
+      const response = enabledLicenses.find((l) => l.id === limit.license);
+      return await this.parseLicenses(env.organization, [response]);
+    } catch (e) { throw e; }
+  };
+
+  public readonly getMe = async (env: Environment): Promise<PublicOrganizationUser> => {
+    try {
+      const response = (await this.parseOrganizationUsers([env.access], {
+        userCache: [env.user],
+        preferences: true,
+      }))[0];
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly updateMe = async (env: Environment, data: UpdateUserOrganization): Promise<PublicOrganizationUser> => {
+    try {
+      Validator.validate(updateUserOrganizationSchema, data);
+
+      // omnipotent accesses are synthetic: can't be updated
+      if (env.user.omnipotent) { throw new Error(`Omnipotent user access can't be updated.`); }
+
+      const { access } = await this.getUserAndAccess(env, env.user.uuid);
+      const updated = await userOrganizationController.update(access.id, data);
+      return (await this.parseOrganizationUsers(updated, { preferences: true }))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly getOwner = async (env: Environment): Promise<PublicOrganizationUser> => {
+    try {
+      if (env.access.role === UserOrganizationRole.Owner && !env.user.omnipotent) { return await this.getMe(env); }
+
+      const owner = (await userOrganizationController.list({
+        organization: env.organization.id,
+        role: UserOrganizationRole.Owner,
+      }))[0];
+      if (!owner) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not find organization owner.`,
+        });
+      }
+
+      return (await this.parseOrganizationUsers([owner]))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly getUsers = async (env: Environment, options: { all: boolean }): Promise<PublicOrganizationUser[]> => {
+    try {
+      const accesses = await userOrganizationController.list({
+        organization: env.organization.id,
+        ...(!options.all ? { invite: { is: null } } : {}),
+      });
+
+      return await this.parseOrganizationUsers(accesses);
+    } catch (e) { throw e; }
+  };
+
+  public readonly inviteUser = async (env: Environment, data: InviteUser): Promise<PublicOrganizationUser> => {
+    try {
+      Validator.validate(inviteUserSchema, data);
+
+      let user = (await userController.list({ email: data.email }, { password: false }))[0];
+
+      if (!user) {
+        // create user
+        user = (await userController.add({ email: data.email }, { password: false }))[0];
+      }
+
+      if (user.omnipotent) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not complete your request.`,
+        });
+      }
+
+      const exists = (await userOrganizationController.list({
+        organization: env.organization.id,
+        user: user.id,
+      }))[0];
+      if (exists) {
+        throw new APIError({
+          code: StatusCodes.CONFLICT,
+          detail: `User is already on organization.`,
+        });
+      }
+
+      const invite = await userOrganizationController.getFreeInvite(env.organization.id);
+      const access = await userOrganizationController.add({
+        user: user.id,
+        organization: env.organization.id,
+        role: data.role,
+        invite: invite,
+        invited_by: env.user.id,
+        enabled: data.enabled,
+        metadata: data.metadata,
+        preferences: {},
+      });
+
+      await authority.register(env.organization.uuid, {
+        name: LicenseLimitNames.Seats,
+        count: +1,
+      });
+
+      await this.sendInvitation(env, user.uuid);
+
+      return (await this.parseOrganizationUsers(access))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly sendInvitation = async (env: Environment, userUUID: string): Promise<void> => {
+    try {
+      const { user, access } = await this.getUserAndAccess(env, userUUID);
+      if (!access.invite) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `User doesn't have a pending invite.`,
+        });
+      }
+
+      await notificationController.invitation(user, access, env.organization);
+    } catch (e) { throw e; }
+  };
+
+  public readonly updateUser = async (env: Environment, userUUID: string, data: UpdateUserAccess): Promise<PublicOrganizationUser> => {
+    try {
+      Validator.validate(updateUserAccessSchema, data);
+      const { access } = await this.getUserAndAccess(env, userUUID);
+
+      if (access.role === UserOrganizationRole.Owner) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Owner's access can't be edited.`,
+        });
+      }
+
+      const updated = await userOrganizationController.update(access.id, data);
+      return (await this.parseOrganizationUsers(updated))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly deleteUser = async (env: Environment, userUUID: string): Promise<void> => {
+    try {
+      const { user, access } = await this.getUserAndAccess(env, userUUID);
+
+      if (access.role === UserOrganizationRole.Owner) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Owner's access can't be deleted.`,
+        });
+      }
+
+      const { deleted } = await userOrganizationController.delete(access.id);
+      if (!deleted) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not delete user access to organization.`,
+        });
+      }
+
+      await authority.register(env.organization.uuid, {
+        name: LicenseLimitNames.Seats,
+        count: -1,
+      });
+
+      await authority.notify<MemberRemoved>(env.organization.uuid, {
+        event: NotificationEventNames.MemberRemoved,
+        data: {
+          user: user,
+          organization: env.organization,
+          cta: {
+            members: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_MEMBERS`),
+            preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+          },
+        },
+      });
+    } catch (e) { throw e; }
+  };
+
+  public readonly ownership = async (env: Environment, data: { user: string }): Promise<void> => {
+    try {
+      Validator.validate(changeOwnershipSchema, data);
+
+      const { access } = await this.getUserAndAccess(env, data.user);
+
+      if (access.invite) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `User has a pending invite and can't be owner.`,
+        });
+      }
+
+      if (access.role !== UserOrganizationRole.Owner) {
+        await userOrganizationController.update(env.access.id, { role: UserOrganizationRole.Admin });
+        await userOrganizationController.update(access.id, { role: UserOrganizationRole.Owner });
+      }
+    } catch (e) { throw e; }
+  };
+
+  public readonly parse = async (env: Environment, records: Organization[]): Promise<PublicOrganization[]> => {
+    try {
+      const response: PublicOrganization[] = [];
+
+      for (const record of records) {
+        const p: PublicOrganization = {
+          uuid: record.uuid,
+          properties: record.properties,
+          preferences: record.preferences,
+          billing: record.billing,
+          created_date: new Date2(record.created_date).format(Formats.ISO),
+          modified_date: new Date2(record.modified_date).format(Formats.ISO),
+          status: record.status,
+          metadata: record.metadata,
+        };
+
+        if (!env || env.access.role === UserOrganizationRole.Staff) {
+          delete p.billing;
+        }
+
+        response.push(p);
+      }
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly parseOrganizationUsers = async (records: UserOrganization[], options: { userCache?: User[], preferences?: boolean } = {}): Promise<PublicOrganizationUser[]> => {
+    try {
+      const missingUserIDs = _.compact(
+        _.uniq(records
+          .filter((access) => !(options.userCache || []).some((u) => u.id === access.user || u.id === access.invited_by))
+          .map((r) => [r.user, r.invited_by])
+          .flat()));
+      const users = [
+        ...options.userCache || [],
+        ...missingUserIDs.length ? await userController.list({ id: { in: missingUserIDs } }, { password: false, timestamp: true }) : [],
+      ];
+
+      const response: PublicOrganizationUser[] = [];
+      for (const record of records) {
+        const accessUser = users.find((u) => u.id === record.user);
+        if (!accessUser) { continue; }
+
+        response.push({
+          user: (await publicUserController.parseUser([accessUser]))[0],
+          access: (await publicUserController.parseAccess([record], {
+            userCache: users,
+            preferences: options.preferences,
+          }))[0],
+        });
+      }
+
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly parseLicenses = async (organization: Organization, records: OrganizationLicense[]): Promise<PublicOrganizationLicense[]> => {
+    try {
+      let cycle: BillingCycle;
+      try {
+        const context = await billingController.cycleContext(organization);
+        cycle = context.cycle;
+      } catch { }
+
+      const [services, limits, associatedLicenses] = await Promise.all([
+        adminServiceController.list({ id: { in: records.map((r) => r.service) } }),
+        organizationLicenseLimitController.list({ license: { in: records.map((l) => l.id) } }),
+        organizationLicenseController.list({ id: { in: _.compact(records.map((r) => r.associated)) } }),
+      ]);
+
+      const response: PublicOrganizationLicense[] = [];
+      for (const record of records) {
+        const service = services.find((s) => s.id === record.service);
+        if (!service) { continue; }
+
+        const licenseLimits = limits.filter((l) => l.license === record.id);
+
+        response.push({
+          uuid: record.uuid,
+          service: (await publicServiceController.parseServices([service]))[0],
+          type: record.type,
+          associated: record.associated ?
+            associatedLicenses.find((l) => l.id === record.associated)?.uuid || null
+            : null,
+          billing: record.billing,
+          properties: record.properties,
+          data: record.data,
+          annual_price: record.annual_price,
+          monthly_price: record.monthly_price,
+          limits: licenseLimits.map((ll) => ({
+            name: ll.name,
+            limit: ll.limit,
+            period: ll.period,
+            monthly_price_abs: ll.monthly_price_abs,
+            annual_price_abs: ll.annual_price_abs,
+            overconsume: ll.overconsume,
+            overconsume_monthly_price_per_unit: ll.overconsume_monthly_price_per_unit,
+            overconsume_annual_price_per_unit: ll.overconsume_annual_price_per_unit,
+            metadata: ll.metadata,
+          })),
+          start_date: record.start_date,
+          ...cycle ? {
+            current_billing_start_date: cycle.start_date,
+            current_billing_end_date: cycle.end_date,
+            current_billing_trial: cycle.trial,
+          } : {
+            current_billing_start_date: null,
+            current_billing_end_date: null,
+            current_billing_trial: false,
+          },
+          end_date: record.end_date,
+          enabled: record.enabled,
+          metadata: record.metadata,
+        });
+      }
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly parsePaymentMethods = async (env: Environment, records: PaymentMethod[]): Promise<PublicPaymentMethod[]> => {
+    try {
+      const response: PublicPaymentMethod[] = [];
+
+      for (const record of records) {
+        const p: PublicPaymentMethod = {
+          uuid: record.uuid,
+          type: record.type,
+          properties: {
+            name: record.properties.name,
+            alias: record.properties.alias,
+            brand: record.properties.brand,
+            country: record.properties.country,
+            exp_year: record.properties.exp_year,
+            exp_month: record.properties.exp_month,
+          },
+          created_date: new Date2(record.created_date).format(Formats.ISO),
+          modified_date: new Date2(record.modified_date).format(Formats.ISO),
+          enabled: record.enabled,
+          metadata: record.metadata,
+        };
+        response.push(p);
+      }
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly parseInvoices = async (env: Environment, records: Invoice[]): Promise<PublicInvoice[]> => {
+    try {
+      const response: PublicInvoice[] = [];
+
+      const methods = await paymentMethodController.list({
+        id: { in: _.uniq(_.compact(records.map((r) => r.method))) },
+      });
+
+      for (const record of records) {
+        const method = methods.find((m) => m.id === record.method);
+
+        const p: PublicInvoice = {
+          uuid: record.uuid,
+          date: new Date2(record.date).format(Formats.ISO),
+          base: record.base,
+          tax_percentage: record.tax_percentage,
+          tax: record.tax,
+          amount: record.amount,
+          concepts: _.orderBy(record.concepts, (c) => c.price, `desc`),
+          billing: record.billing,
+          method: method ? (await this.parsePaymentMethods(env, [method]))[0] : null,
+          invoice: !!record.invoice,
+          number: record.number || null,
+          status: record.status,
+          metadata: record.metadata,
+        };
+        response.push(p);
+      }
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  // license helpers -----------------------------------------------------------
+
+  private readonly getLicenses = async (env: Environment, serviceUUID: string, params: Where<OrganizationLicense>): Promise<PublicOrganizationLicense[]> => {
+    try {
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      const serviceLicenses = await organizationLicenseController.list({
+        ...params,
+        organization: env.organization.id,
+        service: service.id,
+      });
+
+      return await this.parseLicenses(env.organization, serviceLicenses);
+    } catch (e) { throw e; }
+  };
+
+  private readonly licenseActivationContext = async (env: Environment, serviceUUID: string, data: { license: string, billing: OrganizationLicense[`billing`], type: OrganizationLicense[`type`] }) => {
+    try {
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      // the base license of the quota service can't be activated/edited
+      if (service.uuid === authority.configuration.uuid
+        && data.type === LicenseType.Base) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Invalid license activation request.`,
+        });
+      }
+
+      const license = (await licenseController.list({
+        uuid: data.license,
+        service: service.id,
+        type: data.type,
+        enabled: true,
+      }))[0];
+      if (!license || license.type !== data.type) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `No license ${data.license} found.`,
+        });
+      }
+
+      const base = await billingController.getBaseLicense(env.organization);
+      let cycle: BillingCycle;
+
+      // if organization billing yet not configured
+      if (base.billing === `lifetime`) {
+        // set organization billing cycle
+        await organizationLicenseController.update(base.id, { billing: data.billing });
+
+        // start 14 day trial
+        const now = new Date2().toMoment().startOf(`day`);
+        const trial = 14;
+
+        cycle = (await billingCycleController.add({
+          organization: env.organization.id,
+          start_date: now.format(Formats.ISO),
+          end_date: now.add(trial, `days`).format(Formats.ISO),
+          trial: true,
+          metadata: {},
+          internal: {},
+        }))[0];
+      } else if (base.billing !== data.billing) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `All active licenses must be billed on the same billing cycle: ${base.billing}.`,
+        });
+      } else {
+        // get organization cycle
+        const context = await billingController.cycleContext(env.organization);
+        cycle = context.cycle;
+      }
+
+      // get all licenses for service
+      const allServiceLicenses = (await organizationLicenseController.list({
+        service: service.id,
+        type: LicenseType.Base,
+        organization: env.organization.id,
+      }));
+
+      // filter service bases: it can only have 2 bases, one enabled and one future
+      const currentAndFutureLicenses = allServiceLicenses.filter((l) => (!l.end_date || new Date2(l.end_date).isFuture()));
+      if (currentAndFutureLicenses.length > 2) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Organization has an invalid license configuration.`,
+        });
+      }
+
+      const [enabled, future] = [currentAndFutureLicenses.find((eb) => eb.enabled), currentAndFutureLicenses.find((eb) => !eb.enabled)];
+
+      // power-ups require a base license
+      if (!enabled && data.type === LicenseType.Variant) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Organization has no active license for this service. Activate a base license before activating power-ups.`,
+        });
+      }
+
+      return {
+        cycle: cycle,
+        service: service,
+        license: license,
+        setup: license.type === LicenseType.Base && !allServiceLicenses.some((l) => l.service === service.id && l.end_date && new Date2(l.end_date).isPast()),
+        enabled: enabled,
+        future: future,
+      };
+    } catch (e) { throw e; }
+  };
+
+  private readonly configureLicense = async (organization: Organization, license: License, data: {
+    associated?: OrganizationLicense,
+    billing: OrganizationLicense[`billing`],
+    start_date: Date2,
+    end_date?: Date2,
+    metadata?: OrganizationLicense[`metadata`],
+    internal: OrganizationLicense[`internal`],
+  }): Promise<OrganizationLicense> => {
+    try {
+      let associatedOrganizationLicense: OrganizationLicense;
+      if (license.associated) {
+        associatedOrganizationLicense = (await organizationLicenseController.list({
+          organization: organization.id,
+          original: license.associated,
+          ...data.associated ? { id: data.associated.id } : { enabled: true },
+        }))[0];
+      }
+
+      const organizationLicense = (await organizationLicenseController.add({
+        organization: organization.id,
+        service: license.service,
+        type: license.type,
+        associated: associatedOrganizationLicense?.id,
+        original: license.id,
+        billing: data.billing,
+        properties: license.properties,
+        data: license.data,
+        start_date: data.start_date.format(Formats.ISO),
+        end_date: data.end_date ? data.end_date.format(Formats.ISO) : null,
+        metadata: data.metadata,
+        internal: data.internal,
+      }))[0];
+
+      const licenseLimits = await licenseLimitController.list({ license: license.id });
+      for (const ll of licenseLimits) {
+        await organizationLicenseLimitController.add({
+          organization: organization.id,
+          license: organizationLicense.id,
+          name: ll.name,
+          limit: ll.limit,
+          period: ll.period,
+          monthly_price_abs: ll.monthly_price_abs,
+          annual_price_abs: ll.annual_price_abs,
+          overconsume: false, // default to false
+          overconsume_monthly_price_per_unit: ll.overconsume_monthly_price_per_unit,
+          overconsume_annual_price_per_unit: ll.overconsume_annual_price_per_unit,
+          metadata: ll.metadata,
+        });
+      }
+
+      // configure also associated licenses
+      const associatedLicenses = await licenseController.list({
+        associated: license.id,
+        enabled: true,
+      });
+
+      for (const associated of associatedLicenses) {
+        await this.configureLicense(organization, associated, {
+          associated: organizationLicense,
+          billing: data.billing,
+          start_date: data.start_date,
+          end_date: data.end_date,
+          metadata: {},
+          internal: {},
+        });
+      }
+
+      return organizationLicense;
+    } catch (e) { throw e; }
+  };
+
+  private readonly cancelLicense = async (env: Environment, serviceUUID: string, licenseUUID: string, type: OrganizationLicense[`type`]): Promise<PublicOrganizationLicense | void> => {
+    try {
+      const service = (await adminServiceController.list({ uuid: serviceUUID }))[0];
+      if (!service) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `No service ${serviceUUID} found.`,
+        });
+      }
+
+      if (service.uuid === authority.configuration.uuid
+        && type === LicenseType.Base) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Base license can't be cancelled.`,
+        });
+      }
+
+      let license = (await organizationLicenseController.list({
+        uuid: licenseUUID,
+        organization: env.organization.id,
+        service: service.id,
+        type: type,
+        end_date: [
+          { is: null },
+          { gt: Date2.current().format(Formats.ISO) },
+        ],
+      }))[0];
+      if (!license || license.type !== type) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `No license ${licenseUUID} found.`,
+        });
+      }
+
+      if (license.associated) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Associated license can't be cancelled independently. Please, cancel the main license.`,
+        });
+      }
+
+      // delete future licenses
+      if (new Date2(license.start_date).isFuture()) {
+        await organizationLicenseController.delete(license.id);
+        return;
+      }
+
+      if (!license.enabled) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `License is already cancelled.`,
+        });
+      }
+
+      const { cycle } = await billingController.cycleContext(env.organization);
+
+      license = (await organizationLicenseController.update(license.id, {
+        end_date: cycle.end_date,
+      }))[0];
+
+      // notify power-up removal
+      if (type === LicenseType.Variant) {
+        await authority.notify<PowerUpRemoved>(env.organization.uuid, {
+          event: NotificationEventNames.PowerUpRemoved,
+          data: {
+            cta: {
+              dashboard: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_DASHBOARD`),
+              preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+            },
+            organization: env.organization,
+          },
+        });
+      }
+
+      return (await this.parseLicenses(env.organization, [license]))[0];
+    } catch (e) { throw e; }
+  };
+
+  // user helpers --------------------------------------------------------
+  private readonly getUserAndAccess = async (env: Environment, userUUID: string): Promise<{ user: User, access: UserOrganization }> => {
+    try {
+      const user = (await userController.list({ uuid: userUUID, status: { is: UserStatus.Blocked, inverse: true } }, { password: true }))[0];
+      if (!user) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `No active user found.`,
+        });
+      }
+
+      const access = (await userOrganizationController.list({
+        organization: env.organization.id,
+        user: user.id,
+      }))[0];
+      if (!access) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `User is not on organization.`,
+        });
+      }
+
+      return { user: user, access: access };
+    } catch (e) { throw e; }
+  };
+
+  // payments --------------------------------------------------------
+  public readonly setupPaymentMethod = async (env: Environment): Promise<Stripe.SetupIntent> => {
+    try {
+      // don't use env organization -> may be cached
+      const organization = (await organizationController.get(env.organization.id))[0];
+
+      let customer = organization.internal.customer;
+      if (!customer) {
+        // setup customer
+        customer = (await this.configureStripeCustomer(organization)).id;
+      }
+
+      const response = await stripe.setupIntents.create({
+        customer: customer,
+        usage: `off_session`,
+      });
+      return response;
+    } catch (e) { throw e; }
+  };
+
+  public readonly getPaymentMethod = async (env: Environment, uuid: string): Promise<PublicPaymentMethod[]> => {
+    try {
+      const methods = await paymentMethodController.list({ organization: env.organization.id, uuid: uuid });
+      return await this.parsePaymentMethods(env, methods);
+    } catch (e) { throw e; }
+  };
+
+  public readonly listPaymentMethods = async (env: Environment): Promise<PublicPaymentMethod[]> => {
+    try {
+      const methods = await paymentMethodController.list({ organization: env.organization.id });
+      return await this.parsePaymentMethods(env, methods);
+    } catch (e) { throw e; }
+  };
+
+  public readonly addPaymentMethod = async (env: Environment, data: AddPaymentMethod): Promise<PublicPaymentMethod> => {
+    try {
+      Validator.validate(addPaymentMethodSchema, data);
+
+      // don't use env organization -> may be cached
+      const organization = (await organizationController.get(env.organization.id))[0];
+
+      const method = await stripe.paymentMethods.retrieve(data.payment_method_id);
+      if (!method) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `Payment method not found.`,
+        });
+      }
+      if (method.customer !== organization.internal.customer) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Payment method does not belong to the organization.`,
+        });
+      }
+      if (method.type !== `card`) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Unsupported payment method type: ${method.type}.`,
+        });
+      }
+      if (!method.card) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Payment method has no card information.`,
+        });
+      }
+
+      // disable previously enabled payment method
+      if (data.enabled) {
+        const enabled = (await paymentMethodController.list({
+          organization: organization.id,
+          enabled: true,
+        }))[0];
+        if (enabled) { await paymentMethodController.update(enabled.id, { enabled: false }); }
+      }
+
+      const created = await paymentMethodController.add({
+        organization: organization.id,
+        type: PaymentMethodType.Card,
+        properties: {
+          alias: data.properties?.alias,
+          name: method.card.last4,
+          brand: method.card.brand,
+          exp_month: method.card.exp_month,
+          exp_year: method.card.exp_year,
+          country: method.card.country,
+        },
+        enabled: data.enabled,
+        metadata: data.metadata,
+        internal: {
+          payment_method_id: method.id,
+          fingerprint: method.card.fingerprint,
+        },
+      });
+
+      return (await this.parsePaymentMethods(env, created))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly updatePaymentMethod = async (env: Environment, uuid: string, data: UpdatePaymentMethod): Promise<PublicPaymentMethod> => {
+    try {
+      Validator.validate(updatePaymentMethodSchema, data);
+
+      const old = (await paymentMethodController.list({ organization: env.organization.id, uuid: uuid }))[0];
+      if (!old) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `Payment method not found.`,
+        });
+      }
+
+      // disable previously enabled payment method
+      if (!old.enabled && data.enabled) {
+        const enabled = (await paymentMethodController.list({
+          organization: env.organization.id,
+          enabled: true,
+        }))[0];
+        if (enabled) { await paymentMethodController.update(enabled.id, { enabled: false }); }
+      }
+
+      const updated = await paymentMethodController.update(old.id, data);
+
+      await authority.notify<BillingChanged>(env.organization.uuid, {
+        event: NotificationEventNames.BillingChanged,
+        data: {
+          organization: env.organization,
+          cta: {
+            billing: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:ORG_BILLING`),
+            preferences: nconf.get(`SERVICES:NOTIFICATIONS:CTAS:USER_PREF_LIST`),
+          },
+        },
+      });
+
+      return (await this.parsePaymentMethods(env, updated))[0];
+    } catch (e) { throw e; }
+  };
+
+  public readonly deletePaymentMethod = async (env: Environment, uuid: string): Promise<void> => {
+    try {
+      const old = (await paymentMethodController.list({ organization: env.organization.id, uuid: uuid }))[0];
+      if (!old) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `Payment method not found.`,
+        });
+      }
+
+      const { deleted } = await paymentMethodController.delete(old.id);
+      if (!deleted) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Could not delete payment method.`,
+        });
+      }
+    } catch (e) { throw e; }
+  };
+
+  public readonly listInvoices = async (env: Environment): Promise<PublicInvoice[]> => {
+    try {
+      const invoices = await invoiceController.list({ organization: env.organization.id }, { order: { by: `date`, direction: `descendent` } });
+      return await this.parseInvoices(env, invoices);
+    } catch (e) { throw e; }
+  };
+
+  public readonly getInvoicePDF = async (env: Environment, uuid: string): Promise<{
+    name: string,
+    data: string,
+  }> => {
+    try {
+      const invoice = (await invoiceController.list({
+        organization: env.organization.id,
+        uuid: uuid,
+      }, { order: { by: `date`, direction: `descendent` } }))[0];
+
+      if (!invoice) {
+        throw new APIError({
+          code: StatusCodes.NOT_FOUND,
+          detail: `Invoice ${uuid} not found.`,
+        });
+      }
+      if (!invoice.invoice) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Invoice ${uuid} does not have a PDF available.`,
+        });
+      }
+
+      // get invoice from holded
+      const [holdedInvoice, { data: pdf }] = await Promise.all([
+        holded.getInvoice(invoice.invoice),
+        holded.getInvoicePDF(invoice.invoice),
+      ]);
+
+      if (!holdedInvoice.docNumber) {
+        throw new APIError({
+          code: StatusCodes.INTERNAL_SERVER_ERROR,
+          detail: `Invoice ${uuid} does not have a document number.`,
+        });
+      }
+
+      return {
+        name: `${holdedInvoice.docNumber}.pdf`,
+        data: pdf,
+      };
+    } catch (e) { throw e; }
+  };
+
+  public readonly configureHoldedContact = async (organization: Organization): Promise<Holded.Contact> => {
+    try {
+      if (!organization.billing.document) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Configure your billing information first.`,
+        });
+      }
+
+      let contact = (await holded.listContacts({ customId: organization.uuid }))[0];
+
+      // TODO: change this to country code when upgrading to holded v2
+      const country = getCountry(organization.billing.address.country) || getName(organization.billing.address.country) || organization.billing.address.country;
+
+      if (!contact) {
+        // create client record
+        const account = await holded.createAccount({
+          prefix: 4300,
+          name: organization.billing.name,
+        });
+
+        // create contact
+        contact = await holded.createContact({
+          customId: organization.uuid,
+          name: organization.billing.name,
+          code: organization.billing.document,
+          email: organization.billing.email,
+          phone: organization.billing.phone,
+          type: `client`,
+          isperson: organization.billing.individual,
+          clientRecord: account.accountNum,
+          billAddress: {
+            address: organization.billing.address.address,
+            city: organization.billing.address.city,
+            postalCode: organization.billing.address.zip,
+            province: organization.billing.address.province,
+            country: country,
+          },
+        });
+      } else {
+        let clientRecord: number;
+        if (!contact.clientRecord) {
+          // create client record
+          const account = await holded.createAccount({
+            prefix: 4300,
+            name: organization.billing.name,
+          });
+          clientRecord = account.accountNum;
+        }
+
+        // update contact
+        contact = await holded.updateContacts(contact.id, {
+          name: organization.billing.name,
+          code: organization.billing.document,
+          email: organization.billing.email,
+          phone: organization.billing.phone,
+          type: `client`,
+          isperson: organization.billing.individual,
+          clientRecord: clientRecord,
+          billAddress: {
+            address: organization.billing.address.address,
+            city: organization.billing.address.city,
+            postalCode: organization.billing.address.zip,
+            province: organization.billing.address.province,
+            country: country,
+          },
+        });
+      }
+
+      await organizationController.update(organization.id, {
+        internal: { contact: contact.id },
+      });
+
+      return contact;
+    } catch (e) { throw e; }
+  };
+
+  public readonly configureStripeCustomer = async (organization: Organization): Promise<Stripe.Customer> => {
+    try {
+      if (!organization.billing.document) {
+        throw new APIError({
+          code: StatusCodes.BAD_REQUEST,
+          detail: `Configure your billing information first.`,
+        });
+      }
+
+      let { data: [customer] } = await stripe.customers.search({
+        query: `metadata['uuid']:'${organization.uuid}'`,
+        limit: 1,
+      });
+
+      if (!customer) {
+        customer = await stripe.customers.create({
+          name: organization.billing.name,
+          ...(organization.billing.individual ?? true) ? {
+            individual_name: organization.billing.name,
+            business_name: null,
+          } : {
+            individual_name: null,
+            business_name: organization.billing.name,
+          },
+          email: organization.billing.email,
+          phone: organization.billing.phone,
+          address: {
+            line1: organization.billing.address.address,
+            city: organization.billing.address.city,
+            postal_code: organization.billing.address.zip,
+            state: organization.billing.address.province,
+            country: organization.billing.address.country,
+          },
+          metadata: {
+            uuid: organization.uuid,
+            document: organization.billing.document,
+          },
+        });
+      } else {
+        // update information
+        customer = await stripe.customers.update(customer.id, {
+          name: organization.billing.name,
+          ...(organization.billing.individual ?? true) ? {
+            individual_name: organization.billing.name,
+            business_name: null,
+          } : {
+            individual_name: null,
+            business_name: organization.billing.name,
+          },
+          email: organization.billing.email,
+          phone: organization.billing.phone,
+          address: {
+            line1: organization.billing.address.address,
+            city: organization.billing.address.city,
+            postal_code: organization.billing.address.zip,
+            state: organization.billing.address.province,
+            country: organization.billing.address.country,
+          },
+          metadata: {
+            uuid: organization.uuid,
+            document: organization.billing.document,
+          },
+        });
+      }
+
+      await organizationController.update(organization.id, {
+        internal: { customer: customer.id },
+      });
+
+      return customer;
+    } catch (e) { throw e; }
+  };
+}
+
+const publicOrganizationController = new PublicOrganizationCtrl();
+export default publicOrganizationController;