@serialsubscriptions/platform-integration 0.0.79

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;

package/lib/auth.server.d.ts

@@ -0,0 +1,192 @@
+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";
+};
+export type AuthConfig = {
+    issuerBaseUrl?: string;
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    logoutEndpoint?: string;
+    jwksUri?: string;
+    jwksPath?: string;
+    jwks?: {
+        keys: Array<{
+            kty: string;
+            n: string;
+            e: string;
+            kid?: string;
+        }>;
+    };
+    clientId?: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    scopes?: string | string[];
+    audience?: string;
+    storage?: SSIStorage;
+};
+export type LoginUrlOptions = {
+    stateKey?: string;
+    extraParams?: Record<string, string>;
+    stateTtlSeconds?: number;
+};
+export type CallbackParams = {
+    code?: string | null;
+    state?: string | null;
+};
+export type TokenResponse = {
+    access_token?: string;
+    id_token?: string;
+    token_type?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    raw: any;
+    id_claims?: Record<string, unknown>;
+    access_claims?: Record<string, unknown>;
+};
+export declare class AuthServer {
+    private cfg;
+    private stateStorage;
+    private jwksCache;
+    private lastTokens?;
+    constructor(config?: AuthConfig);
+    /**
+     * Build the authorization URL and persist a CSRF state for the callback.
+     * Returns: { url, stateKey, stateValue }
+     */
+    getLoginUrl(opts?: LoginUrlOptions): Promise<{
+        url: string;
+        stateKey: string;
+        stateValue: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+    /**
+     * Build the logout URL for RP-initiated logout.
+     * Common params: id_token_hint, post_logout_redirect_uri
+     */
+    getLogoutUrl(opts?: {
+        idTokenHint?: string;
+        postLogoutRedirectUri?: string;
+        extraParams?: Record<string, string>;
+    }): {
+        url: string;
+    };
+    /**
+     * Handle the OAuth callback: validates state and exchanges the code for tokens.
+     * Returns TokenResponse (and includes raw for debugging).
+     */
+    handleCallback(params: CallbackParams): Promise<TokenResponse>;
+    /**
+     * Exchange a refresh_token for new tokens.
+     * Verifies any returned JWTs and returns a TokenResponse.
+     *
+     * @param refreshToken - The refresh token to exchange for new tokens
+     * @param options - Optional parameters for the refresh request
+     * @param options.scope - Optional scope parameter (cannot exceed originally granted scope)
+     * @param options.useAuthHeader - Use Authorization header instead of client_secret in body
+     * @returns Promise<TokenResponse> - New tokens with verified claims
+     */
+    refreshTokens(refreshToken: string, options?: {
+        scope?: string;
+        useAuthHeader?: boolean;
+    }): Promise<TokenResponse>;
+    /**
+     * Fetch and cache JWKS from the remote endpoint.
+     * Uses SSICache to cache the JWKS response.
+     * @private
+     */
+    private fetchAndCacheJWKS;
+    /**
+     * Verify JWT signature and claims using jose library.
+     * Handles JWKS fetching, caching, kid selection, and algorithm validation.
+     * @private
+     */
+    private verifyWithIssuer;
+    /**
+     * Public method to verify a JWT.
+     * Use this in middleware or anywhere you need to validate tokens.
+     */
+    verifyJwt<T = unknown>(jwt: string): Promise<T>;
+    /**
+     * Verify and decode a JWT before returning its claims.
+     * Throws if the JWT is invalid, expired, or fails signature verification.
+     *
+     * This method is safe to use in middleware or debugging contexts when you
+     * simply need the decoded, verified claims from a JWT string.
+     */
+    verifyAndDecodeJwt<T = unknown>(jwt?: string): Promise<T>;
+    /**
+     * Automatically refresh tokens if they are expired or about to expire.
+     * This is a convenience method that handles the refresh logic automatically.
+     *
+     * @param refreshToken - The refresh token to use for refreshing
+     * @param options - Optional parameters for the refresh request
+     * @param options.bufferSeconds - How many seconds before expiry to consider tokens as "about to expire" (default: 60)
+     * @param options.scope - Optional scope parameter
+     * @param options.useAuthHeader - Use Authorization header instead of client_secret in body
+     * @returns Promise<TokenResponse | null> - New tokens if refreshed, null if not needed
+     */
+    autoRefreshTokens(refreshToken: string, options?: {
+        bufferSeconds?: number;
+        scope?: string;
+        useAuthHeader?: boolean;
+    }): Promise<TokenResponse | null>;
+    /**
+     * Check if the current tokens are expired or about to expire.
+     *
+     * @param bufferSeconds - How many seconds before expiry to consider tokens as "about to expire" (default: 60)
+     * @returns boolean - true if tokens need refreshing, false otherwise
+     */
+    needsTokenRefresh(bufferSeconds?: number): boolean;
+    /**
+     * Get the time until the current access token expires.
+     *
+     * @returns number - Seconds until expiry, or 0 if no token or expired
+     */
+    getTokenExpirySeconds(): number;
+    /** Returns the last TokenResponse produced by handleCallback/refreshTokens in this instance */
+    getLastTokenResponse(): TokenResponse | undefined;
+}
+/**
+ * USAGE EXAMPLES
+ *
+ * // Basic token refresh
+ * const auth = new AuthServer(config);
+ * const newTokens = await auth.refreshTokens(refreshToken);
+ *
+ * // Refresh with Authorization header instead of client_secret in body
+ * const newTokens = await auth.refreshTokens(refreshToken, {
+ *   useAuthHeader: true
+ * });
+ *
+ * // Refresh with specific scope (cannot exceed originally granted scope)
+ * const newTokens = await auth.refreshTokens(refreshToken, {
+ *   scope: "openid profile email offline_access"
+ * });
+ *
+ * // Automatic refresh - only refreshes if tokens are expired or about to expire
+ * const newTokens = await auth.autoRefreshTokens(refreshToken, {
+ *   bufferSeconds: 120, // Refresh if expires within 2 minutes
+ *   useAuthHeader: true
+ * });
+ *
+ * // Check if tokens need refreshing
+ * if (auth.needsTokenRefresh(60)) {
+ *   const newTokens = await auth.refreshTokens(refreshToken);
+ * }
+ *
+ * // Get time until token expires
+ * const secondsUntilExpiry = auth.getTokenExpirySeconds();
+ * console.log(`Token expires in ${secondsUntilExpiry} seconds`);
+ *
+ * // Error handling
+ * try {
+ *   const newTokens = await auth.refreshTokens(refreshToken);
+ *   // Use new tokens...
+ * } catch (error) {
+ *   if (error.message.includes('invalid_grant')) {
+ *     // Refresh token is invalid/expired - redirect to login
+ *     return Response.redirect('/login');
+ *   }
+ *   // Handle other errors...
+ * }
+ */