@serialsubscriptions/platform-integration 0.0.8-5.1

package/lib/SubscribedPlanManager.d.ts

@@ -0,0 +1,400 @@
+/**
+ * @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);
+ *
+ * // Use the ACCESS_TOKEN from your session (not id_token). Set it before each request if the manager is shared.
+ * manager.setBearerToken(accessTokenFromSession);
+ *
+ * // 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 single plan for a project (or null)
+ * const plan = await manager.getPlanForProject(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.
+ */
+/**
+ * Known values for subscribed plan `status` (and for project `subscription_status`
+ * when synced from the platform). Document the full list in SUBSCRIBEDPLAN_MANAGER.md.
+ */
+export declare const SUBSCRIPTION_STATUS: {};
+export type SubscriptionStatusValue = (typeof SUBSCRIPTION_STATUS)[keyof typeof SUBSCRIPTION_STATUS] | string;
+export interface SubscribedPlanAttributes {
+    drupal_internal__id: number;
+    name: string;
+    /** Plan status from the platform. See SUBSCRIBEDPLAN_MANAGER.md for possible values. */
+    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.
+     * Use the OAuth access_token from your session (e.g. SessionManager.getSessionData(sessionId, 'access_token')).
+     * Do not use the id_token — the JSON:API expects the access_token for authorization.
+     * If the manager is shared across requests, call this with the current request's access_token before each API call.
+     */
+    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[]>;
+    /**
+     * Get the single subscribed plan for a given project_id (with features and limits).
+     * Returns the first matching plan, or null if none. Use when at most one plan per project.
+     *
+     * Uses: ?filter[project_id]={project_int_id}
+     */
+    getPlanForProject(projectId: number): Promise<SubscribedPlan | null>;
+    /**
+     * 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;
+}