@ale-rainbow/web-sdk 5.1.0

package/lib/services/subscription/subscription.service.d.ts

@@ -0,0 +1,510 @@
+/**
+ * @module Subscription
+ */
+import type { EventableService } from "../../services/service";
+import { CompanySubscription, TrialStatus } from "../../models/subscription.model";
+import type { CommercialState, OfferGroup, PurchaseOptions, SeatUsage, SubscriptionOffer, SubscriptionPurchaseOrder, SubscriptionQuotation, SubscriptionQuotationOptions, UpdateSubscriptionPatch } from "../../models/subscription.model";
+export declare const SUBSCRIPTION_SVC = "SubscriptionService";
+export interface ISubscriptionServiceEvents {
+    /**
+     * @eventProperty
+     * This `RBEvent` is sent when the company's subscriptions have changed — bought, updated,
+     * cancelled, or announced by the backend over XMPP.
+     *
+     * Carries no payload: it says the previous read is stale, not what now holds. Ask the service
+     * again — the cache is already dropped when this fires, so the next read hits the server.
+     */
+    ON_COMPANY_SUBSCRIPTIONS_CHANGED: unknown;
+}
+export interface SubscriptionService extends EventableService<ISubscriptionServiceEvents> {
+    /**
+     * Fetches all available subscription offers (the catalog).
+     *
+     * Does not require authentication. Results may be geo-filtered based on the caller's location.
+     *
+     * @returns An array of available {@link SubscriptionOffer} objects.
+     * @throws {@link RainbowError} when the request fails.
+     */
+    getOffers: () => Promise<SubscriptionOffer[]>;
+    /**
+     * Subscribes the authenticated user to an offer. The user id is read from the current session;
+     * {@link SubscriptionOffer.isFreemium} decides the path:
+     * - **Freemium**: free self-service. The backend creates the company on the fly, named after
+     *   `companyName` when given, otherwise a placeholder the caller is expected to replace via
+     *   {@link CompanyService.updateCompany}.
+     * - **Paid**: requires `purchaseOptions` (billing cycle, seats, billing address).
+     *
+     * @param purchaseOptions - Required for a paid offer, ignored for freemium.
+     * @param companyName - Only meaningful for a user with no company yet; ignored for a paid offer.
+     * @returns The {@link SubscriptionPurchaseOrder} for a paid offer; `undefined` for freemium.
+     * @throws {@link RainbowError} when the request fails, or an error when a paid offer is
+     *   subscribed without `purchaseOptions`.
+     */
+    subscribeToOffer: (offer: SubscriptionOffer, purchaseOptions?: PurchaseOptions, companyName?: string) => Promise<SubscriptionPurchaseOrder | undefined>;
+    /**
+     * Fetches the subscriptions of the authenticated user's company, read from the current
+     * session. Cached in memory until invalidated (a new subscription, or a `companysubscription`
+     * XMPP event).
+     *
+     * @param forceRefresh - Bypasses the cache and refetches.
+     */
+    getCompanySubscriptions: (forceRefresh?: boolean) => Promise<CompanySubscription[]>;
+    /**
+     * Fetches a single subscription of the authenticated user's company.
+     *
+     * @returns The {@link CompanySubscription} or `undefined` if not found.
+     */
+    getCompanySubscription: (subscriptionId: string) => Promise<CompanySubscription | undefined>;
+    /**
+     * Updates an existing subscription. Mainly used to change the licence count:
+     * `patch.maxNumberUsers` is the new **absolute total**, not a delta.
+     *
+     * Takes no payment method — the billing consequence (immediate pro-rata charge or adjustment
+     * at the next renewal) is decided server-side.
+     *
+     * @param patch - Only the keys present are sent; the backend leaves the others untouched.
+     * @throws {@link RainbowError} when the request fails (e.g. the new seat count is below the
+     *   number of assigned licences, or the admin lacks the right).
+     */
+    updateSubscription: (subscriptionId: string, patch: UpdateSubscriptionPatch) => Promise<CompanySubscription>;
+    /**
+     * Cancels a subscription. **Never immediate** — the period already paid for runs out, then
+     * access stops.
+     *
+     * Two backend calls, chosen from the billing cycle:
+     * - **monthly** — `DELETE .../companies/:companyId/subscriptions/:subscriptionId`. Keeps
+     *   `status: "active"` with an `expirationDate`; a cron moves it to `terminated` on that date,
+     *   so it stays listed meanwhile.
+     * - **prepaid** — `DELETE` is refused whatever the date (`403450`, "Prepaid subscriptions
+     *   cannot be deleted in direct sell model"); automatic renewal is switched off instead, via
+     *   {@link updateSubscription} as `{ autoRenew: false }`. Same outcome.
+     *
+     * {@link CompanySubscription.isCancelled} tells either apart from a live subscription.
+     *
+     * Also refused by the backend: sync with Business Store / Zuora in flight (`403311`), licences
+     * still allocated (`403316`, `403317`, `403318`), promo code outside its window on a monthly
+     * subscription (`403394`). The default subscription is never cancellable. A
+     * `linkedSubscriptionId` is cancelled in the same request. No cancellation reason is accepted
+     * by either endpoint — collect it separately if the product needs one.
+     */
+    cancelSubscription: (subscriptionId: string) => Promise<void>;
+    /**
+     * Un-cancels a prepaid subscription by switching automatic renewal back on — the mirror of
+     * {@link cancelSubscription}'s prepaid branch.
+     *
+     * Prepaid only: a cancelled monthly one was `DELETE`d and carries an `expirationDate` nothing
+     * takes back. Running only: past the end date the backend has terminated it and released its
+     * licences, so the offer has to be bought again. Renewal already on returns without a call —
+     * the backend answers a second `autoRenew: true` with a `409`.
+     *
+     * The backend may still refuse: sync with Business Store / Zuora in flight answers `403311`.
+     *
+     * @throws When the subscription is unknown, monthly, or already over.
+     */
+    restoreSubscription: (subscriptionId: string) => Promise<void>;
+    /**
+     * Prices a prospective change without applying it — read-only, nothing is written.
+     *
+     * Which fields come back depends on the subscription: a monthly one reports recurring amounts
+     * ({@link SubscriptionQuotation.contractedMrr}, {@link SubscriptionQuotation.totalDeltaMrr}), a
+     * prepaid one reports contract values ({@link SubscriptionQuotation.totalContractedValue},
+     * {@link SubscriptionQuotation.totalDeltaTcv}). Branch on
+     * {@link CompanySubscription.isMonthly} — reading `contractedMrr` on a prepaid subscription
+     * reports a monthly figure as if it were the contract total.
+     *
+     * Every field is optional: treat an absent one as "do not show that row" rather than
+     * substituting a computed value. {@link SubscriptionQuotation.taxAmount} in particular is the
+     * only trustworthy tax figure.
+     *
+     * @throws {@link RainbowError} when the request fails (e.g. invalid promo code).
+     */
+    getSubscriptionQuotation: (subscriptionId: string, options: SubscriptionQuotationOptions) => Promise<SubscriptionQuotation>;
+    /**
+     * Prices a catalog offer without buying it — read-only, nothing is written.
+     *
+     * What {@link getSubscriptionQuotation} does for an existing subscription, keyed by the offer
+     * instead. Monthly and annual are separate offers, so `offerId` already fixes the cycle.
+     *
+     * @throws {@link RainbowError} when the request fails.
+     */
+    getOfferQuotation: (offerId: string, maxNumberUsers: number) => Promise<SubscriptionQuotation>;
+    /**
+     * The company's trial as the interface needs to talk about it: end date, days left, whether it
+     * is over, whether an upsell is still worth showing.
+     *
+     * The single answer to "should this screen show the trial banner?" — read
+     * {@link TrialStatus.shouldPromptUpsell} rather than re-combining the trial, the paid
+     * subscriptions and the user's flags, which is how the several banners drift apart.
+     *
+     * Synchronous: read off the in-memory subscription cache, which `start()` fills before any
+     * screen runs and every change refreshes in place.
+     *
+     * @param groupName - Case-insensitive group filter (e.g. `"webinar"`); all trials when omitted.
+     * @returns `undefined` when the user is on no trial offer, or the company runs no trial
+     *   carrying an end date.
+     */
+    getTrialStatus: (groupName?: string) => TrialStatus | undefined;
+    /**
+     * Every trial the banner has to talk about: one status per product among the running trials,
+     * soonest to end first. A company running a Webinar and a Collaboration trial gets both, which
+     * is what lets the banner name each product with its own day count.
+     *
+     * When no trial is running, the last one to have ended alone, as {@link getTrialStatus} would
+     * answer — there is only one "your trial has ended" to say.
+     *
+     * @returns An empty array when the user is on no trial offer, or the company runs no trial
+     *   carrying an end date.
+     */
+    getTrialStatuses: () => TrialStatus[];
+    /**
+     * Where the account stands commercially — see {@link CommercialState}.
+     *
+     * The one place to ask "may we sell to this user, and is there anything left to sell?". Do not
+     * rebuild it from the trial roles: those survive the trial's end and a purchase.
+     */
+    getCommercialState: () => CommercialState;
+    /**
+     * Whether the company runs at least one live subscription in `groupName` — asked of the
+     * subscriptions, not of the login payload: {@link Contact.isWebinarTrial} /
+     * {@link Contact.isCollaborationTrial} are rebuilt from roles read at login, so an offer
+     * subscribed since leaves them false and one that ended leaves them true.
+     *
+     * Unlike a paid-only check, freemium trials **count** here — a trial grants the product,
+     * which is its point. A running one sits at `status: "trial"`, so this reads
+     * {@link ACCESS_STATUSES}, not the paid-only list; a spent trial keeps that status and is
+     * ruled out by its date.
+     *
+     * Excludes the default base tier (held by every company) and `terminated` / `terminating`.
+     *
+     * @param groupName - Matched case-insensitively (e.g. `"collaboration"`, `"webinar"`).
+     */
+    hasLiveSubscriptionOfGroup: (groupName: string) => boolean;
+    /**
+     * The live **paid** subscriptions the company runs in `groupName` — what it bought, not what
+     * it was granted. The paid-only counterpart of {@link hasLiveSubscriptionOfGroup}: a freemium
+     * trial grants the product but is precisely what a purchase upgrades, so it is excluded here,
+     * as are the default base tier (held by every company) and the never-sold Beta offer.
+     *
+     * Reads {@link LIVE_STATUSES}, not {@link ACCESS_STATUSES}: a running trial sits at
+     * `status: "trial"`, absent from the paid list, and a spent one is ruled out by its date.
+     *
+     * Returns the subscriptions rather than a boolean so a caller can also tell *which* plans are
+     * held — the offer sizes, for instance, which a yes/no answer cannot give. Emptiness is the
+     * boolean: no live paid subscription in that group.
+     *
+     * Synchronous: read off the in-memory subscription cache, which `start()` fills before any
+     * screen runs and every change refreshes in place.
+     *
+     * @param groupName - Matched case-insensitively (e.g. `"webinar"`, `"collaboration"`).
+     */
+    getLivePaidSubscriptionsOfGroup: (groupName: string) => CompanySubscription[];
+    /**
+     * The group the company holds **only** a running trial of, when that trial is the single thing
+     * it runs at all — `undefined` in every other case.
+     *
+     * Answers "is this account here on the strength of one free trial, and nothing else?", which is
+     * what an offer catalog reads to decide which family to open on: a company trialling one
+     * product and owning nothing wants that product's offers in front of it, not the first family
+     * of the catalog's own order.
+     *
+     * Deliberately stricter than {@link hasLiveSubscriptionOfGroup}, which answers per group and
+     * says nothing of what else is held. Every subscription of the company is weighed here: a
+     * second trial in another family, or any live paid plan, means the account is not defined by
+     * the one trial and this returns `undefined` rather than picking a winner.
+     *
+     * Ignores what {@link getLivePaidSubscriptionsOfGroup} ignores, and for the same reasons: the
+     * default base tier every company holds, and the never-sold Beta offer. A spent trial is ruled
+     * out by its date, not its status, which the backend leaves at `trial`.
+     *
+     * Group-agnostic: it reports whichever family the trial belongs to, so no caller has to name
+     * the products it expects.
+     *
+     * Synchronous, off the in-memory cache `start()` fills and every change refreshes.
+     *
+     * @returns The trial's group name as the catalog spells it (e.g. `"Webinar"`), or `undefined`.
+     */
+    getSoleTrialGroupName: () => string | undefined;
+    /**
+     * Seats the company holds and seats already taken — read this before offering to invite
+     * anyone, and to show any "x / y licences" figure.
+     *
+     * Sums only the subscriptions whose licences are seats
+     * ({@link CompanySubscription.isUserLicense}): Webinar and the other `nb_services` offers hold
+     * their licences against the company, not against a user, so adding them would credit the
+     * company with places nobody can take.
+     *
+     * A cancelled subscription still counts until its last paid day — its seats are still assigned
+     * and still billed. A terminated or expired one does not: its licences are released.
+     *
+     * Synchronous, off the in-memory cache `start()` fills and every change refreshes.
+     */
+    getSeatUsage: () => SeatUsage;
+    /**
+     * Purchasable offers grouped by product and variant: one {@link OfferGroup} per product family
+     * (e.g. "Webinar"), one {@link OfferVariant} per size (e.g. "Webinar 120") with its monthly
+     * and/or annual offer.
+     *
+     * A group whose trial is still available carries it in {@link OfferVariant.trial}. Trials
+     * already granted are filtered out upstream by {@link getPurchasableOffers}.
+     *
+     * @param groupName - Case-insensitive filter on the group name.
+     */
+    getPurchasableOfferGroups: (groupName?: string) => Promise<OfferGroup[]>;
+}
+declare const SubscriptionServiceRB_base: object & (abstract new (...args: any[]) => import("../../services/service").EventsMixinTemplate<ISubscriptionServiceEvents>);
+/** @internal */
+export declare class SubscriptionServiceRB extends SubscriptionServiceRB_base implements SubscriptionService {
+    /**
+     * Statuses of a running *paid* subscription — "has this company bought anything?". Excludes
+     * `terminated` (licences released) and `terminating` (cancellation requested — the offer must
+     * stay re-purchasable). A trial carries none of them; it sits at `trial`. To ask whether the
+     * company *holds* the product rather than paid for it, read {@link ACCESS_STATUSES}.
+     */
+    private static readonly LIVE_STATUSES;
+    /**
+     * Statuses under which the company holds the product — {@link LIVE_STATUSES} plus `trial`,
+     * a trial granting it exactly as a purchase does.
+     * Says nothing of the trial's end: a spent trial stays at `status: "trial"`, so the date ends
+     * it, not the status. Pair with {@link CompanySubscription.isExpired}.
+     */
+    private static readonly ACCESS_STATUSES;
+    private readonly loggerService;
+    private readonly errorHelperService;
+    private readonly xmppService;
+    private xmppHandler;
+    private pendingSubscriptionResolvers;
+    private companySubscriptions;
+    static getInstance(): SubscriptionServiceRB;
+    static build(): SubscriptionServiceRB;
+    private constructor();
+    start(): Promise<void>;
+    reconnect(): Promise<void>;
+    stop(): void;
+    /**
+     * Refetch then announce — the subscriptions, and the company features they unlock. Both are
+     * awaited before the event so a listener reading either back is served the new state, and the
+     * cache is never left empty in between: `getCompanySubscriptions` only overwrites it once the
+     * response is in.
+     */
+    private onSubscriptionsChanged;
+    private registerXmppHandler;
+    private removeXmppHandler;
+    private onManagementMessage;
+    private waitForXmppConfirmation;
+    getOffers(): Promise<SubscriptionOffer[]>;
+    subscribeToOffer(offer: SubscriptionOffer, purchaseOptions?: PurchaseOptions, companyName?: string): Promise<SubscriptionPurchaseOrder | undefined>;
+    /**
+     * Re-reads the user's own company in place on the connected contact, after any subscription.
+     *
+     * Nothing else pushes the company back: the user payload carries only `companyId` and
+     * `companyName`, and the company is otherwise re-read on reconnection alone. Yet a
+     * subscription changes it — a first purchase stamps its business model as direct-sell (see
+     * {@link purchaseFirstSubscription}), a trial stamps `freemiumTypes`, which
+     * {@link Company.trialTypes} reads and the launch pad gates on.
+     *
+     * Done for every purchase, the caller having no way to tell which fields the backend touched.
+     * Failure is swallowed: the purchase went through, and the refresh can be retried on its own.
+     */
+    private refreshOwnCompany;
+    /**
+     * Re-reads the company features, which live on their own endpoint and are otherwise loaded at
+     * login alone — yet a subscription is precisely what turns one on, `webinarAccess` for a
+     * webinar offer, which {@link ConnectedUserRB.companyHasWebinarAccess} reads.
+     *
+     * Hung off the subscription change rather than off the purchase, so an offer bought from
+     * another tab or granted by an administrator lands here too.
+     *
+     * Failure is swallowed: the previous features are kept rather than cleared, so nothing the
+     * company holds is withdrawn from the interface over a failed refresh.
+     */
+    private refreshOwnCompanyFeatures;
+    /**
+     * Freemium path: creates the company on the fly, waits for the XMPP provisioning
+     * confirmation, then optimistically applies the unlocked roles.
+     *
+     * @param companyName - When omitted, a recognizable placeholder is sent and the caller is
+     *   expected to rename the company afterwards, as the onboarding wizard does.
+     */
+    private subscribeFreemium;
+    /**
+     * Reads the authenticated user's company id from the current session.
+     * Mirrors how {@link subscribeToOffer} reads the user id — the caller is already logged in.
+     */
+    private getCompanyId;
+    /**
+     * The connected user, non-optional: `CONTACT_SVC` starts `sync: true, blocking: true` ahead of
+     * this service in the launch config, so nothing here runs before it is set. Throws rather than
+     * answering a hollow object, which would read as "no company, no trial, not an admin" and
+     * silently deny what the user owns.
+     */
+    private userContact;
+    getCompanySubscriptions(forceRefresh?: boolean): Promise<CompanySubscription[]>;
+    getCompanySubscription(subscriptionId: string): Promise<CompanySubscription | undefined>;
+    /** `PUT .../companies/:companyId/subscriptions/:subscriptionId` — see the interface. */
+    updateSubscription(subscriptionId: string, patch: UpdateSubscriptionPatch): Promise<CompanySubscription>;
+    /**
+     * The cycle is not carried by the id, hence the lookup first — served from the warm cache when
+     * a subscription list is what triggered this. See the interface.
+     */
+    cancelSubscription(subscriptionId: string): Promise<void>;
+    /** See the interface. */
+    restoreSubscription(subscriptionId: string): Promise<void>;
+    /**
+     * Finds a subscription by id, for a caller given only the id. Cache first — a screen
+     * cancelling a subscription has just listed them — then the single-subscription endpoint.
+     *
+     * Answers `undefined` rather than throwing: callers use this to pick a branch, and a failed
+     * lookup should leave them on their default one, not abort them.
+     */
+    private resolveSubscription;
+    /**
+     * `POST .../companies/:companyId/quotations` — read-only pricing, see the interface.
+     */
+    getSubscriptionQuotation(subscriptionId: string, options: SubscriptionQuotationOptions): Promise<SubscriptionQuotation>;
+    /**
+     * `POST .../companies/:companyId/quotations` — read-only pricing, see the interface.
+     */
+    getOfferQuotation(offerId: string, maxNumberUsers: number): Promise<SubscriptionQuotation>;
+    /** Shared POST + error handling for both quotation entry points. */
+    private postQuotation;
+    /**
+     * Keeps only the keys actually set in the patch — the backend treats an absent key
+     * as "leave unchanged", so sending `undefined` values would be a behaviour change.
+     */
+    private buildUpdateBody;
+    /** The trial an upsell should talk about, picked from an already-read list. */
+    private pickTrial;
+    /**
+     * The trial to talk about among already-filtered ones.
+     *
+     * A trial keeps `status: "trial"` past its end date until the backend terminates it, so an
+     * expired one can sit next to a running one. Running ones answer first, soonest to end — the
+     * one about to run out, and the one an upsell should talk about. When all are expired, the
+     * last to have ended is the one the company just lost.
+     */
+    private static pickAmong;
+    getTrialStatus(groupName?: string): TrialStatus | undefined;
+    getTrialStatuses(): TrialStatus[];
+    getCommercialState(): CommercialState;
+    /**
+     * The two populations who may buy: the company administrator, for the company, and the
+     * standalone user of the default company, for themselves.
+     *
+     * `isCompanyAdmin`, not `isAdmin`: site, organization and support admins carry the ADMIN role
+     * without being the ones who sign. Guests are excluded first — they land in the default
+     * company holding no admin role, so they would pass as standalone buyers. Platform-wide roles
+     * administer other people's companies and are never sold to.
+     */
+    private mayBuyOffers;
+    /**
+     * The catalog offers the company can still purchase. An offer is excluded when:
+     * - `groupName` is given and the offer's does not match (case-insensitive);
+     * - it is freemium **and** the company already holds any subscription for that group, in any
+     *   status. A trial is granted once, and a paid plan is never offered the free tier of what it
+     *   already bought.
+     *
+     * Not on the public interface: callers want {@link getPurchasableOfferGroups}, which is what
+     * the offer cards render. Kept public for that method and its tests.
+     *
+     * @param groupName - Group filter (e.g. `"webinar"`, `"collaboration"`).
+     */
+    getPurchasableOffers(groupName?: string): Promise<SubscriptionOffer[]>;
+    /**
+     * The company's own subscriptions, read straight off the cache — `start()` fills it before any
+     * screen runs and every change refreshes it in place, so there is nothing to await.
+     *
+     * A default-company user owns nothing: the shared company's lines are not theirs.
+     */
+    private ownCompanySubscriptions;
+    getPurchasableOfferGroups(groupName?: string): Promise<OfferGroup[]>;
+    hasLiveSubscriptionOfGroup(groupName: string): boolean;
+    getLivePaidSubscriptionsOfGroup(groupName: string): CompanySubscription[];
+    getSoleTrialGroupName(): string | undefined;
+    getSeatUsage(): SeatUsage;
+    /**
+     * Whether the company actually bought something that is running right now.
+     *
+     * Drives the upsell surfaces — the boot offer catalog and the trial banner — so everything
+     * that is not a purchase has to be excluded, or a company holding none is told it already paid
+     * and never sees an offer again:
+     * - `isDefault` — the Essential base tier, granted to everyone.
+     * - `isFreemium` — the trials, which are precisely what the paid catalog upgrades.
+     * - `isInternal` — the Beta offer. Granted for feature testing, never sold, and it is
+     *   `nb_users` with a licence of its own, so nothing but its reference tells it apart from a
+     *   purchase. See {@link CompanySubscription.isInternal}.
+     */
+    private static holdsLivePaid;
+    /**
+     * Lower-cased `offerReference` of every offer the company runs a live subscription to.
+     *
+     * "Live" excludes `terminated` (licences released, the offer is buyable again) and
+     * `terminating` (cancellation requested — the customer must be able to re-subscribe). The
+     * default base tier and the freemium trials are excluded too: not purchases, and a trial is
+     * precisely what the paid catalog upgrades.
+     */
+    private getOwnedOfferReferences;
+    /**
+     * Folds the group's free trial into the paid variant it gives away — the cheapest — and orders
+     * the cards cheapest first.
+     *
+     * The trial is that cheapest paid offer free for a month, not a product of its own: as a card
+     * of its own beside it, the two read as competing plans. It becomes a property of that card,
+     * which the call to action then sells as a trial or as a purchase.
+     *
+     * Runs after the variants are built, not during the slotting: the prices it ranks on are only
+     * known once `monthly`/`annual` are in.
+     */
+    private mergeTrialIntoCheapest;
+    /** Cheapest first, so the trial-bearing card leads and the row reads up in price. */
+    private sortByPrice;
+    /**
+     * What a seat of `variant` costs per month, whichever cycle it sells in — the only basis on
+     * which variants priced in different cycles compare.
+     *
+     * Mirrors the offer card's `currentPrice`, so the ranking matches the prices on screen. A
+     * variant sold in both cycles ranks on its cheaper one (in practice the annual, ~20% off):
+     * which one the card shows follows the billing switch, and "cheapest" must not move when the
+     * user flips it.
+     *
+     * A missing price ranks last, never at zero — it would otherwise win the cheapest race and
+     * take the trial with it.
+     */
+    private monthlyEquivalentPrice;
+    /**
+     * Whether `offer` is already owned. Matches on the exact `offerReference`, so the
+     * monthly and annual variants of one product (`RB-Collab` vs `RB-Collab-1Y`) are
+     * independent — owning one leaves the other purchasable.
+     */
+    private isOfferOwned;
+    /**
+     * Paid purchase. Two backend flows, chosen through `paymentMethodId`:
+     * - **First purchase** (set): `POST .../subscriptions/purchase` — atomically converts the
+     *   company to direct-sell, creates the Zuora account from the payment method, and creates
+     *   the subscription.
+     * - **Account exists** (absent): `POST .../subscriptions` — adds the subscription to it.
+     *
+     * Amounts are computed client-side, the endpoints returning the subscription rather than a
+     * priced order; `orderId` is the real subscription id from the backend.
+     */
+    private purchasePaid;
+    /** First purchase: creates the Zuora account from the payment method and the subscription in one call. */
+    private purchaseFirstSubscription;
+    /** Subscribe on an existing Zuora account: only the subscription is created. */
+    private subscribeToExistingAccount;
+    /** Shared POST + error handling for the two subscription-creation endpoints. */
+    private postSubscription;
+    /**
+     * Optimistically pushes the matching freemium UserRole onto the in-memory user
+     * contact so the UI reflects unlocked features immediately after subscribing.
+     *
+     * ⚠️ TECH DEBT — patch, do not extend. Duplicates the role mapping already done
+     * during Contact hydration (contact.model.ts, `freemiumTypes` → UserRole). It
+     * exists only because the BE did not reliably return `freemiumTypes` right after
+     * a subscription. It derives the role from `hasWebinar` (NOT `freemiumTypes`) and
+     * does NOT handle the "webinar + collaboration" case. Remove once the BE returns
+     * correct subscription data and the contact refresh repopulates roles.
+     */
+    private applySubscriptionRoles;
+}
+export {};
+//# sourceMappingURL=subscription.service.d.ts.map

package/lib/services/subscription/subscription.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.service.d.ts","sourceRoot":"","sources":["../../../src/services/subscription/subscription.service.ts"],"names":[],"mappings":"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"}

package/lib/services/support/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./support.service";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/support/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/support/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/lib/services/support/support.model.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @module Support
+ */
+/**
+ * Lifecycle status of a support ticket.
+ *
+ * Mirrors the statuses exposed by the support backend. Any unknown value coming
+ * from the backend is normalized to `open` server-side, so this union is closed.
+ */
+export type SupportTicketStatus = "new" | "open" | "pending" | "hold" | "solved" | "closed";
+/** A file attached to a ticket comment. */
+export interface SupportAttachment {
+    /** Attachment id — feed to `downloadAttachment`. */
+    readonly id: string;
+    readonly fileName: string;
+    /** MIME type reported by the backend (e.g. `"image/png"`). */
+    readonly contentType: string;
+    readonly sizeBytes: number;
+}
+/**
+ * A ticket as listed by `getMyTickets` / `getCompanyTickets`.
+ *
+ * Only public information is exposed: the backend filters its own payload before
+ * returning it, so no internal identifier ever reaches the client.
+ */
+export interface SupportTicket {
+    readonly id: number;
+    readonly subject: string;
+    readonly status: SupportTicketStatus;
+    /** ISO 8601 creation date. */
+    readonly createdAt: string;
+    /** ISO 8601 date of the last update. */
+    readonly updatedAt: string;
+    /** Display name of the person who opened the ticket. */
+    readonly requesterName: string;
+    /**
+     * Email of the requester, only present when the caller is entitled to it:
+     * their own ticket, or a role covering the owning company.
+     */
+    readonly requesterEmail?: string;
+    /**
+     * Rainbow userId of the requester, when their support account carries one.
+     *
+     * The key to join a ticket back to a Rainbow user: unlike `requesterEmail` it is not
+     * gated on the caller's entitlements, and unlike `requesterName` it survives a rename.
+     */
+    readonly requesterRainbowId?: string;
+    /**
+     * Display name of the admin who filed the ticket on the requester's behalf.
+     *
+     * Absent on a ticket a user filed for themselves, which is the common case.
+     */
+    readonly createdByName?: string;
+    /** Rainbow userId of that admin, when the ticket was filed on behalf of someone. */
+    readonly createdByRainbowId?: string;
+    readonly tags: readonly string[];
+    /** `true` when the authenticated caller is the requester of this ticket. */
+    readonly isOwnTicket: boolean;
+}
+/**
+ * A comment on a ticket.
+ *
+ * Non-public comments are dropped by the backend, and `htmlBody` is sanitized
+ * server-side before being returned.
+ */
+export interface SupportComment {
+    readonly id: number;
+    /** Display name of the comment author. */
+    readonly authorName: string;
+    /**
+     * Rainbow userId of the author, when their support account carries one.
+     *
+     * Absent for support agents, who have no Rainbow account.
+     */
+    readonly authorRainbowId?: string;
+    /** Sanitized HTML body. */
+    readonly htmlBody: string;
+    readonly public: boolean;
+    /** ISO 8601 creation date. */
+    readonly createdAt: string;
+    readonly attachments: readonly SupportAttachment[];
+}
+/** A ticket with its description and full comment thread, as returned by `getTicket`. */
+export interface SupportTicketDetail extends SupportTicket {
+    readonly description: string;
+    readonly comments: readonly SupportComment[];
+    /**
+     * Display name of the support agent handling the ticket, when one is assigned.
+     *
+     * Resolved backend-side — the client never sees the underlying support-tool identifier.
+     */
+    readonly assigneeName?: string;
+}
+/** A Help Center article matching a knowledge base search. */
+export interface HelpCenterArticle {
+    readonly id: number;
+    readonly title: string;
+    /** Public URL of the article. */
+    readonly url: string;
+    /** Short excerpt highlighting the match. */
+    readonly snippet: string;
+}
+/** Technical context attached to a new ticket. */
+export interface SupportDeviceInfo {
+    readonly application?: string;
+    readonly browser?: string;
+    readonly hardware?: string;
+    readonly os?: string;
+    readonly version?: string;
+}
+/**
+ * Payload of `createTicket`.
+ *
+ * The requester defaults to the authenticated user and cannot be set freely — the
+ * only way to file for someone else is `onBehalfOfRainbowUserId`, which the backend
+ * accepts from a company admin and rejects from anyone else.
+ */
+export interface CreateTicketPayload {
+    readonly subject: string;
+    readonly description: string;
+    readonly tags?: readonly string[];
+    /** When the problem happened, as entered by the user. */
+    readonly occurrenceDate?: string;
+    readonly deviceInfo?: SupportDeviceInfo;
+    /** Tokens returned by `uploadAttachment`. */
+    readonly attachmentTokens?: readonly string[];
+    /** Reference to a related internal ticket, when the ticket is an escalation. */
+    readonly internalTicketId?: string;
+    /**
+     * Rainbow userId of the user this ticket is filed for, when an admin files it
+     * on their behalf. Omit for the ordinary case of a user filing their own ticket.
+     *
+     * That user becomes the requester — the ticket lands in their own list and they
+     * can follow it, comment on it and attach files. The caller is added as a CC, so
+     * both sides see the thread.
+     *
+     * The backend enforces who may use this: the caller must be a company admin and
+     * the target must belong to their company, otherwise the call is rejected. The
+     * client-side gate is a convenience, never the guarantee.
+     */
+    readonly onBehalfOfRainbowUserId?: string;
+}
+//# sourceMappingURL=support.model.d.ts.map