@serialsubscriptions/platform-integration 0.0.79

package/lib/SubscribedPlanManager.d.ts

@@ -0,0 +1,380 @@
+/**
+ * @file
+ * SubscribedPlanManager - High-level manager for subscribed plans with features and limits
+ *
+ * This manager wires together the three JSON:API clients (SSISubscribedPlanApi,
+ * SSISubscribedFeatureApi, SSISubscribedLimitApi) and provides a convenient interface
+ * for fetching subscribed plans with their associated features and limits already attached.
+ *
+ * Usage:
+ * @example
+ * ```typescript
+ * const domain = 'https://account.serialsubscriptionsdev.com';
+ * const manager = new SubscribedPlanManager(domain);
+ *
+ * // Optional: set OAuth/JWT Bearer token if needed
+ * manager.setBearerToken('YOUR_ACCESS_TOKEN');
+ *
+ * // Get all plans with features and limits
+ * const allPlans = await manager.getAllPlans();
+ *
+ * // Get a single plan by internal numeric ID
+ * const plan = await manager.getPlanById(1);
+ *
+ * // Get plans by project ID
+ * const projectPlans = await manager.getPlansByProjectId(42);
+ *
+ * // Get plans by user internal ID
+ * const userPlans = await manager.getPlansByUserId(3);
+ * ```
+ */
+import { type JsonApiResource } from './SSISubscribedPlanApi';
+/**
+ * Attributes for a subscribed_plan--subscribed_plan resource.
+ * Based on your JSON sample; extra fields will still be present in the raw JSON:API resource.
+ */
+export interface SubscribedPlanAttributes {
+    drupal_internal__id: number;
+    name: string;
+    status: string;
+    subscription_period: string;
+    name_subscript: string | null;
+    most_popular: boolean;
+    free_trial: boolean;
+    free_trial_days: number;
+    description: string | null;
+    description_features: {
+        value: string | null;
+        format: string | null;
+        processed: string | null;
+    } | null;
+    order: number;
+    price_show: boolean;
+    price_monthly: string;
+    price_monthly_subscript: string | null;
+    price_annually: string;
+    price_annually_subscript: string | null;
+    price_discounted: boolean;
+    price_discount_monthly: string;
+    price_discount_annually: string;
+    price_discount_months: number;
+    price_discount_years: number;
+    button_cta: string;
+    footer_description: string | null;
+    active_date: string | null;
+    archive_date: string | null;
+    trial_end_date: string | null;
+    created: string;
+    changed: string;
+    organization_id: number;
+    project_id: number | null;
+    metadata: unknown | null;
+    [key: string]: unknown;
+}
+/**
+ * Attributes for a subscribed_feature--subscribed_feature resource.
+ */
+export interface SubscribedFeatureAttributes {
+    drupal_internal__id: number;
+    feature_name: string;
+    feature_category: string;
+    feature_type: string;
+    feature_value: string | null;
+    order: number;
+    created: string;
+    changed: string;
+    [key: string]: unknown;
+}
+/**
+ * Attributes for a subscribed_limit--subscribed_limit resource.
+ */
+export interface SubscribedLimitAttributes {
+    drupal_internal__id: number;
+    limit_name: string;
+    limit_description: string;
+    status: boolean;
+    limit_units: string;
+    limit_units_plural: string;
+    limit_type: string;
+    limit_value: number;
+    limit_period: string;
+    base_fee: string;
+    limit_rate: number;
+    allow_overage: boolean;
+    overage_rate: number;
+    overage_limit: number;
+    order: number;
+    created: string;
+    changed: string;
+    [key: string]: unknown;
+}
+export interface SubscribedFeature extends SubscribedFeatureAttributes {
+    /**
+     * UUID of the subscribed_feature entity.
+     */
+    uuid: string;
+    /**
+     * Raw JSON:API relationships if you need them.
+     */
+    relationships?: JsonApiResource['relationships'];
+}
+export interface SubscribedLimit extends SubscribedLimitAttributes {
+    /**
+     * UUID of the subscribed_limit entity.
+     */
+    uuid: string;
+    relationships?: JsonApiResource['relationships'];
+}
+/**
+ * High-level plan object with its features and limits already attached.
+ */
+export interface SubscribedPlan extends SubscribedPlanAttributes {
+    /**
+     * UUID of the subscribed_plan entity.
+     */
+    uuid: string;
+    relationships?: JsonApiResource['relationships'];
+    /**
+     * Features attached to this subscribed plan.
+     */
+    features: SubscribedFeature[];
+    /**
+     * Limits attached to this subscribed plan.
+     */
+    limits: SubscribedLimit[];
+}
+export interface SubscribedPlanManagerOptions {
+    /**
+     * Override the JSON:API base path for subscribed plans.
+     * Default: '/jsonapi/subscribed_plan/subscribed_plan'
+     */
+    planApiBasePath?: string;
+    /**
+     * Override the JSON:API base path for subscribed features.
+     * Default: '/jsonapi/subscribed_feature/subscribed_feature'
+     */
+    featureApiBasePath?: string;
+    /**
+     * Override the JSON:API base path for subscribed limits.
+     * Default: '/jsonapi/subscribed_limit/subscribed_limit'
+     */
+    limitApiBasePath?: string;
+    /**
+     * Optional request timeout (ms) if your API clients support it.
+     */
+    timeout?: number;
+}
+/**
+ * SubscribedPlanManager
+ *
+ * Fetches subscribed plans and hydrates each with its subscribed features and limits.
+ *
+ * Filtering conventions (using internal integer IDs):
+ * - By plan ID:    filter[drupal_internal__id]={subscribed_plan_int_id}
+ * - By project ID: filter[project_id]={project_int_id}
+ * - By user ID:    filter[user_id.meta.drupal_internal__target_id]={user_int_id}
+ *
+ * For features/limits attached to a plan:
+ * - filter[subscribed_plan_id.meta.drupal_internal__target_id]={subscribed_plan_int_id}
+ */
+export declare class SubscribedPlanManager {
+    private planApi;
+    private featureApi;
+    private limitApi;
+    private featureCache;
+    private limitCache;
+    private static readonly CACHE_TTL_SEC;
+    constructor(domain: string, options?: SubscribedPlanManagerOptions);
+    /**
+     * Set a shared Bearer token on all three underlying API clients.
+     */
+    setBearerToken(token: string): void;
+    /**
+     * Get *all* subscribed plans for the current context,
+     * each with its features[] and limits[].
+     */
+    getAllPlans(): Promise<SubscribedPlan[]>;
+    /**
+     * Get a single subscribed plan by its internal numeric ID
+     * (attributes.drupal_internal__id), with features[] and limits[].
+     */
+    getPlanById(subscribedPlanId: number): Promise<SubscribedPlan | null>;
+    /**
+     * Get all subscribed plans for a given project_id.
+     *
+     * Uses: ?filter[project_id]={project_int_id}
+     */
+    getPlansByProjectId(projectId: number): Promise<SubscribedPlan[]>;
+    /**
+     * Filter an array of plans by project_id.
+     *
+     * @param plans - Array of subscribed plans to filter.
+     * @param projectId - The project ID to filter by.
+     * @returns Array of plans that match the project ID.
+     */
+    getPlanByProjectId(plans: SubscribedPlan[], projectId: number): SubscribedPlan[];
+    /**
+     * Get all subscribed plans for a given user (internal user ID).
+     *
+     * Uses: ?filter[user_id.meta.drupal_internal__target_id]={user_int_id}
+     */
+    getPlansByUserId(userId: number): Promise<SubscribedPlan[]>;
+    /**
+     * Get the internal numeric ID of a limit by its name from a plan.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit to find.
+     * @returns The internal numeric ID (drupal_internal__id) of the limit, or null if not found.
+     */
+    getLimitId(plan: SubscribedPlan, limit_name: string): number | null;
+    /**
+     * Internal helper to find a limit by name or ID.
+     */
+    private findLimit;
+    /**
+     * Check if a limit is enabled (status is true).
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit to check.
+     * @returns True if the limit exists and is enabled, false otherwise.
+     */
+    isLimitEnabled(plan: SubscribedPlan, limit_name: string): boolean;
+    /**
+     * Check if a limit is enabled (status is true).
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit to check.
+     * @returns True if the limit exists and is enabled, false otherwise.
+     */
+    isLimitEnabled(plan: SubscribedPlan, limit_id: number): boolean;
+    /**
+     * Get the type of a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The limit_type, or null if not found.
+     */
+    getLimitType(plan: SubscribedPlan, limit_name: string): string | null;
+    /**
+     * Get the type of a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The limit_type, or null if not found.
+     */
+    getLimitType(plan: SubscribedPlan, limit_id: number): string | null;
+    /**
+     * Get the maximum value (limit_value) of a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The limit_value, or null if not found.
+     */
+    getLimitMax(plan: SubscribedPlan, limit_name: string): number | null;
+    /**
+     * Get the maximum value (limit_value) of a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The limit_value, or null if not found.
+     */
+    getLimitMax(plan: SubscribedPlan, limit_id: number): number | null;
+    /**
+     * Check if a limit allows overage.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns True if allow_overage is true, false otherwise.
+     */
+    limitAllowsOverage(plan: SubscribedPlan, limit_name: string): boolean;
+    /**
+     * Check if a limit allows overage.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns True if allow_overage is true, false otherwise.
+     */
+    limitAllowsOverage(plan: SubscribedPlan, limit_id: number): boolean;
+    /**
+     * Get the maximum overage limit. Returns 0 if overage is not allowed.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The overage_limit if allow_overage is true, 0 otherwise.
+     */
+    limitOverageMax(plan: SubscribedPlan, limit_name: string): number;
+    /**
+     * Get the maximum overage limit. Returns 0 if overage is not allowed.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The overage_limit if allow_overage is true, 0 otherwise.
+     */
+    limitOverageMax(plan: SubscribedPlan, limit_id: number): number;
+    /**
+     * Get the units for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The limit_units, or null if not found.
+     */
+    getLimitUnits(plan: SubscribedPlan, limit_name: string): string | null;
+    /**
+     * Get the units for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The limit_units, or null if not found.
+     */
+    getLimitUnits(plan: SubscribedPlan, limit_id: number): string | null;
+    /**
+     * Get the plural units for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The limit_units_plural, or null if not found.
+     */
+    getLimitUnitsPlural(plan: SubscribedPlan, limit_name: string): string | null;
+    /**
+     * Get the plural units for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The limit_units_plural, or null if not found.
+     */
+    getLimitUnitsPlural(plan: SubscribedPlan, limit_id: number): string | null;
+    /**
+     * Get the period for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit.
+     * @returns The limit_period, or null if not found.
+     */
+    getLimitPeriod(plan: SubscribedPlan, limit_name: string): string | null;
+    /**
+     * Get the period for a limit.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_id - The internal numeric ID of the limit.
+     * @returns The limit_period, or null if not found.
+     */
+    getLimitPeriod(plan: SubscribedPlan, limit_id: number): string | null;
+    /**
+     * Internal: turn a JSON:API document of subscribed plans into hydrated SubscribedPlan[]
+     * with features[] and limits[] attached.
+     */
+    private hydratePlans;
+    /**
+     * Internal: hydrate a single plan resource with its features and limits.
+     * Features and limits are cached since they never change.
+     */
+    private hydrateSinglePlan;
+    /**
+     * Internal: map a subscribed_feature JSON:API document to SubscribedFeature[].
+     */
+    private mapFeatures;
+    /**
+     * Internal: map a subscribed_limit JSON:API document to SubscribedLimit[].
+     */
+    private mapLimits;
+}

package/lib/SubscribedPlanManager.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * @file
+ * SubscribedPlanManager - High-level manager for subscribed plans with features and limits
+ *
+ * This manager wires together the three JSON:API clients (SSISubscribedPlanApi,
+ * SSISubscribedFeatureApi, SSISubscribedLimitApi) and provides a convenient interface
+ * for fetching subscribed plans with their associated features and limits already attached.
+ *
+ * Usage:
+ * @example
+ * ```typescript
+ * const domain = 'https://account.serialsubscriptionsdev.com';
+ * const manager = new SubscribedPlanManager(domain);
+ *
+ * // Optional: set OAuth/JWT Bearer token if needed
+ * manager.setBearerToken('YOUR_ACCESS_TOKEN');
+ *
+ * // Get all plans with features and limits
+ * const allPlans = await manager.getAllPlans();
+ *
+ * // Get a single plan by internal numeric ID
+ * const plan = await manager.getPlanById(1);
+ *
+ * // Get plans by project ID
+ * const projectPlans = await manager.getPlansByProjectId(42);
+ *
+ * // Get plans by user internal ID
+ * const userPlans = await manager.getPlansByUserId(3);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscribedPlanManager = void 0;
+const SSISubscribedPlanApi_1 = require("./SSISubscribedPlanApi");
+const SSISubscribedFeatureApi_1 = require("./SSISubscribedFeatureApi");
+const SSISubscribedLimitApi_1 = require("./SSISubscribedLimitApi");
+const SSICache_1 = require("./cache/SSICache");
+/**
+ * SubscribedPlanManager
+ *
+ * Fetches subscribed plans and hydrates each with its subscribed features and limits.
+ *
+ * Filtering conventions (using internal integer IDs):
+ * - By plan ID:    filter[drupal_internal__id]={subscribed_plan_int_id}
+ * - By project ID: filter[project_id]={project_int_id}
+ * - By user ID:    filter[user_id.meta.drupal_internal__target_id]={user_int_id}
+ *
+ * For features/limits attached to a plan:
+ * - filter[subscribed_plan_id.meta.drupal_internal__target_id]={subscribed_plan_int_id}
+ */
+class SubscribedPlanManager {
+    constructor(domain, options = {}) {
+        const mkOptions = (apiBasePath) => apiBasePath || options.timeout
+            ? {
+                apiBasePath,
+                timeout: options.timeout,
+            }
+            : undefined;
+        this.planApi = new SSISubscribedPlanApi_1.SSISubscribedPlanApi(domain, mkOptions(options.planApiBasePath));
+        this.featureApi = new SSISubscribedFeatureApi_1.SSISubscribedFeatureApi(domain, mkOptions(options.featureApiBasePath));
+        this.limitApi = new SSISubscribedLimitApi_1.SSISubscribedLimitApi(domain, mkOptions(options.limitApiBasePath));
+        // Initialize cache instances with prefixes for features and limits
+        const baseCache = SSICache_1.SSICache.fromEnv();
+        this.featureCache = baseCache.withPrefix('features');
+        this.limitCache = baseCache.withPrefix('limits');
+    }
+    /**
+     * Set a shared Bearer token on all three underlying API clients.
+     */
+    setBearerToken(token) {
+        this.planApi.setBearerToken(token);
+        this.featureApi.setBearerToken(token);
+        this.limitApi.setBearerToken(token);
+    }
+    /**
+     * Get *all* subscribed plans for the current context,
+     * each with its features[] and limits[].
+     */
+    async getAllPlans() {
+        const doc = await this.planApi.list();
+        return this.hydratePlans(doc);
+    }
+    /**
+     * Get a single subscribed plan by its internal numeric ID
+     * (attributes.drupal_internal__id), with features[] and limits[].
+     */
+    async getPlanById(subscribedPlanId) {
+        const doc = await this.planApi.list({
+            filters: {
+                // ?filter[drupal_internal__id]={subscribedPlanId}
+                drupal_internal__id: subscribedPlanId,
+            },
+            pagination: {
+                limit: 1,
+            },
+        });
+        const plans = await this.hydratePlans(doc);
+        return plans[0] ?? null;
+    }
+    /**
+     * Get all subscribed plans for a given project_id.
+     *
+     * Uses: ?filter[project_id]={project_int_id}
+     */
+    async getPlansByProjectId(projectId) {
+        const doc = await this.planApi.list({
+            filters: {
+                project_id: projectId,
+            },
+        });
+        return this.hydratePlans(doc);
+    }
+    /**
+     * Filter an array of plans by project_id.
+     *
+     * @param plans - Array of subscribed plans to filter.
+     * @param projectId - The project ID to filter by.
+     * @returns Array of plans that match the project ID.
+     */
+    getPlanByProjectId(plans, projectId) {
+        return plans.filter((plan) => plan.project_id === projectId);
+    }
+    /**
+     * Get all subscribed plans for a given user (internal user ID).
+     *
+     * Uses: ?filter[user_id.meta.drupal_internal__target_id]={user_int_id}
+     */
+    async getPlansByUserId(userId) {
+        const doc = await this.planApi.list({
+            filters: {
+                'user_id.meta.drupal_internal__target_id': userId,
+            },
+        });
+        return this.hydratePlans(doc);
+    }
+    /**
+     * Get the internal numeric ID of a limit by its name from a plan.
+     *
+     * @param plan - The subscribed plan to search in.
+     * @param limit_name - The name of the limit to find.
+     * @returns The internal numeric ID (drupal_internal__id) of the limit, or null if not found.
+     */
+    getLimitId(plan, limit_name) {
+        const limit = plan.limits.find((l) => l.limit_name === limit_name);
+        return limit ? limit.drupal_internal__id : null;
+    }
+    /**
+     * Internal helper to find a limit by name or ID.
+     */
+    findLimit(plan, identifier) {
+        if (typeof identifier === 'string') {
+            return plan.limits.find((l) => l.limit_name === identifier) ?? null;
+        }
+        else {
+            return plan.limits.find((l) => l.drupal_internal__id === identifier) ?? null;
+        }
+    }
+    isLimitEnabled(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.status ?? false;
+    }
+    getLimitType(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.limit_type ?? null;
+    }
+    getLimitMax(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.limit_value ?? null;
+    }
+    limitAllowsOverage(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.allow_overage ?? false;
+    }
+    limitOverageMax(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        if (!limit || !limit.allow_overage) {
+            return 0;
+        }
+        return limit.overage_limit;
+    }
+    getLimitUnits(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.limit_units ?? null;
+    }
+    getLimitUnitsPlural(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.limit_units_plural ?? null;
+    }
+    getLimitPeriod(plan, identifier) {
+        const limit = this.findLimit(plan, identifier);
+        return limit?.limit_period ?? null;
+    }
+    /**
+     * Internal: turn a JSON:API document of subscribed plans into hydrated SubscribedPlan[]
+     * with features[] and limits[] attached.
+     */
+    async hydratePlans(doc) {
+        const data = Array.isArray(doc.data) ? doc.data : doc.data ? [doc.data] : [];
+        const plans = data.filter((resource) => resource.type === 'subscribed_plan--subscribed_plan');
+        const hydrated = [];
+        for (const planResource of plans) {
+            hydrated.push(await this.hydrateSinglePlan(planResource));
+        }
+        return hydrated;
+    }
+    /**
+     * Internal: hydrate a single plan resource with its features and limits.
+     * Features and limits are cached since they never change.
+     */
+    async hydrateSinglePlan(planResource) {
+        const attributes = (planResource.attributes || {});
+        const internalId = attributes.drupal_internal__id;
+        if (typeof internalId !== 'number') {
+            throw new Error('Subscribed plan is missing attributes.drupal_internal__id (required for feature/limit lookups).');
+        }
+        // Cache key format: plan:{internalId}
+        const featureCacheKey = `plan:${internalId}`;
+        const limitCacheKey = `plan:${internalId}`;
+        // Fetch features and limits in parallel, using cache with remember() pattern
+        const [features, limits] = await Promise.all([
+            this.featureCache.remember(featureCacheKey, SubscribedPlanManager.CACHE_TTL_SEC, async () => {
+                const featuresDoc = await this.featureApi.list({
+                    filters: {
+                        // ?filter[subscribed_plan_id.meta.drupal_internal__target_id]={internalId}
+                        'subscribed_plan_id.meta.drupal_internal__target_id': internalId,
+                    },
+                });
+                return this.mapFeatures(featuresDoc);
+            }),
+            this.limitCache.remember(limitCacheKey, SubscribedPlanManager.CACHE_TTL_SEC, async () => {
+                const limitsDoc = await this.limitApi.list({
+                    filters: {
+                        'subscribed_plan_id.meta.drupal_internal__target_id': internalId,
+                    },
+                });
+                return this.mapLimits(limitsDoc);
+            }),
+        ]);
+        const uuid = planResource.id ?? '';
+        const plan = {
+            uuid,
+            ...attributes,
+            relationships: planResource.relationships,
+            features,
+            limits,
+        };
+        return plan;
+    }
+    /**
+     * Internal: map a subscribed_feature JSON:API document to SubscribedFeature[].
+     */
+    mapFeatures(doc) {
+        const data = Array.isArray(doc.data) ? doc.data : doc.data ? [doc.data] : [];
+        return data
+            .filter((resource) => resource.type === 'subscribed_feature--subscribed_feature')
+            .map((resource) => {
+            const attrs = (resource.attributes || {});
+            const uuid = resource.id ?? '';
+            const feature = {
+                uuid,
+                ...attrs,
+                relationships: resource.relationships,
+            };
+            return feature;
+        });
+    }
+    /**
+     * Internal: map a subscribed_limit JSON:API document to SubscribedLimit[].
+     */
+    mapLimits(doc) {
+        const data = Array.isArray(doc.data) ? doc.data : doc.data ? [doc.data] : [];
+        return data
+            .filter((resource) => resource.type === 'subscribed_limit--subscribed_limit')
+            .map((resource) => {
+            const attrs = (resource.attributes || {});
+            const uuid = resource.id ?? '';
+            const limit = {
+                uuid,
+                ...attrs,
+                relationships: resource.relationships,
+            };
+            return limit;
+        });
+    }
+}
+exports.SubscribedPlanManager = SubscribedPlanManager;
+// Cache TTL: 24 hours (86400 seconds) - features and limits never change
+SubscribedPlanManager.CACHE_TTL_SEC = 86400;