@thezelijah/majik-subscription 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+import { MajikMoney } from "@thezelijah/majik-money";
+import { BillingCycle, RateUnit, SubscriptionStatus, SubscriptionType, SubscriptionVisibility } from "./enums";
+export type ObjectType = "class" | "json";
+export type SubscriptionID = string;
+export type SubscriptionSKU = string;
+export type ISODateString = string;
+export type YYYYMM = `${number}${number}${number}${number}-${number}${number}`;
+export type StartDateInput = Date | ISODateString | YYYYMM;
+/**
+ * Represents a Cost of Subscription (COS) item.
+ * E.g., infrastructure, hosting, support, software licenses.
+ */
+export interface COSItem {
+    id: string;
+    item: string;
+    unitCost: MajikMoney;
+    quantity: number;
+    subtotal: MajikMoney;
+    unit?: string;
+}
+/**
+ * Optional monthly subscription capacity plan entry.
+ * Could represent max allowed subscribers or seats per month.
+ */
+export interface MonthlyCapacity {
+    month: YYYYMM;
+    capacity: number;
+    adjustment?: number;
+}
+/**
+ * Value with margin ratio for finance snapshots.
+ */
+export interface ValueRatio {
+    value: MajikMoney;
+    marginRatio: number;
+}
+/**
+ * Subscription finance information.
+ */
+export interface SubscriptionFinance {
+    profit: {
+        gross: ValueRatio;
+        net: ValueRatio;
+    };
+    revenue: {
+        gross: ValueRatio;
+        net: ValueRatio;
+    };
+    income: {
+        gross: ValueRatio;
+        net: ValueRatio;
+    };
+    cos: {
+        gross: ValueRatio;
+        net: ValueRatio;
+    };
+}
+/**
+ * Subscription rate object: amount + billing unit.
+ */
+export interface SubscriptionRate {
+    amount: MajikMoney;
+    unit: RateUnit;
+    billingCycle: BillingCycle;
+}
+/**
+ * Metadata of a subscription.
+ */
+export interface SubscriptionMetadata {
+    sku?: SubscriptionSKU;
+    description: {
+        text: string;
+        html?: string;
+        seo?: string;
+    };
+    photos?: string[];
+    type: SubscriptionType;
+    category: string;
+    rate: SubscriptionRate;
+    cos: COSItem[];
+    capacityPlan?: MonthlyCapacity[];
+    /** Cached finance snapshot */
+    finance: SubscriptionFinance;
+}
+/**
+ * Subscription settings including visibility and status.
+ */
+export interface SubscriptionSettings {
+    status: SubscriptionStatus;
+    visibility: SubscriptionVisibility;
+    system?: {
+        isRestricted: boolean;
+        restrictedUntil?: ISODateString;
+    };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.d.ts

@@ -0,0 +1,26 @@
+import { SubscriptionFinance, StartDateInput, ValueRatio, YYYYMM } from "./types";
+/**
+ * Generates a URL-friendly slug from the name,
+ * appending a Unix timestamp to ensure uniqueness.
+ *
+ * @param name - The name to base the slug on.
+ * @returns A unique slug string.
+ */
+export declare function generateSlug(name: string): string;
+/**
+ * Generates a unique, URL-safe ID for an item based on its name and current timestamp.
+ *
+ * @param prefix - The prefix string name to add.
+ * @returns A unique ID string prefixed.
+ */
+export declare function autogenerateID(prefix?: string): string;
+export declare function isValidYYYYMM(month: string): month is YYYYMM;
+export declare function createZeroValueRatio(currencyCode: string): ValueRatio;
+export declare function createEmptySubscriptionFinance(currencyCode: string): SubscriptionFinance;
+export declare function isoToYYYYMM(isoDate: string): YYYYMM;
+export declare function yyyyMMToISO(yyyyMM: YYYYMM): string;
+export declare function dateToYYYYMM(date: Date): YYYYMM;
+export declare function yyyyMMToDate(yyyyMM: YYYYMM): Date;
+export declare function offsetMonthsToYYYYMM(input: StartDateInput, offsetMonths: number): YYYYMM;
+export declare function monthsInPeriod(earlier: YYYYMM, later: YYYYMM): number;
+export declare function normalizeStartDate(input?: StartDateInput): Date;

package/dist/utils.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSlug = generateSlug;
+exports.autogenerateID = autogenerateID;
+exports.isValidYYYYMM = isValidYYYYMM;
+exports.createZeroValueRatio = createZeroValueRatio;
+exports.createEmptySubscriptionFinance = createEmptySubscriptionFinance;
+exports.isoToYYYYMM = isoToYYYYMM;
+exports.yyyyMMToISO = yyyyMMToISO;
+exports.dateToYYYYMM = dateToYYYYMM;
+exports.yyyyMMToDate = yyyyMMToDate;
+exports.offsetMonthsToYYYYMM = offsetMonthsToYYYYMM;
+exports.monthsInPeriod = monthsInPeriod;
+exports.normalizeStartDate = normalizeStartDate;
+const nanoid_1 = require("nanoid");
+const majik_money_1 = require("@thezelijah/majik-money");
+/**
+ * Generates a URL-friendly slug from the name,
+ * appending a Unix timestamp to ensure uniqueness.
+ *
+ * @param name - The name to base the slug on.
+ * @returns A unique slug string.
+ */
+function generateSlug(name) {
+    // Create the generator function ONCE with your custom alphabet and length
+    const generateSlugID = (0, nanoid_1.customAlphabet)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 6);
+    const genUID = generateSlugID(); // e.g., 'X4tF9z'
+    const slugText = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return `${slugText}-${genUID}`;
+}
+/**
+ * Generates a unique, URL-safe ID for an item based on its name and current timestamp.
+ *
+ * @param prefix - The prefix string name to add.
+ * @returns A unique ID string prefixed.
+ */
+function autogenerateID(prefix = "majik") {
+    // Create the generator function ONCE with your custom alphabet and length
+    const generateID = (0, nanoid_1.customAlphabet)("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz", 8);
+    // Call the generator function to produce the actual ID string
+    const genUID = generateID(); // Example output: 'G7K2aZp9'
+    return `${prefix}-${genUID}`;
+}
+function isValidYYYYMM(month) {
+    return /^\d{4}-0[1-9]|1[0-2]$/.test(month);
+}
+function createZeroValueRatio(currencyCode) {
+    const zero = majik_money_1.MajikMoney.fromMinor(0, currencyCode);
+    return {
+        value: zero,
+        marginRatio: 0,
+    };
+}
+function createEmptySubscriptionFinance(currencyCode) {
+    return {
+        revenue: {
+            gross: createZeroValueRatio(currencyCode),
+            net: createZeroValueRatio(currencyCode),
+        },
+        income: {
+            gross: createZeroValueRatio(currencyCode),
+            net: createZeroValueRatio(currencyCode),
+        },
+        profit: {
+            gross: createZeroValueRatio(currencyCode),
+            net: createZeroValueRatio(currencyCode),
+        },
+        cos: {
+            gross: createZeroValueRatio(currencyCode),
+            net: createZeroValueRatio(currencyCode),
+        },
+    };
+}
+function isoToYYYYMM(isoDate) {
+    const date = new Date(isoDate);
+    if (isNaN(date.getTime())) {
+        throw new Error("Invalid ISO date");
+    }
+    // Use UTC to avoid date shifting backwards/forwards based on timezone
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    return `${year}-${month}`;
+}
+function yyyyMMToISO(yyyyMM) {
+    const [year, month] = yyyyMM.split("-").map(Number);
+    // Construct as UTC Midnight
+    return new Date(Date.UTC(year, month - 1, 1)).toISOString();
+}
+function dateToYYYYMM(date) {
+    if (isNaN(date.getTime())) {
+        throw new Error("Invalid Date object");
+    }
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    return `${year}-${month}`;
+}
+function yyyyMMToDate(yyyyMM) {
+    const [year, month] = yyyyMM.split("-").map(Number);
+    return new Date(Date.UTC(year, month - 1, 1));
+}
+function offsetMonthsToYYYYMM(input, offsetMonths) {
+    const date = normalizeStartDate(input);
+    // Since normalizeStartDate now returns a UTC date,
+    // we can safely use UTC methods here.
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + offsetMonths;
+    const result = new Date(Date.UTC(year, month, 1));
+    return dateToYYYYMM(result);
+}
+function monthsInPeriod(earlier, later) {
+    const start = yyyyMMToDate(earlier);
+    const end = yyyyMMToDate(later);
+    const startYear = start.getUTCFullYear();
+    const startMonth = start.getUTCMonth();
+    const endYear = end.getUTCFullYear();
+    const endMonth = end.getUTCMonth();
+    return (endYear - startYear) * 12 + (endMonth - startMonth) + 1;
+}
+function normalizeStartDate(input) {
+    if (!input) {
+        const now = new Date();
+        // Return UTC version of the first of the current month
+        return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    }
+    // YYYYMM (e.g. "2025-03")
+    if (typeof input === "string" && /^\d{4}-\d{2}$/.test(input)) {
+        const [yyyy, mm] = input.split("-").map(Number);
+        // FIX: Use Date.UTC instead of new Date(yyyy, mm-1, 1)
+        return new Date(Date.UTC(yyyy, mm - 1, 1));
+    }
+    // ISO string
+    if (typeof input === "string") {
+        const date = new Date(input);
+        if (!isNaN(date.getTime())) {
+            return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1));
+        }
+    }
+    // Date instance
+    if (input instanceof Date && !isNaN(input.getTime())) {
+        return new Date(Date.UTC(input.getUTCFullYear(), input.getUTCMonth(), 1));
+    }
+    throw new Error("Invalid startDate format");
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@thezelijah/majik-subscription",
+  "version": "1.0.0",
+  "description": "Majik Subscription is a fully-featured class representing a subscription-based offering in the Majik system, designed for recurring revenue modeling, cost tracking, and subscriber capacity planning. It provides utilities for computing MRR, ARR, revenue, profit, margins, Cost of Subscription (COS), and net income on a per-period basis. Chainable setter methods make it easy to construct and update subscriptions fluently.",
+  "license": "ISC",
+  "author": "Zelijah",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jedlsf/majik-subscription.git"
+  },
+ "keywords": [
+  "majik",
+  "majik-subscription",
+  "subscription-management",
+  "subscription-finance",
+  "cost-of-subscription",
+  "COS",
+  "revenue-calculation",
+  "profit-calculation",
+  "financial-modeling",
+  "capacity-planning",
+  "resource-planning",
+  "timesheet",
+  "billing",
+  "pricing",
+  "business-tools",
+  "typescript",
+  "javascript",
+  "enterprise-tools",
+  "monetary-calculation",
+  "majik-money",
+  "subscription-analytics",
+  "forecasting"
+],
+  "homepage": "https://github.com/jedlsf/majik-subscription#readme",
+  "bugs": {
+    "url": "https://github.com/jedlsf/majik-subscription/issues"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@thezelijah/majik-money": "^1.0.3",
+    "nanoid": "^5.1.6",
+    "typescript": "^5.9.3"
+  }
+}