@serialsubscriptions/platform-integration 0.0.82 → 0.0.83

package/lib/SSISubscribedPlanApi.d.ts

@@ -256,6 +256,17 @@ export declare class SSISubscribedPlanApi {
      * @throws Error if the request fails or entity is not found.
      */
     get(uuid: string, options?: GetOptions): Promise<JsonApiDocument>;
+    /**
+     * Retrieves a single subscribed_plan entity by project ID.
+     * Fetches all subscribed plans (paginated), then returns the first one whose
+     * attributes.project_id matches the given project ID.
+     *
+     * @param projectId - The project ID (e.g. attributes.project_id from the API).
+     * @param options - Optional list options (include, fields). Pagination is handled internally.
+     * @returns Promise resolving to the JSON:API document with the subscribed plan, or null if not found.
+     * @throws Error if the request fails.
+     */
+    getByProjectId(projectId: number, options?: Omit<ListOptions, 'pagination'>): Promise<JsonApiDocument | null>;
     /**
      * Creates a new subscribed_plan entity.
      *

package/lib/SSISubscribedPlanApi.js

@@ -221,6 +221,36 @@ class SSISubscribedPlanApi {
         const url = `${this.baseUrl}${this.apiBasePath}/${uuid}${queryParams.toString() ? `?${queryParams.toString()}` : ''}`;
         return this.request('GET', url);
     }
+    /**
+     * Retrieves a single subscribed_plan entity by project ID.
+     * Fetches all subscribed plans (paginated), then returns the first one whose
+     * attributes.project_id matches the given project ID.
+     *
+     * @param projectId - The project ID (e.g. attributes.project_id from the API).
+     * @param options - Optional list options (include, fields). Pagination is handled internally.
+     * @returns Promise resolving to the JSON:API document with the subscribed plan, or null if not found.
+     * @throws Error if the request fails.
+     */
+    async getByProjectId(projectId, options = {}) {
+        const limit = 50;
+        let offset = 0;
+        while (true) {
+            const doc = await this.list({
+                ...options,
+                pagination: { offset, limit },
+            });
+            const data = Array.isArray(doc.data) ? doc.data : doc.data ? [doc.data] : [];
+            const found = data.find((resource) => resource.attributes &&
+                resource.attributes.project_id === projectId);
+            if (found) {
+                return { data: found, included: doc.included, links: doc.links, meta: doc.meta };
+            }
+            if (data.length < limit) {
+                return null;
+            }
+            offset += limit;
+        }
+    }
     /**
      * Creates a new subscribed_plan entity.
      *

package/lib/SubscribedPlanManager.d.ts

@@ -12,8 +12,8 @@
  * const domain = 'https://account.serialsubscriptionsdev.com';
  * const manager = new SubscribedPlanManager(domain);
  *
- * // Optional: set OAuth/JWT Bearer token if needed
- * manager.setBearerToken('YOUR_ACCESS_TOKEN');
+ * // 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();
@@ -24,6 +24,9 @@
  * // 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);
  * ```
@@ -187,6 +190,9 @@ export declare class SubscribedPlanManager {
     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;
     /**
@@ -205,6 +211,13 @@ export declare class SubscribedPlanManager {
      * 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.
      *

package/lib/SubscribedPlanManager.js

@@ -13,8 +13,8 @@
  * const domain = 'https://account.serialsubscriptionsdev.com';
  * const manager = new SubscribedPlanManager(domain);
  *
- * // Optional: set OAuth/JWT Bearer token if needed
- * manager.setBearerToken('YOUR_ACCESS_TOKEN');
+ * // 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();
@@ -25,6 +25,9 @@
  * // 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);
  * ```
@@ -66,6 +69,9 @@ class SubscribedPlanManager {
     }
     /**
      * 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);
@@ -110,6 +116,16 @@ class SubscribedPlanManager {
         });
         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.
      *

package/lib/auth.server.d.ts

@@ -2,6 +2,24 @@ import { SSIStorage } from "./storage/SSIStorage";
 export declare const scopes: {
     readonly defaultScopes: "openid profile email view_project create_project delete_project update_project view_subscribed_plan view_subscribed_feature view_subscribed_limit access_subscription_usage";
 };
+/**
+ * Check if a JWT is expired (or within bufferSeconds of expiry) by decoding its payload.
+ * Does not verify the signature — use only for expiry checks (e.g. "should I refresh?").
+ * For authorization, use AuthServer.verifyJwt() or verifyAndDecodeJwt().
+ *
+ * @param jwt - The JWT string (e.g. access_token or id_token from session).
+ * @param bufferSeconds - If provided, treat the token as "expired" when it would expire within this many seconds (default: 0).
+ * @returns true if the token is expired (or expiring within bufferSeconds), or if the JWT is missing/invalid; false otherwise.
+ */
+export declare function isJwtExpired(jwt: string, bufferSeconds?: number): boolean;
+/**
+ * Get the number of seconds until a JWT expires, by decoding its payload.
+ * Does not verify the signature. For authorization use AuthServer.verifyJwt().
+ *
+ * @param jwt - The JWT string.
+ * @returns Seconds until expiry (0 if already expired), or null if the JWT has no exp claim or is invalid.
+ */
+export declare function getJwtExpirySeconds(jwt: string): number | null;
 export type AuthConfig = {
     issuerBaseUrl?: string;
     authorizationEndpoint?: string;

package/lib/auth.server.js

@@ -36,6 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthServer = exports.scopes = void 0;
+exports.isJwtExpired = isJwtExpired;
+exports.getJwtExpirySeconds = getJwtExpirySeconds;
 const crypto = __importStar(require("crypto"));
 const jose_1 = require("jose");
 const stateStore_1 = require("./stateStore");
@@ -48,6 +50,48 @@ exports.scopes = {
 function normalizeIssuer(url) {
     return url.replace(/\/+$/, "");
 }
+/**
+ * Check if a JWT is expired (or within bufferSeconds of expiry) by decoding its payload.
+ * Does not verify the signature — use only for expiry checks (e.g. "should I refresh?").
+ * For authorization, use AuthServer.verifyJwt() or verifyAndDecodeJwt().
+ *
+ * @param jwt - The JWT string (e.g. access_token or id_token from session).
+ * @param bufferSeconds - If provided, treat the token as "expired" when it would expire within this many seconds (default: 0).
+ * @returns true if the token is expired (or expiring within bufferSeconds), or if the JWT is missing/invalid; false otherwise.
+ */
+function isJwtExpired(jwt, bufferSeconds = 0) {
+    try {
+        const payload = (0, jose_1.decodeJwt)(jwt);
+        const exp = payload.exp;
+        if (typeof exp !== "number")
+            return false; // no exp claim → not expired
+        const now = Math.floor(Date.now() / 1000);
+        return exp <= now + bufferSeconds;
+    }
+    catch {
+        return true; // malformed or missing → treat as expired
+    }
+}
+/**
+ * Get the number of seconds until a JWT expires, by decoding its payload.
+ * Does not verify the signature. For authorization use AuthServer.verifyJwt().
+ *
+ * @param jwt - The JWT string.
+ * @returns Seconds until expiry (0 if already expired), or null if the JWT has no exp claim or is invalid.
+ */
+function getJwtExpirySeconds(jwt) {
+    try {
+        const payload = (0, jose_1.decodeJwt)(jwt);
+        const exp = payload.exp;
+        if (typeof exp !== "number")
+            return null;
+        const now = Math.floor(Date.now() / 1000);
+        return Math.max(0, exp - now);
+    }
+    catch {
+        return null;
+    }
+}
 class AuthServer {
     constructor(config) {
         // Use empty object as default if config is not provided

package/lib/session/SessionManager.d.ts

@@ -5,6 +5,7 @@ export declare const sessionRoles: {
     allRoles: string[];
     adminRoles: string[];
     userRoles: string[];
+    userWriteRoles: string[];
     userAdminRoles: string[];
 };
 export type SessionDataKey = 'claims' | 'id_token' | 'access_token' | 'refresh_token';

package/lib/session/SessionManager.js

@@ -8,6 +8,7 @@ exports.sessionRoles = {
     allRoles: ['platform_admin', 'member', 'owner', 'admin', 'billing', 'readonly'],
     adminRoles: ['platform_admin', 'owner', 'admin'],
     userRoles: ['member', 'owner', 'admin', 'billing', 'readonly'],
+    userWriteRoles: ['member', 'owner', 'admin'],
     userAdminRoles: ['platform_admin', 'owner', 'admin']
 };
 /** Defaults & env */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@serialsubscriptions/platform-integration",
-    "version": "0.0.82",
+    "version": "0.0.83",
     "description": "Serial Subscriptions Libraries",
     "main": "lib/index.js",
     "types": "lib/index.d.ts",