@thezelijah/majik-subscription 1.0.0

package/dist/majik-subscription.d.ts

@@ -0,0 +1,431 @@
+import { MajikMoney } from "@thezelijah/majik-money";
+import { COSItem, ISODateString, MonthlyCapacity, ObjectType, StartDateInput, SubscriptionID, SubscriptionMetadata, SubscriptionRate, SubscriptionSettings, YYYYMM } from "./types";
+import { CapacityPeriodResizeMode, RateUnit, SubscriptionStatus, SubscriptionType } from "./enums";
+/**
+ * Represents a subscription in the Majik system.
+ * Handles metadata, capacity, COS, and finance calculations (revenue, COS, profit, margins) for recurring subscriptions.
+ */
+export declare class MajikSubscription {
+    readonly __type = "MajikSubscription";
+    readonly __object: ObjectType;
+    id: SubscriptionID;
+    slug: string;
+    name: string;
+    category: string;
+    rate: SubscriptionRate;
+    status: SubscriptionStatus;
+    type: SubscriptionType;
+    timestamp: ISODateString;
+    last_update: ISODateString;
+    metadata: SubscriptionMetadata;
+    settings: SubscriptionSettings;
+    private financeDirty;
+    /**
+     * Creates a new `MajikSubscription` instance.
+     * @param {SubscriptionID | undefined} id - Optional subscription ID. Auto-generated if undefined.
+     * @param {string | undefined} slug - Optional slug. Auto-generated from name if undefined.
+     * @param {string} name - Name of the subscription.
+     * @param {SubscriptionMetadata} metadata - Metadata including type, category, rate, description, COS, and capacity plan.
+     * @param {SubscriptionSettings} settings - Settings including status, visibility, and system flags.
+     * @param {ISODateString} [timestamp=new Date().toISOString()] - Optional creation timestamp.
+     * @param {ISODateString} [last_update=new Date().toISOString()] - Optional last update timestamp.
+     */
+    constructor(id: SubscriptionID | undefined, slug: string | undefined, name: string, metadata: SubscriptionMetadata, settings: SubscriptionSettings, timestamp?: ISODateString, last_update?: ISODateString);
+    /** Marks finance calculations as dirty for lazy recomputation */
+    private markFinanceDirty;
+    /**
+     * Returns a zero-value MajikMoney object in the subscription currency.
+     * @param {string} [currencyCode] - Optional currency code. Defaults to subscription rate currency or PHP.
+     * @returns {MajikMoney} - A zero-value MajikMoney instance.
+     */
+    private DEFAULT_ZERO;
+    /**
+     * Initializes and creates a new `MajikSubscription` with default and null values.
+     * @param type - The type of service to initialize. Defaults to `TIME_BASED`. Use Enum `ServiceType`.
+     * @returns A new `MajikSubscription` instance.
+     */
+    static initialize(name: string, type: SubscriptionType | undefined, rate: SubscriptionRate, category?: string, descriptionText?: string, skuID?: string): MajikSubscription;
+    /**
+     * Updates the subscription name and regenerates the slug.
+     * @param {string} name - New subscription name.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    setName(name: string): this;
+    /**
+     * Updates the subscription rate.
+     * @param {SubscriptionRate} rate - New rate object.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    setRate(rate: SubscriptionRate): this;
+    /**
+     * Updates the rate unit.
+     * @param {RateUnit} unit - New rate unit (e.g., per subscriber, per month).
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    setRateUnit(unit: RateUnit): this;
+    /**
+     * Updates the numeric rate amount.
+     * @param {number} amount - New rate amount (must be positive).
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if amount is non-positive.
+     */
+    setRateAmount(amount: number): this;
+    /**
+     * Updates the subscription category.
+     * @param {string} category - New category name.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    setCategory(category: string): this;
+    /**
+     * Updates the HTML and plain text of the subscription description.
+     * @param {string} html - The new HTML description.
+     * @param {string} text - The new plain text description.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if either html or text is invalid.
+     */
+    setDescription(html: string, text: string): this;
+    /**
+     * Updates only the plain text of the subscription description.
+     * @param {string} text - The new plain text description.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if text is invalid.
+     */
+    setDescriptionText(text: string): this;
+    /**
+     * Updates only the HTML of the subscription description.
+     * @param {string} html - The new HTML description.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if html is invalid.
+     */
+    setDescriptionHTML(html: string): this;
+    /**
+     * Updates SEO-friendly text of the subscription description.
+     * @param {string} text - SEO text.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    setDescriptionSEO(text: string): this;
+    /**
+     * Updates the Type of the Subscription.
+     * @param type - The new Type of the Subscription. Use Enum `SubscriptionType`.
+     * @throws Will throw an error if the `type` is not provided or is not a string.
+     */
+    setType(type: SubscriptionType): this;
+    /**
+     * Returns SEO text if available; otherwise the plain text description.
+     * @returns {string} - SEO or plain text description.
+     */
+    get seo(): string;
+    /**
+     * Returns true if the subscription has at least one COS (cost breakdown) item.
+     */
+    hasCostBreakdown(): boolean;
+    /**
+     * Adds a new COS (Cost of Subscription) item.
+     * @param {string} name - COS item name.
+     * @param {MajikMoney} unitCost - Cost per unit.
+     * @param {number} [quantity=1] - Number of units.
+     * @param {string} [unit] - Optional unit (e.g., "subscriber", "month").
+     * @returns {MajikSubscription} - Returns self for chaining.
+     */
+    addCOS(name: string, unitCost: MajikMoney, quantity?: number, unit?: string): this;
+    /**
+     * Pushes an existing COSItem into the metadata.
+     * @param {COSItem} item - COSItem to add.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if item is missing required properties or has currency mismatch.
+     */
+    pushCOS(item: COSItem): this;
+    /**
+     * Updates an existing COS item by ID.
+     * @param {string} id - COS item ID.
+     * @param {Partial<Pick<COSItem, "quantity" | "unitCost" | "unit">>} updates - Fields to update.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if the COS item does not exist or has invalid updates.
+     */
+    updateCOS(id: string, updates: Partial<Pick<COSItem, "quantity" | "unitCost" | "unit" | "item">>): this;
+    /**
+     * Replaces all COS items with a new array.
+     * @param {COSItem[]} items - Array of COS items.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if items are missing required properties or have currency mismatch.
+     */
+    setCOS(items: COSItem[]): this;
+    /**
+     * Removes a COS item by ID.
+     * @param {string} id - COS item ID.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if the COS item does not exist.
+     */
+    removeCOS(id: string): this;
+    /** Clears all COS items. */
+    clearCostBreakdown(): this;
+    /**
+     * Returns true if the subscription has at least one Capacity Plan item.
+     */
+    hasCapacity(): boolean;
+    /**
+     * Returns the earliest (initial) YYYYMM from the capacity plan.
+     */
+    get earliestCapacityMonth(): YYYYMM | null;
+    /**
+     * Returns the most recent (latest) YYYYMM from the capacity plan.
+     */
+    get latestCapacityMonth(): YYYYMM | null;
+    get capacity(): MonthlyCapacity[];
+    /**
+     * Returns the total capacity units across all months.
+     */
+    get totalCapacity(): number;
+    /**
+     * Returns the average capacity per month.
+     * Includes adjustments.
+     */
+    get averageMonthlyCapacity(): number;
+    /**
+     * Returns the MonthlyCapacity entry with the highest supply.
+     * Includes adjustments.
+     */
+    get maxSupplyMonth(): MonthlyCapacity | null;
+    /**
+     * Returns the MonthlyCapacity entry with the lowest supply.
+     * Includes adjustments.
+     */
+    get minSupplyMonth(): MonthlyCapacity | null;
+    /**
+     * Generates and replaces the capacity plan automatically.
+     *
+     * @param months - Number of months to generate from the start date.
+     * @param amount - Base units for the first month.
+     * @param growthRate - Optional growth rate per month (e.g. 0.03 = +3%).
+     * @param startDate - Date | ISO date | YYYYMM. Defaults to current month.
+     * @returns {this} Updated subscription instance.
+     */
+    generateCapacityPlan(months: number, amount: number, growthRate?: number, startDate?: StartDateInput): this;
+    /**
+     * Normalizes all supply plan entries to have the same unit amount.
+     *
+     * - Throws if supply plan is empty
+     * - If only one entry exists, does nothing
+     * - If multiple entries exist, sets all units to the provided amount
+     *
+     * @param amount - Unit amount to apply to all months
+     * @returns {this} Updated subscription instance
+     */
+    normalizeCapacityUnits(amount: number): this;
+    recomputeCapacityPeriod(start: YYYYMM, end: YYYYMM, mode?: CapacityPeriodResizeMode): this;
+    /**
+     * Sets the entire monthly capacity plan.
+     * @param {MonthlyCapacity[]} capacityPlan - Array of MonthlyCapacity.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if month format or capacity is invalid.
+     */
+    setCapacity(capacityPlan: MonthlyCapacity[]): this;
+    /**
+     * Adds capacity for a specific month.
+     * @param {YYYYMM} month - YYYY-MM string.
+     * @param {number} units - Number of subscription units for the month.
+     * @param {number} [adjustment] - Optional adjustment to capacity.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if month already exists.
+     */
+    addCapacity(month: YYYYMM, units: number, adjustment?: number): this;
+    /**
+     * Updates capacity units for a month.
+     * @param {YYYYMM} month - YYYY-MM string.
+     * @param {number} units - New subscription units.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if month does not exist.
+     */
+    updateCapacityUnits(month: YYYYMM, units: number): this;
+    /**
+     * Updates capacity adjustment for a month.
+     * @param {YYYYMM} month - YYYY-MM string.
+     * @param {number} [adjustment] - Optional adjustment value.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if month does not exist.
+     */
+    updateCapacityAdjustment(month: YYYYMM, adjustment?: number): this;
+    /**
+     * Removes a month from the capacity plan.
+     * @param {YYYYMM} month - YYYY-MM string.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws Will throw an error if month does not exist.
+     */
+    removeCapacity(month: YYYYMM): this;
+    /** Clears the entire capacity plan. */
+    clearCapacity(): this;
+    /** Computes gross revenue across all months. */
+    private computeGrossRevenue;
+    /** Computes gross COS across all months. */
+    private computeGrossCOS;
+    /** Computes gross profit (revenue - COS). */
+    private computeGrossProfit;
+    /** Recomputes and stores aggregate finance info. */
+    private recomputeFinance;
+    get averageMonthlyRevenue(): MajikMoney;
+    get averageMonthlyProfit(): MajikMoney;
+    /**
+     * Returns total gross revenue across all months.
+     * @returns {MajikMoney} - Gross revenue.
+     */
+    get grossRevenue(): MajikMoney;
+    /**
+     * Returns total gross cost of subscription (COS) across all months.
+     * @returns {MajikMoney} - Gross COS.
+     */
+    get grossCost(): MajikMoney;
+    /**
+     * Returns total gross profit across all months.
+     * @returns {MajikMoney} - Gross profit.
+     */
+    get grossProfit(): MajikMoney;
+    /**
+     * Returns net revenue (same as gross in this model).
+     * @returns {MajikMoney} - Net revenue.
+     */
+    get netRevenue(): MajikMoney;
+    /**
+     * Returns net profit (same as gross in this model).
+     * @returns {MajikMoney} - Net profit.
+     */
+    get netProfit(): MajikMoney;
+    get unitCost(): MajikMoney;
+    get unitProfit(): MajikMoney;
+    get unitMargin(): number;
+    get price(): MajikMoney;
+    getMonthlySnapshot(month: YYYYMM): {
+        month: `${number}${number}${number}${number}-${number}${number}`;
+        revenue: MajikMoney;
+        cogs: MajikMoney;
+        profit: MajikMoney;
+        margin: number;
+        netRevenue: MajikMoney;
+        netIncome: MajikMoney;
+    };
+    /**
+     * Calculates Net Revenue for a given month.
+     * @param month - YYYYMM
+     * @param discounts - Total discounts for the month (optional)
+     * @param returns - Total returns for the month (optional)
+     * @param allowances - Total allowances for the month (optional)
+     * @returns {MajikMoney} Net Revenue
+     */
+    getNetRevenue(month: YYYYMM, discounts?: MajikMoney, returns?: MajikMoney, allowances?: MajikMoney): MajikMoney;
+    /**
+     * Calculates Net Profit for a given month.
+     * @param month - YYYYMM
+     * @param operatingExpenses - Total operating expenses (optional)
+     * @param taxes - Total taxes (optional)
+     * @param discounts - Total discounts for the month (optional)
+     * @param returns - Total returns for the month (optional)
+     * @param allowances - Total allowances for the month (optional)
+     * @returns {MajikMoney} Net Profit
+     */
+    getNetProfit(month: YYYYMM, operatingExpenses?: MajikMoney, taxes?: MajikMoney, discounts?: MajikMoney, returns?: MajikMoney, allowances?: MajikMoney): MajikMoney;
+    /**
+     * Alias for getNetProfit, same as Net Income
+     */
+    getNetIncome(month: YYYYMM, operatingExpenses?: MajikMoney, taxes?: MajikMoney, discounts?: MajikMoney, returns?: MajikMoney, allowances?: MajikMoney): MajikMoney;
+    /**
+     * Returns revenue for a specific month.
+     * @param {YYYYMM} month - Month in YYYY-MM format.
+     * @returns {MajikMoney} - Monthly revenue.
+     */
+    getRevenue(month: YYYYMM): MajikMoney;
+    /**
+     * Returns all COS items.
+     * @returns {readonly COSItem[]} - Array of COS items.
+     */
+    get cos(): readonly COSItem[];
+    /**
+     * Returns COS for a specific month.
+     * @param {YYYYMM} month - Month in YYYY-MM format.
+     * @returns {MajikMoney} - Monthly COS.
+     */
+    getCOS(month: YYYYMM): MajikMoney;
+    /**
+     * Alias for Get COS. Retrieves COS for a given month.
+     * @param month - YYYYMM month.
+     * @returns {MajikMoney} COS for the month.
+     */
+    getCost(month: YYYYMM): MajikMoney;
+    /**
+     * Returns profit for a specific month.
+     * @param {YYYYMM} month - Month in YYYY-MM format.
+     * @returns {MajikMoney} - Monthly profit.
+     */
+    getProfit(month: YYYYMM): MajikMoney;
+    /**
+     * Returns profit margin (as a decimal) for a specific month.
+     * @param {YYYYMM} month - Month in YYYY-MM format.
+     * @returns {number} - Profit margin (0–1).
+     */
+    getMargin(month: YYYYMM): number;
+    /**
+     * Applies a trial period to the subscription by reducing the capacity or revenue for the given number of months.
+     * @param {number} months - Number of months for the trial period.
+     * @returns {MajikSubscription} - Returns self for chaining.
+     * @throws {Error} - Throws if months is not a positive integer.
+     */
+    applyTrial(months: number): this;
+    /**
+     * Computes the next billing date for the subscription.
+     * Assumes subscription billing is monthly and starts at the first month in the capacity plan.
+     * @returns {ISODateString | null} - Next billing date in ISO format, or null if no capacity plan exists.
+     */
+    nextBillingDate(): ISODateString | null;
+    /**
+     * Forecasts revenue for the next N months based on current rate and capacity plan.
+     * @param {number} nextNMonths - Number of future months to forecast.
+     * @returns {MajikMoney} - Forecasted revenue as MajikMoney.
+     * @throws {Error} - Throws if nextNMonths is not a positive integer.
+     */
+    forecastRevenue(nextNMonths: number): MajikMoney;
+    /** Monthly Recurring Revenue (MRR) for a specific month or current month if not provided */
+    getMRR(month?: YYYYMM): MajikMoney;
+    /** Annual Recurring Revenue (ARR) based on sum of next 12 months revenue
+     *
+     * Forecasts revenue for the next N months based on current rate and capacity plan.
+     * @param {number} months - Number of future months to forecast. Defaults to 12.
+     */
+    getARR(months?: number): MajikMoney;
+    /**
+     * Validates the subscription instance.
+     * @param {boolean} [throwError=false] - Whether to throw an error on first invalid property.
+     * @returns {boolean} - True if valid, false if invalid and throwError is false.
+     * @throws {Error} - Throws error if throwError is true and a required field is missing/invalid.
+     */
+    validateSelf(throwError?: boolean): boolean;
+    /**
+     * Converts the subscription to a plain object and generates a new ID.
+     * @returns {object} - Serialized subscription.
+     */
+    finalize(): object;
+    /**
+     * Converts the subscription instance to a plain JSON object.
+     * @returns {object} - Plain object representation.
+     */
+    toJSON(): object;
+    /**
+     * Parses a plain object or JSON string into a MajikSubscription instance.
+     * @param {string | object} json - JSON string or object.
+     * @returns {MajikSubscription} - Parsed subscription instance.
+     * @throws {Error} - Throws if required properties are missing.
+     */
+    static parseFromJSON(json: string | object): MajikSubscription;
+    /**
+     * Updates the last_update timestamp to current time.
+     * Should be called whenever a property is modified.
+     * @private
+     */
+    private updateTimestamp;
+    /**
+     * Ensures the given MajikMoney object matches the subscription currency.
+     * @param {MajikMoney} money - Money object to validate.
+     * @private
+     * @throws {Error} - Throws if currency does not match subscription rate.
+     */
+    private assertCurrency;
+}
+export declare function isMajikSubscriptionClass(item: MajikSubscription): boolean;
+export declare function isMajikSubscriptionJSON(item: MajikSubscription): boolean;