spaps-sdk 1.5.1 → 1.6.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as spaps_types from 'spaps-types';
-import { CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
-export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreateCryptoInvoiceRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, Price, Product, ProductSyncResult, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, createSecureMessageRequestSchema, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
+import { ResourceType, Entitlement, CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
+export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreateCryptoInvoiceRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, Entitlement, Price, Product, ProductSyncResult, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, createSecureMessageRequestSchema, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -85,6 +85,164 @@ declare class PermissionChecker {
 declare function createPermissionChecker(customAdmins?: (string | AdminConfig)[]): PermissionChecker;
 declare const defaultPermissionChecker: PermissionChecker;
 
+/**
+ * RoleHierarchy - Hierarchical role comparison utility
+ *
+ * Allows defining a numeric level for each role and comparing
+ * whether a user's role meets or exceeds a required minimum.
+ */
+declare class RoleHierarchy {
+    private levels;
+    /**
+     * @param levels - Mapping of role name to numeric level.
+     *   Higher numbers indicate greater privilege.
+     *   Example: { guest: 0, user: 10, accountant: 20, admin: 30 }
+     */
+    constructor(levels: {
+        [role: string]: number;
+    });
+    /**
+     * Get the numeric level for a role.
+     * Returns undefined if the role is not registered.
+     */
+    getLevel(role: string): number | undefined;
+    /**
+     * Check whether `userRole` meets or exceeds `requiredRole` in the hierarchy.
+     * Returns false if either role is unknown (not registered in the hierarchy).
+     */
+    hasMinimumRole(userRole: string, requiredRole: string): boolean;
+}
+
+/**
+ * FeatureEvaluator - 3-layer feature gate evaluation
+ *
+ * Evaluation order (stops at first failing layer):
+ *   1. System kill switch  - If a system entitlement with key "kill:{featureName}" exists, feature is DISABLED.
+ *   2. Resource block       - If a resource-scoped block entitlement exists for a specific company/org, feature is DISABLED.
+ *   3. Role minimum         - If user's role does not meet the required minimum, feature is DISABLED.
+ *
+ * Admin bypass: Only SPAPS super admins bypass all checks (NOT app-level admins).
+ * Unknown / unconfigured features are enabled by default.
+ */
+
+/** Definition of a feature's gating layers (all optional). */
+interface FeatureDefinition {
+    /** System kill-switch entitlement key. When this entitlement exists the feature is globally disabled. */
+    killSwitchKey?: string;
+    /** Resource-scoped block entitlement key. When this entitlement exists for a given resource the feature is disabled for that resource. */
+    resourceBlockKey?: string;
+    /** The resource type used for resource-block lookups (e.g. "company", "org"). */
+    resourceBlockType?: ResourceType;
+    /** Minimum role required (evaluated via the attached RoleHierarchy). */
+    minimumRole?: string;
+}
+/** Runtime context supplied when evaluating a feature. */
+interface FeatureContext {
+    /** The user's current role name. */
+    userRole?: string;
+    /** Whether the user is a SPAPS super admin. */
+    isSuperAdmin?: boolean;
+    /** Active entitlements to evaluate against. */
+    entitlements?: Entitlement[];
+    /** Resource ID to check for resource-scoped blocks (e.g. company ID). */
+    resourceId?: string;
+}
+declare class FeatureEvaluator {
+    private features;
+    private roleHierarchy;
+    /**
+     * @param roleHierarchy - Optional RoleHierarchy instance used for role-minimum checks.
+     */
+    constructor(roleHierarchy?: RoleHierarchy);
+    /**
+     * Register (or replace) a feature definition.
+     */
+    registerFeature(name: string, definition: FeatureDefinition): void;
+    /**
+     * Evaluate whether a feature is enabled for the given context.
+     *
+     * Returns `true` (enabled) or `false` (disabled).
+     */
+    isEnabled(featureName: string, context?: FeatureContext): boolean;
+}
+
+/**
+ * WebSocketAuthHelper - Authenticated WebSocket connection manager
+ *
+ * Features:
+ *   - Builds authenticated WebSocket URLs with access tokens
+ *   - Refreshes tokens before expiry (configurable buffer)
+ *   - Reconnects on auth-related close codes (4001, 4003)
+ *   - Exponential backoff for network failures
+ *   - Ping/pong mechanism to detect stale connections
+ */
+interface WebSocketAuthHelperConfig {
+    /** Base WebSocket URL (e.g. "wss://api.sweetpotato.dev/ws") */
+    url: string;
+    /** Function that returns the current access token. */
+    getAccessToken: () => string | undefined;
+    /**
+     * Function to refresh the access token.
+     * Should perform the refresh and return the new access token.
+     */
+    refreshAccessToken: () => Promise<string>;
+    /** Seconds before token expiry to proactively refresh (default 30). */
+    refreshBufferSeconds?: number;
+    /** Maximum number of reconnection attempts on auth failures (default 3). */
+    maxAuthRetries?: number;
+    /** Maximum number of reconnection attempts on network failures (default 5). */
+    maxNetworkRetries?: number;
+    /** Initial backoff delay in ms for network reconnections (default 1000). */
+    initialBackoffMs?: number;
+    /** Maximum backoff delay in ms (default 30000). */
+    maxBackoffMs?: number;
+    /** Ping interval in ms to detect stale connections. 0 disables (default 30000). */
+    pingIntervalMs?: number;
+    /** Callback invoked when a message is received. */
+    onMessage?: (data: string) => void;
+    /** Callback invoked when the connection opens. */
+    onOpen?: () => void;
+    /** Callback invoked when the connection closes. */
+    onClose?: (code: number, reason: string) => void;
+    /** Callback invoked on errors. */
+    onError?: (error: Event) => void;
+}
+declare class WebSocketAuthHelper {
+    private config;
+    private ws;
+    private authRetries;
+    private networkRetries;
+    private pingTimer;
+    private refreshTimer;
+    private intentionalClose;
+    constructor(config: WebSocketAuthHelperConfig);
+    /**
+     * Open an authenticated WebSocket connection.
+     * Appends the access token as a query parameter.
+     */
+    connect(): Promise<void>;
+    /**
+     * Cleanly disconnect. No reconnection attempts will be made.
+     */
+    disconnect(): void;
+    /**
+     * Send data over the WebSocket.
+     * Throws if the connection is not open.
+     */
+    send(data: string): void;
+    /** Build the authenticated WebSocket URL. */
+    buildAuthUrl(): string;
+    private openConnection;
+    private handleAuthClose;
+    private handleNetworkClose;
+    private startPing;
+    /**
+     * Schedule a proactive token refresh before the current token expires.
+     */
+    private scheduleTokenRefresh;
+    private cleanup;
+}
+
 type ApiKeyType = 'publishable' | 'secret';
 interface SPAPSConfig {
     apiUrl?: string;
@@ -172,6 +330,20 @@ interface EmailTemplatePreview {
     html: string;
     text?: string;
 }
+interface EntitlementListParams {
+    /** Filter by entitlement key */
+    key?: string;
+    /** Filter by source type */
+    source?: 'crypto' | 'stripe_subscription' | 'stripe_checkout' | 'manual';
+    /** Include revoked entitlements (default false) */
+    include_revoked?: boolean;
+}
+interface EntitlementCheckResult {
+    /** Whether the user has the entitlement */
+    entitled: boolean;
+    /** The matching entitlement, if any */
+    entitlement?: Entitlement;
+}
 
 declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Record<string, any>> {
     private client;
@@ -226,6 +398,37 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         getTemplate: (templateKey: string) => Promise<EmailTemplate>;
         previewTemplate: (templateKey: string, context?: Record<string, unknown>) => Promise<EmailTemplatePreview>;
     };
+    /**
+     * Entitlements namespace for querying user and resource entitlements.
+     *
+     * Scope rules:
+     * - Publishable key contexts (browser): JWT required, user derived from JWT, can only query user-scoped entitlements.
+     * - Secret key contexts (server): can query any resource scope.
+     * - `listByResource` with non-user resource types will fail with 403 for publishable keys (enforced server-side).
+     */
+    entitlements: {
+        /**
+         * List the current user's entitlements.
+         * Requires authentication (JWT).
+         */
+        list: (params?: EntitlementListParams) => Promise<Entitlement[]>;
+        /**
+         * Boolean access check — does the user hold an active entitlement with the given key?
+         * @param key - The entitlement key to check (e.g. "premium").
+         * @param userId - Optional user ID override (secret key contexts only).
+         */
+        check: (key: string, userId?: string) => Promise<EntitlementCheckResult>;
+        /**
+         * List entitlements scoped to a specific resource type and optional resource ID.
+         *
+         * Note: For publishable key contexts, only `resource_type=user` is permitted.
+         * Non-user resource types will return a 403 error (enforced server-side).
+         *
+         * @param resourceType - The resource type (e.g. "user", "company", "org", "system").
+         * @param resourceId - Optional specific resource ID.
+         */
+        listByResource: (resourceType: ResourceType, resourceId?: string) => Promise<Entitlement[]>;
+    };
     constructor(config?: SPAPSConfig);
     /** Raw API request helper that returns an ApiResponse-like shape */
     request<T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, requiresAuth?: boolean): Promise<{
@@ -692,4 +895,4 @@ declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfi
  */
 declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type TemplateVariable, TokenManager, WalletUtils, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };
+export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type PermissionCheckResult, PermissionChecker, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type TemplateVariable, TokenManager, WalletUtils, WebSocketAuthHelper, type WebSocketAuthHelperConfig, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as spaps_types from 'spaps-types';
-import { CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
-export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreateCryptoInvoiceRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, Price, Product, ProductSyncResult, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, createSecureMessageRequestSchema, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
+import { ResourceType, Entitlement, CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, CryptoReconcileRequest, CreateSecureMessageRequest, SecureMessage, AuthResponse, User as User$1, CreateCryptoInvoiceRequest, CryptoInvoiceStatusSnapshot, CheckoutSession, DayrateAvailabilityResponse, DayrateBookingRequest, DayrateBookingResponse, DayrateMultiBookingRequest, DayrateMultiBookingResponse, Subscription, UsageBalance, VerifyCryptoWebhookSignatureOptions } from 'spaps-types';
+export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreateCryptoInvoiceRequest, CreatePriceRequest, CreateProductRequest, CreateSecureMessageInput, CreateSecureMessageRequest, CryptoInvoice, CryptoInvoiceResponse, CryptoInvoiceStatusSnapshot, CryptoReconcileRequest, DayrateAvailabilityResponse, DayrateAvailableSlot, DayrateBookingRequest, DayrateBookingResponse, DayrateDayOfWeek, DayrateMultiBookingRequest, DayrateMultiBookingResponse, DayratePriceBreakdown, DayrateSlotType, Entitlement, Price, Product, ProductSyncResult, ResourceType, SecureMessage, SecureMessageOutput, Subscription, TokenPair, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet, VerifyCryptoWebhookSignatureOptions, createSecureMessageRequestSchema, secureMessageMetadataSchema, secureMessageSchema } from 'spaps-types';
 
 /**
  * Permission checking utilities for SPAPS SDK
@@ -85,6 +85,164 @@ declare class PermissionChecker {
 declare function createPermissionChecker(customAdmins?: (string | AdminConfig)[]): PermissionChecker;
 declare const defaultPermissionChecker: PermissionChecker;
 
+/**
+ * RoleHierarchy - Hierarchical role comparison utility
+ *
+ * Allows defining a numeric level for each role and comparing
+ * whether a user's role meets or exceeds a required minimum.
+ */
+declare class RoleHierarchy {
+    private levels;
+    /**
+     * @param levels - Mapping of role name to numeric level.
+     *   Higher numbers indicate greater privilege.
+     *   Example: { guest: 0, user: 10, accountant: 20, admin: 30 }
+     */
+    constructor(levels: {
+        [role: string]: number;
+    });
+    /**
+     * Get the numeric level for a role.
+     * Returns undefined if the role is not registered.
+     */
+    getLevel(role: string): number | undefined;
+    /**
+     * Check whether `userRole` meets or exceeds `requiredRole` in the hierarchy.
+     * Returns false if either role is unknown (not registered in the hierarchy).
+     */
+    hasMinimumRole(userRole: string, requiredRole: string): boolean;
+}
+
+/**
+ * FeatureEvaluator - 3-layer feature gate evaluation
+ *
+ * Evaluation order (stops at first failing layer):
+ *   1. System kill switch  - If a system entitlement with key "kill:{featureName}" exists, feature is DISABLED.
+ *   2. Resource block       - If a resource-scoped block entitlement exists for a specific company/org, feature is DISABLED.
+ *   3. Role minimum         - If user's role does not meet the required minimum, feature is DISABLED.
+ *
+ * Admin bypass: Only SPAPS super admins bypass all checks (NOT app-level admins).
+ * Unknown / unconfigured features are enabled by default.
+ */
+
+/** Definition of a feature's gating layers (all optional). */
+interface FeatureDefinition {
+    /** System kill-switch entitlement key. When this entitlement exists the feature is globally disabled. */
+    killSwitchKey?: string;
+    /** Resource-scoped block entitlement key. When this entitlement exists for a given resource the feature is disabled for that resource. */
+    resourceBlockKey?: string;
+    /** The resource type used for resource-block lookups (e.g. "company", "org"). */
+    resourceBlockType?: ResourceType;
+    /** Minimum role required (evaluated via the attached RoleHierarchy). */
+    minimumRole?: string;
+}
+/** Runtime context supplied when evaluating a feature. */
+interface FeatureContext {
+    /** The user's current role name. */
+    userRole?: string;
+    /** Whether the user is a SPAPS super admin. */
+    isSuperAdmin?: boolean;
+    /** Active entitlements to evaluate against. */
+    entitlements?: Entitlement[];
+    /** Resource ID to check for resource-scoped blocks (e.g. company ID). */
+    resourceId?: string;
+}
+declare class FeatureEvaluator {
+    private features;
+    private roleHierarchy;
+    /**
+     * @param roleHierarchy - Optional RoleHierarchy instance used for role-minimum checks.
+     */
+    constructor(roleHierarchy?: RoleHierarchy);
+    /**
+     * Register (or replace) a feature definition.
+     */
+    registerFeature(name: string, definition: FeatureDefinition): void;
+    /**
+     * Evaluate whether a feature is enabled for the given context.
+     *
+     * Returns `true` (enabled) or `false` (disabled).
+     */
+    isEnabled(featureName: string, context?: FeatureContext): boolean;
+}
+
+/**
+ * WebSocketAuthHelper - Authenticated WebSocket connection manager
+ *
+ * Features:
+ *   - Builds authenticated WebSocket URLs with access tokens
+ *   - Refreshes tokens before expiry (configurable buffer)
+ *   - Reconnects on auth-related close codes (4001, 4003)
+ *   - Exponential backoff for network failures
+ *   - Ping/pong mechanism to detect stale connections
+ */
+interface WebSocketAuthHelperConfig {
+    /** Base WebSocket URL (e.g. "wss://api.sweetpotato.dev/ws") */
+    url: string;
+    /** Function that returns the current access token. */
+    getAccessToken: () => string | undefined;
+    /**
+     * Function to refresh the access token.
+     * Should perform the refresh and return the new access token.
+     */
+    refreshAccessToken: () => Promise<string>;
+    /** Seconds before token expiry to proactively refresh (default 30). */
+    refreshBufferSeconds?: number;
+    /** Maximum number of reconnection attempts on auth failures (default 3). */
+    maxAuthRetries?: number;
+    /** Maximum number of reconnection attempts on network failures (default 5). */
+    maxNetworkRetries?: number;
+    /** Initial backoff delay in ms for network reconnections (default 1000). */
+    initialBackoffMs?: number;
+    /** Maximum backoff delay in ms (default 30000). */
+    maxBackoffMs?: number;
+    /** Ping interval in ms to detect stale connections. 0 disables (default 30000). */
+    pingIntervalMs?: number;
+    /** Callback invoked when a message is received. */
+    onMessage?: (data: string) => void;
+    /** Callback invoked when the connection opens. */
+    onOpen?: () => void;
+    /** Callback invoked when the connection closes. */
+    onClose?: (code: number, reason: string) => void;
+    /** Callback invoked on errors. */
+    onError?: (error: Event) => void;
+}
+declare class WebSocketAuthHelper {
+    private config;
+    private ws;
+    private authRetries;
+    private networkRetries;
+    private pingTimer;
+    private refreshTimer;
+    private intentionalClose;
+    constructor(config: WebSocketAuthHelperConfig);
+    /**
+     * Open an authenticated WebSocket connection.
+     * Appends the access token as a query parameter.
+     */
+    connect(): Promise<void>;
+    /**
+     * Cleanly disconnect. No reconnection attempts will be made.
+     */
+    disconnect(): void;
+    /**
+     * Send data over the WebSocket.
+     * Throws if the connection is not open.
+     */
+    send(data: string): void;
+    /** Build the authenticated WebSocket URL. */
+    buildAuthUrl(): string;
+    private openConnection;
+    private handleAuthClose;
+    private handleNetworkClose;
+    private startPing;
+    /**
+     * Schedule a proactive token refresh before the current token expires.
+     */
+    private scheduleTokenRefresh;
+    private cleanup;
+}
+
 type ApiKeyType = 'publishable' | 'secret';
 interface SPAPSConfig {
     apiUrl?: string;
@@ -172,6 +330,20 @@ interface EmailTemplatePreview {
     html: string;
     text?: string;
 }
+interface EntitlementListParams {
+    /** Filter by entitlement key */
+    key?: string;
+    /** Filter by source type */
+    source?: 'crypto' | 'stripe_subscription' | 'stripe_checkout' | 'manual';
+    /** Include revoked entitlements (default false) */
+    include_revoked?: boolean;
+}
+interface EntitlementCheckResult {
+    /** Whether the user has the entitlement */
+    entitled: boolean;
+    /** The matching entitlement, if any */
+    entitlement?: Entitlement;
+}
 
 declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Record<string, any>> {
     private client;
@@ -226,6 +398,37 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         getTemplate: (templateKey: string) => Promise<EmailTemplate>;
         previewTemplate: (templateKey: string, context?: Record<string, unknown>) => Promise<EmailTemplatePreview>;
     };
+    /**
+     * Entitlements namespace for querying user and resource entitlements.
+     *
+     * Scope rules:
+     * - Publishable key contexts (browser): JWT required, user derived from JWT, can only query user-scoped entitlements.
+     * - Secret key contexts (server): can query any resource scope.
+     * - `listByResource` with non-user resource types will fail with 403 for publishable keys (enforced server-side).
+     */
+    entitlements: {
+        /**
+         * List the current user's entitlements.
+         * Requires authentication (JWT).
+         */
+        list: (params?: EntitlementListParams) => Promise<Entitlement[]>;
+        /**
+         * Boolean access check — does the user hold an active entitlement with the given key?
+         * @param key - The entitlement key to check (e.g. "premium").
+         * @param userId - Optional user ID override (secret key contexts only).
+         */
+        check: (key: string, userId?: string) => Promise<EntitlementCheckResult>;
+        /**
+         * List entitlements scoped to a specific resource type and optional resource ID.
+         *
+         * Note: For publishable key contexts, only `resource_type=user` is permitted.
+         * Non-user resource types will return a 403 error (enforced server-side).
+         *
+         * @param resourceType - The resource type (e.g. "user", "company", "org", "system").
+         * @param resourceId - Optional specific resource ID.
+         */
+        listByResource: (resourceType: ResourceType, resourceId?: string) => Promise<Entitlement[]>;
+    };
     constructor(config?: SPAPSConfig);
     /** Raw API request helper that returns an ApiResponse-like shape */
     request<T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, requiresAuth?: boolean): Promise<{
@@ -692,4 +895,4 @@ declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfi
  */
 declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type TemplateVariable, TokenManager, WalletUtils, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };
+export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type EmailSendOptions, type EmailSendResult, type EmailTemplate, type EmailTemplatePreview, type EntitlementCheckResult, type EntitlementListParams, type FeatureContext, type FeatureDefinition, FeatureEvaluator, type PermissionCheckResult, PermissionChecker, RoleHierarchy, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type TemplateVariable, TokenManager, WalletUtils, WebSocketAuthHelper, type WebSocketAuthHelperConfig, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };

package/dist/index.js

@@ -195,11 +195,14 @@ var init_permissions = __esm({
 var index_exports = {};
 __export(index_exports, {
   DEFAULT_ADMIN_ACCOUNTS: () => DEFAULT_ADMIN_ACCOUNTS,
+  FeatureEvaluator: () => FeatureEvaluator,
   PermissionChecker: () => PermissionChecker,
+  RoleHierarchy: () => RoleHierarchy,
   SPAPS: () => SPAPSClient,
   SPAPSClient: () => SPAPSClient,
   TokenManager: () => TokenManager,
   WalletUtils: () => WalletUtils,
+  WebSocketAuthHelper: () => WebSocketAuthHelper,
   canAccessAdmin: () => canAccessAdmin,
   createBrowserClient: () => createBrowserClient,
   createPermissionChecker: () => createPermissionChecker,
@@ -222,6 +225,281 @@ var import_crypto = __toESM(require("crypto"));
 var import_axios = __toESM(require("axios"));
 var import_spaps_types = require("spaps-types");
 init_permissions();
+
+// src/role-hierarchy.ts
+var RoleHierarchy = class {
+  levels;
+  /**
+   * @param levels - Mapping of role name to numeric level.
+   *   Higher numbers indicate greater privilege.
+   *   Example: { guest: 0, user: 10, accountant: 20, admin: 30 }
+   */
+  constructor(levels) {
+    this.levels = new Map(Object.entries(levels));
+  }
+  /**
+   * Get the numeric level for a role.
+   * Returns undefined if the role is not registered.
+   */
+  getLevel(role) {
+    return this.levels.get(role);
+  }
+  /**
+   * Check whether `userRole` meets or exceeds `requiredRole` in the hierarchy.
+   * Returns false if either role is unknown (not registered in the hierarchy).
+   */
+  hasMinimumRole(userRole, requiredRole) {
+    const userLevel = this.levels.get(userRole);
+    const requiredLevel = this.levels.get(requiredRole);
+    if (userLevel === void 0 || requiredLevel === void 0) {
+      return false;
+    }
+    return userLevel >= requiredLevel;
+  }
+};
+
+// src/feature-evaluator.ts
+var FeatureEvaluator = class {
+  features = /* @__PURE__ */ new Map();
+  roleHierarchy;
+  /**
+   * @param roleHierarchy - Optional RoleHierarchy instance used for role-minimum checks.
+   */
+  constructor(roleHierarchy) {
+    this.roleHierarchy = roleHierarchy;
+  }
+  /**
+   * Register (or replace) a feature definition.
+   */
+  registerFeature(name, definition) {
+    this.features.set(name, definition);
+  }
+  /**
+   * Evaluate whether a feature is enabled for the given context.
+   *
+   * Returns `true` (enabled) or `false` (disabled).
+   */
+  isEnabled(featureName, context = {}) {
+    if (context.isSuperAdmin) {
+      return true;
+    }
+    const definition = this.features.get(featureName);
+    if (!definition) {
+      return true;
+    }
+    if (definition.killSwitchKey && context.entitlements) {
+      const killed = context.entitlements.some(
+        (e) => e.entitlement_key === definition.killSwitchKey && e.resource_type === "system" && !e.revoked_at
+      );
+      if (killed) {
+        return false;
+      }
+    }
+    if (definition.resourceBlockKey && definition.resourceBlockType && context.resourceId && context.entitlements) {
+      const blocked = context.entitlements.some(
+        (e) => e.entitlement_key === definition.resourceBlockKey && e.resource_type === definition.resourceBlockType && e.resource_id === context.resourceId && !e.revoked_at
+      );
+      if (blocked) {
+        return false;
+      }
+    }
+    if (definition.minimumRole && this.roleHierarchy) {
+      const userRole = context.userRole;
+      if (!userRole) {
+        return false;
+      }
+      if (!this.roleHierarchy.hasMinimumRole(userRole, definition.minimumRole)) {
+        return false;
+      }
+    }
+    return true;
+  }
+};
+
+// src/websocket-auth-helper.ts
+var AUTH_CLOSE_CODES = /* @__PURE__ */ new Set([4001, 4003]);
+var WebSocketAuthHelper = class {
+  config;
+  ws = null;
+  authRetries = 0;
+  networkRetries = 0;
+  pingTimer = null;
+  refreshTimer = null;
+  intentionalClose = false;
+  constructor(config) {
+    this.config = {
+      url: config.url,
+      getAccessToken: config.getAccessToken,
+      refreshAccessToken: config.refreshAccessToken,
+      refreshBufferSeconds: config.refreshBufferSeconds ?? 30,
+      maxAuthRetries: config.maxAuthRetries ?? 3,
+      maxNetworkRetries: config.maxNetworkRetries ?? 5,
+      initialBackoffMs: config.initialBackoffMs ?? 1e3,
+      maxBackoffMs: config.maxBackoffMs ?? 3e4,
+      pingIntervalMs: config.pingIntervalMs ?? 3e4,
+      onMessage: config.onMessage,
+      onOpen: config.onOpen,
+      onClose: config.onClose,
+      onError: config.onError
+    };
+  }
+  // ── Public API ──────────────────────────────────────────────────────────
+  /**
+   * Open an authenticated WebSocket connection.
+   * Appends the access token as a query parameter.
+   */
+  async connect() {
+    this.intentionalClose = false;
+    this.authRetries = 0;
+    this.networkRetries = 0;
+    await this.openConnection();
+  }
+  /**
+   * Cleanly disconnect. No reconnection attempts will be made.
+   */
+  disconnect() {
+    this.intentionalClose = true;
+    this.cleanup();
+    if (this.ws) {
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+  }
+  /**
+   * Send data over the WebSocket.
+   * Throws if the connection is not open.
+   */
+  send(data) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket is not connected");
+    }
+    this.ws.send(data);
+  }
+  // ── Internal helpers ────────────────────────────────────────────────────
+  /** Build the authenticated WebSocket URL. */
+  buildAuthUrl() {
+    const token = this.config.getAccessToken();
+    if (!token) {
+      throw new Error("No access token available for WebSocket authentication");
+    }
+    const separator = this.config.url.includes("?") ? "&" : "?";
+    return `${this.config.url}${separator}token=${encodeURIComponent(token)}`;
+  }
+  async openConnection() {
+    const url = this.buildAuthUrl();
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(url);
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      this.ws.onopen = () => {
+        this.networkRetries = 0;
+        this.startPing();
+        this.scheduleTokenRefresh();
+        this.config.onOpen?.();
+        resolve();
+      };
+      this.ws.onmessage = (event) => {
+        this.config.onMessage?.(String(event.data));
+      };
+      this.ws.onerror = (event) => {
+        this.config.onError?.(event);
+      };
+      this.ws.onclose = (event) => {
+        this.cleanup();
+        this.config.onClose?.(event.code, event.reason);
+        if (this.intentionalClose) {
+          return;
+        }
+        if (AUTH_CLOSE_CODES.has(event.code)) {
+          this.handleAuthClose();
+        } else {
+          this.handleNetworkClose();
+        }
+      };
+    });
+  }
+  async handleAuthClose() {
+    if (this.authRetries >= this.config.maxAuthRetries) {
+      return;
+    }
+    this.authRetries++;
+    try {
+      await this.config.refreshAccessToken();
+      await this.openConnection();
+    } catch {
+    }
+  }
+  handleNetworkClose() {
+    if (this.networkRetries >= this.config.maxNetworkRetries) {
+      return;
+    }
+    this.networkRetries++;
+    const delay = Math.min(
+      this.config.initialBackoffMs * Math.pow(2, this.networkRetries - 1),
+      this.config.maxBackoffMs
+    );
+    setTimeout(async () => {
+      if (this.intentionalClose) return;
+      try {
+        await this.openConnection();
+      } catch {
+      }
+    }, delay);
+  }
+  startPing() {
+    if (this.config.pingIntervalMs <= 0) return;
+    this.pingTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: "ping" }));
+      }
+    }, this.config.pingIntervalMs);
+  }
+  /**
+   * Schedule a proactive token refresh before the current token expires.
+   */
+  scheduleTokenRefresh() {
+    const token = this.config.getAccessToken();
+    if (!token) return;
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3 || !parts[1]) return;
+      const payload = JSON.parse(
+        typeof atob === "function" ? atob(parts[1]) : Buffer.from(parts[1], "base64").toString("utf8")
+      );
+      if (typeof payload.exp !== "number") return;
+      const msUntilExpiry = payload.exp * 1e3 - Date.now();
+      const refreshIn = msUntilExpiry - this.config.refreshBufferSeconds * 1e3;
+      if (refreshIn <= 0) {
+        this.config.refreshAccessToken().catch(() => {
+        });
+        return;
+      }
+      this.refreshTimer = setTimeout(async () => {
+        try {
+          await this.config.refreshAccessToken();
+          this.scheduleTokenRefresh();
+        } catch {
+        }
+      }, refreshIn);
+    } catch {
+    }
+  }
+  cleanup() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+};
+
+// src/index.ts
 if (typeof globalThis.fetch === "undefined") {
   require("cross-fetch/polyfill");
 }
@@ -286,6 +564,72 @@ var SPAPSClient = class {
     getTemplate: (templateKey) => this.getEmailTemplate(templateKey),
     previewTemplate: (templateKey, context) => this.previewEmailTemplate(templateKey, context)
   };
+  /**
+   * Entitlements namespace for querying user and resource entitlements.
+   *
+   * Scope rules:
+   * - Publishable key contexts (browser): JWT required, user derived from JWT, can only query user-scoped entitlements.
+   * - Secret key contexts (server): can query any resource scope.
+   * - `listByResource` with non-user resource types will fail with 403 for publishable keys (enforced server-side).
+   */
+  entitlements = {
+    /**
+     * List the current user's entitlements.
+     * Requires authentication (JWT).
+     */
+    list: async (params) => {
+      const q = new URLSearchParams();
+      if (params?.key) q.append("entitlement_key", params.key);
+      if (params?.source) q.append("source", params.source);
+      if (params?.include_revoked) q.append("include_revoked", "true");
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/entitlements${qs ? `?${qs}` : ""}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      const payload = this.unwrapApiResponse(res, "Failed to list entitlements");
+      if (payload && Array.isArray(payload.entitlements)) {
+        return payload.entitlements;
+      }
+      return payload;
+    },
+    /**
+     * Boolean access check — does the user hold an active entitlement with the given key?
+     * @param key - The entitlement key to check (e.g. "premium").
+     * @param userId - Optional user ID override (secret key contexts only).
+     */
+    check: async (key, userId) => {
+      const q = new URLSearchParams({ key });
+      if (userId) q.append("user_id", userId);
+      const res = await this.client.get(
+        `/api/entitlements/check?${q.toString()}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to check entitlement");
+    },
+    /**
+     * List entitlements scoped to a specific resource type and optional resource ID.
+     *
+     * Note: For publishable key contexts, only `resource_type=user` is permitted.
+     * Non-user resource types will return a 403 error (enforced server-side).
+     *
+     * @param resourceType - The resource type (e.g. "user", "company", "org", "system").
+     * @param resourceId - Optional specific resource ID.
+     */
+    listByResource: async (resourceType, resourceId) => {
+      const q = new URLSearchParams({ resource_type: resourceType });
+      if (resourceId) q.append("resource_id", resourceId);
+      const res = await this.client.get(
+        `/api/entitlements?${q.toString()}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      const payload = this.unwrapApiResponse(res, "Failed to list entitlements by resource");
+      if (payload && Array.isArray(payload.entitlements)) {
+        return payload.entitlements;
+      }
+      return payload;
+    }
+  };
   constructor(config = {}) {
     const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || process.env.NEXT_PUBLIC_SPAPS_API_URL;
     const isBrowser = typeof window !== "undefined";
@@ -1317,11 +1661,14 @@ function detectKeyType(key) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_ADMIN_ACCOUNTS,
+  FeatureEvaluator,
   PermissionChecker,
+  RoleHierarchy,
   SPAPS,
   SPAPSClient,
   TokenManager,
   WalletUtils,
+  WebSocketAuthHelper,
   canAccessAdmin,
   createBrowserClient,
   createPermissionChecker,

package/dist/index.mjs

@@ -195,6 +195,281 @@ import {
   secureMessageSchema,
   secureMessageMetadataSchema
 } from "spaps-types";
+
+// src/role-hierarchy.ts
+var RoleHierarchy = class {
+  levels;
+  /**
+   * @param levels - Mapping of role name to numeric level.
+   *   Higher numbers indicate greater privilege.
+   *   Example: { guest: 0, user: 10, accountant: 20, admin: 30 }
+   */
+  constructor(levels) {
+    this.levels = new Map(Object.entries(levels));
+  }
+  /**
+   * Get the numeric level for a role.
+   * Returns undefined if the role is not registered.
+   */
+  getLevel(role) {
+    return this.levels.get(role);
+  }
+  /**
+   * Check whether `userRole` meets or exceeds `requiredRole` in the hierarchy.
+   * Returns false if either role is unknown (not registered in the hierarchy).
+   */
+  hasMinimumRole(userRole, requiredRole) {
+    const userLevel = this.levels.get(userRole);
+    const requiredLevel = this.levels.get(requiredRole);
+    if (userLevel === void 0 || requiredLevel === void 0) {
+      return false;
+    }
+    return userLevel >= requiredLevel;
+  }
+};
+
+// src/feature-evaluator.ts
+var FeatureEvaluator = class {
+  features = /* @__PURE__ */ new Map();
+  roleHierarchy;
+  /**
+   * @param roleHierarchy - Optional RoleHierarchy instance used for role-minimum checks.
+   */
+  constructor(roleHierarchy) {
+    this.roleHierarchy = roleHierarchy;
+  }
+  /**
+   * Register (or replace) a feature definition.
+   */
+  registerFeature(name, definition) {
+    this.features.set(name, definition);
+  }
+  /**
+   * Evaluate whether a feature is enabled for the given context.
+   *
+   * Returns `true` (enabled) or `false` (disabled).
+   */
+  isEnabled(featureName, context = {}) {
+    if (context.isSuperAdmin) {
+      return true;
+    }
+    const definition = this.features.get(featureName);
+    if (!definition) {
+      return true;
+    }
+    if (definition.killSwitchKey && context.entitlements) {
+      const killed = context.entitlements.some(
+        (e) => e.entitlement_key === definition.killSwitchKey && e.resource_type === "system" && !e.revoked_at
+      );
+      if (killed) {
+        return false;
+      }
+    }
+    if (definition.resourceBlockKey && definition.resourceBlockType && context.resourceId && context.entitlements) {
+      const blocked = context.entitlements.some(
+        (e) => e.entitlement_key === definition.resourceBlockKey && e.resource_type === definition.resourceBlockType && e.resource_id === context.resourceId && !e.revoked_at
+      );
+      if (blocked) {
+        return false;
+      }
+    }
+    if (definition.minimumRole && this.roleHierarchy) {
+      const userRole = context.userRole;
+      if (!userRole) {
+        return false;
+      }
+      if (!this.roleHierarchy.hasMinimumRole(userRole, definition.minimumRole)) {
+        return false;
+      }
+    }
+    return true;
+  }
+};
+
+// src/websocket-auth-helper.ts
+var AUTH_CLOSE_CODES = /* @__PURE__ */ new Set([4001, 4003]);
+var WebSocketAuthHelper = class {
+  config;
+  ws = null;
+  authRetries = 0;
+  networkRetries = 0;
+  pingTimer = null;
+  refreshTimer = null;
+  intentionalClose = false;
+  constructor(config) {
+    this.config = {
+      url: config.url,
+      getAccessToken: config.getAccessToken,
+      refreshAccessToken: config.refreshAccessToken,
+      refreshBufferSeconds: config.refreshBufferSeconds ?? 30,
+      maxAuthRetries: config.maxAuthRetries ?? 3,
+      maxNetworkRetries: config.maxNetworkRetries ?? 5,
+      initialBackoffMs: config.initialBackoffMs ?? 1e3,
+      maxBackoffMs: config.maxBackoffMs ?? 3e4,
+      pingIntervalMs: config.pingIntervalMs ?? 3e4,
+      onMessage: config.onMessage,
+      onOpen: config.onOpen,
+      onClose: config.onClose,
+      onError: config.onError
+    };
+  }
+  // ── Public API ──────────────────────────────────────────────────────────
+  /**
+   * Open an authenticated WebSocket connection.
+   * Appends the access token as a query parameter.
+   */
+  async connect() {
+    this.intentionalClose = false;
+    this.authRetries = 0;
+    this.networkRetries = 0;
+    await this.openConnection();
+  }
+  /**
+   * Cleanly disconnect. No reconnection attempts will be made.
+   */
+  disconnect() {
+    this.intentionalClose = true;
+    this.cleanup();
+    if (this.ws) {
+      this.ws.close(1e3, "Client disconnect");
+      this.ws = null;
+    }
+  }
+  /**
+   * Send data over the WebSocket.
+   * Throws if the connection is not open.
+   */
+  send(data) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket is not connected");
+    }
+    this.ws.send(data);
+  }
+  // ── Internal helpers ────────────────────────────────────────────────────
+  /** Build the authenticated WebSocket URL. */
+  buildAuthUrl() {
+    const token = this.config.getAccessToken();
+    if (!token) {
+      throw new Error("No access token available for WebSocket authentication");
+    }
+    const separator = this.config.url.includes("?") ? "&" : "?";
+    return `${this.config.url}${separator}token=${encodeURIComponent(token)}`;
+  }
+  async openConnection() {
+    const url = this.buildAuthUrl();
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(url);
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      this.ws.onopen = () => {
+        this.networkRetries = 0;
+        this.startPing();
+        this.scheduleTokenRefresh();
+        this.config.onOpen?.();
+        resolve();
+      };
+      this.ws.onmessage = (event) => {
+        this.config.onMessage?.(String(event.data));
+      };
+      this.ws.onerror = (event) => {
+        this.config.onError?.(event);
+      };
+      this.ws.onclose = (event) => {
+        this.cleanup();
+        this.config.onClose?.(event.code, event.reason);
+        if (this.intentionalClose) {
+          return;
+        }
+        if (AUTH_CLOSE_CODES.has(event.code)) {
+          this.handleAuthClose();
+        } else {
+          this.handleNetworkClose();
+        }
+      };
+    });
+  }
+  async handleAuthClose() {
+    if (this.authRetries >= this.config.maxAuthRetries) {
+      return;
+    }
+    this.authRetries++;
+    try {
+      await this.config.refreshAccessToken();
+      await this.openConnection();
+    } catch {
+    }
+  }
+  handleNetworkClose() {
+    if (this.networkRetries >= this.config.maxNetworkRetries) {
+      return;
+    }
+    this.networkRetries++;
+    const delay = Math.min(
+      this.config.initialBackoffMs * Math.pow(2, this.networkRetries - 1),
+      this.config.maxBackoffMs
+    );
+    setTimeout(async () => {
+      if (this.intentionalClose) return;
+      try {
+        await this.openConnection();
+      } catch {
+      }
+    }, delay);
+  }
+  startPing() {
+    if (this.config.pingIntervalMs <= 0) return;
+    this.pingTimer = setInterval(() => {
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(JSON.stringify({ type: "ping" }));
+      }
+    }, this.config.pingIntervalMs);
+  }
+  /**
+   * Schedule a proactive token refresh before the current token expires.
+   */
+  scheduleTokenRefresh() {
+    const token = this.config.getAccessToken();
+    if (!token) return;
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3 || !parts[1]) return;
+      const payload = JSON.parse(
+        typeof atob === "function" ? atob(parts[1]) : Buffer.from(parts[1], "base64").toString("utf8")
+      );
+      if (typeof payload.exp !== "number") return;
+      const msUntilExpiry = payload.exp * 1e3 - Date.now();
+      const refreshIn = msUntilExpiry - this.config.refreshBufferSeconds * 1e3;
+      if (refreshIn <= 0) {
+        this.config.refreshAccessToken().catch(() => {
+        });
+        return;
+      }
+      this.refreshTimer = setTimeout(async () => {
+        try {
+          await this.config.refreshAccessToken();
+          this.scheduleTokenRefresh();
+        } catch {
+        }
+      }, refreshIn);
+    } catch {
+    }
+  }
+  cleanup() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+};
+
+// src/index.ts
 if (typeof globalThis.fetch === "undefined") {
   __require("cross-fetch/polyfill");
 }
@@ -259,6 +534,72 @@ var SPAPSClient = class {
     getTemplate: (templateKey) => this.getEmailTemplate(templateKey),
     previewTemplate: (templateKey, context) => this.previewEmailTemplate(templateKey, context)
   };
+  /**
+   * Entitlements namespace for querying user and resource entitlements.
+   *
+   * Scope rules:
+   * - Publishable key contexts (browser): JWT required, user derived from JWT, can only query user-scoped entitlements.
+   * - Secret key contexts (server): can query any resource scope.
+   * - `listByResource` with non-user resource types will fail with 403 for publishable keys (enforced server-side).
+   */
+  entitlements = {
+    /**
+     * List the current user's entitlements.
+     * Requires authentication (JWT).
+     */
+    list: async (params) => {
+      const q = new URLSearchParams();
+      if (params?.key) q.append("entitlement_key", params.key);
+      if (params?.source) q.append("source", params.source);
+      if (params?.include_revoked) q.append("include_revoked", "true");
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/entitlements${qs ? `?${qs}` : ""}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      const payload = this.unwrapApiResponse(res, "Failed to list entitlements");
+      if (payload && Array.isArray(payload.entitlements)) {
+        return payload.entitlements;
+      }
+      return payload;
+    },
+    /**
+     * Boolean access check — does the user hold an active entitlement with the given key?
+     * @param key - The entitlement key to check (e.g. "premium").
+     * @param userId - Optional user ID override (secret key contexts only).
+     */
+    check: async (key, userId) => {
+      const q = new URLSearchParams({ key });
+      if (userId) q.append("user_id", userId);
+      const res = await this.client.get(
+        `/api/entitlements/check?${q.toString()}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to check entitlement");
+    },
+    /**
+     * List entitlements scoped to a specific resource type and optional resource ID.
+     *
+     * Note: For publishable key contexts, only `resource_type=user` is permitted.
+     * Non-user resource types will return a 403 error (enforced server-side).
+     *
+     * @param resourceType - The resource type (e.g. "user", "company", "org", "system").
+     * @param resourceId - Optional specific resource ID.
+     */
+    listByResource: async (resourceType, resourceId) => {
+      const q = new URLSearchParams({ resource_type: resourceType });
+      if (resourceId) q.append("resource_id", resourceId);
+      const res = await this.client.get(
+        `/api/entitlements?${q.toString()}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      const payload = this.unwrapApiResponse(res, "Failed to list entitlements by resource");
+      if (payload && Array.isArray(payload.entitlements)) {
+        return payload.entitlements;
+      }
+      return payload;
+    }
+  };
   constructor(config = {}) {
     const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || process.env.NEXT_PUBLIC_SPAPS_API_URL;
     const isBrowser = typeof window !== "undefined";
@@ -1289,11 +1630,14 @@ function detectKeyType(key) {
 }
 export {
   DEFAULT_ADMIN_ACCOUNTS,
+  FeatureEvaluator,
   PermissionChecker,
+  RoleHierarchy,
   SPAPSClient as SPAPS,
   SPAPSClient,
   TokenManager,
   WalletUtils,
+  WebSocketAuthHelper,
   canAccessAdmin,
   createBrowserClient,
   createPermissionChecker,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Sweet Potato Authentication & Payment Service SDK - Zero-config client with built-in permission checking, role-based access control, and dayrate scheduling",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --watch",
-    "test": "echo \"No tests yet\"",
+    "test": "vitest run",
     "smoke-test": "npm run build && node smoke-test.js",
     "prepublishOnly": "npm run build && npm run smoke-test"
   },
@@ -46,14 +46,15 @@
     "email": "buildooor@gmail.com"
   },
   "dependencies": {
-    "spaps-types": "^1.0.60",
     "axios": "^1.6.0",
-    "cross-fetch": "^4.0.0"
+    "cross-fetch": "^4.0.0",
+    "spaps-types": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.2"
+    "typescript": "^5.3.2",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "typescript": ">=4.5.0"
@@ -74,4 +75,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}