@serialsubscriptions/platform-integration 0.0.8-5.1

package/lib/SubscribedPlanManager.js

@@ -0,0 +1,319 @@
+"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);
+ *
+ * // 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);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscribedPlanManager = exports.SUBSCRIPTION_STATUS = void 0;
+const SSISubscribedPlanApi_1 = require("./SSISubscribedPlanApi");
+const SSISubscribedFeatureApi_1 = require("./SSISubscribedFeatureApi");
+const SSISubscribedLimitApi_1 = require("./SSISubscribedLimitApi");
+const SSICache_1 = require("./cache/SSICache");
+/**
+ * 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.
+ */
+exports.SUBSCRIPTION_STATUS = {
+// Add values as the platform defines them, e.g.:
+// ACTIVE: 'active',
+// CANCELLED: 'cancelled',
+// TRIALING: 'trialing',
+// PAST_DUE: 'past_due',
+};
+/**
+ * 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.
+     * 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) {
+        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);
+    }
+    /**
+     * 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}
+     */
+    async getPlanForProject(projectId) {
+        const plans = await this.getPlansByProjectId(projectId);
+        return plans[0] ?? 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, 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;

package/lib/UsageApi.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Usage Reporting API Client
+ *
+ * Sends usage events to the subscription usage API endpoint.
+ * Requires a base URL and Bearer token for authentication.
+ */
+/**
+ * Usage event data structure
+ */
+export interface UsageEvent {
+    /** The internal ID of the Limit entity this usage event applies to (required) */
+    limit_id: number;
+    /** Positive usage amount for this event (optional, default: 1.0) */
+    amount?: number;
+    /** Project entity ID when mode supports projects (optional) */
+    project_id?: number;
+    /** Aggregate/grouping identifier (e.g. campaign/job ID) (optional) */
+    aggregate_id?: number;
+    /** Human-readable name for the aggregate (not indexed) (optional) */
+    aggregate_name?: string;
+    /** Arbitrary JSON metadata from the client (optional) */
+    metadata?: Record<string, any> | string;
+    /** Unix timestamp (UTC seconds since epoch) for when the usage event occurred (optional) */
+    event_timestamp?: number;
+}
+/**
+ * API response structure
+ */
+export interface UsageApiResponse {
+    /** Status of the response (always "recorded" on success) */
+    status: string;
+    /** Number of events successfully processed */
+    count: number;
+}
+/**
+ * API error response structure
+ */
+export interface UsageApiError {
+    message: string;
+    status?: number;
+    statusText?: string;
+}
+/**
+ * Usage information structure
+ */
+export interface UsageInfo {
+    /** The internal ID of the Limit entity */
+    limit_id: number;
+    /** Total usage amount for this limit */
+    total_usage: number;
+}
+/**
+ * Project usage information structure
+ */
+export interface ProjectUsageInfo {
+    /** The internal ID of the Limit entity */
+    limit_id: number;
+    /** Total usage amount for this limit */
+    total_usage: number;
+    /** The project entity ID */
+    project_id: number;
+}
+/**
+ * Usage API client for reporting subscription usage events
+ */
+export declare class UsageApi {
+    private baseUrl;
+    private bearerToken;
+    private endpoint;
+    /**
+     * Creates a new UsageApi instance
+     *
+     * @param baseUrl - The base URL of the API (e.g., "https://account.serialsubscriptionsdev.com/")
+     * @param bearerToken - The Bearer token for authentication
+     */
+    constructor(baseUrl: string, bearerToken: string);
+    /**
+     * Reports a single usage event
+     *
+     * @param event - The usage event to report
+     * @returns Promise resolving to the API response
+     * @throws {UsageApiError} If the request fails
+     */
+    reportEvent(event: UsageEvent): Promise<UsageApiResponse>;
+    /**
+     * Reports multiple usage events in a single batch request
+     *
+     * All events in a batch are processed within a single database transaction.
+     * If any event fails validation, the entire batch is rolled back.
+     *
+     * @param events - Array of usage events to report
+     * @returns Promise resolving to the API response
+     * @throws {UsageApiError} If the request fails
+     */
+    reportEvents(events: UsageEvent[]): Promise<UsageApiResponse>;
+    /**
+     * Gets usage information for all limits
+     *
+     * @returns Promise resolving to an array of usage information
+     * @throws {UsageApiError} If the request fails
+     */
+    getUsageAll(): Promise<UsageInfo[]>;
+    /**
+     * Gets usage information for a specific limit
+     *
+     * @param limit_id - The limit ID to get usage for
+     * @returns Promise resolving to the total usage value, or undefined if not found
+     * @throws {UsageApiError} If the request fails
+     */
+    getUsage(limit_id: number): Promise<number | undefined>;
+    /**
+     * Gets usage information for all limits for a specific project
+     *
+     * @param project_id - The project ID to get usage for
+     * @returns Promise resolving to an array of project usage information
+     * @throws {UsageApiError} If the request fails
+     */
+    getProjectUsageAll(project_id: number): Promise<ProjectUsageInfo[]>;
+    /**
+     * Gets usage information for a specific limit within a project
+     *
+     * @param project_id - The project ID to get usage for
+     * @param limit_id - The limit ID to get usage for
+     * @returns Promise resolving to the total usage value, or undefined if not found
+     * @throws {UsageApiError} If the request fails
+     */
+    getProjectUsage(project_id: number, limit_id: number): Promise<number | undefined>;
+}

package/lib/UsageApi.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * Usage Reporting API Client
+ *
+ * Sends usage events to the subscription usage API endpoint.
+ * Requires a base URL and Bearer token for authentication.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageApi = void 0;
+/**
+ * Usage API client for reporting subscription usage events
+ */
+class UsageApi {
+    /**
+     * Creates a new UsageApi instance
+     *
+     * @param baseUrl - The base URL of the API (e.g., "https://account.serialsubscriptionsdev.com/")
+     * @param bearerToken - The Bearer token for authentication
+     */
+    constructor(baseUrl, bearerToken) {
+        this.endpoint = '/api/v1/usage/report';
+        // Normalize base URL: ensure it ends with a slash
+        this.baseUrl = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+        this.bearerToken = bearerToken;
+    }
+    /**
+     * Reports a single usage event
+     *
+     * @param event - The usage event to report
+     * @returns Promise resolving to the API response
+     * @throws {UsageApiError} If the request fails
+     */
+    async reportEvent(event) {
+        return this.reportEvents([event]);
+    }
+    /**
+     * Reports multiple usage events in a single batch request
+     *
+     * All events in a batch are processed within a single database transaction.
+     * If any event fails validation, the entire batch is rolled back.
+     *
+     * @param events - Array of usage events to report
+     * @returns Promise resolving to the API response
+     * @throws {UsageApiError} If the request fails
+     */
+    async reportEvents(events) {
+        if (events.length === 0) {
+            throw {
+                message: 'At least one event is required',
+            };
+        }
+        // Normalize: if single event, send as object; if multiple, send as array
+        const payload = events.length === 1 ? events[0] : events;
+        const url = `${this.baseUrl}${this.endpoint.replace(/^\//, '')}`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.bearerToken}`,
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                let errorMessage = `API request failed with status ${response.status}`;
+                try {
+                    const errorData = await response.json();
+                    if (errorData.message) {
+                        errorMessage = errorData.message;
+                    }
+                }
+                catch {
+                    // If response is not JSON, use the status text
+                    errorMessage = response.statusText || errorMessage;
+                }
+                throw {
+                    message: errorMessage,
+                    status: response.status,
+                    statusText: response.statusText,
+                };
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'status' in error) {
+                // Re-throw UsageApiError
+                throw error;
+            }
+            // Handle network errors or other exceptions
+            throw {
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+            };
+        }
+    }
+    /**
+     * Gets usage information for all limits
+     *
+     * @returns Promise resolving to an array of usage information
+     * @throws {UsageApiError} If the request fails
+     */
+    async getUsageAll() {
+        const endpoint = '/api/v1/usage/get';
+        const url = `${this.baseUrl}${endpoint.replace(/^\//, '')}`;
+        try {
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.bearerToken}`,
+                    'Accept': 'application/json',
+                },
+            });
+            if (!response.ok) {
+                let errorMessage = `API request failed with status ${response.status}`;
+                try {
+                    const errorData = await response.json();
+                    if (errorData.message) {
+                        errorMessage = errorData.message;
+                    }
+                }
+                catch {
+                    // If response is not JSON, use the status text
+                    errorMessage = response.statusText || errorMessage;
+                }
+                throw {
+                    message: errorMessage,
+                    status: response.status,
+                    statusText: response.statusText,
+                };
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'status' in error) {
+                // Re-throw UsageApiError
+                throw error;
+            }
+            // Handle network errors or other exceptions
+            throw {
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+            };
+        }
+    }
+    /**
+     * Gets usage information for a specific limit
+     *
+     * @param limit_id - The limit ID to get usage for
+     * @returns Promise resolving to the total usage value, or undefined if not found
+     * @throws {UsageApiError} If the request fails
+     */
+    async getUsage(limit_id) {
+        const allUsage = await this.getUsageAll();
+        const usageInfo = allUsage.find((info) => info.limit_id === limit_id);
+        return usageInfo?.total_usage;
+    }
+    /**
+     * Gets usage information for all limits for a specific project
+     *
+     * @param project_id - The project ID to get usage for
+     * @returns Promise resolving to an array of project usage information
+     * @throws {UsageApiError} If the request fails
+     */
+    async getProjectUsageAll(project_id) {
+        const endpoint = '/api/v1/usage/get';
+        const url = `${this.baseUrl}${endpoint.replace(/^\//, '')}`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.bearerToken}`,
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                },
+                body: JSON.stringify({ project_id }),
+            });
+            if (!response.ok) {
+                let errorMessage = `API request failed with status ${response.status}`;
+                try {
+                    const errorData = await response.json();
+                    if (errorData.message) {
+                        errorMessage = errorData.message;
+                    }
+                }
+                catch {
+                    // If response is not JSON, use the status text
+                    errorMessage = response.statusText || errorMessage;
+                }
+                throw {
+                    message: errorMessage,
+                    status: response.status,
+                    statusText: response.statusText,
+                };
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'status' in error) {
+                // Re-throw UsageApiError
+                throw error;
+            }
+            // Handle network errors or other exceptions
+            throw {
+                message: error instanceof Error ? error.message : 'Unknown error occurred',
+            };
+        }
+    }
+    /**
+     * Gets usage information for a specific limit within a project
+     *
+     * @param project_id - The project ID to get usage for
+     * @param limit_id - The limit ID to get usage for
+     * @returns Promise resolving to the total usage value, or undefined if not found
+     * @throws {UsageApiError} If the request fails
+     */
+    async getProjectUsage(project_id, limit_id) {
+        const allUsage = await this.getProjectUsageAll(project_id);
+        const usageInfo = allUsage.find((info) => info.limit_id === limit_id);
+        return usageInfo?.total_usage;
+    }
+}
+exports.UsageApi = UsageApi;